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

Confirms that a transaction response was successfully received and marks the transaction as COMPLETED. Must be sent within 3 minutes of the original transaction response or PayFacto will automatically reverse the transaction.

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 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}.

⚠️

Applicable Input Types Only

This endpoint applies only when the original transaction used InputType I (Internet), U (Unattended), or M (MOTO). It does not apply to terminal/pinpad (N) transactions.

Request

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

ℹ️

All parameters are passed inside the Base64-encoded payload form field. Raw body format: auth-api-key=<key>&payload=<base64>. The Ack has no optional fields.

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`
TransactionNumber	Numeric(12)	The transaction number obtained in the response of the transaction for which an acknowledgement is wanted. Left (0) padded. 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.

cURL

# Ack — POST /v1/ack
# Step 1: Build the cleartext payload
PAYLOAD="CompanyNumber=12345&MerchantNumber=53400000&TransactionNumber=000111222333"

# 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/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 exact status of the result. `00` = acknowledged successfully. All other values indicate a failure — retry the Ack up to 2 more times (3 total). For the complete list of codes, see Section 6 below.

Response — Code Example

JSON — 200 Acknowledged

{
  "returnCode": "00"
}

JSON — Not Acknowledged / Error

{
  "returnCode": "9004"
}

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 acknowledgement was recorded. The transaction is now COMPLETED.	No further action required. Fulfil the order.
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	Invalid length: company number	`CompanyNumber` does not match the required 5-digit length.	Check your application. The field must correspond to the specification in the documentation.
9006	Rejected value: company number	`CompanyNumber` 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	Invalid length: merchant number	`MerchantNumber` does not match the required 8-digit length.	Check your application. The field must correspond to the specification in the documentation.
9009	Rejected value: merchant number	`MerchantNumber` 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.
9068	Transaction number not found	No transaction matching the submitted `TransactionNumber` exists in the system.	Check your application. Make sure you are sending the correct transaction number from the original transaction response.
9051	Time out	Transaction processing timed out. Often caused by an inactive Dispatcher module.	Retry the Ack. If the problem persists, contact PayFacto customer service. If the 3-minute window has elapsed, treat the original transaction as VOIDED.
9049 / 9050	Fatal error	A critical error occurred while processing the Ack.	Retry the Ack. If the problem persists, contact PayFacto customer service.