PayFacto API - v1.0 - POST /v1/recur/ack

Confirms that the response from a recurring billing (token-based) transaction has been received. Instructs the PayFacto host to mark the transaction as COMPLETED. The ACK must be sent within 3 minutes of the original transaction response — after that window, PayFacto automatically reverses the transaction and it must be considered VOIDED.

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

🔄

Recurring Billing Context Only

This endpoint applies exclusively to token-based recurring billing transactions. It is not applicable to semi-integrated terminal transactions or standard E-Commerce purchases. No MerchantTerminalNumber is required.

⏱️

3-Minute Window — Transaction Will Be VOIDED If Missed

The ACK must be sent within 3 minutes of receiving the original recurring transaction response. After this window, PayFacto automatically reverses the transaction. The transaction must then be considered VOIDED and the cardholder will not be charged.

✔️

Boolean Result — Not a Standard Return Code

The outcome of the acknowledgment is returned in the result field as true (ACK accepted — transaction marked COMPLETED) or false (ACK not accepted). A returnCode of 00 confirms only that the request was processed — always inspect result to determine the final transaction status.

Request

POST https://test.api.payfacto.cloud/v1/recur/ack

ℹ️

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, amounts, or invoice numbers.

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`
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`
TransactionNumber	Numeric(12)	The PayFacto gateway transaction identifier of the recurring billing transaction to acknowledge. This is the `transactionNumber` returned in the recurring transaction response. Must be sent within 3 minutes of that response. Example: `000111222333`

Request — Code Example

⚠️

The example below uses the test endpoint and a sandbox API key. Replace credentials and base URL before going live. The ACK must be sent within 3 minutes of receiving the recurring transaction response, or the transaction will be automatically reversed and considered VOIDED.

cURL

# Recur ACK -- POST /v1/recur/ack
# Step 1: Build the cleartext payload
PAYLOAD="CompanyNumber=12345&MerchantNumber=53400000&LanguageCode=E&OperatorID=USER0001&TransactionNumber=000111222333"

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

# Step 3: Submit the request (within 3 minutes of the recurring transaction response)
curl -X POST "https://test.api.payfacto.cloud/v1/recur/ack" \
  -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 request processing. `00` = request was processed — check `result` for the acknowledgment outcome. All other values indicate a request-level failure. Refer to Section 6 for endpoint-specific codes.
serverNumber	Alphanumeric(4)	Identifies the PayFacto Network server that processed the request.
timeStamp	Alphanumeric(17)	Date and time the request was processed. Format: `YYYYMMDD-HHMMSSCC`. Example: `20240515-14320100`

Conditionally returned

Returned when returnCode is 00. The result field is the definitive indicator of whether the transaction has been marked COMPLETED or should be treated as VOIDED.

Field	Type	Description
result	Alphanumeric	★ Always inspect this field. The outcome of the acknowledgment. `true` = ACK accepted — the transaction is marked COMPLETED and the cardholder will be charged. `false` = ACK not accepted — the 3-minute window has elapsed, PayFacto has reversed the transaction, and it must be treated as VOIDED.
errorDescription	Alphanumeric(50)	Only returned when the request fails (non-`00` returnCode). Human-readable description of the failure reason.

Response — Code Example

JSON — ACK accepted (transaction COMPLETED)

{
  "returnCode":   "00",
  "serverNumber": "0001",
  "timeStamp":    "20240515-14320100",
  "result":       "true"
}

JSON — ACK not accepted (3-minute window elapsed — transaction VOIDED)

{
  "returnCode":   "00",
  "serverNumber": "0001",
  "timeStamp":    "20240515-14360100",
  "result":       "false"
}

JSON — Request-level error

{
  "returnCode":       "9006",
  "errorDescription": "INVALID COMPANY NUMBER",
  "serverNumber":     "0001",
  "timeStamp":        "20240515-14320200"
}

Error / Return Codes

The following codes apply to the request processing result in returnCode. A returnCode of 00 does not guarantee the transaction was marked COMPLETED — always read the result field. For the complete catalogue see the Return Code Index.

Return Code	Meaning	When it occurs	Recommended Action
00	Request processed	The ACK request reached the PayFacto host successfully. The acknowledgment outcome is in the `result` field.	Read `result`. If `true`, the transaction is COMPLETED and the cardholder will be charged. If `false`, the window elapsed — PayFacto has already reversed the transaction and it must be treated as VOIDED.
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.
9051	Time out	Request processing timed out.	Retry the request immediately. Be aware the 3-minute acknowledgment window is still running. If the problem persists, contact PayFacto customer service.
9049 / 9050	Fatal error	A critical error occurred while processing the request.	Retry the request immediately. Be aware the 3-minute acknowledgment window is still running. If the problem persists, contact PayFacto customer service.