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

Retrieves the billing history for a specific recurring subscription. Returns a list of invoice records, each containing the billing date, amount, transaction identifiers, and result code for that cycle. No transaction is processed and no vault record is modified.

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 Info Invoice 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, terminal numbers, or transaction amounts.

📋

Subscription ID Required

The SubscriptionID field identifies which subscription's billing history to retrieve. It must be the value originally assigned when the subscription was created via /v1/recur/AddSubscription.

🔍

Read-Only Operation

This endpoint retrieves data only. No transaction is processed, no vault record is modified, and no charge is made to the cardholder.

Request

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

ℹ️

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, terminal 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 the integration team. Example: `53400000`
CustomerNumber	Alphanumeric(8)	Merchant-assigned customer identifier associated with the subscription. Example: `CLIENT12`
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`
SubscriptionID	Alphanumeric	The subscription identifier whose billing history to retrieve. Must match the `SubscriptionID` originally assigned when the subscription was created via `/v1/recur/AddSubscription`. Example: `SUBSCRIP0001`

Request — Code Example

⚠️

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

cURL

# Info Invoice -- POST /v1/recur/InfoInvoice
# Step 1: Build the cleartext payload
PAYLOAD="CompanyNumber=12345&MerchantNumber=53400000&CustomerNumber=CLIENT12&LanguageCode=E&OperatorID=USER0001&SubscriptionID=SUBSCRIP0001"

# 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/InfoInvoice" \
  -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 query. `00` = query 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.
timeStamp	Alphanumeric(17)	Date and time the request was processed. Format: `YYYYMMDD-HHMMSSCC`. Example: `20240901-10000100`
companyNumber	Numeric(5)	Echo of the request CompanyNumber.
merchantNumber	Numeric(8)	Echo of the request MerchantNumber.
languageCode	Alphanumeric(1)	Echo of the request LanguageCode.

Conditionally returned — Invoice records

When returnCode is 00, the response includes an array of invoice records for the subscription. Each record represents one billing cycle attempt and contains the following fields.

Field	Type	Description
invoiceNumber	Alphanumeric(12)	Invoice number assigned to this billing cycle.
amount	Numeric(11)	Amount charged in this billing cycle, including the decimal portion, left (0) padded. Example: `00000002999` = $29.99
trxDate	Numeric(8)	Date on which this billing cycle was processed. Format: `MMDDYYYY`. Example: `07012024`
trxCode	Alphanumeric(2)	Transaction type code for this billing cycle. Recurring charges are always `00` (Purchase).
returnCode	Alphanumeric(4)	Result of this specific billing cycle. `00` = approved, `05` = declined. Other values indicate a processing error for that cycle.
authorizationNumber	Alphanumeric(8)	Authorization code from the issuing bank for this billing cycle. Only present when the cycle was approved. Example: `APPROV01`
transactionNumber	Numeric(12)	PayFacto gateway transaction identifier for this billing cycle. Example: `000111222333`
errorDescription	Alphanumeric(50)	Only present when the billing cycle was not approved. Human-readable description of the failure reason for that cycle.

Response — Code Example

JSON — 200 Success (three billing cycles, mixed results)

{
  "returnCode":    "00",
  "serverNumber":  "0001",
  "timeStamp":     "20240901-10000100",
  "companyNumber": "12345",
  "merchantNumber": "53400000",
  "languageCode":  "E",
  "invoices": [
    {
      "invoiceNumber":       "SUB000000001",
      "amount":              "00000002999",
      "trxDate":             "06012024",
      "trxCode":             "00",
      "returnCode":          "00",
      "authorizationNumber": "APPROV01",
      "transactionNumber":   "000111222333"
    },
    {
      "invoiceNumber":       "SUB000000002",
      "amount":              "00000002999",
      "trxDate":             "07012024",
      "trxCode":             "00",
      "returnCode":          "00",
      "authorizationNumber": "APPROV02",
      "transactionNumber":   "000111222334"
    },
    {
      "invoiceNumber":       "SUB000000003",
      "amount":              "00000002999",
      "trxDate":             "08012024",
      "trxCode":             "00",
      "returnCode":          "05",
      "transactionNumber":   "000111222335",
      "errorDescription":    "TRANSACTION DECLINED"
    }
  ]
}

JSON — Error

{
  "returnCode":       "9006",
  "errorDescription": "INVALID COMPANY NUMBER",
  "serverNumber":     "0001",
  "timeStamp":        "20240901-10000200",
  "companyNumber":    "12345",
  "merchantNumber":   "53400000",
  "languageCode":     "E"
}

Error / Return Codes

The following codes apply to the overall query result returned in the top-level returnCode field. Individual invoice records within the response each carry their own returnCode reflecting the outcome of that billing cycle. For the complete catalogue see the Return Code Index.

Return Code	Meaning	When it occurs	Recommended Action
00	Query successful	The billing history for the subscription was retrieved successfully. The response includes an array of invoice records.	Iterate over the invoice records. Check each record's `returnCode` to identify approved and declined billing cycles.
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. 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.