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

Checks whether a token is valid and active in the PayFacto recurring billing vault. Returns the associated masked card details on success. No transaction is processed and no vault record is modified. Use this endpoint to confirm a cardholder registration is still valid before initiating a billing operation, or to retrieve the card details associated with a stored token.

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 Verify 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}. This endpoint does not require card data, terminal numbers, or transaction amounts.

💾

Token Required

The Token field identifies the cardholder vault registration to verify. It must be a token previously returned by /v1/recur/AddUser, /v1/recur/CreateSession, or /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/VerifyUser

ℹ️

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 token to verify. 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`
Token	Alphanumeric(35)	The token to verify. Must be a token previously returned by `/v1/recur/AddUser`, `/v1/recur/CreateSession`, or `/v1/recur/AddSubscription`. Example: `4111110000001111000000000000000001`

Request — Code Example

⚠️

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

cURL

# Verify User -- POST /v1/recur/VerifyUser
# Step 1: Build the cleartext payload
PAYLOAD="CompanyNumber=12345&MerchantNumber=53400000&CustomerNumber=CLIENT12&LanguageCode=E&OperatorID=USER0001&Token=4111110000001111000000000000000001"

# 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/VerifyUser" \
  -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 verification. `00` = token is valid and active. `05` = token not found or no longer valid. Refer to Section 6 for all 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-09000100`
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

Returned when returnCode is 00. These fields confirm the token is valid and describe the associated cardholder vault registration.

Field	Type	Description
token	Alphanumeric(35)	Echo of the request Token, confirming which vault registration was verified.
cardNumber	Alphanumeric(40)	Masked card number associated with this token.
cardType	Alphanumeric(1)	Card brand associated with this token. `A` = Amex, `M` = Mastercard, `V` = Visa, `I` = Diners, `O` = Discover.
expirationDate	Numeric(4)	Card expiration date associated with this token, in `MMYY` format.
customerNumber	Alphanumeric(8)	Echo of the request CustomerNumber.
errorDescription	Alphanumeric(50)	Only returned when the verification fails. Human-readable description of the failure reason.

Response — Code Example

JSON — 200 Success (token valid)

{
  "returnCode":     "00",
  "serverNumber":   "0001",
  "timeStamp":      "20240601-09000100",
  "companyNumber":  "12345",
  "merchantNumber": "53400000",
  "languageCode":   "E",
  "token":          "4111110000001111000000000000000001 ",
  "cardNumber":     "411111XXXXXX1111                       ",
  "cardType":       "V",
  "expirationDate": "1226",
  "customerNumber": "CLIENT12"
}

JSON — Token not found

{
  "returnCode":       "05",
  "errorDescription": "TOKEN NOT FOUND",
  "serverNumber":     "0001",
  "timeStamp":        "20240601-09000200",
  "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	Token valid	The token exists in the PayFacto vault and is active. The response includes the associated masked card details.	The token may be used for billing operations. Check the `expirationDate` to confirm the card has not expired before initiating a charge.
05	Token not found	The token does not exist in the vault, has been deleted via `/v1/recur/DelUser`, or is no longer valid.	Do not attempt to use this token for billing. Re-register the cardholder via `/v1/recur/AddUser` or `/v1/recur/CreateSession` to obtain a new token.
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.