Token Events

Real-time notifications for stored payment method events: token.created and token.removed.

Delivery, retries and signature verification work exactly as for transaction events. See Webhooks.

Token created

POSTTokenCreated to your webhook endpoint

This webhook event is triggered when a card is tokenized and stored as a payment method.

Parameters

Name	In	Type	Description
`x-fsk-wh-chksm`	header	string	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-id`	header	string	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-timestamp`	header	string	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-signature`	header	string	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 token.created webhook event.

application/json · TokenCreatedWebhook

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 object required

Represents the response to a physical card tokenization request.

Child attributes

id string

Unique ID for this card tokenization 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: "Auth"

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"

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"

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: 1

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: 1

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

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

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

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"

Example

{
  "event": {
    "id": "evt_01JS21X856RR8R69GV5F17XK9C",
    "type": "token.created",
    "timestamp": "2025-05-27T18:49:31Z",
    "merchantId": "mer_01JQZC2Y6W3F8XKT5H9DPNBMVR"
  },
  "originalResponse": {
    "id": "trx_01J2F0ZJ2JW5B63CJFPXRGAB1S",
    "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"
    },
    "referenceId": "ref_add_card_12345",
    "resultCode": 0,
    "resultText": "APPROVED",
    "requestedAmount": 0,
    "approvedAmount": 0,
    "transactionResponses": [
      {
        "responseCode": 1,
        "authCode": "123456",
        "amountApproved": 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"
      }
    ]
  }
}

Responses

200

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

application/json · object

SuccessfulWebhookResponse

{}

Token removed

POSTTokenRemoved to your webhook endpoint

This webhook event is triggered when a previously tokenized card is removed from the system.

Parameters

Name	In	Type	Description
`x-fsk-wh-chksm`	header	string	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-id`	header	string	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-timestamp`	header	string	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-signature`	header	string	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 token.removed webhook event.

application/json · TokenRemovedWebhook

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 CardOnFileRemoveResponse required

Represents the response to a tokenized card removal request.

Child attributes

id string

Unique ID for this payment-method operation (ops_ prefix).

Example: "ops_01J2F0ZJ2JW5B63CJFPXRGAB1S"

paymentMethod object

The payment method used for this transaction.

Child attributes

id string required

Example: "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"

dateDeleted string (date-time)

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"

referenceId ReferenceIdForResponse

max length 100

Example: "ref_s192i49i"

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.

Example: 0

resultText ResultText

Example: "APPROVED"

Example

{
  "event": {
    "id": "evt_01JS21X856RR8R69GV5F17XK9C",
    "type": "token.removed",
    "timestamp": "2025-04-16T14:30:00Z",
    "merchantId": "mer_01JQZC2Y6W3F8XKT5H9DPNBMVR"
  },
  "originalResponse": {
    "id": "ops_01J2F0ZJ2JW5B63CJFPXRGAB1S",
    "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"
      },
      "dateDeleted": "2025-05-29T20:07:50.4723483Z",
      "cardType": "VISA"
    },
    "referenceId": "ref_remove_card_12345",
    "resultCode": 0,
    "resultText": "Card successfully removed"
  }
}

Responses

200

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

application/json · object

SuccessfulWebhookResponse

{}