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

Queries a semi-integrated terminal for the result of its last processed transaction. Used when a terminal becomes unresponsive or a previous transaction response was lost or ambiguous. The response includes the last transaction details so the POS can determine whether the transaction was approved and take appropriate corrective action.

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.

🌐

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}. This endpoint does not require card data, invoice numbers, or transaction amounts.

🖥️

Semi-Integrated Terminal Only

This endpoint targets a specific semi-integrated terminal via MerchantTerminalNumber. It is not applicable to E-Commerce or MOTO transactions. The terminal number must correspond to the terminal on which the last transaction was processed.

🔍

Read the Response and Act Accordingly

Recover returns the last transaction result from the terminal. The POS application must inspect the conditional response fields — particularly trxCode, authorizationNumber, and transactionNumber — to determine whether the last transaction was approved and whether a void or correction is needed.

Request

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

ℹ️

All parameters are passed inside the Base64-encoded payload form field. Raw body format: auth-api-key=<key>&payload=<base64>. This endpoint does not require card data, invoice numbers, or transaction amounts.

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 PayFacto during onboarding. Example: `53400000`
MerchantTerminalNumber	Numeric(5)	Identifies the semi-integrated terminal to query. Must correspond to the terminal on which the last transaction was processed. Example: `12345`
LanguageCode	Alphanumeric(1)	Language for PayFacto responses. `F` = French, `E` = English.
OperatorID	Alphanumeric(8)	Identifies the cashier, agent, or system that initiated the request. Example: `USER0001`

Request — Code Example

⚠️

The example below uses the test endpoint and a sandbox API key. Replace credentials and base URL before going live. Send to the same terminal number as the transaction whose result is unknown.

cURL

# Recover -- POST /v1/recover
# Step 1: Build the cleartext payload
PAYLOAD="CompanyNumber=12345&MerchantNumber=53400000&MerchantTerminalNumber=12345&LanguageCode=E&OperatorID=USER0001"

# 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/recover" \
  -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 result of the recovery operation. `00` = recovery successful. All other values indicate a failure. Refer to Section 6 for endpoint-specific codes.
serverNumber	Alphanumeric(4)	Identifies the PayFacto Network server that processed the request.
terminalNumber	Numeric(5)	Identifies the terminal in the PayFacto Network that was queried.
timeStamp	Alphanumeric(17)	Date and time the recovery request was processed on the payment server. Format: `YYYYMMDD-HHMMSSCC`. Example: `20240515-15300100`

Conditionally returned — Last transaction details

When returnCode is 00, the following fields describe the last transaction processed on the terminal. Inspect these values to determine whether the original transaction was approved and whether corrective action is required.

Field	Type	Description
authorizationNumber	Alphanumeric(8)	Authorization code of the last transaction. Present when the last transaction was approved. Example: `APPROV01`
transactionNumber	Numeric(12)	PayFacto gateway transaction identifier of the last transaction. Use this to identify the transaction for voiding or correction if needed. Example: `000111222333`
amount	Numeric(11)	Amount of the last transaction, left (0) padded.
cardNumber	Alphanumeric(40)	Masked card number from the last transaction.
cardType	Alphanumeric(1)	Card brand from the last transaction. `A` = Amex, `M` = Mastercard, `V` = Visa, `D` = Debit/Interac.
invoiceNumber	Alphanumeric(12)	Invoice number of the last transaction. Use this to match the recovered transaction against your records.
trxCode	Alphanumeric(2)	Transaction type code of the last transaction. `00` = Purchase, `01` = Pre-Authorization, `02` = Completion, `03` = Refund.
trxType	Alphanumeric(1)	Type of card used in the last transaction. `C` = Credit, `D` = Debit.
receiptDisp	Alphanumeric(32)	Receipt message from the last transaction. Example: `APPROVED-THANK-YOU`
terminalDisp	Alphanumeric(24)	Terminal display message from the last transaction. Example: `APPROVED`
errorDescription	Alphanumeric(50)	Only returned when the recovery request itself fails. Human-readable description of the failure reason.
demoMode	Alphanumeric(4)	Only returned when the terminal is in demo mode. Value will be `true`.

Response — Code Example

JSON — 200 Recovery Successful (last transaction approved)

{
  "returnCode":          "00",
  "serverNumber":        "0001",
  "terminalNumber":      "12345",
  "timeStamp":           "20240515-15300100",
  "authorizationNumber": "APPROV01",
  "transactionNumber":   "000111222333",
  "amount":              "00000010000",
  "cardNumber":          "411111XXXXXX1111                       ",
  "cardType":            "V",
  "invoiceNumber":       "PUR000000001",
  "trxCode":             "00",
  "trxType":             "C",
  "receiptDisp":         "APPROVED-THANK-YOU      ",
  "terminalDisp":        "APPROVED        "
}

JSON — Error (terminal busy)

{
  "returnCode":       "3667",
  "errorDescription": "SEMI-INTEGRATED TERMINAL IS BUSY",
  "serverNumber":     "0001",
  "terminalNumber":   "12345",
  "timeStamp":        "20240515-15300200"
}

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	Recovery successful	The terminal responded with the result of its last transaction. The conditional response fields contain the last transaction details.	Inspect the returned `trxCode`, `authorizationNumber`, and `transactionNumber`. If the last transaction was approved but should not have been, use the appropriate void or correction endpoint to reverse it.
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.
9031	"Null" value: POS terminal number	`MerchantTerminalNumber` is null or blank in the payload.	Provide the terminal number of the semi-integrated terminal to be queried.
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.
3666	One or more terminals are busy	All of the merchant's terminals are currently processing transactions.	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 already in progress.	Wait 15 seconds and retry. 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 operation 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.
9051	Time out	Request processing timed out. Often caused by an inactive Dispatcher module.	Retry the request. If the problem persists, contact PayFacto customer service.
9049 / 9050	Fatal error	A critical error occurred while processing the request.	Retry the request. If the problem persists, contact PayFacto customer service.