Skip to Content
Doura Developer Docs Markdown llms.txt API 2026.08.03

Transaction Events

Real-time notifications for completed transaction events: sale.completed, auth.completed, capture.completed, refund.completed and void.completed.

Each event type is separate, so an endpoint subscribes only to the events it wants. Each event is delivered as a POST request whose body is a JSON payload describing the event.

Delivery, retries, endpoint configuration and signature verification are covered in the webhooks documentation - every delivery must have its signature verified before it is trusted. Legacy webhooks, the delivery method every merchant has today, are verified with the x-fsk-wh-chksm checksum (Verifying the checksum). Svix webhooks, which are invite only, are verified with the svix-* headers (Verifying signatures).

Sale completed

POSTSaleCompleted to your webhook endpoint

This webhook event is triggered when a financial transaction is processed and completed, whether it was approved or not. Read transactionResponses[].responseCode for the outcome.

When the ACH processor resubmits a sale, the resubmission is a new Sale transaction with its own trx_ ID and its own sale.completed event, which can arrive days after the first. Its originalTransactionId is the first sale's ID and its referenceId ends in -resubmission.

Parameters

NameInTypeDescription
x-fsk-wh-chksmheaderstring

Present on legacy deliveries, the delivery method every merchant has today. A lowercase hex-encoded HMAC-SHA256 of the raw request body, keyed with the shared secret provided by support for this endpoint. Carries no timestamp, so deduplicate on the payload's event.id to defend against replay. See Verifying the checksum.

Svix deliveries carry the svix-* headers instead. Svix webhooks are invite only; see Webhooks.

svix-idheaderstring

Present on Svix deliveries only. The unique message id for this delivery, constant across retries of the same message.

Svix webhooks are invite only. Most merchants receive legacy deliveries, which carry x-fsk-wh-chksm instead of the svix-* headers; see Webhooks.

svix-timestampheaderstring

Present on Svix deliveries only. The time the message was sent, as a Unix timestamp in seconds. Reject stale timestamps to protect against replay attacks. See Verifying signatures.

svix-signatureheaderstring

Present on Svix deliveries only. One or more space-delimited signatures in the form v1,<base64 signature> - an HMAC-SHA256 over {svix-id}.{svix-timestamp}.{raw request body} keyed with the endpoint's signing secret. See Verifying signatures.

Payload

The request body for the sale.completed webhook event.

application/json · SaleCompletedWebhook

event object required

Webhook event details.

Child attributes
id string required

Unique ID for this webhook event.

Example: "evt_01JS21X856RR8R69GV5F17XK9C"

type string required

The type of event that occurred.

Example: "event.completed"

timestamp string (date-time) required

The time when the event was triggered (UTC).

Example: "2025-04-16T14:30:00Z"

merchantId string required

The merchant that owns the transaction or token.

Example: "mer_01JQZC2Y6W3F8XKT5H9DPNBMVR"

originalResponse TransactionResponseObject required

Represents the response to a sale or authorization transaction.

Child attributes
id string

Unique ID for this transaction.

Example: "trx_01J2F0EKHC7HY2R93C8ENBD1FG"

timestamp string (date-time)

Transaction timestamp in UTC

Example: "2025-05-27T18:49:31Z"

type string

Type of transaction.

Chargeback records an ACH payment that the payer's bank returned after the funds reached the merchant. It is a separate transaction: the original sale is not changed and stays approved. originalTransactionId holds the sale's ID, and the amount is the returned amount. Its approved outcome (resultCode 0, responseCode 1) means the chargeback took effect and the money went back to the payer. See Chargebacks.

Treat this list as open: ignore a value your integration does not recognize instead of rejecting the transaction.

Allowed: Sale, Auth, Capture, Refund, Void, Chargeback

Example: "Sale"

status TransactionStatus

The processing lifecycle, separate from approval or decline. Pending waits for customer input; Submitted, Acknowledged, and Processing are in flight; AwaitingSettlement waits for a bank transfer outcome. Completed can be approved or declined: inspect resultCode and transactionResponses[].responseCode. Failed means processing stopped because of a technical issue. Abandoned means the customer did not complete the flow before submission. Both states close the request.

Allowed: Unknown, Created, Pending, Submitted, Acknowledged, Processing, AwaitingSettlement, Completed, Failed, Abandoned

Example: "Completed"

accountHolder object

Account holder information associated with the transaction

Child attributes
id string required

Account holder ID assigned by the API.

Example: "aho_01JRZPRGFF4J2SZC3HMDBYEN2J"

externalId string required

External account holder ID assigned by your application.

Example: "usr_1234567890123"

contact object

Contact information for the account holder. Only returned for Card Not Present transactions.

Child attributes
name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "60606"

address string

Example: "300 S Wacker Dr"

state string

Example: "IL"

city string

Example: "Chicago"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

paymentMethod object

The payment method used for this transaction.

Child attributes
id string required

The unique identifier of the payment method. This ID has a prefix that makes it human-readable (pmt_trm_ for physical terminals, pmt_vrt_ for virtual card terminals, pmt_ach_ for virtual ACH terminals, pmt_tkn_ for tokens, which store a card or an ACH bank account), but applications should always use the type field to determine the payment method type rather than parsing this ID.

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

The date and time (UTC) when this payment method token was removed from the system using the Remove Token endpoint. This parameter will only be returned if the token was removed/deleted from the system.

This field will be present in three scenarios:

  • As part of a successful Remove Token endpoint response
  • In token.removed webhook notifications
  • In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

  • Physical - A physical payment terminal for Card Present transactions
  • Virtual - A hosted payment form/iframe for Card Not Present transactions
  • VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
  • Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
  • VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
  • Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

Child attributes
name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "12345"

address string

Example: "123 Main St"

state string

Example: "NY"

city string

Example: "Anytown"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

cardType string

The type of card used for this transaction:

  • UNKNOWN - The card type is unknown
  • DEBIT - Debit Card
  • VISA - Visa Credit Card
  • MASTERCARD - MasterCard Credit Card
  • AMEX - American Express Credit Card
  • DINERS - Diners Club Credit Card
  • DISCOVER - Discover Credit Card
  • JCB - JCB Credit Card
  • UNIONPAY - UnionPay Credit Card
  • MAESTRO - Maestro Debit Card
  • GIFT - Gift Card
  • CASH - All-cash Transaction
  • EBT - Electronic Benefits Transfer Card
  • INTERAC - Interac (Canadian PIN-debit network), Card Present only
  • OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

  • For card tokens: Credit or Debit.
  • For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

invoiceNumber InvoiceNumber

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.

max length 100

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

referenceId ReferenceIdForResponse

The reference ID for this transaction. This will either be the reference ID provided in the transaction request or, if no value was provided, a value generated automatically by the system. This reference ID can be used for processing captures and referenced refunds by including it in the originalReferenceId field of subsequent transactions.

max length 100

Example: "ref_s192i49i"

originalTransactionId string

The trx_ ID of the earlier transaction this one belongs to, when the link has been verified. Set on card-present captures and voids, card-present Interac refunds, ACH refunds once the gateway confirms the original sale, ACH chargebacks (the charged-back sale), and ACH resubmissions (the original sale).

Absent when there is no verified link. That includes card-not-present captures, refunds, and voids, other card-present refunds, and older transactions recorded before the link was stored. Do not treat an absent value as proof that the transaction has no original.

Example: "trx_01JWBPE27KHY2K4J7A13ATQ786"

resultCode ResultCode

Result codes:

  • 0 - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)
  • 1003 - The payment terminal is busy or unavailable. (If this error persists, the user may need to close and re-open the Payment Application on the terminal or restart the terminal)
  • 1005 - The specified terminal could not be found.
  • 1010 - The transaction request is pending to become transaction.
  • 2014 - The payment method or card brand is not enabled for the merchant. resultText carries the message, such as ACH payments are not enabled for this merchant. or Visa cards are not enabled for this merchant. The transaction is Completed and failed; do not retry it with the same payment method.
  • 3000 - An unexpected error occurred. Please try again.
  • 3002 - The transaction could not be completed because the payment terminal could not find the related transaction.
  • 3005 - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.
  • 3006 - The transaction could not be completed because the payment terminal is low on battery.
  • 3009 - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.
  • 3010 - The transaction took too long and was cancelled by the application.
  • 3011 - Invalid transaction request. Please consult the documentation for valid transaction requests.
  • 3012 - Invalid transaction request. paymentMethodId is invalid.
  • 3013 - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.
  • 3014 - Invalid amount. Please try your transaction again with an amount greater than $0.
  • 3020 - An unsupported transaction result was received.
  • 4001 - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.
  • 6800 - 3D Secure authentication was rejected by the issuer's ACS (card auth failed, security failure, stolen card, suspected fraud, etc.). Surfaced on declined CNP transactions when formConfig.enable3DSecure: true and the gateway reports a 3D Secure reason; other failures in a 3D Secure session use 6900-6902. See SDK Error Codes for guidance.
  • 6801 - 3D Secure authentication could not be completed because of an upstream technical issue (ACS timeout, directory server unreachable). Retry later or, if merchant policy allows, retry with 3DS disabled.
  • 6802 - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.
  • 6900 - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText. See SDK Error Codes for guidance.
  • 6901 - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision. See SDK Error Codes for guidance.
  • 6902 - The gateway reported no failure but returned no payment token. See SDK Error Codes for guidance.
  • 9998 - The system is not ready to process a transaction.
  • 9999 - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.
  • 1010 - The transaction request is pending customer interaction.
  • 4100 - Cardholder verification is required. Follow threeDsChallenge.redirectUrl and reconcile the final transaction outcome before retrying.
  • 55 - The customer cancelled the hosted payment attempt.

Allowed: 0, 55, 1003, 1005, 1010, 2014, 3000, 3002, 3005, 3006, 3009, 3010, 3011, 3012, 3013, 3014, 3020, 4001, 4100, 6800, 6801, 6802, 6900, 6901, 6902, 9998, 9999

Example: 0

resultText ResultText

A message describing the result code in more detail. On a stored transaction it is uppercase, such as APPROVED, DECLINED, or the gateway's reason, except for resultCode 2014, where it is the message in sentence case. Use it for display, not for branching.

Example: "APPROVED"

requestedAmount integer

The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization.

Example: 1000

approvedAmount integer

The approved amount in minor units. This is 0 for a decline or an outcome that is still in flight. A terminal may adjust the amount, for example by adding a tip.

Example: 1000

balanceAmount integer

The balance that remains to be paid on the transaction. This amount is always an integer in the smallest denomination of the currency (e.g. cents for USD or CAD).

Example: 0

refundableAmount integer

The amount that can still be refunded against this sale or capture, in the smallest denomination of the currency. Normally available within seconds of approval. Absent for authorizations, refunds, voids, and declined transactions; it can also be absent briefly after a sale or capture is approved. Absence does not mean unlimited; it means this value is not yet available or not applicable. An ACH chargeback reduces it like a refund. 0 means fully refunded, voided, or charged back.

Example: 1000

transactionResponses array of object

Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.

Child attributes
responseCode ResponseCode

The outcome of the payment, and the field that tells you whether the transaction succeeded. The HTTP status, resultCode, and status do not. A transaction succeeded only when status is Completed and a transaction response has responseCode 1 or 2.

Outcomes:

  • Approved - 1, 2. For 2, only amountApproved was approved. On a Chargeback transaction, approved means the chargeback took effect: the money went back to the payer.
  • Declined - 10 to 18. The issuer or bank refused the payment. Do not retry with the same payment details.
  • Canceled - 54, 55. No money moved.
  • Pending - 57. The outcome is not final. Wait for the webhook or query the transaction again.
  • Unknown - 0. No specific code was reported. While status is not Completed, the outcome is not final. On a Completed transaction it is not an approval: read resultCode and resultText for the reason, for example 2014, 6901, or 6902.
  • Error - every other code. Processing failed for a technical or request reason.

See Transaction response codes.

Response codes:

  • 0 - UNKNOWN
  • 1 - APPROVED - Transaction was approved
  • 2 - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.
  • 10 - DECLINED - Transaction was declined by the issuer or bank. For Card-Present, the transaction can also be declined offline by the terminal.
  • 11 - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.
  • 12 - CARD_EXPIRED - The card used for the transaction has expired.
  • 13 - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.
  • 14 - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).
  • 15 - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).
  • 16 - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).
  • 17 - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.
  • 18 - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.
  • 19 - BATCH_EMPTY - Indicates that the batch for processing is empty.
  • 20 - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).
  • 21 - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.
  • 50 - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.
  • 51 - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.
  • 52 - NOT_SUPPORTED - Rejected because the requested operation is not supported.
  • 53 - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.
  • 54 - CANCELLED - Cancelled by the user or merchant.
  • 55 - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.
  • 56 - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.
  • 57 - PENDING - The transaction is awaiting an asynchronous outcome.

Allowed: 0, 1, 2, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 50, 51, 52, 53, 54, 55, 56, 57

authCode string

The authorization code provided by the card issuer, confirming transaction approval.

Example: "123456"

amountApproved integer

The amount approved for this transaction response.

Example: 1000

approvedAmountBreakdown ApprovedAmountBreakdown

A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.

Child attributes
amountGoodsAndServices integer

The approved amount for goods and services.

Example: 900

tax integer

The approved tax amount.

Example: 100

cashback integer

The approved cashback amount.

Example: 0

tip integer

The approved tip amount.

Example: 0

paymentMethod object

The payment method used for this transaction.

Child attributes
id string required

The unique identifier of the payment method. This ID has a prefix that makes it human-readable (pmt_trm_ for physical terminals, pmt_vrt_ for virtual card terminals, pmt_ach_ for virtual ACH terminals, pmt_tkn_ for tokens, which store a card or an ACH bank account), but applications should always use the type field to determine the payment method type rather than parsing this ID.

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

The date and time (UTC) when this payment method token was removed from the system using the Remove Token endpoint. This parameter will only be returned if the token was removed/deleted from the system.

This field will be present in three scenarios:

  • As part of a successful Remove Token endpoint response
  • In token.removed webhook notifications
  • In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

  • Physical - A physical payment terminal for Card Present transactions
  • Virtual - A hosted payment form/iframe for Card Not Present transactions
  • VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
  • Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
  • VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
  • Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

cardType string

The type of card used for this transaction:

  • UNKNOWN - The card type is unknown
  • DEBIT - Debit Card
  • VISA - Visa Credit Card
  • MASTERCARD - MasterCard Credit Card
  • AMEX - American Express Credit Card
  • DINERS - Diners Club Credit Card
  • DISCOVER - Discover Credit Card
  • JCB - JCB Credit Card
  • UNIONPAY - UnionPay Credit Card
  • MAESTRO - Maestro Debit Card
  • GIFT - Gift Card
  • CASH - All-cash Transaction
  • EBT - Electronic Benefits Transfer Card
  • INTERAC - Interac (Canadian PIN-debit network), Card Present only
  • OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

  • For card tokens: Credit or Debit.
  • For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

cardType CardType

The type of card used for this transaction:

  • UNKNOWN - The card type is unknown
  • DEBIT - Debit Card
  • VISA - Visa Credit Card
  • MASTERCARD - MasterCard Credit Card
  • AMEX - American Express Credit Card
  • DINERS - Diners Club Credit Card
  • DISCOVER - Discover Credit Card
  • JCB - JCB Credit Card
  • UNIONPAY - UnionPay Credit Card
  • MAESTRO - Maestro Debit Card
  • GIFT - Gift Card
  • CASH - All-cash Transaction
  • EBT - Electronic Benefits Transfer Card
  • INTERAC - Interac (Canadian PIN-debit network), Card Present only
  • OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

avsResult AVSResult

The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.

  • A - Address matches, ZIP does not. The first five numerical characters contained in the address match those stored at the VIC or issuer's center. However, the ZIP code does not match.
  • E - Ineligible transaction.
  • N - Neither address nor ZIP matches. Neither the first five numerical characters contained in the address match with those stored at the VIC nor issuer's center nor the ZIP code match.
  • R - Retry (system unavailable or timed out).
  • S - Card type not supported. The card type for this transaction is not supported by AVS. AVS can verify addresses for Visa cards, MasterCard, proprietary cards, and private label transactions.
  • U - Address information unavailable.
  • G - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.
  • W - Nine-digit ZIP match, address does not. The nine-digit Postal ZIP code matches that stored at the VIC or card issuer's centre. However, the first five numerical characters contained in the address do not match.
  • X - Exact match (nine digit ZIP and address). Both the nine-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
  • Y - Address and five-digit ZIP match. Both the five-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
  • Z - Five-digit ZIP matches, address does not. The five-digit Postal ZIP code matches that stored at the VIC or card issuer's centre.

NOTE: Transactions can still be authorized if the AVS responses are no match or failure. AVS responses are for merchant information only, and usually do not influence the overall Authorization result. This can vary based on the Issuing Bank.

Allowed: A, E, N, R, S, U, G, W, X, Y, Z

cvvResult CVVResult

The CVV verification result. Typically returned on Card Not Present transactions.

  • M - CVV Match
  • N - CVV No Match
  • P - Not Processed
  • S - CVV should be on the card but the merchant indicates it is not.
  • U - User is unregistered

NOTE: Transactions can still be authorized if the CVV responses are no match or failure. CVV responses are for merchant information only, and usually do not influence the overall Authorization result. This can vary based on the Issuing Bank.

Allowed: M, N, P, S, U

accountType string

The funding-source classification associated with the payment method used in this transaction.

  • For credit/debit cards: Credit or Debit. May be null when the classification is unavailable, including on older transactions.
  • For ACH/EFT bank accounts: Checking or Savings.

The immediate hosted ACH response uses lowercase checking or savings. Retrieved transaction responses normally use Checking or Savings.

Allowed: Credit, Debit, Checking, Savings, checking, savings

Example: "Credit"

hostResponseText string

A meaningful text explaining the response code from the host.

Example: "APPROVED 00"

receipt Receipt

Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.

Child attributes
lines array of string required

The receipt lines.

sourceId string

Identifier of the session or other source that initiated the transaction. For an ACH chargeback, it is the chargeback's own trx_ ID, or the billing subscription ID when the charged-back sale was a subscription payment.

threeDs ThreeDsAuthentication

3D Secure (EMV 3DS2) authentication outcome. Populated on transactions initiated with formConfig.enable3DSecure: true. All fields (other than status) are optional - what the issuer returns depends on whether the transaction was frictionless, challenged, or declined.

Child attributes
status string

The authentication outcome to use in your integration. The other threeDs fields provide supporting authentication data.

Allowed: Authenticated, Attempted, NotAuthenticated, Failed, Unavailable, NotEnrolled

Example: "Authenticated"

cavv string

Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions.

Example: "AAABBkgwVoRhY2tcYlZGAAAAAAA="

eci string

E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:

  • 02 / 05 - Fully authenticated (liability shift to issuer).
  • 01 / 06 - Attempted authentication (partial liability shift).
  • 00 / 07 - Not authenticated (no liability shift).

Example: "05"

xid string

3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility.

Example: "MDAwMDAwMDAwMDAwMDAwMTM3MDI="

dsTransId string

Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction.

Example: "b71a7d5d-cc38-4ce9-80c3-50a7d53271f7"

threeDReasonId string

Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use status to handle the outcome and threeDReason for the explanation.

Example: "10"

threeDReason string

Human-readable description matching threeDReasonId.

Example: "Stolen Card"

threeDsChallenge ThreeDsChallenge

Present when a token payment requires a cardholder challenge (resultCode: 4100).

Child attributes
redirectUrl string (uri) required

Hosted URL where the cardholder completes the challenge.

followUpToken string required

Opaque token identifying the pending challenge.

Example
{
  "event": {
    "id": "evt_01JS21X856RR8R69GV5F17XK9C",
    "type": "sale.completed",
    "timestamp": "2025-05-27T18:49:31Z",
    "merchantId": "mer_01JQZC2Y6W3F8XKT5H9DPNBMVR"
  },
  "originalResponse": {
    "id": "trx_01J2F0EKHC7HY2R93C8ENBD1FG",
    "timestamp": "2025-05-27T18:49:31Z",
    "type": "Sale",
    "status": "Completed",
    "accountHolder": {
      "id": "aho_01JRZPRGFF4J2SZC3HMDBYEN2J",
      "externalId": "usr_1234567890123",
      "contact": {
        "name": "John Doe",
        "countryCode": "US",
        "zipCode": "60606",
        "address": "300 S Wacker Dr",
        "state": "IL",
        "city": "Chicago"
      }
    },
    "paymentMethod": {
      "id": "pmt_trm_01JRZPTMTBN41PC3VPQNZ5T3HF",
      "type": "Physical",
      "currency": "USD",
      "description": "Main Store Terminal"
    },
    "invoiceNumber": "inv_1234567890123456",
    "orderNumber": "order_number_1234",
    "referenceId": "ref_s192i49i",
    "resultCode": 0,
    "resultText": "APPROVED",
    "requestedAmount": 1000,
    "approvedAmount": 1000,
    "balanceAmount": 0,
    "transactionResponses": [
      {
        "responseCode": 1,
        "authCode": "123456",
        "amountApproved": 1000,
        "approvedAmountBreakdown": {
          "amountGoodsAndServices": 900,
          "tax": 100,
          "cashback": 0,
          "tip": 0
        },
        "paymentMethod": {
          "id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
          "type": "Token",
          "currency": "USD",
          "description": "Token for John Doe's Visa",
          "billingContact": {
            "name": "John Doe",
            "countryCode": "US",
            "zipCode": "12345",
            "address": "123 Main St",
            "state": "NY",
            "city": "Anytown"
          },
          "cardType": "VISA",
          "maskedCardNumber": "************0011",
          "cardExpDate": "1225"
        },
        "cardType": "VISA",
        "avsResult": "Y",
        "cvvResult": "M",
        "accountType": "Credit",
        "hostResponseText": "APPROVED 00",
        "receipt": {
          "lines": [
            "     Test Merchant      ",
            "      300 S Wacker      ",
            "         Loop,          ",
            "                        ",
            "                        ",
            "TERM #          11000367",
            "RECORD #         0656191",
            "HOST INVOICE #    000038",
            "HOST SEQ #    1720656191",
            "MERCH                   ",
            "INVOICE inv_123456789012",
            "        3456",
            "------------------------",
            "CARD    ************0011",
            "VISA             Contact",
            "07/10/2024      20:03:05",
            "------------------------",
            "Purchase      USD $10.00",
            "Tip           USD  $0.00",
            "Cashback      USD  $0.00",
            "                        ",
            "TOTAL         USD $10.00",
            "------------------------",
            "AUTH#:123456       B:171",
            "          Sale          ",
            "      APPROVED 00       ",
            "       THANK YOU        ",
            "                        ",
            "      Visa Credit       ",
            "AID:      A0000000031010",
            "TC:     43F4ACF64B07551A",
            "TVR:          8000008000",
            "TSI:                7800",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "     MERCHANT COPY      ",
            "     Test Merchant      ",
            "      300 S Wacker      ",
            "         Loop,          ",
            "                        ",
            "                        ",
            "TERM #          11000367",
            "RECORD #         0656191",
            "HOST INVOICE #    000038",
            "HOST SEQ #    1720656191",
            "MERCH                   ",
            "INVOICE inv_123456789012",
            "        3456",
            "------------------------",
            "CARD    ************0011",
            "VISA             Contact",
            "07/10/2024      20:03:05",
            "------------------------",
            "Purchase      USD $10.00",
            "Tip           USD  $0.00",
            "Cashback      USD  $0.00",
            "                        ",
            "TOTAL         USD $10.00",
            "------------------------",
            "AUTH#:123456       B:171",
            "          Sale          ",
            "      APPROVED 00       ",
            "       THANK YOU        ",
            "                        ",
            "      Visa Credit       ",
            "AID:      A0000000031010",
            "TC:     43F4ACF64B07551A",
            "TVR:          8000008000",
            "TSI:                7800",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "     CUSTOMER COPY      "
          ]
        }
      }
    ]
  }
}

Responses

200

Successful acknowledgement of a webhook event. The response should be a 200 OK status with an empty body.

application/json · object

SuccessfulWebhookResponse
{}

Auth completed

POSTAuthCompleted to your webhook endpoint

This webhook event is triggered when a transaction authorization is completed.

Parameters

NameInTypeDescription
x-fsk-wh-chksmheaderstring

Present on legacy deliveries, the delivery method every merchant has today. A lowercase hex-encoded HMAC-SHA256 of the raw request body, keyed with the shared secret provided by support for this endpoint. Carries no timestamp, so deduplicate on the payload's event.id to defend against replay. See Verifying the checksum.

Svix deliveries carry the svix-* headers instead. Svix webhooks are invite only; see Webhooks.

svix-idheaderstring

Present on Svix deliveries only. The unique message id for this delivery, constant across retries of the same message.

Svix webhooks are invite only. Most merchants receive legacy deliveries, which carry x-fsk-wh-chksm instead of the svix-* headers; see Webhooks.

svix-timestampheaderstring

Present on Svix deliveries only. The time the message was sent, as a Unix timestamp in seconds. Reject stale timestamps to protect against replay attacks. See Verifying signatures.

svix-signatureheaderstring

Present on Svix deliveries only. One or more space-delimited signatures in the form v1,<base64 signature> - an HMAC-SHA256 over {svix-id}.{svix-timestamp}.{raw request body} keyed with the endpoint's signing secret. See Verifying signatures.

Payload

The request body for the auth.completed webhook event.

application/json · AuthCompletedWebhook

event object required

Webhook event details.

Child attributes
id string required

Unique ID for this webhook event.

Example: "evt_01JS21X856RR8R69GV5F17XK9C"

type string required

The type of event that occurred.

Example: "event.completed"

timestamp string (date-time) required

The time when the event was triggered (UTC).

Example: "2025-04-16T14:30:00Z"

merchantId string required

The merchant that owns the transaction or token.

Example: "mer_01JQZC2Y6W3F8XKT5H9DPNBMVR"

originalResponse TransactionResponseObject required

Represents the response to a sale or authorization transaction.

Child attributes
id string

Unique ID for this transaction.

Example: "trx_01J2F0EKHC7HY2R93C8ENBD1FG"

timestamp string (date-time)

Transaction timestamp in UTC

Example: "2025-05-27T18:49:31Z"

type string

Type of transaction.

Chargeback records an ACH payment that the payer's bank returned after the funds reached the merchant. It is a separate transaction: the original sale is not changed and stays approved. originalTransactionId holds the sale's ID, and the amount is the returned amount. Its approved outcome (resultCode 0, responseCode 1) means the chargeback took effect and the money went back to the payer. See Chargebacks.

Treat this list as open: ignore a value your integration does not recognize instead of rejecting the transaction.

Allowed: Sale, Auth, Capture, Refund, Void, Chargeback

Example: "Sale"

status TransactionStatus

The processing lifecycle, separate from approval or decline. Pending waits for customer input; Submitted, Acknowledged, and Processing are in flight; AwaitingSettlement waits for a bank transfer outcome. Completed can be approved or declined: inspect resultCode and transactionResponses[].responseCode. Failed means processing stopped because of a technical issue. Abandoned means the customer did not complete the flow before submission. Both states close the request.

Allowed: Unknown, Created, Pending, Submitted, Acknowledged, Processing, AwaitingSettlement, Completed, Failed, Abandoned

Example: "Completed"

accountHolder object

Account holder information associated with the transaction

Child attributes
id string required

Account holder ID assigned by the API.

Example: "aho_01JRZPRGFF4J2SZC3HMDBYEN2J"

externalId string required

External account holder ID assigned by your application.

Example: "usr_1234567890123"

contact object

Contact information for the account holder. Only returned for Card Not Present transactions.

Child attributes
name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "60606"

address string

Example: "300 S Wacker Dr"

state string

Example: "IL"

city string

Example: "Chicago"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

paymentMethod object

The payment method used for this transaction.

Child attributes
id string required

The unique identifier of the payment method. This ID has a prefix that makes it human-readable (pmt_trm_ for physical terminals, pmt_vrt_ for virtual card terminals, pmt_ach_ for virtual ACH terminals, pmt_tkn_ for tokens, which store a card or an ACH bank account), but applications should always use the type field to determine the payment method type rather than parsing this ID.

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

The date and time (UTC) when this payment method token was removed from the system using the Remove Token endpoint. This parameter will only be returned if the token was removed/deleted from the system.

This field will be present in three scenarios:

  • As part of a successful Remove Token endpoint response
  • In token.removed webhook notifications
  • In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

  • Physical - A physical payment terminal for Card Present transactions
  • Virtual - A hosted payment form/iframe for Card Not Present transactions
  • VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
  • Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
  • VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
  • Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

Child attributes
name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "12345"

address string

Example: "123 Main St"

state string

Example: "NY"

city string

Example: "Anytown"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

cardType string

The type of card used for this transaction:

  • UNKNOWN - The card type is unknown
  • DEBIT - Debit Card
  • VISA - Visa Credit Card
  • MASTERCARD - MasterCard Credit Card
  • AMEX - American Express Credit Card
  • DINERS - Diners Club Credit Card
  • DISCOVER - Discover Credit Card
  • JCB - JCB Credit Card
  • UNIONPAY - UnionPay Credit Card
  • MAESTRO - Maestro Debit Card
  • GIFT - Gift Card
  • CASH - All-cash Transaction
  • EBT - Electronic Benefits Transfer Card
  • INTERAC - Interac (Canadian PIN-debit network), Card Present only
  • OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

  • For card tokens: Credit or Debit.
  • For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

invoiceNumber InvoiceNumber

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.

max length 100

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

referenceId ReferenceIdForResponse

The reference ID for this transaction. This will either be the reference ID provided in the transaction request or, if no value was provided, a value generated automatically by the system. This reference ID can be used for processing captures and referenced refunds by including it in the originalReferenceId field of subsequent transactions.

max length 100

Example: "ref_s192i49i"

originalTransactionId string

The trx_ ID of the earlier transaction this one belongs to, when the link has been verified. Set on card-present captures and voids, card-present Interac refunds, ACH refunds once the gateway confirms the original sale, ACH chargebacks (the charged-back sale), and ACH resubmissions (the original sale).

Absent when there is no verified link. That includes card-not-present captures, refunds, and voids, other card-present refunds, and older transactions recorded before the link was stored. Do not treat an absent value as proof that the transaction has no original.

Example: "trx_01JWBPE27KHY2K4J7A13ATQ786"

resultCode ResultCode

Result codes:

  • 0 - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)
  • 1003 - The payment terminal is busy or unavailable. (If this error persists, the user may need to close and re-open the Payment Application on the terminal or restart the terminal)
  • 1005 - The specified terminal could not be found.
  • 1010 - The transaction request is pending to become transaction.
  • 2014 - The payment method or card brand is not enabled for the merchant. resultText carries the message, such as ACH payments are not enabled for this merchant. or Visa cards are not enabled for this merchant. The transaction is Completed and failed; do not retry it with the same payment method.
  • 3000 - An unexpected error occurred. Please try again.
  • 3002 - The transaction could not be completed because the payment terminal could not find the related transaction.
  • 3005 - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.
  • 3006 - The transaction could not be completed because the payment terminal is low on battery.
  • 3009 - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.
  • 3010 - The transaction took too long and was cancelled by the application.
  • 3011 - Invalid transaction request. Please consult the documentation for valid transaction requests.
  • 3012 - Invalid transaction request. paymentMethodId is invalid.
  • 3013 - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.
  • 3014 - Invalid amount. Please try your transaction again with an amount greater than $0.
  • 3020 - An unsupported transaction result was received.
  • 4001 - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.
  • 6800 - 3D Secure authentication was rejected by the issuer's ACS (card auth failed, security failure, stolen card, suspected fraud, etc.). Surfaced on declined CNP transactions when formConfig.enable3DSecure: true and the gateway reports a 3D Secure reason; other failures in a 3D Secure session use 6900-6902. See SDK Error Codes for guidance.
  • 6801 - 3D Secure authentication could not be completed because of an upstream technical issue (ACS timeout, directory server unreachable). Retry later or, if merchant policy allows, retry with 3DS disabled.
  • 6802 - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.
  • 6900 - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText. See SDK Error Codes for guidance.
  • 6901 - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision. See SDK Error Codes for guidance.
  • 6902 - The gateway reported no failure but returned no payment token. See SDK Error Codes for guidance.
  • 9998 - The system is not ready to process a transaction.
  • 9999 - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.
  • 1010 - The transaction request is pending customer interaction.
  • 4100 - Cardholder verification is required. Follow threeDsChallenge.redirectUrl and reconcile the final transaction outcome before retrying.
  • 55 - The customer cancelled the hosted payment attempt.

Allowed: 0, 55, 1003, 1005, 1010, 2014, 3000, 3002, 3005, 3006, 3009, 3010, 3011, 3012, 3013, 3014, 3020, 4001, 4100, 6800, 6801, 6802, 6900, 6901, 6902, 9998, 9999

Example: 0

resultText ResultText

A message describing the result code in more detail. On a stored transaction it is uppercase, such as APPROVED, DECLINED, or the gateway's reason, except for resultCode 2014, where it is the message in sentence case. Use it for display, not for branching.

Example: "APPROVED"

requestedAmount integer

The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization.

Example: 1000

approvedAmount integer

The approved amount in minor units. This is 0 for a decline or an outcome that is still in flight. A terminal may adjust the amount, for example by adding a tip.

Example: 1000

balanceAmount integer

The balance that remains to be paid on the transaction. This amount is always an integer in the smallest denomination of the currency (e.g. cents for USD or CAD).

Example: 0

refundableAmount integer

The amount that can still be refunded against this sale or capture, in the smallest denomination of the currency. Normally available within seconds of approval. Absent for authorizations, refunds, voids, and declined transactions; it can also be absent briefly after a sale or capture is approved. Absence does not mean unlimited; it means this value is not yet available or not applicable. An ACH chargeback reduces it like a refund. 0 means fully refunded, voided, or charged back.

Example: 1000

transactionResponses array of object

Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.

Child attributes
responseCode ResponseCode

The outcome of the payment, and the field that tells you whether the transaction succeeded. The HTTP status, resultCode, and status do not. A transaction succeeded only when status is Completed and a transaction response has responseCode 1 or 2.

Outcomes:

  • Approved - 1, 2. For 2, only amountApproved was approved. On a Chargeback transaction, approved means the chargeback took effect: the money went back to the payer.
  • Declined - 10 to 18. The issuer or bank refused the payment. Do not retry with the same payment details.
  • Canceled - 54, 55. No money moved.
  • Pending - 57. The outcome is not final. Wait for the webhook or query the transaction again.
  • Unknown - 0. No specific code was reported. While status is not Completed, the outcome is not final. On a Completed transaction it is not an approval: read resultCode and resultText for the reason, for example 2014, 6901, or 6902.
  • Error - every other code. Processing failed for a technical or request reason.

See Transaction response codes.

Response codes:

  • 0 - UNKNOWN
  • 1 - APPROVED - Transaction was approved
  • 2 - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.
  • 10 - DECLINED - Transaction was declined by the issuer or bank. For Card-Present, the transaction can also be declined offline by the terminal.
  • 11 - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.
  • 12 - CARD_EXPIRED - The card used for the transaction has expired.
  • 13 - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.
  • 14 - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).
  • 15 - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).
  • 16 - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).
  • 17 - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.
  • 18 - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.
  • 19 - BATCH_EMPTY - Indicates that the batch for processing is empty.
  • 20 - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).
  • 21 - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.
  • 50 - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.
  • 51 - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.
  • 52 - NOT_SUPPORTED - Rejected because the requested operation is not supported.
  • 53 - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.
  • 54 - CANCELLED - Cancelled by the user or merchant.
  • 55 - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.
  • 56 - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.
  • 57 - PENDING - The transaction is awaiting an asynchronous outcome.

Allowed: 0, 1, 2, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 50, 51, 52, 53, 54, 55, 56, 57

authCode string

The authorization code provided by the card issuer, confirming transaction approval.

Example: "123456"

amountApproved integer

The amount approved for this transaction response.

Example: 1000

approvedAmountBreakdown ApprovedAmountBreakdown

A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.

Child attributes
amountGoodsAndServices integer

The approved amount for goods and services.

Example: 900

tax integer

The approved tax amount.

Example: 100

cashback integer

The approved cashback amount.

Example: 0

tip integer

The approved tip amount.

Example: 0

paymentMethod object

The payment method used for this transaction.

Child attributes
id string required

The unique identifier of the payment method. This ID has a prefix that makes it human-readable (pmt_trm_ for physical terminals, pmt_vrt_ for virtual card terminals, pmt_ach_ for virtual ACH terminals, pmt_tkn_ for tokens, which store a card or an ACH bank account), but applications should always use the type field to determine the payment method type rather than parsing this ID.

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

The date and time (UTC) when this payment method token was removed from the system using the Remove Token endpoint. This parameter will only be returned if the token was removed/deleted from the system.

This field will be present in three scenarios:

  • As part of a successful Remove Token endpoint response
  • In token.removed webhook notifications
  • In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

  • Physical - A physical payment terminal for Card Present transactions
  • Virtual - A hosted payment form/iframe for Card Not Present transactions
  • VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
  • Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
  • VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
  • Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

cardType string

The type of card used for this transaction:

  • UNKNOWN - The card type is unknown
  • DEBIT - Debit Card
  • VISA - Visa Credit Card
  • MASTERCARD - MasterCard Credit Card
  • AMEX - American Express Credit Card
  • DINERS - Diners Club Credit Card
  • DISCOVER - Discover Credit Card
  • JCB - JCB Credit Card
  • UNIONPAY - UnionPay Credit Card
  • MAESTRO - Maestro Debit Card
  • GIFT - Gift Card
  • CASH - All-cash Transaction
  • EBT - Electronic Benefits Transfer Card
  • INTERAC - Interac (Canadian PIN-debit network), Card Present only
  • OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

  • For card tokens: Credit or Debit.
  • For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

cardType CardType

The type of card used for this transaction:

  • UNKNOWN - The card type is unknown
  • DEBIT - Debit Card
  • VISA - Visa Credit Card
  • MASTERCARD - MasterCard Credit Card
  • AMEX - American Express Credit Card
  • DINERS - Diners Club Credit Card
  • DISCOVER - Discover Credit Card
  • JCB - JCB Credit Card
  • UNIONPAY - UnionPay Credit Card
  • MAESTRO - Maestro Debit Card
  • GIFT - Gift Card
  • CASH - All-cash Transaction
  • EBT - Electronic Benefits Transfer Card
  • INTERAC - Interac (Canadian PIN-debit network), Card Present only
  • OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

avsResult AVSResult

The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.

  • A - Address matches, ZIP does not. The first five numerical characters contained in the address match those stored at the VIC or issuer's center. However, the ZIP code does not match.
  • E - Ineligible transaction.
  • N - Neither address nor ZIP matches. Neither the first five numerical characters contained in the address match with those stored at the VIC nor issuer's center nor the ZIP code match.
  • R - Retry (system unavailable or timed out).
  • S - Card type not supported. The card type for this transaction is not supported by AVS. AVS can verify addresses for Visa cards, MasterCard, proprietary cards, and private label transactions.
  • U - Address information unavailable.
  • G - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.
  • W - Nine-digit ZIP match, address does not. The nine-digit Postal ZIP code matches that stored at the VIC or card issuer's centre. However, the first five numerical characters contained in the address do not match.
  • X - Exact match (nine digit ZIP and address). Both the nine-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
  • Y - Address and five-digit ZIP match. Both the five-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
  • Z - Five-digit ZIP matches, address does not. The five-digit Postal ZIP code matches that stored at the VIC or card issuer's centre.

NOTE: Transactions can still be authorized if the AVS responses are no match or failure. AVS responses are for merchant information only, and usually do not influence the overall Authorization result. This can vary based on the Issuing Bank.

Allowed: A, E, N, R, S, U, G, W, X, Y, Z

cvvResult CVVResult

The CVV verification result. Typically returned on Card Not Present transactions.

  • M - CVV Match
  • N - CVV No Match
  • P - Not Processed
  • S - CVV should be on the card but the merchant indicates it is not.
  • U - User is unregistered

NOTE: Transactions can still be authorized if the CVV responses are no match or failure. CVV responses are for merchant information only, and usually do not influence the overall Authorization result. This can vary based on the Issuing Bank.

Allowed: M, N, P, S, U

accountType string

The funding-source classification associated with the payment method used in this transaction.

  • For credit/debit cards: Credit or Debit. May be null when the classification is unavailable, including on older transactions.
  • For ACH/EFT bank accounts: Checking or Savings.

The immediate hosted ACH response uses lowercase checking or savings. Retrieved transaction responses normally use Checking or Savings.

Allowed: Credit, Debit, Checking, Savings, checking, savings

Example: "Credit"

hostResponseText string

A meaningful text explaining the response code from the host.

Example: "APPROVED 00"

receipt Receipt

Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.

Child attributes
lines array of string required

The receipt lines.

sourceId string

Identifier of the session or other source that initiated the transaction. For an ACH chargeback, it is the chargeback's own trx_ ID, or the billing subscription ID when the charged-back sale was a subscription payment.

threeDs ThreeDsAuthentication

3D Secure (EMV 3DS2) authentication outcome. Populated on transactions initiated with formConfig.enable3DSecure: true. All fields (other than status) are optional - what the issuer returns depends on whether the transaction was frictionless, challenged, or declined.

Child attributes
status string

The authentication outcome to use in your integration. The other threeDs fields provide supporting authentication data.

Allowed: Authenticated, Attempted, NotAuthenticated, Failed, Unavailable, NotEnrolled

Example: "Authenticated"

cavv string

Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions.

Example: "AAABBkgwVoRhY2tcYlZGAAAAAAA="

eci string

E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:

  • 02 / 05 - Fully authenticated (liability shift to issuer).
  • 01 / 06 - Attempted authentication (partial liability shift).
  • 00 / 07 - Not authenticated (no liability shift).

Example: "05"

xid string

3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility.

Example: "MDAwMDAwMDAwMDAwMDAwMTM3MDI="

dsTransId string

Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction.

Example: "b71a7d5d-cc38-4ce9-80c3-50a7d53271f7"

threeDReasonId string

Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use status to handle the outcome and threeDReason for the explanation.

Example: "10"

threeDReason string

Human-readable description matching threeDReasonId.

Example: "Stolen Card"

threeDsChallenge ThreeDsChallenge

Present when a token payment requires a cardholder challenge (resultCode: 4100).

Child attributes
redirectUrl string (uri) required

Hosted URL where the cardholder completes the challenge.

followUpToken string required

Opaque token identifying the pending challenge.

Example
{
  "event": {
    "id": "evt_01JS21X856RR8R69GV5F17XK9C",
    "type": "auth.completed",
    "timestamp": "2025-05-27T18:49:31Z",
    "merchantId": "mer_01JQZC2Y6W3F8XKT5H9DPNBMVR"
  },
  "originalResponse": {
    "id": "trx_01J2F0EKHC7HY2R93C8ENBD1FG",
    "timestamp": "2025-05-27T18:49:31Z",
    "type": "Auth",
    "status": "Completed",
    "accountHolder": {
      "id": "aho_01JRZPRGFF4J2SZC3HMDBYEN2J",
      "externalId": "usr_1234567890123",
      "contact": {
        "name": "John Doe",
        "countryCode": "US",
        "zipCode": "60606",
        "address": "300 S Wacker Dr",
        "state": "IL",
        "city": "Chicago"
      }
    },
    "paymentMethod": {
      "id": "pmt_trm_01JRZPTMTBN41PC3VPQNZ5T3HF",
      "type": "Physical",
      "currency": "USD",
      "description": "Main Store Terminal"
    },
    "invoiceNumber": "inv_1234567890123456",
    "orderNumber": "order_number_1234",
    "referenceId": "ref_s192i49i",
    "resultCode": 0,
    "resultText": "APPROVED",
    "requestedAmount": 1000,
    "approvedAmount": 1000,
    "balanceAmount": 0,
    "transactionResponses": [
      {
        "responseCode": 1,
        "authCode": "123456",
        "amountApproved": 1000,
        "approvedAmountBreakdown": {
          "amountGoodsAndServices": 900,
          "tax": 100,
          "cashback": 0,
          "tip": 0
        },
        "paymentMethod": {
          "id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
          "type": "Token",
          "currency": "USD",
          "description": "Token for John Doe's Visa",
          "billingContact": {
            "name": "John Doe",
            "countryCode": "US",
            "zipCode": "12345",
            "address": "123 Main St",
            "state": "NY",
            "city": "Anytown"
          },
          "cardType": "VISA",
          "maskedCardNumber": "************0011",
          "cardExpDate": "1225"
        },
        "cardType": "VISA",
        "avsResult": "Y",
        "cvvResult": "M",
        "accountType": "Credit",
        "hostResponseText": "APPROVED 00",
        "receipt": {
          "lines": [
            "     Test Merchant      ",
            "      300 S Wacker      ",
            "         Loop,          ",
            "                        ",
            "                        ",
            "TERM #          11000367",
            "RECORD #         0656191",
            "HOST INVOICE #    000038",
            "HOST SEQ #    1720656191",
            "MERCH                   ",
            "INVOICE inv_123456789012",
            "        3456",
            "------------------------",
            "CARD    ************0011",
            "VISA             Contact",
            "07/10/2024      20:03:05",
            "------------------------",
            "        PRE AUTH        ",
            "TOTAL         USD $10.00",
            "------------------------",
            "AUTH#:123456            ",
            "                        ",
            "      APPROVED 00       ",
            "       THANK YOU        ",
            "                        ",
            "      Visa Credit       ",
            "AID:      A0000000031010",
            "TC:     43F4ACF64B07551A",
            "TVR:          8000008000",
            "TSI:                7800",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "     MERCHANT COPY      ",
            "     Test Merchant      ",
            "      300 S Wacker      ",
            "         Loop,          ",
            "                        ",
            "                        ",
            "TERM #          11000367",
            "RECORD #         0656191",
            "HOST INVOICE #    000038",
            "HOST SEQ #    1720656191",
            "MERCH                   ",
            "INVOICE inv_123456789012",
            "        3456",
            "------------------------",
            "CARD    ************0011",
            "VISA             Contact",
            "07/10/2024      20:03:05",
            "------------------------",
            "        PRE AUTH        ",
            "TOTAL         USD $10.00",
            "------------------------",
            "AUTH#:123456            ",
            "                        ",
            "      APPROVED 00       ",
            "       THANK YOU        ",
            "                        ",
            "      Visa Credit       ",
            "AID:      A0000000031010",
            "TC:     43F4ACF64B07551A",
            "TVR:          8000008000",
            "TSI:                7800",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "     CUSTOMER COPY      "
          ]
        }
      }
    ]
  }
}

Responses

200

Successful acknowledgement of a webhook event. The response should be a 200 OK status with an empty body.

application/json · object

SuccessfulWebhookResponse
{}

Capture completed

POSTCaptureCompleted to your webhook endpoint

This webhook event is triggered when a transaction capture for a previously authorized transaction is completed.

Parameters

NameInTypeDescription
x-fsk-wh-chksmheaderstring

Present on legacy deliveries, the delivery method every merchant has today. A lowercase hex-encoded HMAC-SHA256 of the raw request body, keyed with the shared secret provided by support for this endpoint. Carries no timestamp, so deduplicate on the payload's event.id to defend against replay. See Verifying the checksum.

Svix deliveries carry the svix-* headers instead. Svix webhooks are invite only; see Webhooks.

svix-idheaderstring

Present on Svix deliveries only. The unique message id for this delivery, constant across retries of the same message.

Svix webhooks are invite only. Most merchants receive legacy deliveries, which carry x-fsk-wh-chksm instead of the svix-* headers; see Webhooks.

svix-timestampheaderstring

Present on Svix deliveries only. The time the message was sent, as a Unix timestamp in seconds. Reject stale timestamps to protect against replay attacks. See Verifying signatures.

svix-signatureheaderstring

Present on Svix deliveries only. One or more space-delimited signatures in the form v1,<base64 signature> - an HMAC-SHA256 over {svix-id}.{svix-timestamp}.{raw request body} keyed with the endpoint's signing secret. See Verifying signatures.

Payload

The request body for the capture.completed webhook event.

application/json · CaptureCompletedWebhook

event object required

Webhook event details.

Child attributes
id string required

Unique ID for this webhook event.

Example: "evt_01JS21X856RR8R69GV5F17XK9C"

type string required

The type of event that occurred.

Example: "event.completed"

timestamp string (date-time) required

The time when the event was triggered (UTC).

Example: "2025-04-16T14:30:00Z"

merchantId string required

The merchant that owns the transaction or token.

Example: "mer_01JQZC2Y6W3F8XKT5H9DPNBMVR"

originalResponse CaptureResponse required

Represents the response to a capture request.

Child attributes
id string

Unique ID for this capture transaction.

Example: "trx_01J2F0ZJ2JW5B63CJFPXRGAB1S"

timestamp string (date-time)

Transaction timestamp in UTC

Example: "2025-05-27T18:49:31Z"

type string

Type of transaction

Allowed: Sale, Auth, Capture, Refund, Void

Example: "Capture"

status TransactionStatus

The processing lifecycle, separate from approval or decline. Pending waits for customer input; Submitted, Acknowledged, and Processing are in flight; AwaitingSettlement waits for a bank transfer outcome. Completed can be approved or declined: inspect resultCode and transactionResponses[].responseCode. Failed means processing stopped because of a technical issue. Abandoned means the customer did not complete the flow before submission. Both states close the request.

Allowed: Unknown, Created, Pending, Submitted, Acknowledged, Processing, AwaitingSettlement, Completed, Failed, Abandoned

Example: "Completed"

accountHolder object

Account holder information associated with the transaction

Child attributes
id string required

Account holder ID assigned by the API.

Example: "aho_01JRZPRGFF4J2SZC3HMDBYEN2J"

externalId string required

External account holder ID assigned by your application.

Example: "usr_1234567890123"

contact object

Contact information for the account holder. Only returned for Card Not Present transactions.

Child attributes
name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "60606"

address string

Example: "300 S Wacker Dr"

state string

Example: "IL"

city string

Example: "Chicago"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

paymentMethod object

The payment method used for this transaction.

Child attributes
id string required

The unique identifier of the payment method. This ID has a prefix that makes it human-readable (pmt_trm_ for physical terminals, pmt_vrt_ for virtual card terminals, pmt_ach_ for virtual ACH terminals, pmt_tkn_ for tokens, which store a card or an ACH bank account), but applications should always use the type field to determine the payment method type rather than parsing this ID.

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

The date and time (UTC) when this payment method token was removed from the system using the Remove Token endpoint. This parameter will only be returned if the token was removed/deleted from the system.

This field will be present in three scenarios:

  • As part of a successful Remove Token endpoint response
  • In token.removed webhook notifications
  • In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

  • Physical - A physical payment terminal for Card Present transactions
  • Virtual - A hosted payment form/iframe for Card Not Present transactions
  • VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
  • Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
  • VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
  • Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

Child attributes
name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "12345"

address string

Example: "123 Main St"

state string

Example: "NY"

city string

Example: "Anytown"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

cardType string

The type of card used for this transaction:

  • UNKNOWN - The card type is unknown
  • DEBIT - Debit Card
  • VISA - Visa Credit Card
  • MASTERCARD - MasterCard Credit Card
  • AMEX - American Express Credit Card
  • DINERS - Diners Club Credit Card
  • DISCOVER - Discover Credit Card
  • JCB - JCB Credit Card
  • UNIONPAY - UnionPay Credit Card
  • MAESTRO - Maestro Debit Card
  • GIFT - Gift Card
  • CASH - All-cash Transaction
  • EBT - Electronic Benefits Transfer Card
  • INTERAC - Interac (Canadian PIN-debit network), Card Present only
  • OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

  • For card tokens: Credit or Debit.
  • For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

invoiceNumber InvoiceNumber

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.

max length 100

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

referenceId ReferenceIdForResponse

The reference ID for this transaction. This will either be the reference ID provided in the transaction request or, if no value was provided, a value generated automatically by the system. This reference ID can be used for processing captures and referenced refunds by including it in the originalReferenceId field of subsequent transactions.

max length 100

Example: "ref_s192i49i"

originalTransactionId string

The trx_ ID of the earlier transaction this one belongs to, when the link has been verified. Set on card-present captures and voids, card-present Interac refunds, ACH refunds once the gateway confirms the original sale, ACH chargebacks (the charged-back sale), and ACH resubmissions (the original sale).

Absent when there is no verified link. That includes card-not-present captures, refunds, and voids, other card-present refunds, and older transactions recorded before the link was stored. Do not treat an absent value as proof that the transaction has no original.

Example: "trx_01JWBPE27KHY2K4J7A13ATQ786"

resultCode ResultCode

Result codes:

  • 0 - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)
  • 1003 - The payment terminal is busy or unavailable. (If this error persists, the user may need to close and re-open the Payment Application on the terminal or restart the terminal)
  • 1005 - The specified terminal could not be found.
  • 1010 - The transaction request is pending to become transaction.
  • 2014 - The payment method or card brand is not enabled for the merchant. resultText carries the message, such as ACH payments are not enabled for this merchant. or Visa cards are not enabled for this merchant. The transaction is Completed and failed; do not retry it with the same payment method.
  • 3000 - An unexpected error occurred. Please try again.
  • 3002 - The transaction could not be completed because the payment terminal could not find the related transaction.
  • 3005 - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.
  • 3006 - The transaction could not be completed because the payment terminal is low on battery.
  • 3009 - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.
  • 3010 - The transaction took too long and was cancelled by the application.
  • 3011 - Invalid transaction request. Please consult the documentation for valid transaction requests.
  • 3012 - Invalid transaction request. paymentMethodId is invalid.
  • 3013 - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.
  • 3014 - Invalid amount. Please try your transaction again with an amount greater than $0.
  • 3020 - An unsupported transaction result was received.
  • 4001 - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.
  • 6800 - 3D Secure authentication was rejected by the issuer's ACS (card auth failed, security failure, stolen card, suspected fraud, etc.). Surfaced on declined CNP transactions when formConfig.enable3DSecure: true and the gateway reports a 3D Secure reason; other failures in a 3D Secure session use 6900-6902. See SDK Error Codes for guidance.
  • 6801 - 3D Secure authentication could not be completed because of an upstream technical issue (ACS timeout, directory server unreachable). Retry later or, if merchant policy allows, retry with 3DS disabled.
  • 6802 - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.
  • 6900 - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText. See SDK Error Codes for guidance.
  • 6901 - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision. See SDK Error Codes for guidance.
  • 6902 - The gateway reported no failure but returned no payment token. See SDK Error Codes for guidance.
  • 9998 - The system is not ready to process a transaction.
  • 9999 - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.
  • 1010 - The transaction request is pending customer interaction.
  • 4100 - Cardholder verification is required. Follow threeDsChallenge.redirectUrl and reconcile the final transaction outcome before retrying.
  • 55 - The customer cancelled the hosted payment attempt.

Allowed: 0, 55, 1003, 1005, 1010, 2014, 3000, 3002, 3005, 3006, 3009, 3010, 3011, 3012, 3013, 3014, 3020, 4001, 4100, 6800, 6801, 6802, 6900, 6901, 6902, 9998, 9999

Example: 0

resultText ResultText

A message describing the result code in more detail. On a stored transaction it is uppercase, such as APPROVED, DECLINED, or the gateway's reason, except for resultCode 2014, where it is the message in sentence case. Use it for display, not for branching.

Example: "APPROVED"

requestedAmount integer

The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization.

Example: 1000

approvedAmount integer

The approved amount in minor units. This is 0 for a decline or an outcome that is still in flight. A terminal may adjust the amount, for example by adding a tip.

Example: 1000

transactionResponses array of TransactionResponse

Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.

Child attributes
responseCode ResponseCode

The outcome of the payment, and the field that tells you whether the transaction succeeded. The HTTP status, resultCode, and status do not. A transaction succeeded only when status is Completed and a transaction response has responseCode 1 or 2.

Outcomes:

  • Approved - 1, 2. For 2, only amountApproved was approved. On a Chargeback transaction, approved means the chargeback took effect: the money went back to the payer.
  • Declined - 10 to 18. The issuer or bank refused the payment. Do not retry with the same payment details.
  • Canceled - 54, 55. No money moved.
  • Pending - 57. The outcome is not final. Wait for the webhook or query the transaction again.
  • Unknown - 0. No specific code was reported. While status is not Completed, the outcome is not final. On a Completed transaction it is not an approval: read resultCode and resultText for the reason, for example 2014, 6901, or 6902.
  • Error - every other code. Processing failed for a technical or request reason.

See Transaction response codes.

Response codes:

  • 0 - UNKNOWN
  • 1 - APPROVED - Transaction was approved
  • 2 - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.
  • 10 - DECLINED - Transaction was declined by the issuer or bank. For Card-Present, the transaction can also be declined offline by the terminal.
  • 11 - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.
  • 12 - CARD_EXPIRED - The card used for the transaction has expired.
  • 13 - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.
  • 14 - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).
  • 15 - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).
  • 16 - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).
  • 17 - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.
  • 18 - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.
  • 19 - BATCH_EMPTY - Indicates that the batch for processing is empty.
  • 20 - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).
  • 21 - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.
  • 50 - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.
  • 51 - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.
  • 52 - NOT_SUPPORTED - Rejected because the requested operation is not supported.
  • 53 - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.
  • 54 - CANCELLED - Cancelled by the user or merchant.
  • 55 - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.
  • 56 - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.
  • 57 - PENDING - The transaction is awaiting an asynchronous outcome.

Allowed: 0, 1, 2, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 50, 51, 52, 53, 54, 55, 56, 57

authCode string

The authorization code provided by the card issuer, confirming transaction approval.

Example: "123456"

amountApproved integer

The amount approved for this transaction response.

Example: 1000

approvedAmountBreakdown ApprovedAmountBreakdown

A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.

Child attributes
amountGoodsAndServices integer

The approved amount for goods and services.

Example: 900

tax integer

The approved tax amount.

Example: 100

cashback integer

The approved cashback amount.

Example: 0

tip integer

The approved tip amount.

Example: 0

paymentMethod object

The payment method used for this transaction.

Child attributes
id string required

The unique identifier of the payment method. This ID has a prefix that makes it human-readable (pmt_trm_ for physical terminals, pmt_vrt_ for virtual card terminals, pmt_ach_ for virtual ACH terminals, pmt_tkn_ for tokens, which store a card or an ACH bank account), but applications should always use the type field to determine the payment method type rather than parsing this ID.

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

The date and time (UTC) when this payment method token was removed from the system using the Remove Token endpoint. This parameter will only be returned if the token was removed/deleted from the system.

This field will be present in three scenarios:

  • As part of a successful Remove Token endpoint response
  • In token.removed webhook notifications
  • In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

  • Physical - A physical payment terminal for Card Present transactions
  • Virtual - A hosted payment form/iframe for Card Not Present transactions
  • VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
  • Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
  • VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
  • Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

cardType string

The type of card used for this transaction:

  • UNKNOWN - The card type is unknown
  • DEBIT - Debit Card
  • VISA - Visa Credit Card
  • MASTERCARD - MasterCard Credit Card
  • AMEX - American Express Credit Card
  • DINERS - Diners Club Credit Card
  • DISCOVER - Discover Credit Card
  • JCB - JCB Credit Card
  • UNIONPAY - UnionPay Credit Card
  • MAESTRO - Maestro Debit Card
  • GIFT - Gift Card
  • CASH - All-cash Transaction
  • EBT - Electronic Benefits Transfer Card
  • INTERAC - Interac (Canadian PIN-debit network), Card Present only
  • OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

  • For card tokens: Credit or Debit.
  • For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

cardType CardType

The type of card used for this transaction:

  • UNKNOWN - The card type is unknown
  • DEBIT - Debit Card
  • VISA - Visa Credit Card
  • MASTERCARD - MasterCard Credit Card
  • AMEX - American Express Credit Card
  • DINERS - Diners Club Credit Card
  • DISCOVER - Discover Credit Card
  • JCB - JCB Credit Card
  • UNIONPAY - UnionPay Credit Card
  • MAESTRO - Maestro Debit Card
  • GIFT - Gift Card
  • CASH - All-cash Transaction
  • EBT - Electronic Benefits Transfer Card
  • INTERAC - Interac (Canadian PIN-debit network), Card Present only
  • OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

avsResult AVSResult

The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.

  • A - Address matches, ZIP does not. The first five numerical characters contained in the address match those stored at the VIC or issuer's center. However, the ZIP code does not match.
  • E - Ineligible transaction.
  • N - Neither address nor ZIP matches. Neither the first five numerical characters contained in the address match with those stored at the VIC nor issuer's center nor the ZIP code match.
  • R - Retry (system unavailable or timed out).
  • S - Card type not supported. The card type for this transaction is not supported by AVS. AVS can verify addresses for Visa cards, MasterCard, proprietary cards, and private label transactions.
  • U - Address information unavailable.
  • G - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.
  • W - Nine-digit ZIP match, address does not. The nine-digit Postal ZIP code matches that stored at the VIC or card issuer's centre. However, the first five numerical characters contained in the address do not match.
  • X - Exact match (nine digit ZIP and address). Both the nine-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
  • Y - Address and five-digit ZIP match. Both the five-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
  • Z - Five-digit ZIP matches, address does not. The five-digit Postal ZIP code matches that stored at the VIC or card issuer's centre.

NOTE: Transactions can still be authorized if the AVS responses are no match or failure. AVS responses are for merchant information only, and usually do not influence the overall Authorization result. This can vary based on the Issuing Bank.

Allowed: A, E, N, R, S, U, G, W, X, Y, Z

cvvResult CVVResult

The CVV verification result. Typically returned on Card Not Present transactions.

  • M - CVV Match
  • N - CVV No Match
  • P - Not Processed
  • S - CVV should be on the card but the merchant indicates it is not.
  • U - User is unregistered

NOTE: Transactions can still be authorized if the CVV responses are no match or failure. CVV responses are for merchant information only, and usually do not influence the overall Authorization result. This can vary based on the Issuing Bank.

Allowed: M, N, P, S, U

accountType string

The funding-source classification associated with the payment method used in this transaction.

  • For credit/debit cards: Credit or Debit. May be null when the classification is unavailable, including on older transactions.
  • For ACH/EFT bank accounts: Checking or Savings.

The immediate hosted ACH response uses lowercase checking or savings. Retrieved transaction responses normally use Checking or Savings.

Allowed: Credit, Debit, Checking, Savings, checking, savings

Example: "Credit"

hostResponseText string

A meaningful text explaining the response code from the host.

Example: "APPROVED 00"

receipt Receipt

Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.

Child attributes
lines array of string required

The receipt lines.

sourceId string

Identifier of the session or other source that initiated the transaction.

threeDs ThreeDsAuthentication

3D Secure (EMV 3DS2) authentication outcome. Populated on transactions initiated with formConfig.enable3DSecure: true. All fields (other than status) are optional - what the issuer returns depends on whether the transaction was frictionless, challenged, or declined.

Child attributes
status string

The authentication outcome to use in your integration. The other threeDs fields provide supporting authentication data.

Allowed: Authenticated, Attempted, NotAuthenticated, Failed, Unavailable, NotEnrolled

Example: "Authenticated"

cavv string

Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions.

Example: "AAABBkgwVoRhY2tcYlZGAAAAAAA="

eci string

E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:

  • 02 / 05 - Fully authenticated (liability shift to issuer).
  • 01 / 06 - Attempted authentication (partial liability shift).
  • 00 / 07 - Not authenticated (no liability shift).

Example: "05"

xid string

3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility.

Example: "MDAwMDAwMDAwMDAwMDAwMTM3MDI="

dsTransId string

Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction.

Example: "b71a7d5d-cc38-4ce9-80c3-50a7d53271f7"

threeDReasonId string

Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use status to handle the outcome and threeDReason for the explanation.

Example: "10"

threeDReason string

Human-readable description matching threeDReasonId.

Example: "Stolen Card"

threeDsChallenge ThreeDsChallenge

Present when a token payment requires a cardholder challenge (resultCode: 4100).

Child attributes
redirectUrl string (uri) required

Hosted URL where the cardholder completes the challenge.

followUpToken string required

Opaque token identifying the pending challenge.

balanceAmount integer

The balance that remains to be paid on the transaction. This amount is always an integer in the smallest denomination of the currency (e.g. cents for USD or CAD).

Example: 0

refundableAmount integer

The amount that can still be refunded against this sale or capture, in the smallest denomination of the currency. Normally available within seconds of approval. Absent for authorizations, refunds, voids, and declined transactions; it can also be absent briefly after a sale or capture is approved. Absence does not mean unlimited; it means this value is not yet available or not applicable. 0 means fully refunded or voided.

Example: 1000

Example
{
  "event": {
    "id": "evt_01JS21X856RR8R69GV5F17XK9C",
    "type": "capture.completed",
    "timestamp": "2025-05-27T18:49:31Z",
    "merchantId": "mer_01JQZC2Y6W3F8XKT5H9DPNBMVR"
  },
  "originalResponse": {
    "id": "trx_01J2F0ZJ2JW5B63CJFPXRGAB1S",
    "timestamp": "2025-05-27T18:49:31Z",
    "type": "Capture",
    "status": "Completed",
    "accountHolder": {
      "id": "aho_01JRZPRGFF4J2SZC3HMDBYEN2J",
      "externalId": "usr_1234567890123",
      "contact": {
        "name": "John Doe",
        "countryCode": "US",
        "zipCode": "60606",
        "address": "300 S Wacker Dr",
        "state": "IL",
        "city": "Chicago"
      }
    },
    "paymentMethod": {
      "id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
      "type": "Token",
      "currency": "USD",
      "description": "Token for John Doe's Visa",
      "billingContact": {
        "name": "John Doe",
        "countryCode": "US",
        "zipCode": "12345",
        "address": "123 Main St",
        "state": "NY",
        "city": "Anytown"
      },
      "cardType": "VISA",
      "maskedCardNumber": "************0011",
      "cardExpDate": "1225"
    },
    "invoiceNumber": "inv_1234567890123456",
    "orderNumber": "order_number_1234",
    "referenceId": "ref_s192i49i",
    "resultCode": 0,
    "resultText": "APPROVED",
    "requestedAmount": 1000,
    "approvedAmount": 1000,
    "transactionResponses": [
      {
        "responseCode": 1,
        "authCode": "123456",
        "amountApproved": 1000,
        "approvedAmountBreakdown": {
          "amountGoodsAndServices": 900,
          "tax": 100,
          "cashback": 0,
          "tip": 0
        },
        "paymentMethod": {
          "id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
          "type": "Token",
          "currency": "USD",
          "description": "Token for John Doe's Visa"
        },
        "billingContact": {
          "name": "John Doe",
          "countryCode": "US",
          "zipCode": "12345",
          "address": "123 Main St",
          "state": "NY",
          "city": "Anytown",
          "cardType": "VISA",
          "maskedCardNumber": "************0011",
          "cardExpDate": "1225"
        },
        "cardType": "VISA",
        "avsResult": "Y",
        "cvvResult": "M",
        "accountType": "Credit",
        "hostResponseText": "APPROVED 00",
        "receipt": {
          "lines": [
            "     Test Merchant      ",
            "      300 S Wacker      ",
            "         Loop,          ",
            "                        ",
            "                        ",
            "TERM #          11000367",
            "RECORD #         0656191",
            "HOST INVOICE #    000038",
            "HOST SEQ #    1720656191",
            "MERCH                   ",
            "INVOICE inv_123456789012",
            "        3456",
            "------------------------",
            "CARD    ************0011",
            "VISA             Contact",
            "07/10/2024      20:03:05",
            "------------------------",
            "                        ",
            "   PRE AUTH COMPLETE    ",
            "                        ",
            "TOTAL         USD $10.00",
            "------------------------",
            "AUTH#:123456       B:171",
            "                        ",
            "      APPROVED 00       ",
            "       THANK YOU        ",
            "                        ",
            "      Visa Credit       ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "     MERCHANT COPY      ",
            "     Test Merchant      ",
            "      300 S Wacker      ",
            "         Loop,          ",
            "                        ",
            "                        ",
            "TERM #          11000367",
            "RECORD #         0656191",
            "HOST INVOICE #    000038",
            "HOST SEQ #    1720656191",
            "MERCH                   ",
            "INVOICE inv_123456789012",
            "        3456",
            "------------------------",
            "CARD    ************0011",
            "VISA             Contact",
            "07/10/2024      20:03:05",
            "------------------------",
            "                        ",
            "   PRE AUTH COMPLETE    ",
            "                        ",
            "TOTAL         USD $10.00",
            "------------------------",
            "AUTH#:123456       B:171",
            "                        ",
            "      APPROVED 00       ",
            "       THANK YOU        ",
            "                        ",
            "      Visa Credit       ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "     CUSTOMER COPY      "
          ]
        }
      }
    ]
  }
}

Responses

200

Successful acknowledgement of a webhook event. The response should be a 200 OK status with an empty body.

application/json · object

SuccessfulWebhookResponse
{}

Refund completed

POSTRefundCompleted to your webhook endpoint

This webook event is triggered when a transaction void or refund for a previously completed transaction is completed.

Parameters

NameInTypeDescription
x-fsk-wh-chksmheaderstring

Present on legacy deliveries, the delivery method every merchant has today. A lowercase hex-encoded HMAC-SHA256 of the raw request body, keyed with the shared secret provided by support for this endpoint. Carries no timestamp, so deduplicate on the payload's event.id to defend against replay. See Verifying the checksum.

Svix deliveries carry the svix-* headers instead. Svix webhooks are invite only; see Webhooks.

svix-idheaderstring

Present on Svix deliveries only. The unique message id for this delivery, constant across retries of the same message.

Svix webhooks are invite only. Most merchants receive legacy deliveries, which carry x-fsk-wh-chksm instead of the svix-* headers; see Webhooks.

svix-timestampheaderstring

Present on Svix deliveries only. The time the message was sent, as a Unix timestamp in seconds. Reject stale timestamps to protect against replay attacks. See Verifying signatures.

svix-signatureheaderstring

Present on Svix deliveries only. One or more space-delimited signatures in the form v1,<base64 signature> - an HMAC-SHA256 over {svix-id}.{svix-timestamp}.{raw request body} keyed with the endpoint's signing secret. See Verifying signatures.

Payload

The request body for the refund.completed webhook event.

application/json · RefundCompletedWebhook

event object required

Webhook event details.

Child attributes
id string required

Unique ID for this webhook event.

Example: "evt_01JS21X856RR8R69GV5F17XK9C"

type string required

The type of event that occurred.

Example: "event.completed"

timestamp string (date-time) required

The time when the event was triggered (UTC).

Example: "2025-04-16T14:30:00Z"

merchantId string required

The merchant that owns the transaction or token.

Example: "mer_01JQZC2Y6W3F8XKT5H9DPNBMVR"

originalResponse RefundResponse required

Represents the response to a refund request.

Child attributes
id string

Unique ID for this refund transaction.

Example: "trx_01J2F0ZJ2JW5B63CJFPXRGAB1S"

timestamp string (date-time)

Transaction timestamp in UTC

Example: "2025-05-27T18:49:31Z"

type string

Type of transaction

Allowed: Sale, Auth, Capture, Refund, Void

Example: "Refund"

status TransactionStatus

The processing lifecycle, separate from approval or decline. Pending waits for customer input; Submitted, Acknowledged, and Processing are in flight; AwaitingSettlement waits for a bank transfer outcome. Completed can be approved or declined: inspect resultCode and transactionResponses[].responseCode. Failed means processing stopped because of a technical issue. Abandoned means the customer did not complete the flow before submission. Both states close the request.

Allowed: Unknown, Created, Pending, Submitted, Acknowledged, Processing, AwaitingSettlement, Completed, Failed, Abandoned

Example: "Completed"

accountHolder object

Account holder information associated with the transaction

Child attributes
id string required

Account holder ID assigned by the API.

Example: "aho_01JRZPRGFF4J2SZC3HMDBYEN2J"

externalId string required

External account holder ID assigned by your application.

Example: "usr_1234567890123"

contact object

Contact information for the account holder. Only returned for Card Not Present transactions.

Child attributes
name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "60606"

address string

Example: "300 S Wacker Dr"

state string

Example: "IL"

city string

Example: "Chicago"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

paymentMethod object

The payment method used for this transaction.

Child attributes
id string required

The unique identifier of the payment method. This ID has a prefix that makes it human-readable (pmt_trm_ for physical terminals, pmt_vrt_ for virtual card terminals, pmt_ach_ for virtual ACH terminals, pmt_tkn_ for tokens, which store a card or an ACH bank account), but applications should always use the type field to determine the payment method type rather than parsing this ID.

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

The date and time (UTC) when this payment method token was removed from the system using the Remove Token endpoint. This parameter will only be returned if the token was removed/deleted from the system.

This field will be present in three scenarios:

  • As part of a successful Remove Token endpoint response
  • In token.removed webhook notifications
  • In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

  • Physical - A physical payment terminal for Card Present transactions
  • Virtual - A hosted payment form/iframe for Card Not Present transactions
  • VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
  • Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
  • VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
  • Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

Child attributes
name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "12345"

address string

Example: "123 Main St"

state string

Example: "NY"

city string

Example: "Anytown"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

cardType string

The type of card used for this transaction:

  • UNKNOWN - The card type is unknown
  • DEBIT - Debit Card
  • VISA - Visa Credit Card
  • MASTERCARD - MasterCard Credit Card
  • AMEX - American Express Credit Card
  • DINERS - Diners Club Credit Card
  • DISCOVER - Discover Credit Card
  • JCB - JCB Credit Card
  • UNIONPAY - UnionPay Credit Card
  • MAESTRO - Maestro Debit Card
  • GIFT - Gift Card
  • CASH - All-cash Transaction
  • EBT - Electronic Benefits Transfer Card
  • INTERAC - Interac (Canadian PIN-debit network), Card Present only
  • OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

  • For card tokens: Credit or Debit.
  • For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

invoiceNumber InvoiceNumber

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.

max length 100

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

referenceId ReferenceIdForResponse

The reference ID for this transaction. This will either be the reference ID provided in the transaction request or, if no value was provided, a value generated automatically by the system. This reference ID can be used for processing captures and referenced refunds by including it in the originalReferenceId field of subsequent transactions.

max length 100

Example: "ref_s192i49i"

originalTransactionId string

The trx_ ID of the earlier transaction this one belongs to, when the link has been verified. Set on card-present captures and voids, card-present Interac refunds, ACH refunds once the gateway confirms the original sale, ACH chargebacks (the charged-back sale), and ACH resubmissions (the original sale).

Absent when there is no verified link. That includes card-not-present captures, refunds, and voids, other card-present refunds, and older transactions recorded before the link was stored. Do not treat an absent value as proof that the transaction has no original.

Example: "trx_01JWBPE27KHY2K4J7A13ATQ786"

resultCode ResultCode

Result codes:

  • 0 - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)
  • 1003 - The payment terminal is busy or unavailable. (If this error persists, the user may need to close and re-open the Payment Application on the terminal or restart the terminal)
  • 1005 - The specified terminal could not be found.
  • 1010 - The transaction request is pending to become transaction.
  • 2014 - The payment method or card brand is not enabled for the merchant. resultText carries the message, such as ACH payments are not enabled for this merchant. or Visa cards are not enabled for this merchant. The transaction is Completed and failed; do not retry it with the same payment method.
  • 3000 - An unexpected error occurred. Please try again.
  • 3002 - The transaction could not be completed because the payment terminal could not find the related transaction.
  • 3005 - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.
  • 3006 - The transaction could not be completed because the payment terminal is low on battery.
  • 3009 - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.
  • 3010 - The transaction took too long and was cancelled by the application.
  • 3011 - Invalid transaction request. Please consult the documentation for valid transaction requests.
  • 3012 - Invalid transaction request. paymentMethodId is invalid.
  • 3013 - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.
  • 3014 - Invalid amount. Please try your transaction again with an amount greater than $0.
  • 3020 - An unsupported transaction result was received.
  • 4001 - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.
  • 6800 - 3D Secure authentication was rejected by the issuer's ACS (card auth failed, security failure, stolen card, suspected fraud, etc.). Surfaced on declined CNP transactions when formConfig.enable3DSecure: true and the gateway reports a 3D Secure reason; other failures in a 3D Secure session use 6900-6902. See SDK Error Codes for guidance.
  • 6801 - 3D Secure authentication could not be completed because of an upstream technical issue (ACS timeout, directory server unreachable). Retry later or, if merchant policy allows, retry with 3DS disabled.
  • 6802 - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.
  • 6900 - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText. See SDK Error Codes for guidance.
  • 6901 - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision. See SDK Error Codes for guidance.
  • 6902 - The gateway reported no failure but returned no payment token. See SDK Error Codes for guidance.
  • 9998 - The system is not ready to process a transaction.
  • 9999 - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.
  • 1010 - The transaction request is pending customer interaction.
  • 4100 - Cardholder verification is required. Follow threeDsChallenge.redirectUrl and reconcile the final transaction outcome before retrying.
  • 55 - The customer cancelled the hosted payment attempt.

Allowed: 0, 55, 1003, 1005, 1010, 2014, 3000, 3002, 3005, 3006, 3009, 3010, 3011, 3012, 3013, 3014, 3020, 4001, 4100, 6800, 6801, 6802, 6900, 6901, 6902, 9998, 9999

Example: 0

resultText ResultText

A message describing the result code in more detail. On a stored transaction it is uppercase, such as APPROVED, DECLINED, or the gateway's reason, except for resultCode 2014, where it is the message in sentence case. Use it for display, not for branching.

Example: "APPROVED"

requestedAmount integer

The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization.

Example: 1000

approvedAmount integer

The approved amount in minor units. This is 0 for a decline or an outcome that is still in flight. A terminal may adjust the amount, for example by adding a tip.

Example: 1000

refundableAmount integer

The amount that remains refundable on the original transaction after this refund, in the smallest denomination of the currency. The balance reflects this refund attempt. When the gateway declines the refund, this equals the balance before the attempt.

Example: 0

transactionResponses array of TransactionResponse

Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.

Child attributes
responseCode ResponseCode

The outcome of the payment, and the field that tells you whether the transaction succeeded. The HTTP status, resultCode, and status do not. A transaction succeeded only when status is Completed and a transaction response has responseCode 1 or 2.

Outcomes:

  • Approved - 1, 2. For 2, only amountApproved was approved. On a Chargeback transaction, approved means the chargeback took effect: the money went back to the payer.
  • Declined - 10 to 18. The issuer or bank refused the payment. Do not retry with the same payment details.
  • Canceled - 54, 55. No money moved.
  • Pending - 57. The outcome is not final. Wait for the webhook or query the transaction again.
  • Unknown - 0. No specific code was reported. While status is not Completed, the outcome is not final. On a Completed transaction it is not an approval: read resultCode and resultText for the reason, for example 2014, 6901, or 6902.
  • Error - every other code. Processing failed for a technical or request reason.

See Transaction response codes.

Response codes:

  • 0 - UNKNOWN
  • 1 - APPROVED - Transaction was approved
  • 2 - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.
  • 10 - DECLINED - Transaction was declined by the issuer or bank. For Card-Present, the transaction can also be declined offline by the terminal.
  • 11 - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.
  • 12 - CARD_EXPIRED - The card used for the transaction has expired.
  • 13 - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.
  • 14 - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).
  • 15 - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).
  • 16 - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).
  • 17 - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.
  • 18 - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.
  • 19 - BATCH_EMPTY - Indicates that the batch for processing is empty.
  • 20 - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).
  • 21 - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.
  • 50 - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.
  • 51 - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.
  • 52 - NOT_SUPPORTED - Rejected because the requested operation is not supported.
  • 53 - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.
  • 54 - CANCELLED - Cancelled by the user or merchant.
  • 55 - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.
  • 56 - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.
  • 57 - PENDING - The transaction is awaiting an asynchronous outcome.

Allowed: 0, 1, 2, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 50, 51, 52, 53, 54, 55, 56, 57

authCode string

The authorization code provided by the card issuer, confirming transaction approval.

Example: "123456"

amountApproved integer

The amount approved for this transaction response.

Example: 1000

approvedAmountBreakdown ApprovedAmountBreakdown

A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.

Child attributes
amountGoodsAndServices integer

The approved amount for goods and services.

Example: 900

tax integer

The approved tax amount.

Example: 100

cashback integer

The approved cashback amount.

Example: 0

tip integer

The approved tip amount.

Example: 0

paymentMethod object

The payment method used for this transaction.

Child attributes
id string required

The unique identifier of the payment method. This ID has a prefix that makes it human-readable (pmt_trm_ for physical terminals, pmt_vrt_ for virtual card terminals, pmt_ach_ for virtual ACH terminals, pmt_tkn_ for tokens, which store a card or an ACH bank account), but applications should always use the type field to determine the payment method type rather than parsing this ID.

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

The date and time (UTC) when this payment method token was removed from the system using the Remove Token endpoint. This parameter will only be returned if the token was removed/deleted from the system.

This field will be present in three scenarios:

  • As part of a successful Remove Token endpoint response
  • In token.removed webhook notifications
  • In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

  • Physical - A physical payment terminal for Card Present transactions
  • Virtual - A hosted payment form/iframe for Card Not Present transactions
  • VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
  • Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
  • VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
  • Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

cardType string

The type of card used for this transaction:

  • UNKNOWN - The card type is unknown
  • DEBIT - Debit Card
  • VISA - Visa Credit Card
  • MASTERCARD - MasterCard Credit Card
  • AMEX - American Express Credit Card
  • DINERS - Diners Club Credit Card
  • DISCOVER - Discover Credit Card
  • JCB - JCB Credit Card
  • UNIONPAY - UnionPay Credit Card
  • MAESTRO - Maestro Debit Card
  • GIFT - Gift Card
  • CASH - All-cash Transaction
  • EBT - Electronic Benefits Transfer Card
  • INTERAC - Interac (Canadian PIN-debit network), Card Present only
  • OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

  • For card tokens: Credit or Debit.
  • For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

cardType CardType

The type of card used for this transaction:

  • UNKNOWN - The card type is unknown
  • DEBIT - Debit Card
  • VISA - Visa Credit Card
  • MASTERCARD - MasterCard Credit Card
  • AMEX - American Express Credit Card
  • DINERS - Diners Club Credit Card
  • DISCOVER - Discover Credit Card
  • JCB - JCB Credit Card
  • UNIONPAY - UnionPay Credit Card
  • MAESTRO - Maestro Debit Card
  • GIFT - Gift Card
  • CASH - All-cash Transaction
  • EBT - Electronic Benefits Transfer Card
  • INTERAC - Interac (Canadian PIN-debit network), Card Present only
  • OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

avsResult AVSResult

The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.

  • A - Address matches, ZIP does not. The first five numerical characters contained in the address match those stored at the VIC or issuer's center. However, the ZIP code does not match.
  • E - Ineligible transaction.
  • N - Neither address nor ZIP matches. Neither the first five numerical characters contained in the address match with those stored at the VIC nor issuer's center nor the ZIP code match.
  • R - Retry (system unavailable or timed out).
  • S - Card type not supported. The card type for this transaction is not supported by AVS. AVS can verify addresses for Visa cards, MasterCard, proprietary cards, and private label transactions.
  • U - Address information unavailable.
  • G - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.
  • W - Nine-digit ZIP match, address does not. The nine-digit Postal ZIP code matches that stored at the VIC or card issuer's centre. However, the first five numerical characters contained in the address do not match.
  • X - Exact match (nine digit ZIP and address). Both the nine-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
  • Y - Address and five-digit ZIP match. Both the five-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
  • Z - Five-digit ZIP matches, address does not. The five-digit Postal ZIP code matches that stored at the VIC or card issuer's centre.

NOTE: Transactions can still be authorized if the AVS responses are no match or failure. AVS responses are for merchant information only, and usually do not influence the overall Authorization result. This can vary based on the Issuing Bank.

Allowed: A, E, N, R, S, U, G, W, X, Y, Z

cvvResult CVVResult

The CVV verification result. Typically returned on Card Not Present transactions.

  • M - CVV Match
  • N - CVV No Match
  • P - Not Processed
  • S - CVV should be on the card but the merchant indicates it is not.
  • U - User is unregistered

NOTE: Transactions can still be authorized if the CVV responses are no match or failure. CVV responses are for merchant information only, and usually do not influence the overall Authorization result. This can vary based on the Issuing Bank.

Allowed: M, N, P, S, U

accountType string

The funding-source classification associated with the payment method used in this transaction.

  • For credit/debit cards: Credit or Debit. May be null when the classification is unavailable, including on older transactions.
  • For ACH/EFT bank accounts: Checking or Savings.

The immediate hosted ACH response uses lowercase checking or savings. Retrieved transaction responses normally use Checking or Savings.

Allowed: Credit, Debit, Checking, Savings, checking, savings

Example: "Credit"

hostResponseText string

A meaningful text explaining the response code from the host.

Example: "APPROVED 00"

receipt Receipt

Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.

Child attributes
lines array of string required

The receipt lines.

sourceId string

Identifier of the session or other source that initiated the transaction.

threeDs ThreeDsAuthentication

3D Secure (EMV 3DS2) authentication outcome. Populated on transactions initiated with formConfig.enable3DSecure: true. All fields (other than status) are optional - what the issuer returns depends on whether the transaction was frictionless, challenged, or declined.

Child attributes
status string

The authentication outcome to use in your integration. The other threeDs fields provide supporting authentication data.

Allowed: Authenticated, Attempted, NotAuthenticated, Failed, Unavailable, NotEnrolled

Example: "Authenticated"

cavv string

Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions.

Example: "AAABBkgwVoRhY2tcYlZGAAAAAAA="

eci string

E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:

  • 02 / 05 - Fully authenticated (liability shift to issuer).
  • 01 / 06 - Attempted authentication (partial liability shift).
  • 00 / 07 - Not authenticated (no liability shift).

Example: "05"

xid string

3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility.

Example: "MDAwMDAwMDAwMDAwMDAwMTM3MDI="

dsTransId string

Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction.

Example: "b71a7d5d-cc38-4ce9-80c3-50a7d53271f7"

threeDReasonId string

Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use status to handle the outcome and threeDReason for the explanation.

Example: "10"

threeDReason string

Human-readable description matching threeDReasonId.

Example: "Stolen Card"

threeDsChallenge ThreeDsChallenge

Present when a token payment requires a cardholder challenge (resultCode: 4100).

Child attributes
redirectUrl string (uri) required

Hosted URL where the cardholder completes the challenge.

followUpToken string required

Opaque token identifying the pending challenge.

balanceAmount integer

The balance that remains to be paid on the transaction. This amount is always an integer in the smallest denomination of the currency (e.g. cents for USD or CAD).

Example: 0

Example
{
  "event": {
    "id": "evt_01JS21X856RR8R69GV5F17XK9C",
    "type": "refund.completed",
    "timestamp": "2025-05-27T18:49:31Z",
    "merchantId": "mer_01JQZC2Y6W3F8XKT5H9DPNBMVR"
  },
  "originalResponse": {
    "id": "trx_01J2F0ZJ2JW5B63CJFPXRGAB1S",
    "timestamp": "2025-05-27T18:49:31Z",
    "type": "Refund",
    "status": "Completed",
    "accountHolder": {
      "id": "aho_01JRZPRGFF4J2SZC3HMDBYEN2J",
      "externalId": "usr_1234567890123",
      "contact": {
        "name": "John Doe",
        "countryCode": "US",
        "zipCode": "60606",
        "address": "300 S Wacker Dr",
        "state": "IL",
        "city": "Chicago"
      }
    },
    "paymentMethod": {
      "id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
      "type": "Token",
      "currency": "USD",
      "description": "Token for John Doe's Visa",
      "billingContact": {
        "name": "John Doe",
        "countryCode": "US",
        "zipCode": "12345",
        "address": "123 Main St",
        "state": "NY",
        "city": "Anytown"
      },
      "cardType": "VISA",
      "maskedCardNumber": "************0011",
      "cardExpDate": "1225"
    },
    "invoiceNumber": "inv_1234567890123456",
    "orderNumber": "order_number_1234",
    "referenceId": "ref_s192i49i",
    "resultCode": 0,
    "resultText": "APPROVED",
    "requestedAmount": 1000,
    "approvedAmount": 1000,
    "transactionResponses": [
      {
        "responseCode": 1,
        "authCode": "123456",
        "amountApproved": 1000,
        "paymentMethod": {
          "id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
          "type": "Token",
          "currency": "USD",
          "billingContact": {
            "name": "John Doe",
            "countryCode": "US",
            "zipCode": "12345",
            "address": "123 Main St",
            "state": "NY",
            "city": "Anytown"
          },
          "description": "Token for John Doe's Visa",
          "cardType": "VISA",
          "maskedCardNumber": "************0011",
          "cardExpDate": "1225"
        },
        "cardType": "VISA",
        "avsResult": "Y",
        "cvvResult": "M",
        "accountType": "Credit",
        "hostResponseText": "APPROVED 00"
      }
    ]
  }
}

Responses

200

Successful acknowledgement of a webhook event. The response should be a 200 OK status with an empty body.

application/json · object

SuccessfulWebhookResponse
{}

Void completed

POSTVoidCompleted to your webhook endpoint

This webhook event is triggered when a transaction void for a previously completed transaction is completed.

Parameters

NameInTypeDescription
x-fsk-wh-chksmheaderstring

Present on legacy deliveries, the delivery method every merchant has today. A lowercase hex-encoded HMAC-SHA256 of the raw request body, keyed with the shared secret provided by support for this endpoint. Carries no timestamp, so deduplicate on the payload's event.id to defend against replay. See Verifying the checksum.

Svix deliveries carry the svix-* headers instead. Svix webhooks are invite only; see Webhooks.

svix-idheaderstring

Present on Svix deliveries only. The unique message id for this delivery, constant across retries of the same message.

Svix webhooks are invite only. Most merchants receive legacy deliveries, which carry x-fsk-wh-chksm instead of the svix-* headers; see Webhooks.

svix-timestampheaderstring

Present on Svix deliveries only. The time the message was sent, as a Unix timestamp in seconds. Reject stale timestamps to protect against replay attacks. See Verifying signatures.

svix-signatureheaderstring

Present on Svix deliveries only. One or more space-delimited signatures in the form v1,<base64 signature> - an HMAC-SHA256 over {svix-id}.{svix-timestamp}.{raw request body} keyed with the endpoint's signing secret. See Verifying signatures.

Payload

The request body for the void.completed webhook event.

application/json · VoidCompletedWebhook

event object required

Webhook event details.

Child attributes
id string required

Unique ID for this webhook event.

Example: "evt_01JS21X856RR8R69GV5F17XK9C"

type string required

The type of event that occurred.

Example: "event.completed"

timestamp string (date-time) required

The time when the event was triggered (UTC).

Example: "2025-04-16T14:30:00Z"

merchantId string required

The merchant that owns the transaction or token.

Example: "mer_01JQZC2Y6W3F8XKT5H9DPNBMVR"

originalResponse VoidResponse required

Represents the response to a void request.

Child attributes
id string

Unique ID for this void transaction.

Example: "trx_01J2F0ZJ2JW5B63CJFPXRGAB1S"

timestamp string (date-time)

Transaction timestamp in UTC

Example: "2025-05-27T18:49:31Z"

type string

Type of transaction

Allowed: Sale, Auth, Capture, Refund, Void

Example: "Void"

status TransactionStatus

The processing lifecycle, separate from approval or decline. Pending waits for customer input; Submitted, Acknowledged, and Processing are in flight; AwaitingSettlement waits for a bank transfer outcome. Completed can be approved or declined: inspect resultCode and transactionResponses[].responseCode. Failed means processing stopped because of a technical issue. Abandoned means the customer did not complete the flow before submission. Both states close the request.

Allowed: Unknown, Created, Pending, Submitted, Acknowledged, Processing, AwaitingSettlement, Completed, Failed, Abandoned

Example: "Completed"

accountHolder object

Account holder information associated with the transaction

Child attributes
id string required

Account holder ID assigned by the API.

Example: "aho_01JRZPRGFF4J2SZC3HMDBYEN2J"

externalId string required

External account holder ID assigned by your application.

Example: "usr_1234567890123"

contact object

Contact information for the account holder. Only returned for Card Not Present transactions.

Child attributes
name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "60606"

address string

Example: "300 S Wacker Dr"

state string

Example: "IL"

city string

Example: "Chicago"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

paymentMethod object

The payment method used for this transaction.

Child attributes
id string required

The unique identifier of the payment method. This ID has a prefix that makes it human-readable (pmt_trm_ for physical terminals, pmt_vrt_ for virtual card terminals, pmt_ach_ for virtual ACH terminals, pmt_tkn_ for tokens, which store a card or an ACH bank account), but applications should always use the type field to determine the payment method type rather than parsing this ID.

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

The date and time (UTC) when this payment method token was removed from the system using the Remove Token endpoint. This parameter will only be returned if the token was removed/deleted from the system.

This field will be present in three scenarios:

  • As part of a successful Remove Token endpoint response
  • In token.removed webhook notifications
  • In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

  • Physical - A physical payment terminal for Card Present transactions
  • Virtual - A hosted payment form/iframe for Card Not Present transactions
  • VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
  • Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
  • VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
  • Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

Child attributes
name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "12345"

address string

Example: "123 Main St"

state string

Example: "NY"

city string

Example: "Anytown"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

cardType string

The type of card used for this transaction:

  • UNKNOWN - The card type is unknown
  • DEBIT - Debit Card
  • VISA - Visa Credit Card
  • MASTERCARD - MasterCard Credit Card
  • AMEX - American Express Credit Card
  • DINERS - Diners Club Credit Card
  • DISCOVER - Discover Credit Card
  • JCB - JCB Credit Card
  • UNIONPAY - UnionPay Credit Card
  • MAESTRO - Maestro Debit Card
  • GIFT - Gift Card
  • CASH - All-cash Transaction
  • EBT - Electronic Benefits Transfer Card
  • INTERAC - Interac (Canadian PIN-debit network), Card Present only
  • OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

  • For card tokens: Credit or Debit.
  • For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

invoiceNumber InvoiceNumber

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.

max length 100

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

referenceId ReferenceIdForResponse

The reference ID for this transaction. This will either be the reference ID provided in the transaction request or, if no value was provided, a value generated automatically by the system. This reference ID can be used for processing captures and referenced refunds by including it in the originalReferenceId field of subsequent transactions.

max length 100

Example: "ref_s192i49i"

originalTransactionId string

The trx_ ID of the earlier transaction this one belongs to, when the link has been verified. Set on card-present captures and voids, card-present Interac refunds, ACH refunds once the gateway confirms the original sale, ACH chargebacks (the charged-back sale), and ACH resubmissions (the original sale).

Absent when there is no verified link. That includes card-not-present captures, refunds, and voids, other card-present refunds, and older transactions recorded before the link was stored. Do not treat an absent value as proof that the transaction has no original.

Example: "trx_01JWBPE27KHY2K4J7A13ATQ786"

resultCode ResultCode

Result codes:

  • 0 - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)
  • 1003 - The payment terminal is busy or unavailable. (If this error persists, the user may need to close and re-open the Payment Application on the terminal or restart the terminal)
  • 1005 - The specified terminal could not be found.
  • 1010 - The transaction request is pending to become transaction.
  • 2014 - The payment method or card brand is not enabled for the merchant. resultText carries the message, such as ACH payments are not enabled for this merchant. or Visa cards are not enabled for this merchant. The transaction is Completed and failed; do not retry it with the same payment method.
  • 3000 - An unexpected error occurred. Please try again.
  • 3002 - The transaction could not be completed because the payment terminal could not find the related transaction.
  • 3005 - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.
  • 3006 - The transaction could not be completed because the payment terminal is low on battery.
  • 3009 - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.
  • 3010 - The transaction took too long and was cancelled by the application.
  • 3011 - Invalid transaction request. Please consult the documentation for valid transaction requests.
  • 3012 - Invalid transaction request. paymentMethodId is invalid.
  • 3013 - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.
  • 3014 - Invalid amount. Please try your transaction again with an amount greater than $0.
  • 3020 - An unsupported transaction result was received.
  • 4001 - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.
  • 6800 - 3D Secure authentication was rejected by the issuer's ACS (card auth failed, security failure, stolen card, suspected fraud, etc.). Surfaced on declined CNP transactions when formConfig.enable3DSecure: true and the gateway reports a 3D Secure reason; other failures in a 3D Secure session use 6900-6902. See SDK Error Codes for guidance.
  • 6801 - 3D Secure authentication could not be completed because of an upstream technical issue (ACS timeout, directory server unreachable). Retry later or, if merchant policy allows, retry with 3DS disabled.
  • 6802 - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.
  • 6900 - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText. See SDK Error Codes for guidance.
  • 6901 - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision. See SDK Error Codes for guidance.
  • 6902 - The gateway reported no failure but returned no payment token. See SDK Error Codes for guidance.
  • 9998 - The system is not ready to process a transaction.
  • 9999 - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.
  • 1010 - The transaction request is pending customer interaction.
  • 4100 - Cardholder verification is required. Follow threeDsChallenge.redirectUrl and reconcile the final transaction outcome before retrying.
  • 55 - The customer cancelled the hosted payment attempt.

Allowed: 0, 55, 1003, 1005, 1010, 2014, 3000, 3002, 3005, 3006, 3009, 3010, 3011, 3012, 3013, 3014, 3020, 4001, 4100, 6800, 6801, 6802, 6900, 6901, 6902, 9998, 9999

Example: 0

resultText ResultText

A message describing the result code in more detail. On a stored transaction it is uppercase, such as APPROVED, DECLINED, or the gateway's reason, except for resultCode 2014, where it is the message in sentence case. Use it for display, not for branching.

Example: "APPROVED"

requestedAmount integer

The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization.

Example: 1000

approvedAmount integer

The approved amount in minor units. This is 0 for a decline or an outcome that is still in flight. A terminal may adjust the amount, for example by adding a tip.

Example: 1000

transactionResponses array of TransactionResponse

Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.

Child attributes
responseCode ResponseCode

The outcome of the payment, and the field that tells you whether the transaction succeeded. The HTTP status, resultCode, and status do not. A transaction succeeded only when status is Completed and a transaction response has responseCode 1 or 2.

Outcomes:

  • Approved - 1, 2. For 2, only amountApproved was approved. On a Chargeback transaction, approved means the chargeback took effect: the money went back to the payer.
  • Declined - 10 to 18. The issuer or bank refused the payment. Do not retry with the same payment details.
  • Canceled - 54, 55. No money moved.
  • Pending - 57. The outcome is not final. Wait for the webhook or query the transaction again.
  • Unknown - 0. No specific code was reported. While status is not Completed, the outcome is not final. On a Completed transaction it is not an approval: read resultCode and resultText for the reason, for example 2014, 6901, or 6902.
  • Error - every other code. Processing failed for a technical or request reason.

See Transaction response codes.

Response codes:

  • 0 - UNKNOWN
  • 1 - APPROVED - Transaction was approved
  • 2 - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.
  • 10 - DECLINED - Transaction was declined by the issuer or bank. For Card-Present, the transaction can also be declined offline by the terminal.
  • 11 - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.
  • 12 - CARD_EXPIRED - The card used for the transaction has expired.
  • 13 - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.
  • 14 - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).
  • 15 - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).
  • 16 - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).
  • 17 - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.
  • 18 - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.
  • 19 - BATCH_EMPTY - Indicates that the batch for processing is empty.
  • 20 - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).
  • 21 - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.
  • 50 - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.
  • 51 - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.
  • 52 - NOT_SUPPORTED - Rejected because the requested operation is not supported.
  • 53 - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.
  • 54 - CANCELLED - Cancelled by the user or merchant.
  • 55 - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.
  • 56 - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.
  • 57 - PENDING - The transaction is awaiting an asynchronous outcome.

Allowed: 0, 1, 2, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 50, 51, 52, 53, 54, 55, 56, 57

authCode string

The authorization code provided by the card issuer, confirming transaction approval.

Example: "123456"

amountApproved integer

The amount approved for this transaction response.

Example: 1000

approvedAmountBreakdown ApprovedAmountBreakdown

A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.

Child attributes
amountGoodsAndServices integer

The approved amount for goods and services.

Example: 900

tax integer

The approved tax amount.

Example: 100

cashback integer

The approved cashback amount.

Example: 0

tip integer

The approved tip amount.

Example: 0

paymentMethod object

The payment method used for this transaction.

Child attributes
id string required

The unique identifier of the payment method. This ID has a prefix that makes it human-readable (pmt_trm_ for physical terminals, pmt_vrt_ for virtual card terminals, pmt_ach_ for virtual ACH terminals, pmt_tkn_ for tokens, which store a card or an ACH bank account), but applications should always use the type field to determine the payment method type rather than parsing this ID.

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

The date and time (UTC) when this payment method token was removed from the system using the Remove Token endpoint. This parameter will only be returned if the token was removed/deleted from the system.

This field will be present in three scenarios:

  • As part of a successful Remove Token endpoint response
  • In token.removed webhook notifications
  • In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

  • Physical - A physical payment terminal for Card Present transactions
  • Virtual - A hosted payment form/iframe for Card Not Present transactions
  • VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
  • Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
  • VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
  • Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

cardType string

The type of card used for this transaction:

  • UNKNOWN - The card type is unknown
  • DEBIT - Debit Card
  • VISA - Visa Credit Card
  • MASTERCARD - MasterCard Credit Card
  • AMEX - American Express Credit Card
  • DINERS - Diners Club Credit Card
  • DISCOVER - Discover Credit Card
  • JCB - JCB Credit Card
  • UNIONPAY - UnionPay Credit Card
  • MAESTRO - Maestro Debit Card
  • GIFT - Gift Card
  • CASH - All-cash Transaction
  • EBT - Electronic Benefits Transfer Card
  • INTERAC - Interac (Canadian PIN-debit network), Card Present only
  • OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

  • For card tokens: Credit or Debit.
  • For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

cardType CardType

The type of card used for this transaction:

  • UNKNOWN - The card type is unknown
  • DEBIT - Debit Card
  • VISA - Visa Credit Card
  • MASTERCARD - MasterCard Credit Card
  • AMEX - American Express Credit Card
  • DINERS - Diners Club Credit Card
  • DISCOVER - Discover Credit Card
  • JCB - JCB Credit Card
  • UNIONPAY - UnionPay Credit Card
  • MAESTRO - Maestro Debit Card
  • GIFT - Gift Card
  • CASH - All-cash Transaction
  • EBT - Electronic Benefits Transfer Card
  • INTERAC - Interac (Canadian PIN-debit network), Card Present only
  • OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

avsResult AVSResult

The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.

  • A - Address matches, ZIP does not. The first five numerical characters contained in the address match those stored at the VIC or issuer's center. However, the ZIP code does not match.
  • E - Ineligible transaction.
  • N - Neither address nor ZIP matches. Neither the first five numerical characters contained in the address match with those stored at the VIC nor issuer's center nor the ZIP code match.
  • R - Retry (system unavailable or timed out).
  • S - Card type not supported. The card type for this transaction is not supported by AVS. AVS can verify addresses for Visa cards, MasterCard, proprietary cards, and private label transactions.
  • U - Address information unavailable.
  • G - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.
  • W - Nine-digit ZIP match, address does not. The nine-digit Postal ZIP code matches that stored at the VIC or card issuer's centre. However, the first five numerical characters contained in the address do not match.
  • X - Exact match (nine digit ZIP and address). Both the nine-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
  • Y - Address and five-digit ZIP match. Both the five-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
  • Z - Five-digit ZIP matches, address does not. The five-digit Postal ZIP code matches that stored at the VIC or card issuer's centre.

NOTE: Transactions can still be authorized if the AVS responses are no match or failure. AVS responses are for merchant information only, and usually do not influence the overall Authorization result. This can vary based on the Issuing Bank.

Allowed: A, E, N, R, S, U, G, W, X, Y, Z

cvvResult CVVResult

The CVV verification result. Typically returned on Card Not Present transactions.

  • M - CVV Match
  • N - CVV No Match
  • P - Not Processed
  • S - CVV should be on the card but the merchant indicates it is not.
  • U - User is unregistered

NOTE: Transactions can still be authorized if the CVV responses are no match or failure. CVV responses are for merchant information only, and usually do not influence the overall Authorization result. This can vary based on the Issuing Bank.

Allowed: M, N, P, S, U

accountType string

The funding-source classification associated with the payment method used in this transaction.

  • For credit/debit cards: Credit or Debit. May be null when the classification is unavailable, including on older transactions.
  • For ACH/EFT bank accounts: Checking or Savings.

The immediate hosted ACH response uses lowercase checking or savings. Retrieved transaction responses normally use Checking or Savings.

Allowed: Credit, Debit, Checking, Savings, checking, savings

Example: "Credit"

hostResponseText string

A meaningful text explaining the response code from the host.

Example: "APPROVED 00"

receipt Receipt

Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.

Child attributes
lines array of string required

The receipt lines.

sourceId string

Identifier of the session or other source that initiated the transaction.

threeDs ThreeDsAuthentication

3D Secure (EMV 3DS2) authentication outcome. Populated on transactions initiated with formConfig.enable3DSecure: true. All fields (other than status) are optional - what the issuer returns depends on whether the transaction was frictionless, challenged, or declined.

Child attributes
status string

The authentication outcome to use in your integration. The other threeDs fields provide supporting authentication data.

Allowed: Authenticated, Attempted, NotAuthenticated, Failed, Unavailable, NotEnrolled

Example: "Authenticated"

cavv string

Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions.

Example: "AAABBkgwVoRhY2tcYlZGAAAAAAA="

eci string

E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:

  • 02 / 05 - Fully authenticated (liability shift to issuer).
  • 01 / 06 - Attempted authentication (partial liability shift).
  • 00 / 07 - Not authenticated (no liability shift).

Example: "05"

xid string

3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility.

Example: "MDAwMDAwMDAwMDAwMDAwMTM3MDI="

dsTransId string

Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction.

Example: "b71a7d5d-cc38-4ce9-80c3-50a7d53271f7"

threeDReasonId string

Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use status to handle the outcome and threeDReason for the explanation.

Example: "10"

threeDReason string

Human-readable description matching threeDReasonId.

Example: "Stolen Card"

threeDsChallenge ThreeDsChallenge

Present when a token payment requires a cardholder challenge (resultCode: 4100).

Child attributes
redirectUrl string (uri) required

Hosted URL where the cardholder completes the challenge.

followUpToken string required

Opaque token identifying the pending challenge.

balanceAmount integer

The balance that remains to be paid on the transaction. This amount is always an integer in the smallest denomination of the currency (e.g. cents for USD or CAD).

Example: 0

Example
{
  "event": {
    "id": "evt_01JS21X856RR8R69GV5F17XK9C",
    "type": "void.completed",
    "timestamp": "2025-05-27T18:49:31Z",
    "merchantId": "mer_01JQZC2Y6W3F8XKT5H9DPNBMVR"
  },
  "originalResponse": {
    "id": "trx_01J2F0ZJ2JW5B63CJFPXRGAB1S",
    "timestamp": "2025-05-27T18:49:31Z",
    "type": "Void",
    "status": "Completed",
    "accountHolder": {
      "id": "aho_01JRZPRGFF4J2SZC3HMDBYEN2J",
      "externalId": "usr_1234567890123",
      "contact": {
        "name": "John Doe",
        "countryCode": "US",
        "zipCode": "60606",
        "address": "300 S Wacker Dr",
        "state": "IL",
        "city": "Chicago"
      }
    },
    "paymentMethod": {
      "id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
      "type": "Token",
      "currency": "USD",
      "description": "Token for John Doe's Visa",
      "billingContact": {
        "name": "John Doe",
        "countryCode": "US",
        "zipCode": "12345",
        "address": "123 Main St",
        "state": "NY",
        "city": "Anytown"
      },
      "cardType": "VISA",
      "maskedCardNumber": "************0011",
      "cardExpDate": "1225"
    },
    "invoiceNumber": "inv_1234567890123456",
    "orderNumber": "order_number_1234",
    "referenceId": "ref_s192i49i",
    "resultCode": 0,
    "resultText": "APPROVED",
    "requestedAmount": 1000,
    "approvedAmount": 1000,
    "transactionResponses": [
      {
        "responseCode": 1,
        "authCode": "123456",
        "amountApproved": 1000,
        "approvedAmountBreakdown": {
          "amountGoodsAndServices": 900,
          "tax": 100,
          "cashback": 0,
          "tip": 0
        },
        "paymentMethod": {
          "id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
          "type": "Token",
          "currency": "USD",
          "description": "Token for John Doe's Visa",
          "billingContact": {
            "name": "John Doe",
            "countryCode": "US",
            "zipCode": "12345",
            "address": "123 Main St",
            "state": "NY",
            "city": "Anytown"
          },
          "cardType": "VISA",
          "maskedCardNumber": "************0011",
          "cardExpDate": "1225"
        },
        "cardType": "VISA",
        "avsResult": "Y",
        "cvvResult": "M",
        "accountType": "Credit",
        "hostResponseText": "APPROVED 00",
        "receipt": {
          "lines": [
            "     Test Merchant      ",
            "      300 S Wacker      ",
            "         Loop,          ",
            "                        ",
            "                        ",
            "TERM #          11000367",
            "RECORD #         0656191",
            "HOST INVOICE #    000038",
            "HOST SEQ #    1720656191",
            "MERCH                   ",
            "INVOICE inv_123456789012",
            "        3456",
            "------------------------",
            "CARD    ************0011",
            "VISA             Contact",
            "07/10/2024      20:03:05",
            "------------------------",
            "       VOID SALE        ",
            "                        ",
            "TOTAL         USD $10.00",
            "------------------------",
            "AUTH#:123456       B:171",
            "                        ",
            "      APPROVED 00       ",
            "       THANK YOU        ",
            "                        ",
            "      Visa Credit       ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "     MERCHANT COPY      ",
            "     Test Merchant      ",
            "      300 S Wacker      ",
            "         Loop,          ",
            "                        ",
            "                        ",
            "TERM #          11000367",
            "RECORD #         0656191",
            "HOST INVOICE #    000038",
            "HOST SEQ #    1720656191",
            "MERCH                   ",
            "INVOICE inv_123456789012",
            "        3456",
            "------------------------",
            "CARD    ************0011",
            "VISA             Contact",
            "07/10/2024      20:03:05",
            "------------------------",
            "       VOID SALE        ",
            "                        ",
            "TOTAL         USD $10.00",
            "------------------------",
            "AUTH#:123456       B:171",
            "                        ",
            "      APPROVED 00       ",
            "       THANK YOU        ",
            "                        ",
            "      Visa Credit       ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "                        ",
            "     CUSTOMER COPY      "
          ]
        }
      }
    ]
  }
}

Responses

200

Successful acknowledgement of a webhook event. The response should be a 200 OK status with an empty body.

application/json · object

SuccessfulWebhookResponse
{}

Chargeback completed

POSTChargebackCompleted to your webhook endpoint

This webhook event is triggered when the payer's bank returns an ACH payment after the funds reached the merchant. The payload is a new transaction with type Chargeback; the original sale is not changed, and originalTransactionId identifies it. Each charged-back sale produces one chargeback.

On legacy webhooks, an endpoint receives this event only when it is configured for it. On Svix webhooks, an endpoint that is filtered to specific event types must add chargeback.completed.

Parameters

NameInTypeDescription
x-fsk-wh-chksmheaderstring

Present on legacy deliveries, the delivery method every merchant has today. A lowercase hex-encoded HMAC-SHA256 of the raw request body, keyed with the shared secret provided by support for this endpoint. Carries no timestamp, so deduplicate on the payload's event.id to defend against replay. See Verifying the checksum.

Svix deliveries carry the svix-* headers instead. Svix webhooks are invite only; see Webhooks.

svix-idheaderstring

Present on Svix deliveries only. The unique message id for this delivery, constant across retries of the same message.

Svix webhooks are invite only. Most merchants receive legacy deliveries, which carry x-fsk-wh-chksm instead of the svix-* headers; see Webhooks.

svix-timestampheaderstring

Present on Svix deliveries only. The time the message was sent, as a Unix timestamp in seconds. Reject stale timestamps to protect against replay attacks. See Verifying signatures.

svix-signatureheaderstring

Present on Svix deliveries only. One or more space-delimited signatures in the form v1,<base64 signature> - an HMAC-SHA256 over {svix-id}.{svix-timestamp}.{raw request body} keyed with the endpoint's signing secret. See Verifying signatures.

Payload

The request body for the chargeback.completed webhook event.

application/json · ChargebackCompletedWebhook

event object required

Webhook event details.

Child attributes
id string required

Unique ID for this webhook event.

Example: "evt_01JS21X856RR8R69GV5F17XK9C"

type string required

The type of event that occurred.

Example: "event.completed"

timestamp string (date-time) required

The time when the event was triggered (UTC).

Example: "2025-04-16T14:30:00Z"

merchantId string required

The merchant that owns the transaction or token.

Example: "mer_01JQZC2Y6W3F8XKT5H9DPNBMVR"

originalResponse TransactionResponseObject required

Represents the response to a sale or authorization transaction.

Child attributes
id string

Unique ID for this transaction.

Example: "trx_01J2F0EKHC7HY2R93C8ENBD1FG"

timestamp string (date-time)

Transaction timestamp in UTC

Example: "2025-05-27T18:49:31Z"

type string

Type of transaction.

Chargeback records an ACH payment that the payer's bank returned after the funds reached the merchant. It is a separate transaction: the original sale is not changed and stays approved. originalTransactionId holds the sale's ID, and the amount is the returned amount. Its approved outcome (resultCode 0, responseCode 1) means the chargeback took effect and the money went back to the payer. See Chargebacks.

Treat this list as open: ignore a value your integration does not recognize instead of rejecting the transaction.

Allowed: Sale, Auth, Capture, Refund, Void, Chargeback

Example: "Sale"

status TransactionStatus

The processing lifecycle, separate from approval or decline. Pending waits for customer input; Submitted, Acknowledged, and Processing are in flight; AwaitingSettlement waits for a bank transfer outcome. Completed can be approved or declined: inspect resultCode and transactionResponses[].responseCode. Failed means processing stopped because of a technical issue. Abandoned means the customer did not complete the flow before submission. Both states close the request.

Allowed: Unknown, Created, Pending, Submitted, Acknowledged, Processing, AwaitingSettlement, Completed, Failed, Abandoned

Example: "Completed"

accountHolder object

Account holder information associated with the transaction

Child attributes
id string required

Account holder ID assigned by the API.

Example: "aho_01JRZPRGFF4J2SZC3HMDBYEN2J"

externalId string required

External account holder ID assigned by your application.

Example: "usr_1234567890123"

contact object

Contact information for the account holder. Only returned for Card Not Present transactions.

Child attributes
name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "60606"

address string

Example: "300 S Wacker Dr"

state string

Example: "IL"

city string

Example: "Chicago"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

paymentMethod object

The payment method used for this transaction.

Child attributes
id string required

The unique identifier of the payment method. This ID has a prefix that makes it human-readable (pmt_trm_ for physical terminals, pmt_vrt_ for virtual card terminals, pmt_ach_ for virtual ACH terminals, pmt_tkn_ for tokens, which store a card or an ACH bank account), but applications should always use the type field to determine the payment method type rather than parsing this ID.

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

The date and time (UTC) when this payment method token was removed from the system using the Remove Token endpoint. This parameter will only be returned if the token was removed/deleted from the system.

This field will be present in three scenarios:

  • As part of a successful Remove Token endpoint response
  • In token.removed webhook notifications
  • In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

  • Physical - A physical payment terminal for Card Present transactions
  • Virtual - A hosted payment form/iframe for Card Not Present transactions
  • VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
  • Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
  • VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
  • Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

Child attributes
name string

Example: "John Doe"

countryCode string

Example: "US"

zipCode string

Example: "12345"

address string

Example: "123 Main St"

state string

Example: "NY"

city string

Example: "Anytown"

address2 string

Additional address information, when supplied.

Example: "Suite 200"

cardType string

The type of card used for this transaction:

  • UNKNOWN - The card type is unknown
  • DEBIT - Debit Card
  • VISA - Visa Credit Card
  • MASTERCARD - MasterCard Credit Card
  • AMEX - American Express Credit Card
  • DINERS - Diners Club Credit Card
  • DISCOVER - Discover Credit Card
  • JCB - JCB Credit Card
  • UNIONPAY - UnionPay Credit Card
  • MAESTRO - Maestro Debit Card
  • GIFT - Gift Card
  • CASH - All-cash Transaction
  • EBT - Electronic Benefits Transfer Card
  • INTERAC - Interac (Canadian PIN-debit network), Card Present only
  • OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

  • For card tokens: Credit or Debit.
  • For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

invoiceNumber InvoiceNumber

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.

max length 100

Example: "inv_1234567890123456"

orderNumber OrderNumber

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

max length 100

Example: "order_number_1234"

referenceId ReferenceIdForResponse

The reference ID for this transaction. This will either be the reference ID provided in the transaction request or, if no value was provided, a value generated automatically by the system. This reference ID can be used for processing captures and referenced refunds by including it in the originalReferenceId field of subsequent transactions.

max length 100

Example: "ref_s192i49i"

originalTransactionId string

The trx_ ID of the earlier transaction this one belongs to, when the link has been verified. Set on card-present captures and voids, card-present Interac refunds, ACH refunds once the gateway confirms the original sale, ACH chargebacks (the charged-back sale), and ACH resubmissions (the original sale).

Absent when there is no verified link. That includes card-not-present captures, refunds, and voids, other card-present refunds, and older transactions recorded before the link was stored. Do not treat an absent value as proof that the transaction has no original.

Example: "trx_01JWBPE27KHY2K4J7A13ATQ786"

resultCode ResultCode

Result codes:

  • 0 - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)
  • 1003 - The payment terminal is busy or unavailable. (If this error persists, the user may need to close and re-open the Payment Application on the terminal or restart the terminal)
  • 1005 - The specified terminal could not be found.
  • 1010 - The transaction request is pending to become transaction.
  • 2014 - The payment method or card brand is not enabled for the merchant. resultText carries the message, such as ACH payments are not enabled for this merchant. or Visa cards are not enabled for this merchant. The transaction is Completed and failed; do not retry it with the same payment method.
  • 3000 - An unexpected error occurred. Please try again.
  • 3002 - The transaction could not be completed because the payment terminal could not find the related transaction.
  • 3005 - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.
  • 3006 - The transaction could not be completed because the payment terminal is low on battery.
  • 3009 - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.
  • 3010 - The transaction took too long and was cancelled by the application.
  • 3011 - Invalid transaction request. Please consult the documentation for valid transaction requests.
  • 3012 - Invalid transaction request. paymentMethodId is invalid.
  • 3013 - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.
  • 3014 - Invalid amount. Please try your transaction again with an amount greater than $0.
  • 3020 - An unsupported transaction result was received.
  • 4001 - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.
  • 6800 - 3D Secure authentication was rejected by the issuer's ACS (card auth failed, security failure, stolen card, suspected fraud, etc.). Surfaced on declined CNP transactions when formConfig.enable3DSecure: true and the gateway reports a 3D Secure reason; other failures in a 3D Secure session use 6900-6902. See SDK Error Codes for guidance.
  • 6801 - 3D Secure authentication could not be completed because of an upstream technical issue (ACS timeout, directory server unreachable). Retry later or, if merchant policy allows, retry with 3DS disabled.
  • 6802 - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.
  • 6900 - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText. See SDK Error Codes for guidance.
  • 6901 - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision. See SDK Error Codes for guidance.
  • 6902 - The gateway reported no failure but returned no payment token. See SDK Error Codes for guidance.
  • 9998 - The system is not ready to process a transaction.
  • 9999 - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.
  • 1010 - The transaction request is pending customer interaction.
  • 4100 - Cardholder verification is required. Follow threeDsChallenge.redirectUrl and reconcile the final transaction outcome before retrying.
  • 55 - The customer cancelled the hosted payment attempt.

Allowed: 0, 55, 1003, 1005, 1010, 2014, 3000, 3002, 3005, 3006, 3009, 3010, 3011, 3012, 3013, 3014, 3020, 4001, 4100, 6800, 6801, 6802, 6900, 6901, 6902, 9998, 9999

Example: 0

resultText ResultText

A message describing the result code in more detail. On a stored transaction it is uppercase, such as APPROVED, DECLINED, or the gateway's reason, except for resultCode 2014, where it is the message in sentence case. Use it for display, not for branching.

Example: "APPROVED"

requestedAmount integer

The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization.

Example: 1000

approvedAmount integer

The approved amount in minor units. This is 0 for a decline or an outcome that is still in flight. A terminal may adjust the amount, for example by adding a tip.

Example: 1000

balanceAmount integer

The balance that remains to be paid on the transaction. This amount is always an integer in the smallest denomination of the currency (e.g. cents for USD or CAD).

Example: 0

refundableAmount integer

The amount that can still be refunded against this sale or capture, in the smallest denomination of the currency. Normally available within seconds of approval. Absent for authorizations, refunds, voids, and declined transactions; it can also be absent briefly after a sale or capture is approved. Absence does not mean unlimited; it means this value is not yet available or not applicable. An ACH chargeback reduces it like a refund. 0 means fully refunded, voided, or charged back.

Example: 1000

transactionResponses array of object

Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.

Child attributes
responseCode ResponseCode

The outcome of the payment, and the field that tells you whether the transaction succeeded. The HTTP status, resultCode, and status do not. A transaction succeeded only when status is Completed and a transaction response has responseCode 1 or 2.

Outcomes:

  • Approved - 1, 2. For 2, only amountApproved was approved. On a Chargeback transaction, approved means the chargeback took effect: the money went back to the payer.
  • Declined - 10 to 18. The issuer or bank refused the payment. Do not retry with the same payment details.
  • Canceled - 54, 55. No money moved.
  • Pending - 57. The outcome is not final. Wait for the webhook or query the transaction again.
  • Unknown - 0. No specific code was reported. While status is not Completed, the outcome is not final. On a Completed transaction it is not an approval: read resultCode and resultText for the reason, for example 2014, 6901, or 6902.
  • Error - every other code. Processing failed for a technical or request reason.

See Transaction response codes.

Response codes:

  • 0 - UNKNOWN
  • 1 - APPROVED - Transaction was approved
  • 2 - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.
  • 10 - DECLINED - Transaction was declined by the issuer or bank. For Card-Present, the transaction can also be declined offline by the terminal.
  • 11 - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.
  • 12 - CARD_EXPIRED - The card used for the transaction has expired.
  • 13 - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.
  • 14 - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).
  • 15 - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).
  • 16 - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).
  • 17 - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.
  • 18 - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.
  • 19 - BATCH_EMPTY - Indicates that the batch for processing is empty.
  • 20 - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).
  • 21 - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.
  • 50 - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.
  • 51 - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.
  • 52 - NOT_SUPPORTED - Rejected because the requested operation is not supported.
  • 53 - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.
  • 54 - CANCELLED - Cancelled by the user or merchant.
  • 55 - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.
  • 56 - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.
  • 57 - PENDING - The transaction is awaiting an asynchronous outcome.

Allowed: 0, 1, 2, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 50, 51, 52, 53, 54, 55, 56, 57

authCode string

The authorization code provided by the card issuer, confirming transaction approval.

Example: "123456"

amountApproved integer

The amount approved for this transaction response.

Example: 1000

approvedAmountBreakdown ApprovedAmountBreakdown

A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.

Child attributes
amountGoodsAndServices integer

The approved amount for goods and services.

Example: 900

tax integer

The approved tax amount.

Example: 100

cashback integer

The approved cashback amount.

Example: 0

tip integer

The approved tip amount.

Example: 0

paymentMethod object

The payment method used for this transaction.

Child attributes
id string required

The unique identifier of the payment method. This ID has a prefix that makes it human-readable (pmt_trm_ for physical terminals, pmt_vrt_ for virtual card terminals, pmt_ach_ for virtual ACH terminals, pmt_tkn_ for tokens, which store a card or an ACH bank account), but applications should always use the type field to determine the payment method type rather than parsing this ID.

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

The date and time (UTC) when this payment method token was removed from the system using the Remove Token endpoint. This parameter will only be returned if the token was removed/deleted from the system.

This field will be present in three scenarios:

  • As part of a successful Remove Token endpoint response
  • In token.removed webhook notifications
  • In List Transactions responses for transactions where the associated token was later removed

When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.

Example: "2025-07-14T14:05:48.869225Z"

type string required

The type of payment method:

  • Physical - A physical payment terminal for Card Present transactions
  • Virtual - A hosted payment form/iframe for Card Not Present transactions
  • VirtualAch - A hosted payment form/iframe for ACH (US) bank transfer transactions
  • Token - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions
  • VirtualEft - A virtual Canadian bank-transfer payment method, when configured.
  • Unknown - The payment method type is not known.

Allowed: Unknown, Physical, Virtual, VirtualAch, VirtualEft, Token

Example: "Token"

currency string required

The currency of the payment method.

Allowed: USD, CAD

Example: "USD"

description string

A human-readable name for the payment method.

Example: "Token for John Doe's Visa"

billingContact object

Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.

cardType string

The type of card used for this transaction:

  • UNKNOWN - The card type is unknown
  • DEBIT - Debit Card
  • VISA - Visa Credit Card
  • MASTERCARD - MasterCard Credit Card
  • AMEX - American Express Credit Card
  • DINERS - Diners Club Credit Card
  • DISCOVER - Discover Credit Card
  • JCB - JCB Credit Card
  • UNIONPAY - UnionPay Credit Card
  • MAESTRO - Maestro Debit Card
  • GIFT - Gift Card
  • CASH - All-cash Transaction
  • EBT - Electronic Benefits Transfer Card
  • INTERAC - Interac (Canadian PIN-debit network), Card Present only
  • OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

Example: "VISA"

maskedCardNumber string

The masked card number. The format may vary (e.g. **0011, 4**0011, etc.)

Example: "************0011"

cardExpDate string

The expiration date of the card in MMYY format.

Example: "1225"

accountType string

Funding-source classification of this token-type payment method.

  • For card tokens: Credit or Debit.
  • For ACH tokens: Checking or Savings. May be omitted for older tokens that pre-date this field, for non-token payment methods, or when the source did not provide a classification.

Allowed: Credit, Debit, Checking, Savings

Example: "Debit"

accountNumber string

Masked bank account number, when available for a bank-account token.

Example: "*****6789"

cardType CardType

The type of card used for this transaction:

  • UNKNOWN - The card type is unknown
  • DEBIT - Debit Card
  • VISA - Visa Credit Card
  • MASTERCARD - MasterCard Credit Card
  • AMEX - American Express Credit Card
  • DINERS - Diners Club Credit Card
  • DISCOVER - Discover Credit Card
  • JCB - JCB Credit Card
  • UNIONPAY - UnionPay Credit Card
  • MAESTRO - Maestro Debit Card
  • GIFT - Gift Card
  • CASH - All-cash Transaction
  • EBT - Electronic Benefits Transfer Card
  • INTERAC - Interac (Canadian PIN-debit network), Card Present only
  • OTHER - Other tender types

Allowed: UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, INTERAC, OTHER

avsResult AVSResult

The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.

  • A - Address matches, ZIP does not. The first five numerical characters contained in the address match those stored at the VIC or issuer's center. However, the ZIP code does not match.
  • E - Ineligible transaction.
  • N - Neither address nor ZIP matches. Neither the first five numerical characters contained in the address match with those stored at the VIC nor issuer's center nor the ZIP code match.
  • R - Retry (system unavailable or timed out).
  • S - Card type not supported. The card type for this transaction is not supported by AVS. AVS can verify addresses for Visa cards, MasterCard, proprietary cards, and private label transactions.
  • U - Address information unavailable.
  • G - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.
  • W - Nine-digit ZIP match, address does not. The nine-digit Postal ZIP code matches that stored at the VIC or card issuer's centre. However, the first five numerical characters contained in the address do not match.
  • X - Exact match (nine digit ZIP and address). Both the nine-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
  • Y - Address and five-digit ZIP match. Both the five-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
  • Z - Five-digit ZIP matches, address does not. The five-digit Postal ZIP code matches that stored at the VIC or card issuer's centre.

NOTE: Transactions can still be authorized if the AVS responses are no match or failure. AVS responses are for merchant information only, and usually do not influence the overall Authorization result. This can vary based on the Issuing Bank.

Allowed: A, E, N, R, S, U, G, W, X, Y, Z

cvvResult CVVResult

The CVV verification result. Typically returned on Card Not Present transactions.

  • M - CVV Match
  • N - CVV No Match
  • P - Not Processed
  • S - CVV should be on the card but the merchant indicates it is not.
  • U - User is unregistered

NOTE: Transactions can still be authorized if the CVV responses are no match or failure. CVV responses are for merchant information only, and usually do not influence the overall Authorization result. This can vary based on the Issuing Bank.

Allowed: M, N, P, S, U

accountType string

The funding-source classification associated with the payment method used in this transaction.

  • For credit/debit cards: Credit or Debit. May be null when the classification is unavailable, including on older transactions.
  • For ACH/EFT bank accounts: Checking or Savings.

The immediate hosted ACH response uses lowercase checking or savings. Retrieved transaction responses normally use Checking or Savings.

Allowed: Credit, Debit, Checking, Savings, checking, savings

Example: "Credit"

hostResponseText string

A meaningful text explaining the response code from the host.

Example: "APPROVED 00"

receipt Receipt

Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.

Child attributes
lines array of string required

The receipt lines.

sourceId string

Identifier of the session or other source that initiated the transaction. For an ACH chargeback, it is the chargeback's own trx_ ID, or the billing subscription ID when the charged-back sale was a subscription payment.

threeDs ThreeDsAuthentication

3D Secure (EMV 3DS2) authentication outcome. Populated on transactions initiated with formConfig.enable3DSecure: true. All fields (other than status) are optional - what the issuer returns depends on whether the transaction was frictionless, challenged, or declined.

Child attributes
status string

The authentication outcome to use in your integration. The other threeDs fields provide supporting authentication data.

Allowed: Authenticated, Attempted, NotAuthenticated, Failed, Unavailable, NotEnrolled

Example: "Authenticated"

cavv string

Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions.

Example: "AAABBkgwVoRhY2tcYlZGAAAAAAA="

eci string

E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:

  • 02 / 05 - Fully authenticated (liability shift to issuer).
  • 01 / 06 - Attempted authentication (partial liability shift).
  • 00 / 07 - Not authenticated (no liability shift).

Example: "05"

xid string

3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility.

Example: "MDAwMDAwMDAwMDAwMDAwMTM3MDI="

dsTransId string

Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction.

Example: "b71a7d5d-cc38-4ce9-80c3-50a7d53271f7"

threeDReasonId string

Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use status to handle the outcome and threeDReason for the explanation.

Example: "10"

threeDReason string

Human-readable description matching threeDReasonId.

Example: "Stolen Card"

threeDsChallenge ThreeDsChallenge

Present when a token payment requires a cardholder challenge (resultCode: 4100).

Child attributes
redirectUrl string (uri) required

Hosted URL where the cardholder completes the challenge.

followUpToken string required

Opaque token identifying the pending challenge.

Example
{
  "event": {
    "id": "evt_01JWBPE2A3S7D9F2G4H6J8K0LM",
    "type": "chargeback.completed",
    "timestamp": "2025-06-03T15:12:09Z",
    "merchantId": "mer_01JQZC2Y6W3F8XKT5H9DPNBMVR"
  },
  "originalResponse": {
    "id": "trx_01JWBPE27MZ8Q4R1T6V3XKAHB2",
    "timestamp": "2025-06-03T15:12:08Z",
    "type": "Chargeback",
    "status": "Completed",
    "originalTransactionId": "trx_01JWBPE27KHY2K4J7A13ATQ786",
    "sourceId": "trx_01JWBPE27MZ8Q4R1T6V3XKAHB2",
    "accountHolder": {
      "id": "aho_01JRZPRGFF4J2SZC3HMDBYEN2J",
      "externalId": "usr_1234567890123"
    },
    "paymentMethod": {
      "id": "pmt_tkn_01JRZQT5HXNG73E9JKTPK4Z6WC",
      "type": "Token",
      "currency": "USD"
    },
    "invoiceNumber": "inv_1234567890123456",
    "orderNumber": "order_number_1234",
    "referenceId": "ref_s192i49i-chargeback",
    "resultCode": 0,
    "resultText": "APPROVED",
    "requestedAmount": 1000,
    "approvedAmount": 1000,
    "transactionResponses": [
      {
        "responseCode": 1,
        "amountApproved": 1000,
        "paymentMethod": {
          "id": "pmt_tkn_01JRZQT5HXNG73E9JKTPK4Z6WC",
          "type": "Token",
          "currency": "USD",
          "accountNumber": "*****6789",
          "accountType": "Checking"
        },
        "accountType": "Checking"
      }
    ]
  }
}

Responses

200

Successful acknowledgement of a webhook event. The response should be a 200 OK status with an empty body.

application/json · object

SuccessfulWebhookResponse
{}

Questions about your integration? Contact support@doura.ca.