PayFacto API - v1.0 - POST /v1/cash

Records a cash transaction on a Semi-Integrated terminal, allowing tip prompts and receipt printing to be handled by the payment terminal without involving a card or bank authorization.

Prerequisites

🔑

API Key

Generate your API key from the Payments Manager: Administrator Client → API Key → Add New Key. Pass it as auth-api-key in every request.

🏪

Company & Merchant Numbers

Your CompanyNumber (5-digit) and MerchantNumber (8-digit) are issued by PayFacto during onboarding. Both are required on every Cash request.

🌐

Environment Base URL

Test: https://test.api.payfacto.cloud/v1 | Production: Provided by the PayFacto Integration team upon certification.

📦

Request Format — Base64-Encoded Payload

Requests use HTTP POST with an application/x-www-form-urlencoded body. Assemble all parameters as a cleartext query string, Base64-encode it, then send: auth-api-key={key}&payload={base64}.

🖥️

Semi-Integrated Terminal Only

The Cash endpoint is exclusively for Semi-Integrated terminal transactions. A physical payment terminal identified by MerchantTerminalNumber must be online and available. No card data is sent — the terminal handles the customer interaction, tip prompt, and receipt printing. This endpoint does not perform a bank authorization.

Request

POST https://test.api.payfacto.cloud/v1/cash

ℹ️

All parameters are passed inside the Base64-encoded payload form field. Raw body format: auth-api-key=<key>&payload=<base64>. No card data fields are required or accepted. MerchantTerminalNumber must be the assigned terminal number — do not send blank spaces.

Required fields

Field	Type	Description
CompanyNumber	Numeric(5)	Identifies the merchant on PayFacto's network. Provided by PayFacto during onboarding. Example: `12345`
MerchantNumber	Numeric(8)	Identifies the merchant to PayFacto's network. Provided by the integration team. Example: `53400000`
CustomerNumber	Alphanumeric(8)	Merchant-assigned customer identifier. Associates a client record with the transaction. Example: `CLIENT12`
Amount	Numeric(11)	Transaction amount including the decimal portion, left (0) padded. Example: `00000010000` = $100.00
InvoiceNumber	Alphanumeric(12)	Merchant-generated invoice number associated with the transaction. May be unique or reused per merchant needs. Example: `INV000000001`
MerchantTerminalNumber	Numeric(5)	Identifies the Semi-Integrated terminal on PayFacto's network that will handle the customer interaction. Must be the assigned terminal number — blank spaces are not accepted for this endpoint. Example: `12345`
LanguageCode	Alphanumeric(1)	Language for PayFacto responses and terminal display. `F` = French, `E` = English.
CurrencyCode	Alphanumeric(3)	Currency of the transaction (indicative only). `CAD` = Canadian dollars, `USD` = US dollars (requires a US merchant number).
OperatorID	Alphanumeric(8)	Identifies the cashier or system that initiated the transaction. Useful for identifying the employee who generated the transaction on PayFacto's network. Example: `USER0001`

Optional fields

Field	Type	Description
taxAmount	Numeric(11)	Total tax amount included in `Amount`, left (0) padded. Required to enable pre-tax tip prompts on the terminal. Without it, tip is calculated on the full amount including tax. Example: `00000000374` = $3.74
UserEchoData	Alphanumeric(256)	Custom data printed on the terminal receipt (Semi-Integrated only). Pipe-delimited line segments. Contact PayFacto integration before use.

Request — Code Example

⚠️

The example below uses the test endpoint and a sandbox API key. Replace credentials and base URL before going live.

cURL

# Cash — POST /v1/cash
# Step 1: Build the cleartext payload
PAYLOAD="CompanyNumber=12345&MerchantNumber=53400000&CustomerNumber=CLIENT12&Amount=00000010000&InvoiceNumber=INV000000001&MerchantTerminalNumber=12345&LanguageCode=E&CurrencyCode=CAD&OperatorID=USER0001&taxAmount=00000001300"

# Step 2: Base64-encode the payload
ENCODED=$(echo -n "$PAYLOAD" | base64)

# Step 3: Submit the request
curl -X POST "https://test.api.payfacto.cloud/v1/cash" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "auth-api-key=YOUR_TEST_API_KEY&payload=$ENCODED"

Response

Always returned

Field	Type	Description
returnCode	Alphanumeric(4)	Identifies the exact status of the transaction result. `00` = approved. All other values indicate a failure. Refer to Section 6 for endpoint-specific codes.
transactionNumber	Numeric(12)	Unique PayFacto gateway transaction identifier. Example: `000111222333`
amount	Numeric(11)	Echo of the requested transaction amount.
accountType	Alphanumeric(1)	Account type used for the transaction. `C` = Chequing, `S` = Savings.
bankTerminalNumber	Alphanumeric(8)	Terminal identifier at the banking acquirer that processed the transaction.
batchNumber	Numeric(4)	Batch number used by the terminal when the transaction was processed. Can be used when generating client receipts. Example: `0001`
companyNumber	Numeric(5)	Echo of the request CompanyNumber.
invoiceNumber	Alphanumeric(12)	Echo of the request InvoiceNumber.
languageCode	Alphanumeric(1)	Echo of the request LanguageCode.
merchantNumber	Numeric(8)	Echo of the request MerchantNumber.
operatorId	Alphanumeric(8)	Echo of the request OperatorID.
receiptDisp	Alphanumeric(32)	PayFacto-generated receipt message. Can be used to produce a receipt. Example: `APPROVED-THANK-YOU`
referenceNumber	Alphanumeric(10)	Reference number obtained following successful completion of the transaction.
sequenceNumber	Alphanumeric(12)	Sequence number generated by the banking acquirer.
serverNumber	Alphanumeric(4)	Identifies the PayFacto Network server that processed the transaction.
terminalDisp	Alphanumeric(24)	Transaction message displayed on the terminal. Example: `APPROVED`
terminalNumber	Numeric(5)	Identifies the terminal in the PayFacto Network used to process the transaction.
timeStamp	Alphanumeric(17)	Date and time the transaction was processed on the payment server. Format: `YYYYMMDD-HHMMSSCC`. Example: `20240515-14300100`
trxCode	Alphanumeric(2)	Transaction type code. For a Cash transaction this is always `99`.
trxDate	Numeric(8)	Transaction date at the banking acquirer. Format: `MMDDYYYY`. May differ from timeStamp.
trxMethod	Alphanumeric(3)	Summarizes how the transaction was processed. First character: `D` = swiped, `T` = manual entry. Third character: `1` = authorized. Example: `D@1`
trxTime	Numeric(6)	Transaction time at the banking acquirer. Format: `HHMMSS`. May differ from timeStamp.
trxType	Alphanumeric(1)	Type of transaction. For a cash transaction this will be `C` = Credit.

Conditionally returned

Field	Type	Description
customerNumber	Alphanumeric(8)	Only returned when provided in the request. Echo of the request CustomerNumber.
cashbackAmount	Numeric(11)	Only returned when a cash-back amount was applied at the terminal. Left (0) padded.
demoMode	Alphanumeric(4)	Only returned when the terminal is in demo mode. Value will be `true`.
errorDescription	Alphanumeric(50)	Only returned when the transaction is not approved. Human-readable description of the failure reason.
surchargeAmount	Numeric(11)	Only returned when a surcharge was applied. Left (0) padded.
taxAmount	Numeric(11)	Only returned when `taxAmount` was included in the request. Echo of the submitted tax amount.
terminalInvoiceNumber	Numeric(12)	Only returned for terminal transactions. Terminal-assigned invoice number.
tipAmount	Numeric(11)	Only returned when a tip was added by the customer at the terminal. Left (0) padded.

Response — Code Example

JSON — 200 Approved

{
  "returnCode":          "00",
  "transactionNumber":   "000111222333",
  "referenceNumber":     "0000000001",
  "amount":              "00000010000",
  "accountType":         "C",
  "trxType":             "C",
  "trxCode":             "99",
  "trxDate":             "05152024",
  "trxTime":             "143001",
  "trxMethod":           "D@1",
  "timeStamp":           "20240515-14300100",
  "batchNumber":         "0001",
  "sequenceNumber":      "000011112222",
  "serverNumber":        "0001",
  "terminalNumber":      "12345",
  "bankTerminalNumber":  "00000001",
  "terminalInvoiceNumber": "000000000001",
  "companyNumber":       "12345",
  "merchantNumber":      "53400000",
  "invoiceNumber":       "INV000000001",
  "languageCode":        "E",
  "operatorId":          "USER0001",
  "taxAmount":           "00000001300",
  "tipAmount":           "00000000200",
  "receiptDisp":         "APPROVED-THANK-YOU      ",
  "terminalDisp":        "APPROVED        "
}

JSON — Declined / Error

{
  "returnCode":        "P6",
  "errorDescription":  "TRANSACTION CANCELLED BY CLIENT",
  "terminalDisp":      "CANCELLED       ",
  "receiptDisp":       "CANCELLED               ",
  "transactionNumber": "000111222334",
  "timeStamp":         "20240515-14300200"
}

Error / Return Codes

The following codes are most relevant to this endpoint. For the complete catalogue see the Return Code Index.

Return Code	Meaning	When it occurs	Recommended Action
00	Transaction approved	The cash transaction was recorded successfully by the terminal.	No further action required. Print or display the receipt to the customer.
9004	"Null" value: company number	`CompanyNumber` is null or blank in the payload.	Check your application. The field must correspond to the specification in the documentation.
9005 / 9006	Invalid / rejected: company number	`CompanyNumber` does not match the required 5-digit length or is not configured in the payment solution.	Make sure the application uses the correct company number provided by PayFacto. If it does, contact PayFacto customer service.
9007	"Null" value: merchant number	`MerchantNumber` is null or blank in the payload.	Check your application. The field must correspond to the specification in the documentation.
9008 / 9009	Invalid / rejected: merchant number	`MerchantNumber` does not match the required 8-digit length or is not configured in the payment solution.	Make sure the application uses the merchant number provided by PayFacto. If it does, contact PayFacto customer service.
9013 / 9014 / 9015	Null / invalid / rejected: amount	`Amount` is null, does not match the required 11-digit length, or does not follow the specification.	Confirm the amount is left (0) padded to 11 digits and includes the decimal portion. If the problem persists, contact PayFacto customer service.
9016 / 9017 / 9018	Null / invalid / rejected: invoice number	`InvoiceNumber` is null, exceeds 12 characters, or does not follow the specification.	Check your application. The field must correspond to the specification in the documentation.
9031	"Null" value: POS terminal number	`MerchantTerminalNumber` is null or blank. A valid terminal number is required for this endpoint.	Check your application. The field must correspond to the specification in the documentation.
9032 / 9033	Invalid / rejected: POS terminal number	`MerchantTerminalNumber` does not follow the specification, or the merchant is not configured as a POS terminal merchant.	Check your application. The field must correspond to the specification in the documentation. If the problem persists, contact PayFacto customer service.
9034 / 9035 / 9036	Null / invalid / rejected: language code	`LanguageCode` is null, not a single character, or not one of the accepted values (`F`, `E`).	Check your application. The field must correspond to the specification in the documentation.
9037 / 9038 / 9039	Null / invalid / rejected: currency	`CurrencyCode` is null, not 3 characters, or not one of the accepted values (`CAD`, `USD`).	Check your application. The field must correspond to the specification in the documentation.
9040 / 9041 / 9042	Null / invalid / rejected: operator ID	`OperatorID` is null, exceeds 8 characters, or does not follow the specification.	Check your application. The field must correspond to the specification in the documentation.
3666	One or more terminals are busy	All of the merchant's terminals are currently processing transactions. The number of terminals may be insufficient to support peak transaction volumes.	Wait and retry. If the problem persists, contact PayFacto customer service.
3667	Semi-integrated terminal is busy	The target terminal is currently processing another transaction or a recovery is in progress.	Wait 15 seconds and retry the transaction. If the problem persists, contact PayFacto customer service.
3668	Waiting for a recovery	An error occurred with the semi-integrated terminal. A recovery must be completed before another transaction can be processed.	Make sure everything is plugged in correctly. If needed, restart the driver and unplug then replug the terminal power. Wait 35 seconds and retry. If the problem persists, contact PayFacto customer service.
3777	Inexistent terminal and/or merchant	The merchant or terminal has not been configured in the Dispatcher module.	If the problem persists, contact PayFacto customer service.
P5	PIN pad timed out	The customer did not confirm the transaction on the terminal within the allotted time.	Retry the transaction if the customer requests it.
P6	Transaction cancelled by client on PIN pad	The customer pressed the ANNUL/CANCEL button on the terminal.	Retry the transaction if the customer requests it.
9051	Time out	Transaction processing timed out. Often caused by an inactive Dispatcher module.	Retry the transaction. If the problem persists, contact PayFacto customer service.
9049 / 9050	Fatal error	A critical error occurred while processing the transaction.	Retry the transaction. If the problem persists, contact PayFacto customer service.