PayFacto API - v1.0 - Request Parameters

Request Parameters

Complete reference for all request parameters accepted by the PayFacto API v1.0. Parameters are grouped by functional category. Each endpoint requires a specific subset — refer to individual endpoint articles for the exact required and optional fields.

Version: v1.0 | Last updated: 2026-05-28

ℹ️

All parameters are passed inside a Base64-encoded payload form field. Assemble parameters as a cleartext query string (e.g. CompanyNumber=12345&MerchantNumber=53400000&...), Base64-encode the result, then POST as: auth-api-key={key}&payload={base64}.

Contents

💳 Core / Merchant Identity 💵 Amount Fields 💳 Card & AVS 📋 Original Transaction Reference 🌐 Redirect / Hosted Payment 🔒 3-D Secure 📱 OEM Wallet (ApplePay / GooglePay) 🔄 Recurring Billing ⚙ Miscellaneous

💳

Core / Merchant Identity

These parameters appear on virtually every endpoint and establish the merchant identity and transaction context.

Parameter	Type / Length	Format	Description
CompanyNumber	Numeric / 5	`12345`	Identifies the merchant on PayFacto's network. Provided by PayFacto during onboarding.
MerchantNumber	Numeric / 8	`53400000`	Identifies the merchant to PayFacto's network. Provided by the PayFacto integration team. Contact PayFacto to obtain your merchant number.
CustomerNumber	Alphanumeric / 8	`CLIENT12`	Merchant-assigned customer identifier. Used to associate a client record with the transaction. Optional for most endpoints but recommended for reporting.
OperatorID	Alphanumeric / 8	`USER0001`	Identifies the cashier, agent, or system that initiated the transaction. Useful for POS, call-center, and audit trail purposes. Not typically required for Internet transactions.
LanguageCode	Alphanumeric / 1	`F` or `E`	Language for PayFacto responses and hosted payment pages. `F`=French, `E`=English.
CurrencyCode	Alphanumeric / 3	`CAD` or `USD`	Currency of the transaction (indicative only — does not determine billing currency). `CAD`=Canadian dollars. `USD`=US dollars (requires a US merchant number).
InputType	Alphanumeric / 1	`N`, `I`, `M`, `U`	How the transaction is initiated. `N`=terminal/pinpad (Semi-Integrated), `I`=Internet/E-Commerce, `M`=MOTO (Mail Order / Telephone Order), `U`=Unattended.
InvoiceNumber	Alphanumeric / 12	`123456789123`	Merchant-generated invoice number associated with the transaction. May be unique or reused per merchant's requirements.
MerchantTerminalNumber	Numeric / 5	`12345`	Identifies the terminal on PayFacto's network. For E-Commerce transactions (`InputType=I`), send 5 blank spaces.

💵

Amount Fields

All monetary values are sent as integers in the smallest currency unit, zero-padded left to 11 digits. There is no decimal point — $4.29 is transmitted as 00000000429.

Parameter	Type / Length	Format	Description
Amount	Numeric / 11	`00000000429`	Transaction amount in the smallest currency unit. Zero-padded left. Includes decimal digits — no decimal point is sent. Example: $4.29 is sent as 00000000429.
OriginalAmount	Numeric / 11	`00000010000`	The amount of the original Pre-Authorization transaction. Normally used in a Pre-Authorization and Completion scenario. Zero-padded left. Example: $100.00 is sent as 00000010000.
taxAmount	Numeric / 11	`00000000374`	Total tax amount included in `Amount`, zero-padded left. Required to enable pre-tax tip prompts on the terminal. Without it, tip is prompted on the full amount including tax. Example: $3.74 is sent as 00000000374.

💰

Card & AVS

Card parameters for E-Commerce and MOTO transactions. For Semi-Integrated terminal transactions (InputType=N), send CardNumber as 40 spaces and ExpirationDate as 4 spaces — the terminal supplies all card data.

Parameter	Type / Length	Format	Description
CardNumber	Alphanumeric / 40	Left-justified, space-padded	Cardholder's card number. Left-justified and space-padded to 40 characters for manual entry (`M`/`I`). For `InputType=N`, send 40 space characters — the terminal supplies card data. ApplePay and GooglePay use a device ID rather than the actual card number.
CardType	Alphanumeric / 1	`A`, `M`, `V`, `I`, `O`	Card brand. For `InputType=N` send a blank space. For `I`/`M`: `A`=Amex, `M`=Mastercard, `V`=Visa, `I`=Diners, `O`=Discover. Use a blank space for unknown card type.
ExpirationDate	Numeric / 4	`0726`	Card expiration date in `MMYY` format (2 digits for month, 2 for year). Validated by the card issuer. For `InputType=N`, send 4 space characters. Example: `0726` = July 2026.
Cvv2Cvc2Number	Numeric / 4	3 or 4 digits	Card security code from the back of the card (or front for Amex). 3 digits for Visa/Mastercard, 4 digits for Amex. Send 3 spaces to make it optional.
CardHolderAddress	Alphanumeric / 20	Free text	Cardholder's billing street address. Used for Address Verification Service (AVS) validation. When provided, the response includes avsStatus.
CardHolderPostalCode	Alphanumeric / 9	Right space-padded	Cardholder's billing postal code for AVS validation. Right-padded with spaces to 9 characters. Example: `J6A2T8`
CardHolderAVV	AlphaHex / 40	Hex string	Verified by Visa (VbV) authentication token. Required for 3-D Secure Visa transactions.

📋

Original Transaction Reference

These parameters reference a previously processed transaction. Store these values from every transaction response — they are required for Void, Refund, and Completion operations.

Parameter	Type / Length	Format	Description
OriginalInvoiceNumber	Alphanumeric / 12	`123456789123`	The invoice number of the original transaction. Required for Void and Refund Without Card operations to locate the original transaction and retrieve card details.
OriginalTransactionNumber	Numeric / 12	`000123456789`	The unique PayFacto gateway transaction identifier of the original transaction. Obtained from the `transactionNumber` field in the original response. Required for Void and Refund Without Card.
OriginalAuthorizationNumber	Alphanumeric / 8	`AUTH7766`	The authorization number returned in the original Pre-Authorization response. Required for Standalone Completion.
OriginalTerminalInvoiceNumber	Numeric / 12	Zero-padded	The terminal invoice number returned in the original Pre-Authorization response. Required for Standalone Completion to route the request to the correct terminal.
TransactionNumber	Numeric / 12	`000123456789`	The transaction number from the response of a transaction for which an acknowledgment is wanted.
TUID	Numeric / 24	`212400667337208477009882`	PayFacto switch (EPOS) unique transaction number. Used by Refund with TUID to identify the original transaction without card data.

🌐

Redirect / Hosted Payment

Parameters specific to the Redirect (hosted payment page) session flow. The merchant creates a session server-side, then redirects the cardholder's browser to the PayFacto hosted page.

Parameter	Type / Length	Format	Description
SuccessUrl	Alphanumeric / 240	`https://example.com/success`	URL to which PayFacto redirects the cardholder after a successful transaction. Must be a fully qualified HTTPS address. Required for Redirect session creation endpoints.
FailureUrl	Alphanumeric / 240	`https://example.com/failure`	URL to which PayFacto redirects the cardholder after a failed or abandoned transaction. Must be a fully qualified HTTPS address. Required for Redirect session creation endpoints.
SecureID	Alphanumeric / 50	Alphanumeric token	Secure session identifier returned by Redirect session creation. Valid for 15 minutes. Used to build the browser redirect URL and to retrieve the transaction result via Get Response.

🔒

3-D Secure

Authentication tokens generated by 3-D Secure verification (Verified by Visa and Mastercard SecureCode). These values are obtained from your 3-D Secure provider before calling the PayFacto API.

Parameter	Type / Length	Format	Description
CardHolderAVV	AlphaHex / 40	Hex string	Verified by Visa (VbV) authentication token. Required for 3-D Secure Visa transactions.
xID	AlphaHex / 40	Hex string	Transaction identifier returned by a successful Verified by Visa login. Required for 3-D Secure flows.
uCAF	Alphanumeric / 64	Base64 string	Mastercard SecureCode authentication data. Required for 3-D Secure Mastercard transactions.

📱

OEM Wallet (ApplePay / GooglePay)

Parameters for mobile wallet transactions. The payment token is generated by the mobile device's authorized wallet and passed to PayFacto in place of card data.

Parameter	Type / Length	Format	Description
OEMWalletData	Alphanumeric / Variable	JSON message	Payment token generated by the mobile device wallet. For ApplePay, send the Apple payment token as received from PassKit. For Google Pay, send the `paymentData.paymentMethodData.tokenizationData.token` value received from the Google Pay API.
OEMWalletType	Alphanumeric / Variable	`ApplePay` or `GooglePay`	Indicates which OEM wallet generated the OEMWalletData. Accepted values: ApplePay, GooglePay.

🔄

Recurring Billing

Parameters used by the recurring billing module (/v1/recur/* endpoints) to manage subscribers, subscriptions, and invoices.

Parameter	Type / Length	Format	Description
Token	Alphanumeric / 35	`2079wo00wbwp916d3l2mutd8t7965o99mp9`	Security token linked to the subscriber's credit card in the PayFacto Token Vault. Returned on transactions where tokenization is enabled. Used for recurring billing, token-based purchases, and refunds.
ID	Numeric / 12	Zero-padded, e.g. `000000000001`	Unique identifier of a recurring subscription or session. Left zero-padded to 12 digits.
Name	Alphanumeric / 50	Min 3 characters	Cardholder or subscriber name. Can be URI-encoded to allow special characters. Must be at least 3 characters long.
Email	Alphanumeric / 240	`test@test.com`	Email address of the cardholder or subscriber.
StartDate	Numeric / 8	`YYYYMMDD`	Beginning date of the subscription.
EndDate	Numeric / 8	`YYYYMMDD`	End date of the subscription. Send 8 spaces for an open-ended subscription.
Frequency	Numeric / 2	`03`	Frequency code for the recurring subscription. `00`=Postponed (1 withdrawal at a future date), `01`=Daily, `02`=Weekly, `03`=Monthly, `04`=Every 2 months, `05`=Quarterly (3 months), `06`=Every 4 months, `07`=Every 6 months, `08`=Yearly, `09`=Every 2 weeks, `10`=Twice monthly.
NumberOfPayments	Numeric / 3	e.g. `012`	Number of payments to make. Send 3 spaces if not applicable (open-ended).
Description	Alphanumeric / 50	URI-encodable	Merchant reference description for the subscription. Can be URI-encoded to accept special characters.
AccountNumber	Alphanumeric / 50	`ACC00012345`	Merchant reference number for the subscriber account.
Status	Numeric / 2	`01`, `50` (subscription) / `01`–`08` (invoice)	Status code applied to the subscription or invoice. Subscription: `01`=Active, `50`=Pause. Invoice: `01`=Active, `02`=In process, `03`=Processed, `04`=Completed (terminal), `05`=Error, `06`=Suspended, `07`=Expired, `08`=Without card.

⚙

Miscellaneous

Additional parameters for specific use cases such as receipt customisation, credential-on-file transactions, and batch management.

Parameter	Type / Length	Format	Description
DisplayText	Alphanumeric / 80	Free text	Message to display on the terminal when requesting a signature capture.
UserEchoData	Alphanumeric / 256	Pipe-delimited	Custom data to be printed on the terminal receipt (Semi-Integrated only). Pipe-delimited line segments. Format: `\|LineNum(1)FieldValue\|LineNum(1)FieldValue\|`. Contact PayFacto integration before use.
TrxOption	Alpha / 50	`isCredentialOnFile`, `isRecurring`, `isInstallment`	Adds transaction-level options. For Credential-on-File (COF) initial transactions, pass twice: `TrxOption=isCredentialOnFile&TrxOption=isFirst`. Values `isCredentialOnFile`, `isRecurring`, and `isInstallment` are mutually exclusive.
BatchNumber	Numeric / 4	`0001`	The batch number used by the terminal when the transaction was processed. Can be used when creating client receipts.
AccountNumber	Alphanumeric / 50	`123456a789bc`	Merchant reference number for the customer account.