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

Registers a cardholder's credit card in the PayFacto recurring billing vault without processing any transaction. No charge is made. On success, a token is returned that identifies the cardholder for future recurring or token-based billing.

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 Add 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}. E-Commerce transactions send 5 blank spaces for MerchantTerminalNumber.

💳

Credit Card Only — No Transaction Processed

This endpoint registers a credit card in the PayFacto recurring billing vault. No charge is made to the cardholder. Interac debit (IAP) is not supported. To immediately charge the cardholder and create a subscription at the same time, use /v1/recur/AddSubscription instead.

💾

Store the Token

On success, persist the token returned in the response. This token identifies the registered cardholder and is required for all future recurring or token-based billing operations against this card.

Request

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

ℹ️

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 an amount or invoice number. E-Commerce transactions send 5 blank spaces for MerchantTerminalNumber.

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. Associates the registered card with a client record. Example: `CLIENT12`
InputType	Alphanumeric(1)	How the card details are supplied. `I` = Internet/E-Commerce, `M` = MOTO, `N` = terminal/pinpad (Semi-Integrated), `U` = Unattended.
CardType	Alphanumeric(1)	Card brand. For `InputType=N` send a blank space. For `I`/`M`: `A` = Amex, `M` = Mastercard, `V` = Visa, `I` = Diners, `O` = Discover. Blank for unknown.
CardNumber	Alphanumeric(40)	Cardholder's card number, left-justified and space-padded to 40 characters. For `InputType=N`, send 40 space characters — the terminal reads the card directly.
ExpirationDate	Numeric(4)	Card expiration date in `MMYY` format. For `InputType=N`, send 4 space characters. Example: `1226`
Cvv2Cvc2Number	Alphanumeric(4)	Card security code (3 digits for Visa/Mastercard/Discover, 4 digits for Amex). For `InputType=N`, send a blank space. Example: `123`
MerchantTerminalNumber	Numeric(5)	Identifies the terminal on PayFacto's network. For E-Commerce transactions, send 5 blank spaces. Example: `12345`
LanguageCode	Alphanumeric(1)	Language for PayFacto responses. `F` = French, `E` = English.
CurrencyCode	Alphanumeric(3)	Currency associated with the registered card. `CAD` = Canadian dollars, `USD` = US dollars (requires a US merchant number).
OperatorID	Alphanumeric(8)	Identifies the cashier, agent, or system that initiated the request. Example: `USER0001`

Optional fields

Field	Type	Description
AvsStreetNumber	Alphanumeric(10)	Street number portion of the cardholder's billing address for Address Verification Service (AVS). Example: `123`
AvsStreetName	Alphanumeric(28)	Street name portion of the cardholder's billing address for AVS. Example: `Main Street`
AvsZipCode	Alphanumeric(9)	Postal/ZIP code of the cardholder's billing address for AVS. Example: `H1A1A1`
UserEchoData	Alphanumeric(256)	Custom data printed on the terminal receipt (Semi-Integrated only). Pipe-delimited line segments. Contact PayFacto integration before use.

Request — Code Example

⚠️

The example below uses the test endpoint and a sandbox API key, and shows an E-Commerce (InputType=I) card registration. Replace credentials and base URL before going live. No charge is made. Store the token from the response.

cURL

# Add User -- POST /v1/recur/AddUser
# Step 1: Build the cleartext payload (InputType=I, E-Commerce)
PAYLOAD="CompanyNumber=12345&MerchantNumber=53400000&CustomerNumber=CLIENT12&InputType=I&CardType=V&CardNumber=4111111111111111                       &ExpirationDate=1226&Cvv2Cvc2Number=123&MerchantTerminalNumber=     &LanguageCode=E&CurrencyCode=CAD&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/AddUser" \
  -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 registration. `00` = card registered successfully. 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.
terminalNumber	Numeric(5)	Identifies the terminal in the PayFacto Network used to process 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

Field	Type	Description
token	Alphanumeric(35)	★ Store this value. Returned on successful registration. Uniquely identifies this cardholder in the PayFacto vault. Required for all future recurring or token-based billing operations against this card.
cardNumber	Alphanumeric(40)	Echo of the request CardNumber (masked).
cardType	Alphanumeric(1)	Card brand determined by the network. `A` = Amex, `M` = Mastercard, `V` = Visa, `I` = Diners, `O` = Discover.
expirationDate	Numeric(4)	Echo of the request ExpirationDate, in `MMYY` format.
customerNumber	Alphanumeric(8)	Only returned when provided in the request. Echo of the request CustomerNumber.
avsResponse	Alphanumeric(1)	Only returned when AVS fields were submitted. Address Verification Service result code from the card issuer. Example: `Y` = address and ZIP match.
cvv2Response	Alphanumeric(1)	Only returned when `Cvv2Cvc2Number` was submitted. CVV2/CVC2 validation result. `M` = match, `N` = no match, `P` = not processed.
errorDescription	Alphanumeric(50)	Only returned when the registration fails. Human-readable description of the failure reason.
demoMode	Alphanumeric(4)	Only returned when the terminal is in demo mode. Value will be `true`.

Response — Code Example

JSON — 200 Success

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

JSON — Error

{
  "returnCode":       "05",
  "errorDescription": "CARD VALIDATION FAILED",
  "serverNumber":     "0001",
  "terminalNumber":   "00000",
  "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	Registration successful	The cardholder's card has been registered in the PayFacto recurring billing vault. No charge has been made.	Store the `token`. Use it to identify this cardholder in future recurring or token-based billing operations.
05	Card validation failed	The card details provided could not be validated by the issuing bank. No registration was created.	Verify the card details and retry. If the problem persists, ask the cardholder to provide an alternative payment method or contact PayFacto customer service.
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.
9019 / 9020 / 9021	Null / invalid / rejected: input type	`InputType` is null, not a single character, not in the list of accepted values, or not associated with the merchant.	Check your application. The field must correspond to the specification in the documentation.
9022 / 9023 / 9024	Null / invalid / rejected: card type	`CardType` is null, not a single character, or not in the list of accepted values.	Check your application. For terminal transactions send a blank space.
9025 / 9026 / 9027	Null / invalid / rejected: card number	`CardNumber` is null, exceeds 40 characters, or does not follow the specification.	For E-Commerce, ensure the card number is left-justified and padded to 40 characters. For terminal transactions send 40 space characters.
9028 / 9029 / 9030	Null / invalid / rejected: expiration date	`ExpirationDate` is null, not 4 characters, or does not follow the specification.	Ensure the date is in `MMYY` format. For terminal transactions send 4 space characters.
9031	"Null" value: POS terminal number	`MerchantTerminalNumber` is null or blank when a terminal transaction is being attempted.	For terminal transactions provide a valid terminal number; for E-Commerce send 5 blank spaces.
9032 / 9033	Invalid / rejected: POS terminal number	`MerchantTerminalNumber` does not follow the specification, or the merchant is not configured as a POS terminal merchant.	Check your application. The field must correspond to the specification in the documentation. If the problem persists, contact PayFacto customer service.
9051	Time out	Request processing timed out. Often caused by an inactive Dispatcher module.	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.