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

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.

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.

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

Field	Type	Description
CompanyNumber	Numeric(5)	Identifies the merchant on PayFacto's network. Provided by PayFacto. Example: `12345`
MerchantNumber	Numeric(8)	Identifies the merchant to PayFacto's network. Provided by the integration team. Example: `53400000`
CustomerNumber	Alphanumeric(8)	The merchant-assigned identifier of the subscriber to look up. Example: `CLIENT12`
Token	Alphanumeric(35)	Security token linked to the subscriber's credit card in the PayFacto Token Vault. Identifies the specific record to retrieve. Example: `2079wo00wbwp916d3l2mutd8t7965o99mp9`
OperatorID	Alphanumeric(8)	Identifies the operator or system performing the lookup. Example: `USER0001`

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"

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

Field	Type	Description
recurReturnCode	Alphanumeric(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.
token	Alphanumeric(35)	Echo of the Token sent in the request. Confirms which vault record was retrieved.
id	Numeric(12)	Unique identifier of the subscriber record in the PayFacto recurring system. Left zero-padded.
subscriptionId	Numeric(12)	Identifier of the subscription associated with this subscriber.
client	Alphanumeric(8)	Subscriber (customer) number associated with this token.
name	Alphanumeric(50)	Cardholder name on file for the subscriber.
email	Alphanumeric(240)	Email address of the subscriber, if on file.
languageCode	Alphanumeric(1)	Language preference of the subscriber. `F`=French, `E`=English.
cardNumber	Alphanumeric(40)	Masked card number on file for the subscriber.
cardType	Alphanumeric(1)	Card brand on file. `A`=Amex, `D`=Debit, `M`=Mastercard, `V`=Visa, `O`=Discover, `I`=Diners, `J`=JCB, `F`=Datacandy.
expirationDate	Numeric(4)	Card expiration date on file. Format: `MMYY`.
status	Numeric(2)	Current status of the subscriber's record. See the Recurring — Modify User article for status code definitions.
amount	Numeric(11)	Amount associated with the subscriber's subscription. Zero-padded left.
currencyCode	Alphanumeric(3)	Currency of the subscription. `CAD`=Canadian dollars, `USD`=US dollars.
frequency	Numeric(2)	Frequency code of the subscription associated with this subscriber.
numberOfPayments	Numeric(3)	Number of payments scheduled for the subscription.
startDate	Numeric(8)	Start date of the subscription. Format: `YYYYMMDD`.
endDate	Numeric(8)	End date of the subscription, or 8 spaces if open-ended. Format: `YYYYMMDD`.
lastInvoiceDate	Numeric(8)	Date the last invoice was processed. Format: `YYYYMMDD`.
nextInvoiceDate	Numeric(8)	Date the next invoice is scheduled. Format: `YYYYMMDD`.
accountNumber	Alphanumeric(50)	Merchant reference number for the subscriber account.
description	Alphanumeric(50)	Merchant reference description for the subscription.
avsStatus	Alphanumeric(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.
cvv2Cvc2Status	Alphanumeric(1)	CVD verification status from the most recent transaction on this token. `M`=Matches, `N`=Does not match, blank=Unknown.
transactionReturnCode	Alphanumeric(4)	Return code of the most recent transaction associated with this subscriber, if applicable.
transactionNumber	Numeric(12)	Unique PayFacto gateway identifier of the most recent transaction associated with this subscriber, if applicable.
secureID	Alphanumeric(35)	Secure session identifier, if a hosted session is associated with this subscriber.
errorDescription	Alphanumeric(50)	Only returned when `recurReturnCode` is not `00`. Human-readable description of the failure reason.

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

Error / Return Codes

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

recurReturnCode	Meaning	When it occurs	Recommended Action
00	Success	The 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-00	Lookup failed	The 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.