PayFacto API - v2.0 - Request Parameters

Complete reference for all request parameters accepted by the PayFacto Payment API v2.0. Parameters are organised by object. Each endpoint article lists the exact required and optional fields for that endpoint. Parameters marked with * are required.

ℹ️

All requests use HTTP Basic Authentication and a Content-Type: application/json body. All monetary amounts are positive integers in cents — $12.99 is sent as 1299. Unique identifiers are UUIDs in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Contents

💳 Charge ↩ Refund 🔒 Verification 📳 paymentMethod 💳 card 📅 cardExpiry 🔐 authentication / wallet / 3DS 📳 terminal 🔄 paymentToken / storedCredential 💵 cash 🏠 billingDetail / shippingDetail / address ⚙️ Operation Bodies (capture / increment / void / release)

💳

Charge

Root request body for POST /charges. Creates a payment transaction.

Parameter	Type / Constraint	Example	Description
amount *	integer (int64) · max 11 digits	`1299`	Amount in cents. Must be a positive integer. $12.99 = `1299`.
invoiceNumber *	string · max 25 chars	`INV-001`	Merchant invoice reference number.
capture	boolean · default true	`true` \| `false`	Whether to capture the charge immediately. Set `false` for a pre-authorization to be captured later.
statementDescriptor	string · max 23 chars · pattern A-Z 0-9 .,−?+*/.		Descriptor shown on the cardholder's statement. Defaults to merchant account name if not provided.
metadata	object		Key-value pairs stored with the charge. Any string values. Not sent to the card network.
paymentMethod *	object → paymentMethod		Payment method details. See `paymentMethod` section below.
billingDetail	object → billingDetail		Customer billing information. Used for AVS and customer records.
shippingDetail	object → shippingDetail		Shipping recipient details and tracking number.

↩

Refund

Root request body for POST /refunds. Issues a full or partial refund for a captured charge.

Parameter	Type / Constraint	Example	Description
chargeId *	string (UUID)	`a1822999-...`	The ID of the captured charge to refund.
amount *	integer (int64) · max 11 digits	`1299`	Amount to refund in cents. Must not exceed the remaining captured amount on the charge.
reason *	string · enum	`REQUESTED_BY_CUSTOMER`	Reason for the refund. Values: `DUPLICATE` \| `FRAUDULENT` \| `REQUESTED_BY_CUSTOMER` \| `REQUESTED_BY_MERCHANT`.
metadata	object		Key-value pairs stored with the refund.
paymentMethod	object → paymentMethod		Override payment method. Required for some terminal refund flows.

🔒

Verification

Root request body for POST /verifications. Validates a card with AVS and CVV checks — no funds collected.

Parameter	Type / Constraint	Description
card *	object → card	Card details. See card section below.
billingDetail	object → billingDetail	Billing address for AVS verification.
metadata	object	Key-value pairs stored with the verification.
terminal	object → terminal	Required for terminal verifications. Must include `terminalId`.

📳

paymentMethod

Nested as paymentMethod in the charge or verification body. The type field determines which sub-object is required.

Parameter	Type / Constraint	Example	Description
type *	string · enum	`CARD`	Payment method type. Values: `CARD` \| `TERMINAL` \| `PAYMENT_TOKEN` \| `CASH`.
card	object → card		Required when `type` is `CARD`.
terminal	object → terminal		Required when `type` is `TERMINAL`.
paymentToken	object → paymentToken		Required when `type` is `PAYMENT_TOKEN`.
cash	object → cash		Required when `type` is `CASH`.

💳

card

Nested as paymentMethod.card when paymentMethod.type is CARD. number is required unless a wallet paymentData is provided instead.

Parameter	Type / Constraint	Example	Description
number	string · max 19 chars	`4111111111111111`	The card number (PAN). Not required if wallet paymentData is provided.
cvv	string · max 4 chars	`123`	Card verification value (CVV/CVC). Optional but recommended for CNP transactions.
expiry	object → cardExpiry		Card expiry. Required when a card number is provided.
authentication	object → authentication		3DS or wallet authentication data. See `authentication` section.
trackData	object → trackData		Magnetic stripe track data for card-present swipe transactions.

📅

cardExpiry

Nested as paymentMethod.card.expiry. Both fields are required when a card number is provided.

Parameter	Type / Constraint	Example	Description
month *	string · 2 chars	`05`	Two-digit expiry month. Zero-padded. Example: May = 05.
year *	string · 4 chars	`2039`	Four-digit expiry year. Example: 2039.

🔐

authentication / wallet / threeDomainSecure

Nested as paymentMethod.card.authentication. Used for Apple Pay, Google Pay, and 3DS flows. Include either a wallet sub-object or a threeDomainSecure sub-object — not both.

authentication object

Parameter	Type / Constraint	Example	Description
wallet	object → wallet		Wallet authentication data. Use for `APPLE_PAY` or `GOOGLE_PAY`.
threeDomainSecure	object → threeDomainSecure		3DS authentication data. Use when 3DS is handled externally (not via SHC).

wallet object

Parameter	Type / Constraint	Example	Description
type *	string · enum	`APPLE_PAY`	Wallet type. Values: `APPLE_PAY` \| `GOOGLE_PAY`.
paymentData	string (JSON)		The full encrypted wallet token as a JSON string. Pass as-is — PayFacto decrypts. Use this OR the decrypted fields below.
cryptogram	string · hex-encoded	`C50041...`	Decrypted cryptogram converted to HEX. Required when your server decrypts the wallet token (Method A).
eciIndicator	string	`05`	ECI indicator from the decrypted wallet payload. Required with cryptogram.

threeDomainSecure object — all four fields required

Parameter	Type / Constraint	Example	Description
authenticationValue *	string	`AJkBBklm...`	The 3DS authentication value (CAVV/AAV) returned by the 3DS provider.
directoryServerTransactionId *	string (UUID)	`f38e6948-...`	The directory server transaction ID from the 3DS authentication response.
eciIndicator *	string	`05`	Electronic Commerce Indicator. 05 = fully authenticated, 06 = attempted, 07 = not authenticated.
version *	string	`2.1.0`	3DS protocol version used during authentication.

📳

terminal

Nested as paymentMethod.terminal when paymentMethod.type is TERMINAL. Also used as a sub-object in capture, increment, voidCapture, voidRefund, and release bodies for terminal flows.

Parameter	Type / Constraint	Example	Description
terminalId *	string (UUID)	`3a2049fb-...`	Unique terminal identifier. Required. Provided by PayFacto during terminal deployment.
clerkId	string · max 8 chars	`001`	Clerk or cashier identifier. Optional.
tip	integer (int64)	`100`	Tip amount in cents. Optional.
cashback	integer (int64)	`2000`	Cashback amount in cents. Optional.
accountType	string	`CHEQUING`	Cardholder account type. Optional.
cardBrand	string
cardType	string
configureTerminal	boolean		When set to true, the terminal settings have changed and it must re-download its configuration.
cvv	string
emvRawRequest	string
emvRawResponse	string
entryMode	string
lastFour	string
maskedPan	string
storedCredential	string
surcharge	integer
trackData	string

🔄

paymentToken / storedCredential

Nested as paymentMethod.paymentToken when paymentMethod.type is PAYMENT_TOKEN. Used for SHC-generated tokens and stored credentials.

paymentToken object

Parameter	Type / Constraint	Example	Description
storedCredential *	object → storedCredential		Stored credential details. Required.

storedCredential object

Parameter	Type / Constraint	Example	Description
type *	string · enum	`CIT_INITIAL`	Credential type. Values: `CIT_INITIAL` (first cardholder-initiated use) \| `CIT_SUBSEQUENT` (repeat cardholder use) \| `MIT_SCHEDULED` (merchant-initiated, scheduled) \| `MIT_UNSCHEDULED` (merchant-initiated, unscheduled).
tokenId *	string	`5k46v51j...`	The payment token. For SHC tokens, this is the value from the SHC callback's response.token field.
id	string		Optional transaction reference ID associated with the stored credential.

💵

cash

Nested as paymentMethod.cash when paymentMethod.type is CASH.

Parameter	Type / Constraint	Example	Description
terminalId *	string (UUID)	`3a2049fb-...`	Terminal identifier. Required.
tip	integer (int64)	`100`	Tip amount in cents. Optional.
clerkId	string · max 8 chars	`001`	Clerk identifier. Optional.

🏠

billingDetail / shippingDetail / address

Optional objects nested in the charge or verification body. Used for AVS, receipts, and customer records. All sub-fields are optional unless noted.

billingDetail object

Parameter	Type / Constraint	Example	Description
firstName	string	`John`	Cardholder first name.
lastName	string	`Smith`	Cardholder last name.
email	string	`john@example.com`	Cardholder email address.
phone	string	`5551234567`	Cardholder phone number.
address	object → address		Billing address. See address object below.

shippingDetail object

Parameter	Type / Constraint	Example	Description
firstName	string	`John`	Recipient first name.
lastName	string	`Smith`	Recipient last name.
email	string	`john@example.com`	Recipient email address.
phone	string	`5551234567`	Recipient phone number.
trackingNumber	string	`1Z999AA1...`	Shipping carrier tracking number.
address	object → address		Shipping address. See address object below.

address object

Parameter	Type / Constraint	Example	Description
line1	string	`56 Sparks St`	Street address line 1.
line2	string	`Suite 100`	Street address line 2. Optional.
city	string	`Ottawa`	City name.
state	string	`Ontario`	Province or state name.
postalCode	string	`K5A 1S4`	Postal or ZIP code.
country	string · 2-char ISO 3166	`CA`	Country code. `CA` = Canada, `US` = United States.

⚙️

Operation Bodies

Request bodies for charge and refund management operations on existing transactions.

capture — POST /charges/{chargeId}/captures

Parameter	Type / Constraint	Example	Description
amount *	integer (int64)	`1299`	Amount to capture in cents. Must be less than or equal to the authorized amount.
statementDescriptor	string · max 23 chars		Override statement descriptor for this capture.
terminal	object → terminal		Required for terminal captures. Must include `terminalId`.

increment — POST /charges/{chargeId}/increments

Parameter	Type / Constraint	Example	Description
amount *	integer (int64)	`1599`	New total authorized amount in cents. Must be greater than the current authorized amount.
terminal	object → terminal		Required for terminal increments. Must include `terminalId`.

voidCapture — POST /charges/{chargeId}/voids

Parameter	Type / Constraint	Example	Description
reason *	string · enum	`REQUESTED_BY_CUSTOMER`	Void reason. Values: `REQUESTED_BY_CUSTOMER` \| `REQUESTED_BY_MERCHANT` \| `DUPLICATE` \| `FRAUDULENT` \| `ERROR_CORRECTION`.
terminal	object → terminal		Required for terminal voids. Must include `terminalId`.

voidRefund — POST /refunds/{refundId}/voids

Parameter	Type / Constraint	Example	Description
reason *	string · enum	`REQUESTED_BY_CUSTOMER`	Void reason. Values: `REQUESTED_BY_CUSTOMER` \| `REQUESTED_BY_MERCHANT` \| `DUPLICATE` \| `FRAUDULENT` \| `ERROR_CORRECTION`.
terminal	object → terminal		Required for terminal flows. Must include `terminalId`.

release — POST /charges/{chargeId}/releases

Parameter	Type / Constraint	Example	Description
reason *	string · enum	`REQUESTED_BY_CUSTOMER`	Release reason. Values: `REQUESTED_BY_CUSTOMER` \| `REQUESTED_BY_MERCHANT` \| `EXPIRED_UNCAPTURED_CHARGE` \| `PARTIAL_APPROVAL` \| `ERROR_CORRECTION` \| `TIMEOUT`.
terminal	object → terminal		Required for terminal releases. Must include `terminalId`.