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

Retrieves the result of a hosted recurring billing session after the cardholder has been redirected back to the merchant's success or failure URL. Called immediately following the redirect from /v1/recur/CreateSession. After retrieving the result, the merchant must issue either a /v1/recur/ack to accept the token creation or a /v1/recur/nack to refuse it, within 3 minutes.

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 Get Response 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.

🔄

Hosted Session Flow — Step 2 of 3

This endpoint is the second step in the hosted recurring card registration flow:

Step	Action	Endpoint
1	Create a hosted session and redirect the cardholder to the returned `sessionUrl` to enter their card details	`/v1/recur/CreateSession`
2 ← You are here	After the cardholder is redirected back to your URL, call this endpoint to retrieve the session result and the `transactionNumber`	`/v1/recur/GetResponse`
3	Accept the token creation (COMPLETED) or refuse it (VOIDED) within 3 minutes	`/v1/recur/ack` or `/v1/recur/nack`

⏱️

ACK or NACK Required Within 3 Minutes

After calling this endpoint, a /v1/recur/ack or /v1/recur/nack must be sent within 3 minutes using the transactionNumber returned in this response. If neither is sent in time, PayFacto automatically reverses the transaction and it must be treated as VOIDED.

🔍

Read-Only Operation

This endpoint retrieves the session result only. No transaction is processed and no vault record is created or modified by this call. The token is not confirmed until a subsequent /v1/recur/ack is accepted.

Request

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

ℹ️

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 returned as a query parameter when the cardholder was redirected back to the merchant URL after completing the hosted session. 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. Use the TransactionNumber received as a query parameter on the redirect back to your URL from the hosted session.

cURL

# Get Response -- POST /v1/recur/GetResponse
# Step 1: Build the cleartext payload
# TransactionNumber comes from the redirect back to your success/failure URL
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
curl -X POST "https://test.api.payfacto.cloud/v1/recur/GetResponse" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "auth-api-key=YOUR_TEST_API_KEY&payload=$ENCODED"

# Step 4: After inspecting the response, immediately send ACK or NACK
# using the transactionNumber returned below (within 3 minutes)

Response

Always returned

Field	Type	Description
returnCode	Alphanumeric(4)	Identifies the result of the session retrieval. `00` = session result retrieved successfully. 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.
timeStamp	Alphanumeric(17)	Date and time the request was processed. Format: `YYYYMMDD-HHMMSSCC`. Example: `20240601-10000100`

Conditionally returned — Session result

Returned when returnCode is 00 and the cardholder completed the hosted form. Store the transactionNumber immediately — it is required for the subsequent ACK or NACK call.

Field	Type	Description
transactionNumber	Numeric(12)	★ Pass to ACK or NACK. The PayFacto gateway transaction identifier for this session. Must be passed as `TransactionNumber` in the subsequent `/v1/recur/ack` or `/v1/recur/nack` call within 3 minutes. Example: `000111222333`
token	Alphanumeric(35)	The vault token representing the cardholder's registered card. Only confirmed once a subsequent `/v1/recur/ack` is accepted. Store this token to use for future recurring charges via `/v1/recur/AddSubscription` or token-based payment endpoints.
cardNumber	Alphanumeric(40)	Masked card number entered by the cardholder on the hosted form.
cardType	Alphanumeric(1)	Card brand. `A` = Amex, `M` = Mastercard, `V` = Visa, `I` = Diners, `O` = Discover.
expirationDate	Numeric(4)	Card expiration date in `MMYY` format.
customerNumber	Alphanumeric(8)	The merchant-assigned customer identifier associated with this session.
errorDescription	Alphanumeric(50)	Only returned when the request fails (non-`00` returnCode). Human-readable description of the failure reason.

Response — Code Example

JSON — 200 Success (cardholder completed hosted form)

{
  "returnCode":        "00",
  "serverNumber":      "0001",
  "timeStamp":         "20240601-10000100",
  "transactionNumber": "000111222333",
  "token":             "4111110000001111000000000000000001 ",
  "cardNumber":        "411111XXXXXX1111                       ",
  "cardType":          "V",
  "expirationDate":    "1226",
  "customerNumber":    "CLIENT12"
}

JSON — Error

{
  "returnCode":       "9006",
  "errorDescription": "INVALID COMPANY NUMBER",
  "serverNumber":     "0001",
  "timeStamp":        "20240601-10000200"
}

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	Session result retrieved	The hosted session result was retrieved successfully.	Store the `transactionNumber` and `token` immediately. Send `/v1/recur/ack` to accept the token creation, or `/v1/recur/nack` to refuse it, within 3 minutes.
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 ACK/NACK window is 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 ACK/NACK window is running. If the problem persists, contact PayFacto customer service.