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

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

POST    /v1/recur/InfoUser

Recurring β€” Info User

Retrieves all available information on an existing Token stored in the PayFacto Token Vault. Use this endpoint to look up a subscriber's card details, subscription state, and billing history before performing update or delete operations.

Version: v1.0   |   Last updated: 2026-05-25   |   Author: Annick Lachapelle

1

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

πŸ“„

Existing Token

You must have stored the Token from a prior transaction or recurring session response. This token is the key that identifies the subscriber record in the PayFacto Token Vault.

2

Request

POST https://test.api.payfacto.cloud/v1/recur/InfoUser
ℹ️

All parameters are passed inside the Base64-encoded payload form field. Raw body format: auth-api-key=<key>&payload=<base64>. This is a read-only operation β€” no data is modified in the PayFacto Token Vault.

Required fields

FieldTypeDescription
CompanyNumberNumeric(5)Identifies the merchant on PayFacto's network. Provided by PayFacto. Example: 12345
MerchantNumberNumeric(8)Identifies the merchant to PayFacto's network. Provided by the integration team. Example: 53400000
CustomerNumberAlphanumeric(8)The merchant-assigned identifier of the subscriber to look up. Example: CLIENT12
TokenAlphanumeric(35)Security token linked to the subscriber's credit card in the PayFacto Token Vault. Identifies the specific record to retrieve. Example: 2079wo00wbwp916d3l2mutd8t7965o99mp9
OperatorIDAlphanumeric(8)Identifies the operator or system performing the lookup. Example: USER0001
3

Request β€” Code Example

⚠️

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

cURL
# Recurring: Info User β€” POST /v1/recur/InfoUser
# Step 1: Build the cleartext payload
PAYLOAD="CompanyNumber=12345\
&MerchantNumber=53400000\
&CustomerNumber=CLIENT12\
&Token=2079wo00wbwp916d3l2mutd8t7965o99mp9\
&OperatorID=USER0001"

# 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/InfoUser" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "auth-api-key=YOUR_TEST_API_KEY&payload=$ENCODED"
4

Response

ℹ️

The source specification does not designate any response fields as unconditionally mandatory for this endpoint. Always check recurReturnCode first. On success, the response reflects the complete current state of the subscriber record in the Token Vault.

Response fields

FieldTypeDescription
recurReturnCodeAlphanumeric(4)00=the lookup was successful and subscriber data is returned. Any other value indicates a failure. Check this field first before reading the remaining response fields.
tokenAlphanumeric(35)Echo of the Token sent in the request. Confirms which vault record was retrieved.
idNumeric(12)Unique identifier of the subscriber record in the PayFacto recurring system. Left zero-padded.
subscriptionIdNumeric(12)Identifier of the subscription associated with this subscriber.
clientAlphanumeric(8)Subscriber (customer) number associated with this token.
nameAlphanumeric(50)Cardholder name on file for the subscriber.
emailAlphanumeric(240)Email address of the subscriber, if on file.
languageCodeAlphanumeric(1)Language preference of the subscriber. F=French, E=English.
cardNumberAlphanumeric(40)Masked card number on file for the subscriber.
cardTypeAlphanumeric(1)Card brand on file. A=Amex, D=Debit, M=Mastercard, V=Visa, O=Discover, I=Diners, J=JCB, F=Datacandy.
expirationDateNumeric(4)Card expiration date on file. Format: MMYY.
statusNumeric(2)Current status of the subscriber's record. See the Recurring β€” Modify User article for status code definitions.
amountNumeric(11)Amount associated with the subscriber's subscription. Zero-padded left.
currencyCodeAlphanumeric(3)Currency of the subscription. CAD=Canadian dollars, USD=US dollars.
frequencyNumeric(2)Frequency code of the subscription associated with this subscriber.
numberOfPaymentsNumeric(3)Number of payments scheduled for the subscription.
startDateNumeric(8)Start date of the subscription. Format: YYYYMMDD.
endDateNumeric(8)End date of the subscription, or 8 spaces if open-ended. Format: YYYYMMDD.
lastInvoiceDateNumeric(8)Date the last invoice was processed. Format: YYYYMMDD.
nextInvoiceDateNumeric(8)Date the next invoice is scheduled. Format: YYYYMMDD.
accountNumberAlphanumeric(50)Merchant reference number for the subscriber account.
descriptionAlphanumeric(50)Merchant reference description for the subscription.
avsStatusAlphanumeric(1)AVS verification status from the most recent transaction on this token. M=Both match, N=Neither match, Z=Postal only, A=Address only, U=Unavailable.
cvv2Cvc2StatusAlphanumeric(1)CVD verification status from the most recent transaction on this token. M=Matches, N=Does not match, blank=Unknown.
transactionReturnCodeAlphanumeric(4)Return code of the most recent transaction associated with this subscriber, if applicable.
transactionNumberNumeric(12)Unique PayFacto gateway identifier of the most recent transaction associated with this subscriber, if applicable.
secureIDAlphanumeric(35)Secure session identifier, if a hosted session is associated with this subscriber.
errorDescriptionAlphanumeric(50)Only returned when recurReturnCode is not 00. Human-readable description of the failure reason.
5

Response β€” Code Example

JSON β€” 200 Success
{
  "recurReturnCode":       "00",
  "token":                 "2079wo00wbwp916d3l2mutd8t7965o99mp9",
  "id":                    "000000000001",
  "subscriptionId":        "000000000010",
  "client":                "CLIENT12",
  "name":                  "Jane Doe",
  "email":                 "jane.doe@example.com",
  "languageCode":          "E",
  "cardNumber":            "411111XXXXXX1111",
  "cardType":              "V",
  "expirationDate":        "1226",
  "status":                "01",
  "amount":                "00000010000",
  "currencyCode":          "CAD",
  "frequency":             "03",
  "numberOfPayments":      "012",
  "startDate":             "20240101",
  "endDate":               "20251231",
  "lastInvoiceDate":       "20240501",
  "nextInvoiceDate":       "20240601",
  "accountNumber":         "ACC00012345",
  "description":           "Monthly subscription",
  "avsStatus":             "M",
  "cvv2Cvc2Status":        "M"
}
JSON β€” Token Not Found
{
  "recurReturnCode":  "9121",
  "errorDescription": "TOKEN NOT FOUND"
}
6

Error / Return Codes

The following codes are specific to this endpoint. For the complete catalogue see the Return Code Index.

recurReturnCodeMeaningWhen it occursRecommended Action
00SuccessThe token was found and the subscriber record was retrieved successfully.Use the returned data to verify subscriber details before performing update or delete operations. Note the expirationDate to proactively catch expiring cards before the next billing cycle.
Non-00Lookup failedThe token or subscriber could not be found. Common causes: the Token does not exist in the vault, the CustomerNumber does not match the token, or the subscriber was previously deleted.Check errorDescription. Verify the Token and CustomerNumber values are correct and were not altered. If the subscriber was deleted, a new token must be created via a new transaction. Refer to the Return Code Index for code-specific guidance.

    • Related Articles

    • PayFacto API - v1.0 - POST /v1/recur/ModUser

      POST /v1/recur/ModUser Recurring β€” Modify User Updates the information linked to a Token in the PayFacto recurring billing module. Supports full card replacement or expiry-date-only updates without changing the stored card number. Version: v1.0 | ...

    • PayFacto API - v1.0 - POST /v1/recur/ModInvoice

      POST /v1/recur/ModInvoice Recurring β€” Modify Invoice Updates the status of a recurring invoice. Use this endpoint to activate, suspend, or otherwise change the processing state of a specific invoice within a subscription. Version: v1.0 | Last ...

    • PayFacto API - v1.0 - POST /v1/recur/DelSubscription

      POST /v1/recur/DelSubscription Recurring β€” Delete Subscription Permanently deletes an active subscription from the PayFacto recurring billing module. Once deleted, all associated invoices will cease to be processed and the subscription cannot be ...

    • PayFacto API - v1.0 - POST /v1/recur/nack

      POST /v1/recur/nack Recurring β€” Nack Declines a CVV or AVS verification result from a recurring session and triggers deletion of the associated token. Use this endpoint when your application determines that the CVV or AVS result from a prior ...

    • PayFacto API - v1.0 - POST /v1/standaloneCompletion

      POST /v1/standaloneCompletion Standalone Completion Sends a Pre-Authorization Completion to any properly configured Semi-Integrated terminal. The target terminal can be the one where the original Pre-Authorization was performed, or any other terminal ...