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

Retrieves the full configuration and current status of a specific recurring subscription. Returns the billing schedule, amount, associated card, and status. No transaction is processed and no vault record is modified. To retrieve the list of past billing cycle results for a subscription, use /v1/recur/InfoInvoice instead.

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 Subscription 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 to look up. 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/InfoSubscription

ℹ️

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 to look up. 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 Subscription -- POST /v1/recur/InfoSubscription
# 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/InfoSubscription" \
  -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 — Subscription details

Returned when returnCode is 00. These fields describe the subscription configuration and its current state in the PayFacto recurring billing platform.

Field	Type	Description
subscriptionId	Alphanumeric	Echo of the request SubscriptionID.
status	Alphanumeric	Current state of the subscription. Values: `ACTIVE` = billing is ongoing, `CANCELLED` = subscription was stopped before its end date, `COMPLETED` = end date has been reached and all cycles processed, `SUSPENDED` = billing is paused.
amount	Numeric(11)	Billing amount per cycle, including the decimal portion, left (0) padded. Example: `00000002999` = $29.99
startDate	Numeric(8)	Date on which the subscription began. Format: `YYYYMMDD`. Example: `20240601`
endDate	Numeric(8)	Date on which the subscription ends. Format: `YYYYMMDD`. Example: `20250601`
frequency	Alphanumeric	Billing frequency of the subscription. Values: `DAILY`, `WEEKLY`, `MONTHLY`, `YEARLY`.
token	Alphanumeric(35)	Token identifying the cardholder vault registration associated with this subscription.
cardNumber	Alphanumeric(40)	Masked card number associated with this subscription.
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)	Echo of the request CustomerNumber.
errorDescription	Alphanumeric(50)	Only returned when the query fails. Human-readable description of the failure reason.

Response — Code Example

JSON — 200 Success (active subscription)

{
  "returnCode":     "00",
  "serverNumber":   "0001",
  "timeStamp":      "20240901-10000100",
  "companyNumber":  "12345",
  "merchantNumber": "53400000",
  "languageCode":   "E",
  "subscriptionId": "SUBSCRIP0001",
  "status":         "ACTIVE",
  "amount":         "00000002999",
  "startDate":      "20240601",
  "endDate":        "20250601",
  "frequency":      "MONTHLY",
  "token":          "4111110000001111000000000000000001 ",
  "cardNumber":     "411111XXXXXX1111                       ",
  "cardType":       "V",
  "expirationDate": "1226",
  "customerNumber": "CLIENT12"
}

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 are most relevant to this endpoint. For the complete catalogue see the Return Code Index.

Return Code	Meaning	When it occurs	Recommended Action
00	Query successful	The subscription configuration and status were retrieved successfully.	Read the `status` field to determine the current state of the subscription. Use the schedule fields (`startDate`, `endDate`, `frequency`, `amount`) for display or reconciliation.
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.