PayFacto API - v2.0 - Response Parameters

Complete reference for all response fields returned by the PayFacto Payment API v2.0. Fields are organised by object. Fields marked with † are always present in the response. All others are conditional.

ℹ️

All responses are JSON with Content-Type: application/json. Monetary amounts are returned as positive integers in cents — $12.99 is returned as 1299. Unique identifiers are UUIDs. Timestamps use ISO 8601 format.

Contents

💳 Charge Response ↩ Refund Response 🔒 Verification Response 📳 paymentMethod (response) 💳 card (response) 🔍 avsResult / cvvResult 🔐 authentication / wallet / 3DS (response) 📳 terminal (response) 🏠 billingDetail / shippingDetail / address (response) ⚙️ Operation Responses (capture / increment / void / release) ❌ Error Response

💳

Charge Response

Returned by POST /charges, GET /charges/{{chargeId}}, and GET /charges. Represents a payment transaction object.

Field	Type	Example	Description
id †	string (UUID)	`a1822999-…`	Unique charge identifier. Use for all subsequent operations (capture, void, refund, increment, release).
status †	string · enum	`CAPTURED`	Current charge status. Values: `AUTHORIZED` \| `CAPTURED` \| `VOIDED` \| `RELEASED` \| `DECLINED` \| `FAILED`.
amount †	integer (int64)	`1299`	Original requested charge amount in cents.
capturedAmount	integer (int64)	`1299`	Total amount captured in cents. May differ from `amount` if a partial capture was performed.
refundedAmount	integer (int64)	`0`	Total amount refunded in cents across all refunds on this charge.
currency †	string · ISO 4217	`CAD`	Three-letter currency code for the transaction.
invoiceNumber †	string	`INV-001`	Merchant invoice reference number, as submitted in the request.
capture †	boolean	`true`	Whether the charge was set to capture immediately.
statementDescriptor	string		Descriptor shown on the cardholder statement.
authorizationCode	string	`A12345`	Issuer authorization code. Present on approved transactions.
responseCode	string	`00`	`00` = approved. ISO 8583 response code from the issuer.
responseMessage	string	`APPROVED`	Human-readable issuer response message.
paymentMethod †	object → paymentMethod		Payment method details. See `paymentMethod` section below.
billingDetail	object → billingDetail		Customer billing information as submitted.
shippingDetail	object → shippingDetail		Shipping recipient details as submitted.
metadata	object		Key-value pairs stored with the charge, as submitted.
refunds	array → Refund		Array of refund objects. Empty array if no refunds have been issued.
createdAt †	string (ISO 8601)	`2026-06-08T14:32:00Z`	Timestamp when the charge was created.
updatedAt †	string (ISO 8601)	`2026-06-08T14:32:05Z`	Timestamp of the most recent update to the charge.
capturedAt	string (ISO 8601)		Timestamp when the charge was captured. Absent if not yet captured.

↩

Refund Response

Returned by POST /refunds and GET /refunds/{{refundId}}. Represents a refund transaction object.

Field	Type	Example	Description
id †	string (UUID)	`b2933108-…`	Unique refund identifier.
status †	string · enum	`SUCCEEDED`	Refund status. Values: `PENDING` \| `SUCCEEDED` \| `FAILED` \| `VOIDED`.
chargeId †	string (UUID)	`a1822999-…`	ID of the charge this refund was issued against.
amount †	integer (int64)	`1299`	Refunded amount in cents.
currency †	string · ISO 4217	`CAD`	Three-letter currency code.
reason †	string · enum	`REQUESTED_BY_CUSTOMER`	Refund reason. Values: `DUPLICATE` \| `FRAUDULENT` \| `REQUESTED_BY_CUSTOMER` \| `REQUESTED_BY_MERCHANT`.
responseCode	string	`00`	ISO 8583 response code from the issuer.
responseMessage	string	`APPROVED`	Human-readable issuer response message.
paymentMethod	object → paymentMethod		Payment method used for the refund. Present for some terminal refund flows.
metadata	object		Key-value pairs stored with the refund.
createdAt †	string (ISO 8601)	`2026-06-08T15:00:00Z`	Timestamp when the refund was created.
updatedAt †	string (ISO 8601)		Timestamp of the most recent update.

🔒

Verification Response

Returned by POST /verifications. No funds are collected — reflects card validation results only.

Field	Type	Example	Description
id †	string (UUID)	`c3044217-…`	Unique verification identifier.
status †	string · enum	`SUCCEEDED`	Verification outcome. Values: `SUCCEEDED` \| `FAILED`.
responseCode	string	`00`	ISO 8583 response code from the issuer.
responseMessage	string	`APPROVED`	Human-readable issuer response message.
card †	object → card		Masked card details and AVS/CVV results. See `card` section below.
billingDetail	object → billingDetail		Billing address as submitted.
metadata	object		Key-value pairs stored with the verification.
createdAt †	string (ISO 8601)	`2026-06-08T14:30:00Z`	Timestamp when the verification was created.

📳

paymentMethod (response)

Nested as paymentMethod in charge and refund responses. The type field determines which sub-object is populated.

Field	Type	Example	Description
type †	string · enum	`CARD`	Payment method type. Values: `CARD` \| `TERMINAL` \| `PAYMENT_TOKEN` \| `CASH`.
card	object → card		Present when `type` is `CARD` or `TERMINAL`. Contains masked card details.
terminal	object → terminal		Present when `type` is `TERMINAL`. Contains terminal response details.
paymentToken	object → paymentToken		Present when `type` is `PAYMENT_TOKEN`.

💳

card (response)

Nested as paymentMethod.card in responses. The full PAN is never returned — only masked and derived fields.

Field	Type	Example	Description
brand †	string · enum	`VISA`	Card network. Values: `VISA` \| `MASTERCARD` \| `AMEX` \| `DISCOVER` \| `INTERAC` \| `UNIONPAY` \| `UNKNOWN`.
lastFour †	string · 4 chars	`1111`	Last four digits of the card number.
maskedPan	string	`411111******1111`	Masked card number. All digits except the first six and last four are replaced with asterisks.
bin	string · 6 chars	`411111`	Bank Identification Number (first 6 digits).
cardType	string · enum	`CREDIT`	Card funding type. Values: `CREDIT` \| `DEBIT` \| `PREPAID` \| `UNKNOWN`.
issuerCountry	string · ISO 3166	`CA`	Two-letter country code of the card-issuing bank.
expiry	object → cardExpiry		Card expiry month and year as submitted. Present when a card number was provided.
avsResult	object → avsResult		Address Verification System result. See `avsResult` section below.
cvvResult	object → cvvResult		CVV/CVC verification result. See `cvvResult` section below.
authentication	object → authentication		3DS or wallet authentication response data. See `authentication` section below.
token	string	`5k46v51j…`	SHC-generated payment token. Can be used in subsequent `PAYMENT_TOKEN` charges.

🔍

avsResult / cvvResult

Nested within card in charge and verification responses. Reflect the issuer's address and CVV check outcomes.

avsResult object

Field	Type	Example	Description
code †	string	`Y`	Raw AVS response code from the issuer (e.g. `Y`, `P`, `N`, `U`).
streetMatch †	string · enum	`MATCH`	Street number match. Values: `MATCH` \| `NO_MATCH` \| `NOT_CHECKED` \| `UNAVAILABLE`.
postalMatch †	string · enum	`MATCH`	Postal/ZIP code match. Values: `MATCH` \| `NO_MATCH` \| `NOT_CHECKED` \| `UNAVAILABLE`.

cvvResult object

Field	Type	Example	Description
code †	string	`M`	Raw CVV response code returned by the issuer.
result †	string · enum	`MATCH`	CVV verification outcome. Values: `MATCH` \| `NO_MATCH` \| `NOT_PROCESSED` \| `NOT_PROVIDED` \| `UNAVAILABLE`.

🔐

authentication / wallet / threeDomainSecure (response)

Nested as paymentMethod.card.authentication in responses. Present when Apple Pay, Google Pay, or 3DS was used.

authentication object

Field	Type	Example	Description
wallet	object → wallet		Present when Apple Pay or Google Pay was used.
threeDomainSecure	object → threeDomainSecure		Present when a 3DS flow was used.

wallet object

Field	Type	Example	Description
type †	string · enum	`APPLE_PAY`	Wallet type. Values: `APPLE_PAY` \| `GOOGLE_PAY`.
eciIndicator	string	`05`	Electronic Commerce Indicator returned by the wallet provider or echoed from the request.

threeDomainSecure object

Field	Type	Example	Description
authenticationValue	string	`AJkBBklm…`	3DS authentication value (CAVV/AAV) echoed from the request.
directoryServerTransactionId	string (UUID)	`f38e6948-…`	Directory server transaction ID echoed from the request.
eciIndicator	string	`05`	ECI indicator. `05` = fully authenticated, `06` = attempted, `07` = not authenticated.
version	string	`2.1.0`	3DS protocol version echoed from the request.
status	string · enum	`AUTHENTICATED`	3DS authentication outcome. Values: `AUTHENTICATED` \| `ATTEMPTED` \| `NOT_AUTHENTICATED`.

📳

terminal (response)

Nested as paymentMethod.terminal when paymentMethod.type is TERMINAL.

Field	Type	Example	Description
terminalId †	string (UUID)	`3a2049fb-…`	Unique terminal identifier echoed from the request.
clerkId	string · max 8 chars	`001`	Clerk or cashier identifier echoed from the request.
tip	integer (int64)	`100`	Tip amount in cents as entered by the cardholder on the terminal.
cashback	integer (int64)	`2000`	Cashback amount in cents as entered by the cardholder on the terminal.
surcharge	integer (int64)		Surcharge amount in cents applied by the terminal.
accountType	string	`CHEQUING`	Account type selected by the cardholder.
entryMode	string · enum	`CHIP`	Card entry method. Values: `CHIP` \| `CONTACTLESS` \| `SWIPE` \| `KEYED` \| `FALLBACK`.
cardBrand	string		Card brand as reported by the terminal.
cardType	string		Card funding type as reported by the terminal.
lastFour	string		Last four digits of the card as reported by the terminal.
maskedPan	string		Masked card number as reported by the terminal.
emvRawResponse	string		Raw EMV response data returned by the terminal chip. Provided for advanced reconciliation.

🏠

billingDetail / shippingDetail / address (response)

Optional objects nested in charge and verification responses. All fields are echoed from the request.

billingDetail object

Field	Type	Example	Description
firstName	string	`John`	Cardholder first name as submitted.
lastName	string	`Smith`	Cardholder last name as submitted.
email	string	`john@example.com`	Cardholder email as submitted.
phone	string	`5551234567`	Cardholder phone as submitted.
address	object → address		Billing address. See address object below.

shippingDetail object

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

address object

Field	Type	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 · ISO 3166	`CA`	Country code. `CA` = Canada, `US` = United States.

⚙️

Operation Responses

Response bodies returned by charge and refund management operations on existing transactions.

capture — POST /charges/{chargeId}/captures

Field	Type	Example	Description
id †	string (UUID)	`d4155326-…`	Unique capture operation identifier.
chargeId †	string (UUID)	`a1822999-…`	ID of the charge that was captured.
amount †	integer (int64)	`1299`	Amount captured in cents.
status †	string · enum	`SUCCEEDED`	Capture result. Values: `SUCCEEDED` \| `FAILED`.
statementDescriptor	string		Statement descriptor used for this capture, if overridden.
createdAt †	string (ISO 8601)		Timestamp when the capture was processed.

increment — POST /charges/{chargeId}/increments

Field	Type	Example	Description
id †	string (UUID)	`e5266437-…`	Unique increment operation identifier.
chargeId †	string (UUID)	`a1822999-…`	ID of the charge that was incremented.
previousAmount †	integer (int64)	`1299`	Authorized amount before the increment, in cents.
newAmount †	integer (int64)	`1599`	New total authorized amount after the increment, in cents.
status †	string · enum	`SUCCEEDED`	Increment result. Values: `SUCCEEDED` \| `FAILED`.
createdAt †	string (ISO 8601)		Timestamp when the increment was processed.

voidCapture — POST /charges/{chargeId}/voids

Field	Type	Example	Description
id †	string (UUID)	`f6377548-…`	Unique void operation identifier.
chargeId †	string (UUID)	`a1822999-…`	ID of the charge that was voided.
reason †	string · enum	`REQUESTED_BY_CUSTOMER`	Void reason as submitted.
status †	string · enum	`SUCCEEDED`	Void result. Values: `SUCCEEDED` \| `FAILED`.
createdAt †	string (ISO 8601)		Timestamp when the void was processed.

voidRefund — POST /refunds/{refundId}/voids

Field	Type	Example	Description
id †	string (UUID)	`g7488659-…`	Unique refund void operation identifier.
refundId †	string (UUID)	`b2933108-…`	ID of the refund that was voided.
reason †	string · enum	`ERROR_CORRECTION`	Void reason as submitted.
status †	string · enum	`SUCCEEDED`	Void result. Values: `SUCCEEDED` \| `FAILED`.
createdAt †	string (ISO 8601)		Timestamp when the refund void was processed.

release — POST /charges/{chargeId}/releases

Field	Type	Example	Description
id †	string (UUID)	`h8599760-…`	Unique release operation identifier.
chargeId †	string (UUID)	`a1822999-…`	ID of the charge whose hold was released.
reason †	string · enum	`EXPIRED_UNCAPTURED_CHARGE`	Release reason as submitted.
status †	string · enum	`SUCCEEDED`	Release result. Values: `SUCCEEDED` \| `FAILED`.
createdAt †	string (ISO 8601)		Timestamp when the release was processed.

❌

Error Response

Returned on all non-2xx HTTP responses. The error envelope is consistent across all endpoints.

Field	Type	Example	Description
type †	string · enum	`VALIDATION_ERROR`	Error category. Values: `VALIDATION_ERROR` \| `AUTHENTICATION_ERROR` \| `AUTHORIZATION_ERROR` \| `NOT_FOUND` \| `PROCESSING_ERROR` \| `RATE_LIMIT_ERROR` \| `API_ERROR`.
code †	string	`INVALID_AMOUNT`	Machine-readable error code identifying the specific problem. Stable across API versions.
message †	string	`Amount must be a positive integer.`	Human-readable description of the error. Subject to change — do not parse programmatically.
param	string	`amount`	The request parameter that caused the error. Present for `VALIDATION_ERROR` types.
errors	array		Array of validation error objects when multiple fields fail. Each contains `code`, `message`, and `param`.
requestId †	string (UUID)	`req_9a1b2c3d-…`	Unique identifier for the failed request. Include in any support communication to PayFacto.