> For the complete documentation index, see [llms.txt](https://docs.omni.integratedcommerce.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.omni.integratedcommerce.io/api-reference/models.md).

# Models

## The ResponseCode object

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

## The CardType object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"CardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"}}}}
```

## The CVVResult object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"CVVResult":{"type":"string","enum":["M","N","P","S","U"],"description":"The CVV verification result. Typically returned on Card Not Present transactions.\n * `M` - CVV Match\n * `N` - CVV No Match\n * `P` - Not Processed\n * `S` - CVV should be on the card but the merchant indicates it is not.\n * `U` - User is unregistered\n\nNOTE: 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.\n"}}}}
```

## The AVSResult object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"AVSResult":{"type":"string","enum":["A","E","N","R","S","U","G","W","X","Y","Z"],"description":"The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.\n * `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.\n * `E` - Ineligible transaction.\n * `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.\n * `R` - Retry (system unavailable or timed out).\n * `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.\n * `U` - Address information unavailable.\n * `G` - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.\n * `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.\n * `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.\n * `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.\n * `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.\n\nNOTE: 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.\n"}}}}
```

## The BillingInfoCaptureLevel object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"BillingInfoCaptureLevel":{"type":"string","enum":["Minimal","Full"],"description":"Controls how much billing information is collected in the hosted payment form.\n * `Minimal` - Collects country and ZIP/postal code in a compact layout below the card fields. **Not supported for ACH payment methods.**\n * `Full` - (Fallback when no payment method default is configured) Collects complete billing address (street, city, state, country, ZIP). Required for ACH payment methods.\n"}}}}
```

## The FormConfig object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"FormConfig":{"type":"object","description":"Optional form configuration. If omitted, the payment method defaults apply. With no configured default, billing capture is `Full` and 3D Secure is disabled. When you send this object, include `billingInfoCaptureLevel`; omitted optional fields inherit the payment method defaults.\n","properties":{"billingInfoCaptureLevel":{"allOf":[{"$ref":"#/components/schemas/BillingInfoCaptureLevel"}],"description":"Required when formConfig is supplied. Choose Full or Minimal."},"enable3DSecure":{"type":"boolean","description":"Optional. When `true`, the hosted payment form performs 3D Secure (3DS2) cardholder authentication during card tokenization. The issuer decides whether the transaction is authenticated frictionlessly or requires a cardholder challenge; when a challenge is required, it is rendered in an overlay on the hosted payment form and the SDK resumes automatically on completion.\n\nWhen `false`, 3DS is skipped and liability for fraudulent chargebacks remains with the merchant.\n\nThe resulting transaction exposes the authentication outcome in `threeDs.status` and additional authentication data in `threeDs` when available.\n\n**Card payment methods only.** 3DS is a card-network protocol and is not supported for ACH or EFT payment methods - setting `enable3DSecure: true` on a non-card payment method is rejected with a validation error.\n\nWhen omitted, this field inherits the payment method default.\n\n**Recommended:** Combine with `billingInfoCaptureLevel: Full` (the default) to maximize the likelihood of a frictionless flow. Full billing is not required for 3DS to function, but the risk engine uses address, email, and phone to score the transaction.\n"},"piiFields":{"type":"array","description":"Optional additional contact fields to collect. Omitted values inherit the payment method defaults; an empty array requests neither field.","items":{"type":"string","enum":["Email","Phone"]}}},"required":["billingInfoCaptureLevel"]},"BillingInfoCaptureLevel":{"type":"string","enum":["Minimal","Full"],"description":"Controls how much billing information is collected in the hosted payment form.\n * `Minimal` - Collects country and ZIP/postal code in a compact layout below the card fields. **Not supported for ACH payment methods.**\n * `Full` - (Fallback when no payment method default is configured) Collects complete billing address (street, city, state, country, ZIP). Required for ACH payment methods.\n"}}}}
```

## The ErrorDetail object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"ErrorDetail":{"type":"object","description":"Represents a validation error that occurred during the request.","properties":{"code":{"type":"integer","description":"Error code"},"field":{"type":"string","description":"The field with the error"},"message":{"type":"string","description":"Error message"},"details":{"type":"string","description":"Additional details about the error"}}}}}}
```

## The Receipt object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"Receipt":{"type":"object","description":"Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.","properties":{"lines":{"type":"array","items":{"type":"string"},"description":"The receipt lines."}},"required":["lines"]}}}}
```

## The ApprovedAmountBreakdown object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"ApprovedAmountBreakdown":{"type":"object","description":"A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.","properties":{"amountGoodsAndServices":{"type":"integer","description":"The approved amount for goods and services."},"tax":{"type":"integer","description":"The approved tax amount."},"cashback":{"type":"integer","description":"The approved cashback amount."},"tip":{"type":"integer","description":"The approved tip amount."}}}}}}
```

## The ReferenceIdForTransactions object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"ReferenceIdForTransactions":{"type":"string","maxLength":100,"description":"An optional custom reference ID for this transaction. Include this if you want to use your own reference system for linking transactions together (for example, when processing captures and refunds). Use a unique value per merchant. This field is not an idempotency key and reusing it does not replay the prior response. The reference ID can be used for processing captures and referenced refunds by including it in the originalReferenceId field of subsequent transactions. If not provided, a unique reference ID will be generated automatically by the system.\n"}}}}
```

## The ReferenceIdForVoid object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"ReferenceIdForVoid":{"type":"string","maxLength":100,"description":"An optional custom reference ID for this void transaction. Include this if you want to use your own reference system for linking transactions together. Use a unique value per merchant. This field is not an idempotency key and reusing it does not replay the prior response. If not provided, a unique reference ID will be generated automatically by the system.\n"}}}}
```

## The ReferenceIdForTokens object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"ReferenceIdForTokens":{"type":"string","maxLength":100,"description":"An optional custom reference ID to tag and track this token operation. Use a unique value per merchant. This field is not an idempotency key and reusing it does not replay the prior response. If not provided, a unique reference ID will be generated automatically by the system.\n"}}}}
```

## The ReferenceIdForResponse object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"ReferenceIdForResponse":{"type":"string","maxLength":100,"description":"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.\n"}}}}
```

## The OriginalTransactionId object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"OriginalTransactionId":{"type":"string","description":"The transaction ID (`trx_`) of the original authorization to capture, or sale/capture to refund. Supply exactly one of originalTransactionId and originalReferenceId.","maxLength":30,"minLength":1}}}}
```

## The OriginalTransactionIdForVoid object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"OriginalTransactionIdForVoid":{"type":"string","description":"The unique transaction ID of the original transaction to be voided. This is the 'id' value returned from a previous sale, authorization, or capture transaction. Use this parameter if you prefer to rely on system-generated transaction IDs rather than managing your own reference system. Either originalTransactionId or originalReferenceId must be provided.\n\nThe original transaction must belong to the merchant that owns the API key used for this request. A transaction belonging to a different merchant is rejected as not found, exactly as if the ID did not exist.\n","maxLength":30,"minLength":1}}}}
```

## The OriginalReferenceId object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"OriginalReferenceId":{"type":"string","maxLength":100,"description":"The reference ID of the original transaction to be captured or refunded. This should match the referenceId from a previous sale, authorization, or capture transaction (either a custom reference ID you provided or one that was generated automatically by the system). Use this parameter if you want to link transactions using reference IDs rather than system transaction IDs. Either originalTransactionId or originalReferenceId must be provided.\n","minLength":1}}}}
```

## The OriginalReferenceIdForVoid object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"OriginalReferenceIdForVoid":{"type":"string","maxLength":100,"description":"The reference ID of the original transaction to be voided. This should match the referenceId from a previous sale, authorization, or capture transaction (either a custom reference ID you provided or one that was generated automatically by the system). Use this parameter if you want to link transactions using reference IDs rather than system transaction IDs. Either originalTransactionId or originalReferenceId must be provided.\n","minLength":1}}}}
```

## The InvoiceNumber object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"InvoiceNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.\n"}}}}
```

## The InvoiceNumberCardPresent object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"InvoiceNumberCardPresent":{"type":"string","maxLength":20,"description":"An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response and will appear on the receipt.\n\n**Card Present Limit**: Maximum length is 20 characters. If this limit is exceeded, the API will return a validation error.\n"}}}}
```

## The OrderNumber object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"OrderNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.\n"}}}}
```

## The Amount object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"Amount":{"type":"integer","format":"uint32","minimum":1,"maximum":999999999,"description":"The total transaction amount. This is the full amount that will be processed in the transaction. Transaction amounts are positive integers representing the amount in its smallest denomination of the configured currency (e.g. cents for USD or CAD).\n"}}}}
```

## The AmountBreakdown object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"AmountBreakdown":{"type":"object","description":"Optional fields to specify the portion of the total transaction amount that represents goods/services, tax, cashback and/or tip. These values are for reporting purposes only and will not be added to the Amount field. These amount are represented as a positive integer in the smallest denomination of the configured currency (e.g. cents for USD or CAD). If supplied, the component sum must equal amount; components are not added to amount.","properties":{"amountGoodsAndServices":{"type":"integer","description":"The amount for goods and services.","minimum":0,"maximum":999999999},"tax":{"type":"integer","description":"The tax amount.","minimum":0,"maximum":999999999},"cashback":{"type":"integer","description":"The cashback amount.","minimum":0,"maximum":999999999},"tip":{"type":"integer","description":"The tip amount.","minimum":0,"maximum":999999999}}}}}}
```

## The AmountToCapture object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"AmountToCapture":{"type":"integer","format":"uint32","minimum":1,"maximum":999999999,"description":"The amount to capture. Must be less than or equal to the original authorization amount. If not specified, the full authorized amount will be captured. If you have already performed partial captures on this authorization, you must provide an explicit amount or an error will be returned.\n"}}}}
```

## The AmountToRefund object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"AmountToRefund":{"type":"integer","format":"uint32","minimum":1,"maximum":999999999,"description":"The requested amount to refund or void. If not specified, the full transaction amount will be refunded or voided. For partial refunds, must be less than the original transaction amount. If you have already performed partial refunds on this transaction, you must provide an explicit amount or an error will be returned.\n"}}}}
```

## The AmountToRefundUnreferenced object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"AmountToRefundUnreferenced":{"type":"integer","format":"uint32","minimum":1,"maximum":999999999,"description":"The requested amount to refund."}}}}
```

## The ResultCode object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"ResultCode":{"type":"integer","enum":[0,55,1003,1005,1010,3000,3002,3005,3006,3009,3010,3011,3012,3013,3014,3020,4001,4100,6800,6801,6802,6900,6901,6902,9998,9999],"description":"Result codes:\n* `0` - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)\n* `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)\n* `1005` - The specified terminal could not be found.\n* `1010` - The transaction request is pending to become transaction.\n* `3000` - An unexpected error occurred. Please try again.\n* `3002` - The transaction could not be completed because the payment terminal could not find the related transaction.\n* `3005` - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.\n* `3006` - The transaction could not be completed because the payment terminal is low on battery.\n* `3009` - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.\n* `3010` - The transaction took too long and was cancelled by the application.\n* `3011` - Invalid transaction request. Please consult the documentation for valid transaction requests.\n* `3012` - Invalid transaction request. paymentMethodId is invalid.\n* `3013` - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.\n* `3014` - Invalid amount. Please try your transaction again with an amount greater than $0.\n* `3020` - An unsupported transaction result was received.\n* `4001` - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.\n* `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`. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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.\n* `6802` - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `6902` - The gateway reported no failure but returned no payment token. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `9998` - The system is not ready to process a transaction.\n* `9999` - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.\n* `1010` - The transaction request is pending customer interaction.\n* `4100` - Cardholder verification is required. Follow `threeDsChallenge.redirectUrl` and reconcile the final transaction outcome before retrying.\n* `55` - The customer cancelled the hosted payment attempt.\n"}}}}
```

## The ResultText object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"ResultText":{"type":"string","description":"A message describing the result code in more detail."}}}}
```

## The PaymentMethodDetails object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"PaymentMethodDetails":{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string","description":"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."},"dateDeleted":{"type":"string","format":"date-time","description":"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.\n\nThis field will be present in three scenarios:\n- As part of a successful Remove Token endpoint response\n- In token.removed webhook notifications\n- In List Transactions responses for transactions where the associated token was later removed\n\nWhen this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.\n"},"type":{"type":"string","enum":["Unknown","Physical","Virtual","VirtualAch","VirtualEft","Token"],"description":"The type of payment method:\n- `Physical` - A physical payment terminal for Card Present transactions\n- `Virtual` - A hosted payment form/iframe for Card Not Present transactions\n- `VirtualAch` - A hosted payment form/iframe for ACH (US) bank transfer transactions\n- `Token` - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions\n- `VirtualEft` - A virtual Canadian bank-transfer payment method, when configured.\n- `Unknown` - The payment method type is not known.\n"},"currency":{"type":"string","enum":["USD","CAD"],"description":"The currency of the payment method."},"description":{"type":"string","description":"A human-readable name for the payment method."},"billingContact":{"allOf":[{"$ref":"#/components/schemas/BillingContact"},{"type":"object","description":"Billing contact information. Only returned for tokenized payment methods from Card Not Present transactions."}]},"cardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"maskedCardNumber":{"type":"string","description":"The masked card number. The format may vary (e.g. ************0011, 4****0011, etc.)"},"cardExpDate":{"type":"string","description":"The expiration date of the card in MMYY format."},"accountType":{"type":"string","enum":["Credit","Debit","Checking","Savings"],"description":"Funding-source classification of this token-type payment method.\n- For card tokens: `Credit` or `Debit`.\n- For ACH tokens: `Checking` or `Savings`.\nMay be omitted for older tokens that pre-date this field, for non-token payment methods,\nor when the source did not provide a classification.\n"},"accountNumber":{"type":"string","description":"Masked bank account number, when available for a bank-account token."}},"required":["id","type","currency"]},"BillingContact":{"type":"object","description":"Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}}}}}
```

## The TransactionResponse object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"TransactionResponse":{"type":"object","description":"A single Sale Transaction may result in multiple Responses.","properties":{"responseCode":{"$ref":"#/components/schemas/ResponseCode"},"authCode":{"type":"string","description":"The authorization code provided by the card issuer, confirming transaction approval."},"amountApproved":{"type":"integer","description":"The amount approved for this transaction response."},"approvedAmountBreakdown":{"$ref":"#/components/schemas/ApprovedAmountBreakdown"},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The payment method used for this transaction response."}]},"cardType":{"$ref":"#/components/schemas/CardType"},"avsResult":{"$ref":"#/components/schemas/AVSResult"},"cvvResult":{"$ref":"#/components/schemas/CVVResult"},"accountType":{"type":"string","description":"The funding-source classification associated with the payment method used in this\ntransaction.\n- For credit/debit cards: `Credit` or `Debit`. May be null when the classification is unavailable, including on older transactions.\n- For ACH/EFT bank accounts: `Checking` or `Savings`.\n\nThe immediate hosted ACH response uses lowercase `checking` or `savings`. Retrieved transaction responses normally use `Checking` or `Savings`.\n","enum":["Credit","Debit","Checking","Savings","checking","savings"]},"hostResponseText":{"type":"string","description":"A meaningful text explaining the response code from the host."},"receipt":{"$ref":"#/components/schemas/Receipt"}}},"ResponseCode":{"type":"integer","enum":[0,1,2,10,11,12,13,14,15,16,17,18,19,20,21,50,51,52,53,54,55,56,57],"description":"Response codes:\n * `0` - UNKNOWN\n * `1` - APPROVED - Transaction was approved\n * `2` - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.\n * `10` - DECLINED - Transaction was declined by the issuer or bank.  For Card-Present, the transaction can also be declined offline by the terminal.\n * `11` - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.\n * `12` - CARD_EXPIRED - The card used for the transaction has expired.\n * `13` - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.\n * `14` - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).\n * `15` - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).\n * `16` - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).\n * `17` - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.\n * `18` - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.\n * `19` - BATCH_EMPTY - Indicates that the batch for processing is empty.\n * `20` - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).\n * `21` - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.\n * `50` - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.\n * `51` - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.\n * `52` - NOT_SUPPORTED - Rejected because the requested operation is not supported.\n * `53` - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.\n * `54` - CANCELLED - Cancelled by the user or merchant.\n * `55` - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.\n * `56` - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.\n * `57` - PENDING - The transaction is awaiting an asynchronous outcome.\n"},"ApprovedAmountBreakdown":{"type":"object","description":"A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.","properties":{"amountGoodsAndServices":{"type":"integer","description":"The approved amount for goods and services."},"tax":{"type":"integer","description":"The approved tax amount."},"cashback":{"type":"integer","description":"The approved cashback amount."},"tip":{"type":"integer","description":"The approved tip amount."}}},"PaymentMethodDetails":{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string","description":"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."},"dateDeleted":{"type":"string","format":"date-time","description":"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.\n\nThis field will be present in three scenarios:\n- As part of a successful Remove Token endpoint response\n- In token.removed webhook notifications\n- In List Transactions responses for transactions where the associated token was later removed\n\nWhen this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.\n"},"type":{"type":"string","enum":["Unknown","Physical","Virtual","VirtualAch","VirtualEft","Token"],"description":"The type of payment method:\n- `Physical` - A physical payment terminal for Card Present transactions\n- `Virtual` - A hosted payment form/iframe for Card Not Present transactions\n- `VirtualAch` - A hosted payment form/iframe for ACH (US) bank transfer transactions\n- `Token` - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions\n- `VirtualEft` - A virtual Canadian bank-transfer payment method, when configured.\n- `Unknown` - The payment method type is not known.\n"},"currency":{"type":"string","enum":["USD","CAD"],"description":"The currency of the payment method."},"description":{"type":"string","description":"A human-readable name for the payment method."},"billingContact":{"allOf":[{"$ref":"#/components/schemas/BillingContact"},{"type":"object","description":"Billing contact information. Only returned for tokenized payment methods from Card Not Present transactions."}]},"cardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"maskedCardNumber":{"type":"string","description":"The masked card number. The format may vary (e.g. ************0011, 4****0011, etc.)"},"cardExpDate":{"type":"string","description":"The expiration date of the card in MMYY format."},"accountType":{"type":"string","enum":["Credit","Debit","Checking","Savings"],"description":"Funding-source classification of this token-type payment method.\n- For card tokens: `Credit` or `Debit`.\n- For ACH tokens: `Checking` or `Savings`.\nMay be omitted for older tokens that pre-date this field, for non-token payment methods,\nor when the source did not provide a classification.\n"},"accountNumber":{"type":"string","description":"Masked bank account number, when available for a bank-account token."}},"required":["id","type","currency"]},"BillingContact":{"type":"object","description":"Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}},"CardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"AVSResult":{"type":"string","enum":["A","E","N","R","S","U","G","W","X","Y","Z"],"description":"The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.\n * `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.\n * `E` - Ineligible transaction.\n * `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.\n * `R` - Retry (system unavailable or timed out).\n * `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.\n * `U` - Address information unavailable.\n * `G` - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.\n * `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.\n * `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.\n * `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.\n * `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.\n\nNOTE: 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.\n"},"CVVResult":{"type":"string","enum":["M","N","P","S","U"],"description":"The CVV verification result. Typically returned on Card Not Present transactions.\n * `M` - CVV Match\n * `N` - CVV No Match\n * `P` - Not Processed\n * `S` - CVV should be on the card but the merchant indicates it is not.\n * `U` - User is unregistered\n\nNOTE: 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.\n"},"Receipt":{"type":"object","description":"Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.","properties":{"lines":{"type":"array","items":{"type":"string"},"description":"The receipt lines."}},"required":["lines"]}}}}
```

## The ThreeDsStatus object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"ThreeDsStatus":{"type":"string","enum":["Authenticated","Attempted","NotAuthenticated","Failed","Unavailable","NotEnrolled"],"description":"Outcome classification of the 3D Secure check performed on a card transaction. Only present on transactions initiated with `formConfig.enable3DSecure: true`. Use this status to handle the authentication outcome; the other `threeDs` fields provide supporting authentication data.\n\n* `Authenticated` - Issuer fully authenticated the cardholder (ECI `02` / `05`). Full liability shift to the issuer for fraud chargebacks. Covers both frictionless and challenge-completed flows.\n* `Attempted` - Issuer attempted authentication but did not fully authenticate the cardholder (ECI `01` / `06`). Partial liability shift, scheme-dependent.\n* `NotAuthenticated` - 3DS completed but the issuer did not authenticate the cardholder (ECI `00` / `07`). No liability shift.\n* `Failed` - Issuer's ACS rejected the cardholder authentication. Transaction was declined. See `threeDReasonId` for the issuer's reason.\n* `Unavailable` - A technical issue prevented 3DS authentication from completing.\n* `NotEnrolled` - The card is not enrolled in 3DS.\n"}}}}
```

## The ThreeDsAuthentication object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"ThreeDsAuthentication":{"type":"object","description":"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.\n","properties":{"status":{"allOf":[{"$ref":"#/components/schemas/ThreeDsStatus"}],"description":"The authentication outcome to use in your integration. The other `threeDs` fields provide supporting authentication data.\n"},"cavv":{"type":"string","description":"Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions."},"eci":{"type":"string","description":"E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:\n * `02` / `05` - Fully authenticated (liability shift to issuer).\n * `01` / `06` - Attempted authentication (partial liability shift).\n * `00` / `07` - Not authenticated (no liability shift).\n"},"xid":{"type":"string","description":"3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility."},"dsTransId":{"type":"string","description":"Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction."},"threeDReasonId":{"type":"string","description":"Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use `status` to handle the outcome and `threeDReason` for the explanation.\n"},"threeDReason":{"type":"string","description":"Human-readable description matching `threeDReasonId`."}}},"ThreeDsStatus":{"type":"string","enum":["Authenticated","Attempted","NotAuthenticated","Failed","Unavailable","NotEnrolled"],"description":"Outcome classification of the 3D Secure check performed on a card transaction. Only present on transactions initiated with `formConfig.enable3DSecure: true`. Use this status to handle the authentication outcome; the other `threeDs` fields provide supporting authentication data.\n\n* `Authenticated` - Issuer fully authenticated the cardholder (ECI `02` / `05`). Full liability shift to the issuer for fraud chargebacks. Covers both frictionless and challenge-completed flows.\n* `Attempted` - Issuer attempted authentication but did not fully authenticate the cardholder (ECI `01` / `06`). Partial liability shift, scheme-dependent.\n* `NotAuthenticated` - 3DS completed but the issuer did not authenticate the cardholder (ECI `00` / `07`). No liability shift.\n* `Failed` - Issuer's ACS rejected the cardholder authentication. Transaction was declined. See `threeDReasonId` for the issuer's reason.\n* `Unavailable` - A technical issue prevented 3DS authentication from completing.\n* `NotEnrolled` - The card is not enrolled in 3DS.\n"}}}}
```

## The Error object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"Error":{"type":"object","description":"Represents an error that occurred during the request.","properties":{"code":{"type":"integer","enum":[0,1000,1001,2000,2010,2011,2012,2013,2020,2021,2100,2101,2102,2103,2105,2201,2202,2900,2901,2902,2903,3000,3201,3202,3203,3204,3205,3299,3400,3401,3501,3502,3503,4000,4001,4002,4003,4004,6000,6001,6100,6101,6102,6103,6200,6201,6202,6203,6300,6301,6400,6500,6501,6600,6700,6701,6800,6801,6802,6900,6901,6902,9000,9999],"description":"Numeric error code. These are grouped into ranges for easier identification and troubleshooting.\n\n * `0` - Unknown\n * `1000` - AuthenticationGenericError\n * `1001` - MerchantNotAuthorizedForResource\n * `2000` - RequestValidationGenericError\n * `2010` - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.\n * `2011` - InvalidTransactionType\n * `2012` - InvalidAmount\n * `2013` - PaymentMethodUsageRestricted\n * `2020` - InvalidPaymentMethodOwner\n * `2021` - InvalidAccountHolderOwner\n * `2100` - InvalidAccountHolderInformation\n * `2101` - InvalidCountryCode\n * `2102` - InvalidZipCode\n * `2103` - MissingCountryCodeOrZipCode\n * `2105` - InvalidEmailAddress\n * `2201` - MissingUniqueToken\n * `2202` - TransactionDeclinedError\n * `2900` - RequestValidationUnsupportedPayload\n * `2901` - RequestValidationWebhookMissingTypeAndDmnType\n * `2902` - RequestValidationUnsupportedWebhookTokenization\n * `2903` - RequestValidationUnsupportedWebhookType\n * `3000` - UnknownServerGenericError\n * `3201` - InvalidOrExpiredSession\n * `3202` - FailedToCreateSessionInAdapter\n * `3203` - ErrorWhileTokenizingCard\n * `3204` - FailedToLoadThirdPartySdk\n * `3205` - SessionExpired\n * `3299` - JavaScriptError\n * `3400` - ResourceNotReadyError\n * `3401` - TransactionNotCompleteYet\n * `3501` - CouldNotCreateBillingSubscription\n * `3502` - CouldNotCancelBillingSubscription\n * `3503` - BillingSubscriptionInvalidStatus\n * `4000` - ResourceNotFound\n * `4001` - TokenizedCardNotFound\n * `4002` - PaymentMethodNotFound\n * `4003` - AccountHolderNotFound\n * `4004` - BillingSubscriptionNotFound\n * `6000` - SdkGenericError\n * `6001` - SdkJavaScriptError\n * `6100` - SdkSessionLoadFailed\n * `6101` - SdkSessionExpired\n * `6102` - SdkSessionNotInitialized\n * `6103` - SdkEnvironmentMismatch\n * `6200` - SdkCardFieldsInvalid\n * `6201` - SdkCardTokenizationFailed\n * `6202` - SdkCardInitFailed\n * `6203` - SdkCardProcessingFailed\n * `6300` - SdkAchFieldsInvalid\n * `6301` - SdkAchProcessingFailed\n * `6400` - SdkEftProcessingFailed\n * `6500` - SdkWalletError\n * `6501` - SdkWalletProcessingFailed\n * `6600` - SdkThirdPartySdkLoadFailed\n * `6700` - SdkFormValidationFailed\n * `6701` - SdkBillingValidationFailed\n * `6800` - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when `formConfig.enable3DSecure: true`.\n * `6801` - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.\n * `6802` - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.\n * `6900` - SdkCardDeclined - 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`.\n * `6901` - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.\n * `6902` - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.\n * `9000` - UnhandledGenericError\n * `9999` - MaxErrorCode\n"},"status":{"type":"string","enum":["Completed","Rejected","Interrupted","Unknown"],"description":"Execution status of the request sent to the payment gateway.\n\n * Completed - The request completed successfully.\n * Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.\n * Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.\n * Unknown\n"},"message":{"type":"string","description":"Developer-facing error message."},"traceId":{"type":"string","description":"Unique trace identifier for tracking and debugging this request."},"timestamp":{"type":"string","format":"date-time","description":"The timestamp when the error occurred (UTC)."},"errorDetails":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"ErrorDetail":{"type":"object","description":"Represents a validation error that occurred during the request.","properties":{"code":{"type":"integer","description":"Error code"},"field":{"type":"string","description":"The field with the error"},"message":{"type":"string","description":"Error message"},"details":{"type":"string","description":"Additional details about the error"}}}}}}
```

## The CardPresentRequest object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"CardPresentRequest":{"type":"object","description":"Represents the request to process a Card Present transaction using a physical payment terminal.","properties":{"amount":{"$ref":"#/components/schemas/Amount"},"amountBreakdown":{"$ref":"#/components/schemas/AmountBreakdown"},"paymentMethodId":{"type":"string","description":"The ID of the physical payment terminal that will process this Card Present transaction.\n\n- Example format: `pmt_trm_01JRZPTMTBN41PC3VPQNZ5T3HF`\n- Omit only when the merchant has a configured default for this operation or a single resolvable payment method.\n- Otherwise, provide an explicit payment method ID.\n\nYou can retrieve all available physical payment terminal IDs for your account using the [`GET /payment-methods`](https://fiska.gitbook.io/omni-payment-api/payments/payment-methods) endpoint.\n","maxLength":35},"invoiceNumber":{"$ref":"#/components/schemas/InvoiceNumberCardPresent"},"orderNumber":{"$ref":"#/components/schemas/OrderNumber"},"referenceId":{"$ref":"#/components/schemas/ReferenceIdForTransactions"}},"required":["amount"]},"Amount":{"type":"integer","format":"uint32","minimum":1,"maximum":999999999,"description":"The total transaction amount. This is the full amount that will be processed in the transaction. Transaction amounts are positive integers representing the amount in its smallest denomination of the configured currency (e.g. cents for USD or CAD).\n"},"AmountBreakdown":{"type":"object","description":"Optional fields to specify the portion of the total transaction amount that represents goods/services, tax, cashback and/or tip. These values are for reporting purposes only and will not be added to the Amount field. These amount are represented as a positive integer in the smallest denomination of the configured currency (e.g. cents for USD or CAD). If supplied, the component sum must equal amount; components are not added to amount.","properties":{"amountGoodsAndServices":{"type":"integer","description":"The amount for goods and services.","minimum":0,"maximum":999999999},"tax":{"type":"integer","description":"The tax amount.","minimum":0,"maximum":999999999},"cashback":{"type":"integer","description":"The cashback amount.","minimum":0,"maximum":999999999},"tip":{"type":"integer","description":"The tip amount.","minimum":0,"maximum":999999999}}},"InvoiceNumberCardPresent":{"type":"string","maxLength":20,"description":"An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response and will appear on the receipt.\n\n**Card Present Limit**: Maximum length is 20 characters. If this limit is exceeded, the API will return a validation error.\n"},"OrderNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.\n"},"ReferenceIdForTransactions":{"type":"string","maxLength":100,"description":"An optional custom reference ID for this transaction. Include this if you want to use your own reference system for linking transactions together (for example, when processing captures and refunds). Use a unique value per merchant. This field is not an idempotency key and reusing it does not replay the prior response. The reference ID can be used for processing captures and referenced refunds by including it in the originalReferenceId field of subsequent transactions. If not provided, a unique reference ID will be generated automatically by the system.\n"}}}}
```

## The CardNotPresentRequest object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"CardNotPresentRequest":{"type":"object","description":"Represents the request to process a Card Not Present transaction using a hosted payment form/iframe.","properties":{"amount":{"$ref":"#/components/schemas/Amount"},"amountBreakdown":{"$ref":"#/components/schemas/AmountBreakdown"},"paymentMethodId":{"type":"string","description":"The ID of the hosted payment form / iframe that will collect card information for this Card Not Present transaction.\n\n- Example format: `pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS`\n- Omit only when the merchant has a configured default for this operation or a single resolvable payment method.\n- Otherwise, provide an explicit payment method ID.\n\nYou can retrieve all available hosted payment form IDs for your account using the [`GET /payment-methods`](https://fiska.gitbook.io/omni-payment-api/payments/payment-methods) endpoint.\n","maxLength":35},"invoiceNumber":{"$ref":"#/components/schemas/InvoiceNumber"},"orderNumber":{"$ref":"#/components/schemas/OrderNumber"},"referenceId":{"$ref":"#/components/schemas/ReferenceIdForTransactions"},"returnUrl":{"type":"string","description":"Will be used to redirect user back to merchant's site after iframe completed or canceled if provided. The URL will include various parameters that are detailed in \"Transaction Result Parameters\" section of the Hosted Payment Form section. If you do not provide a returnUrl, the customer will see either a \"Payment Processed Successfully\" or \"Payment Processing Issue\" screen.","maxLength":1000},"useJavaScriptCallback":{"type":"boolean","description":"At the end of the transaction flow, the user is always redirected to either the returnUrl (if provided), or a default success or issue page. In addition, if useJavaScriptCallback is set to true, the iframe will use JavaScript to post a message to the parent window to notify the merchant's site when the iframe completed. This allows for more control over the user experience on the merchant's site."},"formConfig":{"allOf":[{"$ref":"#/components/schemas/FormConfig"}],"description":"Optional form configuration. Omit to use payment method defaults. If supplied, billingInfoCaptureLevel is required."},"accountHolder":{"allOf":[{"$ref":"#/components/schemas/AccountHolderRequest"}],"description":"Optional external customer identifier. Supported by virtual sale and virtual tokenization; ignored by virtual authorization."}},"required":["amount"]},"Amount":{"type":"integer","format":"uint32","minimum":1,"maximum":999999999,"description":"The total transaction amount. This is the full amount that will be processed in the transaction. Transaction amounts are positive integers representing the amount in its smallest denomination of the configured currency (e.g. cents for USD or CAD).\n"},"AmountBreakdown":{"type":"object","description":"Optional fields to specify the portion of the total transaction amount that represents goods/services, tax, cashback and/or tip. These values are for reporting purposes only and will not be added to the Amount field. These amount are represented as a positive integer in the smallest denomination of the configured currency (e.g. cents for USD or CAD). If supplied, the component sum must equal amount; components are not added to amount.","properties":{"amountGoodsAndServices":{"type":"integer","description":"The amount for goods and services.","minimum":0,"maximum":999999999},"tax":{"type":"integer","description":"The tax amount.","minimum":0,"maximum":999999999},"cashback":{"type":"integer","description":"The cashback amount.","minimum":0,"maximum":999999999},"tip":{"type":"integer","description":"The tip amount.","minimum":0,"maximum":999999999}}},"InvoiceNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.\n"},"OrderNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.\n"},"ReferenceIdForTransactions":{"type":"string","maxLength":100,"description":"An optional custom reference ID for this transaction. Include this if you want to use your own reference system for linking transactions together (for example, when processing captures and refunds). Use a unique value per merchant. This field is not an idempotency key and reusing it does not replay the prior response. The reference ID can be used for processing captures and referenced refunds by including it in the originalReferenceId field of subsequent transactions. If not provided, a unique reference ID will be generated automatically by the system.\n"},"FormConfig":{"type":"object","description":"Optional form configuration. If omitted, the payment method defaults apply. With no configured default, billing capture is `Full` and 3D Secure is disabled. When you send this object, include `billingInfoCaptureLevel`; omitted optional fields inherit the payment method defaults.\n","properties":{"billingInfoCaptureLevel":{"allOf":[{"$ref":"#/components/schemas/BillingInfoCaptureLevel"}],"description":"Required when formConfig is supplied. Choose Full or Minimal."},"enable3DSecure":{"type":"boolean","description":"Optional. When `true`, the hosted payment form performs 3D Secure (3DS2) cardholder authentication during card tokenization. The issuer decides whether the transaction is authenticated frictionlessly or requires a cardholder challenge; when a challenge is required, it is rendered in an overlay on the hosted payment form and the SDK resumes automatically on completion.\n\nWhen `false`, 3DS is skipped and liability for fraudulent chargebacks remains with the merchant.\n\nThe resulting transaction exposes the authentication outcome in `threeDs.status` and additional authentication data in `threeDs` when available.\n\n**Card payment methods only.** 3DS is a card-network protocol and is not supported for ACH or EFT payment methods - setting `enable3DSecure: true` on a non-card payment method is rejected with a validation error.\n\nWhen omitted, this field inherits the payment method default.\n\n**Recommended:** Combine with `billingInfoCaptureLevel: Full` (the default) to maximize the likelihood of a frictionless flow. Full billing is not required for 3DS to function, but the risk engine uses address, email, and phone to score the transaction.\n"},"piiFields":{"type":"array","description":"Optional additional contact fields to collect. Omitted values inherit the payment method defaults; an empty array requests neither field.","items":{"type":"string","enum":["Email","Phone"]}}},"required":["billingInfoCaptureLevel"]},"BillingInfoCaptureLevel":{"type":"string","enum":["Minimal","Full"],"description":"Controls how much billing information is collected in the hosted payment form.\n * `Minimal` - Collects country and ZIP/postal code in a compact layout below the card fields. **Not supported for ACH payment methods.**\n * `Full` - (Fallback when no payment method default is configured) Collects complete billing address (street, city, state, country, ZIP). Required for ACH payment methods.\n"},"AccountHolderRequest":{"type":"object","description":"Account holder information for associating a transaction or tokenized payment method with a customer.\n\nWhen you provide an `externalId`, the system will either find an existing account holder with that ID or create a new one. This allows you to link payment methods and transactions to your own customer identifiers (e.g., CRM contact IDs, user IDs from your system).\n","properties":{"externalId":{"type":"string","maxLength":255,"description":"Your external identifier for this customer. This can be any unique identifier from your system.\n\nIf an account holder with this external ID already exists for your merchant account, it will be used. Otherwise, a new account holder will be created with this external ID.\n"}}}}}}
```

## The CardOnFileRequest object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"CardOnFileRequest":{"type":"object","description":"Represents the request to process a Card On File transaction using a token. The token may hold a card or an ACH bank account; an ACH token is accepted for sales only.","properties":{"amount":{"$ref":"#/components/schemas/Amount"},"amountBreakdown":{"$ref":"#/components/schemas/AmountBreakdown"},"paymentMethodId":{"type":"string","description":"The ID of the token that will be used for this Card On File transaction.\n\n- Example format: `pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J`\n- ALWAYS REQUIRED when using a token\n","maxLength":35},"invoiceNumber":{"$ref":"#/components/schemas/InvoiceNumber"},"orderNumber":{"$ref":"#/components/schemas/OrderNumber"},"referenceId":{"$ref":"#/components/schemas/ReferenceIdForTransactions"}},"required":["amount","paymentMethodId"]},"Amount":{"type":"integer","format":"uint32","minimum":1,"maximum":999999999,"description":"The total transaction amount. This is the full amount that will be processed in the transaction. Transaction amounts are positive integers representing the amount in its smallest denomination of the configured currency (e.g. cents for USD or CAD).\n"},"AmountBreakdown":{"type":"object","description":"Optional fields to specify the portion of the total transaction amount that represents goods/services, tax, cashback and/or tip. These values are for reporting purposes only and will not be added to the Amount field. These amount are represented as a positive integer in the smallest denomination of the configured currency (e.g. cents for USD or CAD). If supplied, the component sum must equal amount; components are not added to amount.","properties":{"amountGoodsAndServices":{"type":"integer","description":"The amount for goods and services.","minimum":0,"maximum":999999999},"tax":{"type":"integer","description":"The tax amount.","minimum":0,"maximum":999999999},"cashback":{"type":"integer","description":"The cashback amount.","minimum":0,"maximum":999999999},"tip":{"type":"integer","description":"The tip amount.","minimum":0,"maximum":999999999}}},"InvoiceNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.\n"},"OrderNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.\n"},"ReferenceIdForTransactions":{"type":"string","maxLength":100,"description":"An optional custom reference ID for this transaction. Include this if you want to use your own reference system for linking transactions together (for example, when processing captures and refunds). Use a unique value per merchant. This field is not an idempotency key and reusing it does not replay the prior response. The reference ID can be used for processing captures and referenced refunds by including it in the originalReferenceId field of subsequent transactions. If not provided, a unique reference ID will be generated automatically by the system.\n"}}}}
```

## The CaptureRequest object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"CaptureRequest":{"type":"object","description":"Represents the request to capture a previously authorized transaction.","properties":{"originalTransactionId":{"$ref":"#/components/schemas/OriginalTransactionId"},"originalReferenceId":{"$ref":"#/components/schemas/OriginalReferenceId"},"referenceId":{"$ref":"#/components/schemas/ReferenceIdForTransactions"},"amount":{"$ref":"#/components/schemas/AmountToCapture"},"invoiceNumber":{"$ref":"#/components/schemas/InvoiceNumber"},"orderNumber":{"$ref":"#/components/schemas/OrderNumber"}},"oneOf":[{"title":"Capture using Transaction ID","type":"object","required":["originalTransactionId"]},{"title":"Capture using Reference ID","type":"object","required":["originalReferenceId"]}]},"OriginalTransactionId":{"type":"string","description":"The transaction ID (`trx_`) of the original authorization to capture, or sale/capture to refund. Supply exactly one of originalTransactionId and originalReferenceId.","maxLength":30,"minLength":1},"OriginalReferenceId":{"type":"string","maxLength":100,"description":"The reference ID of the original transaction to be captured or refunded. This should match the referenceId from a previous sale, authorization, or capture transaction (either a custom reference ID you provided or one that was generated automatically by the system). Use this parameter if you want to link transactions using reference IDs rather than system transaction IDs. Either originalTransactionId or originalReferenceId must be provided.\n","minLength":1},"ReferenceIdForTransactions":{"type":"string","maxLength":100,"description":"An optional custom reference ID for this transaction. Include this if you want to use your own reference system for linking transactions together (for example, when processing captures and refunds). Use a unique value per merchant. This field is not an idempotency key and reusing it does not replay the prior response. The reference ID can be used for processing captures and referenced refunds by including it in the originalReferenceId field of subsequent transactions. If not provided, a unique reference ID will be generated automatically by the system.\n"},"AmountToCapture":{"type":"integer","format":"uint32","minimum":1,"maximum":999999999,"description":"The amount to capture. Must be less than or equal to the original authorization amount. If not specified, the full authorized amount will be captured. If you have already performed partial captures on this authorization, you must provide an explicit amount or an error will be returned.\n"},"InvoiceNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.\n"},"OrderNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.\n"}}}}
```

## The RefundRequest object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"RefundRequest":{"type":"object","description":"Represents the request to refund or void a previously completed transaction.","properties":{"originalTransactionId":{"$ref":"#/components/schemas/OriginalTransactionId"},"originalReferenceId":{"$ref":"#/components/schemas/OriginalReferenceId"},"referenceId":{"$ref":"#/components/schemas/ReferenceIdForTransactions"},"amount":{"$ref":"#/components/schemas/AmountToRefund"},"invoiceNumber":{"$ref":"#/components/schemas/InvoiceNumber"},"orderNumber":{"$ref":"#/components/schemas/OrderNumber"}},"oneOf":[{"title":"Refund using Transaction ID","type":"object","required":["originalTransactionId"]},{"title":"Refund using Reference ID","type":"object","required":["originalReferenceId"]}]},"OriginalTransactionId":{"type":"string","description":"The transaction ID (`trx_`) of the original authorization to capture, or sale/capture to refund. Supply exactly one of originalTransactionId and originalReferenceId.","maxLength":30,"minLength":1},"OriginalReferenceId":{"type":"string","maxLength":100,"description":"The reference ID of the original transaction to be captured or refunded. This should match the referenceId from a previous sale, authorization, or capture transaction (either a custom reference ID you provided or one that was generated automatically by the system). Use this parameter if you want to link transactions using reference IDs rather than system transaction IDs. Either originalTransactionId or originalReferenceId must be provided.\n","minLength":1},"ReferenceIdForTransactions":{"type":"string","maxLength":100,"description":"An optional custom reference ID for this transaction. Include this if you want to use your own reference system for linking transactions together (for example, when processing captures and refunds). Use a unique value per merchant. This field is not an idempotency key and reusing it does not replay the prior response. The reference ID can be used for processing captures and referenced refunds by including it in the originalReferenceId field of subsequent transactions. If not provided, a unique reference ID will be generated automatically by the system.\n"},"AmountToRefund":{"type":"integer","format":"uint32","minimum":1,"maximum":999999999,"description":"The requested amount to refund or void. If not specified, the full transaction amount will be refunded or voided. For partial refunds, must be less than the original transaction amount. If you have already performed partial refunds on this transaction, you must provide an explicit amount or an error will be returned.\n"},"InvoiceNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.\n"},"OrderNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.\n"}}}}
```

## The VoidRequest object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"VoidRequest":{"type":"object","description":"Represents the request to void a previously completed transaction. The amount is always the full original transaction amount; an amount supplied in this request is ignored.","properties":{"originalTransactionId":{"$ref":"#/components/schemas/OriginalTransactionIdForVoid"},"originalReferenceId":{"$ref":"#/components/schemas/OriginalReferenceIdForVoid"},"referenceId":{"$ref":"#/components/schemas/ReferenceIdForVoid"},"invoiceNumber":{"$ref":"#/components/schemas/InvoiceNumber"},"orderNumber":{"$ref":"#/components/schemas/OrderNumber"}},"oneOf":[{"title":"Void using Transaction ID","type":"object","required":["originalTransactionId"]},{"title":"Void using Reference ID","type":"object","required":["originalReferenceId"]}]},"OriginalTransactionIdForVoid":{"type":"string","description":"The unique transaction ID of the original transaction to be voided. This is the 'id' value returned from a previous sale, authorization, or capture transaction. Use this parameter if you prefer to rely on system-generated transaction IDs rather than managing your own reference system. Either originalTransactionId or originalReferenceId must be provided.\n\nThe original transaction must belong to the merchant that owns the API key used for this request. A transaction belonging to a different merchant is rejected as not found, exactly as if the ID did not exist.\n","maxLength":30,"minLength":1},"OriginalReferenceIdForVoid":{"type":"string","maxLength":100,"description":"The reference ID of the original transaction to be voided. This should match the referenceId from a previous sale, authorization, or capture transaction (either a custom reference ID you provided or one that was generated automatically by the system). Use this parameter if you want to link transactions using reference IDs rather than system transaction IDs. Either originalTransactionId or originalReferenceId must be provided.\n","minLength":1},"ReferenceIdForVoid":{"type":"string","maxLength":100,"description":"An optional custom reference ID for this void transaction. Include this if you want to use your own reference system for linking transactions together. Use a unique value per merchant. This field is not an idempotency key and reusing it does not replay the prior response. If not provided, a unique reference ID will be generated automatically by the system.\n"},"InvoiceNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.\n"},"OrderNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.\n"}}}}
```

## The UnreferencedPhysicalRefundRequest object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"UnreferencedPhysicalRefundRequest":{"type":"object","description":"Represents the request to process a Card Present unreferenced refund without a matching completed sale or capture transaction.","properties":{"amount":{"$ref":"#/components/schemas/AmountToRefundUnreferenced"},"paymentMethodId":{"type":"string","description":"The ID of the physical payment terminal that will process this Card Present unreferenced refund.\n\n- Example format: `pmt_trm_01JRZPTMTBN41PC3VPQNZ5T3HF`\n- Omit only when the merchant has a configured default for this operation or a single resolvable payment method.\n- Otherwise, provide an explicit payment method ID.\n\nYou can retrieve all available physical payment terminal IDs for your account using the [`GET /payment-methods`](https://fiska.gitbook.io/omni-payment-api/payments/payment-methods) endpoint.\n","maxLength":35},"invoiceNumber":{"$ref":"#/components/schemas/InvoiceNumberCardPresent"},"orderNumber":{"$ref":"#/components/schemas/OrderNumber"},"referenceId":{"$ref":"#/components/schemas/ReferenceIdForTransactions"}},"required":["amount"]},"AmountToRefundUnreferenced":{"type":"integer","format":"uint32","minimum":1,"maximum":999999999,"description":"The requested amount to refund."},"InvoiceNumberCardPresent":{"type":"string","maxLength":20,"description":"An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response and will appear on the receipt.\n\n**Card Present Limit**: Maximum length is 20 characters. If this limit is exceeded, the API will return a validation error.\n"},"OrderNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.\n"},"ReferenceIdForTransactions":{"type":"string","maxLength":100,"description":"An optional custom reference ID for this transaction. Include this if you want to use your own reference system for linking transactions together (for example, when processing captures and refunds). Use a unique value per merchant. This field is not an idempotency key and reusing it does not replay the prior response. The reference ID can be used for processing captures and referenced refunds by including it in the originalReferenceId field of subsequent transactions. If not provided, a unique reference ID will be generated automatically by the system.\n"}}}}
```

## The UnreferencedVirtualRefundRequest object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"UnreferencedVirtualRefundRequest":{"type":"object","description":"Represents the request to process a Card Not Present unreferenced refund without a matching completed sale or capture transaction.","properties":{"amount":{"$ref":"#/components/schemas/AmountToRefundUnreferenced"},"paymentMethodId":{"type":"string","description":"The ID of the hosted payment form / iframe that will collect card information for this Card Not Present unreferenced refund.\n\n- Example format: `pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS`\n- Omit only when the merchant has a configured default for this operation or a single resolvable payment method.\n- Otherwise, provide an explicit payment method ID.\n\nYou can retrieve all available hosted payment form IDs for your account using the [`GET /payment-methods`](https://fiska.gitbook.io/omni-payment-api/payments/payment-methods) endpoint.\n","maxLength":35},"invoiceNumber":{"$ref":"#/components/schemas/InvoiceNumber"},"orderNumber":{"$ref":"#/components/schemas/OrderNumber"},"referenceId":{"$ref":"#/components/schemas/ReferenceIdForTransactions"},"returnUrl":{"type":"string","description":"Will be used to redirect user back to merchant's site after iframe completed or canceled if provided. The URL will include various parameters that are detailed in \"Transaction Result Parameters\" section of the Hosted Payment Form section. If you do not provide a returnUrl, the customer will see either a \"Payment Processed Successfully\" or \"Payment Processing Issue\" screen.","maxLength":1000},"useJavaScriptCallback":{"type":"boolean","description":"At the end of the transaction flow, the user is always redirected to either the returnUrl (if provided), or a default success or issue page. In addition, if useJavaScriptCallback is set to true, the iframe will use JavaScript to post a message to the parent window to notify the merchant's site when the iframe completed. This allows for more control over the user experience on the merchant's site."}},"required":["amount"]},"AmountToRefundUnreferenced":{"type":"integer","format":"uint32","minimum":1,"maximum":999999999,"description":"The requested amount to refund."},"InvoiceNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.\n"},"OrderNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.\n"},"ReferenceIdForTransactions":{"type":"string","maxLength":100,"description":"An optional custom reference ID for this transaction. Include this if you want to use your own reference system for linking transactions together (for example, when processing captures and refunds). Use a unique value per merchant. This field is not an idempotency key and reusing it does not replay the prior response. The reference ID can be used for processing captures and referenced refunds by including it in the originalReferenceId field of subsequent transactions. If not provided, a unique reference ID will be generated automatically by the system.\n"}}}}
```

## The CardOnFileAddRequest object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"CardOnFileAddRequest":{"type":"object","description":"Represents the request to tokenize a card using a physical terminal.","properties":{"paymentMethodId":{"type":"string","description":"The ID of the payment method (physical terminal) to use for adding a card.\n\n- Example format: `pmt_trm_01JRZPTMTBN41PC3VPQNZ5T3HF`\n- Omit only when the merchant has a configured default for this operation or a single resolvable payment method.\n- Otherwise, provide an explicit payment method ID.\n\nYou can retrieve all available physical payment terminal IDs for your account using the [`GET /payment-methods`](https://fiska.gitbook.io/omni-payment-api/payments/payment-methods) endpoint.\n","maxLength":35},"referenceId":{"$ref":"#/components/schemas/ReferenceIdForTokens"}}},"ReferenceIdForTokens":{"type":"string","maxLength":100,"description":"An optional custom reference ID to tag and track this token operation. Use a unique value per merchant. This field is not an idempotency key and reusing it does not replay the prior response. If not provided, a unique reference ID will be generated automatically by the system.\n"}}}}
```

## The CardOnFileVirtualAddRequest object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"CardOnFileVirtualAddRequest":{"type":"object","description":"Represents the request to tokenize a card using a hosted payment form / iframe.","properties":{"paymentMethodId":{"type":"string","description":"The ID of the payment method (hosted payment form/iframe) to use for adding a card.\n\n- Example format: `pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS`\n- Omit only when the merchant has a configured default for this operation or a single resolvable payment method.\n- Otherwise, provide an explicit payment method ID.\n\nYou can retrieve all available payment method IDs for your account using the `GET /payment-methods` endpoint.\n","maxLength":35},"referenceId":{"$ref":"#/components/schemas/ReferenceIdForTokens"},"returnUrl":{"type":"string","description":"Will be used to redirect user back to merchant's site after iframe completed or canceled if provided. The URL will include various parameters that are detailed in \"Transaction Result Parameters\" section of the Hosted Payment Form section. If you do not provide a returnUrl, the customer will see either a \"Payment Processed Successfully\" or \"Payment Processing Issue\" screen.","maxLength":1000},"useJavaScriptCallback":{"type":"boolean","description":"At the end of the transaction flow, the user is always redirected to either the returnUrl (if provided), or a default success or issue page. In addition, if useJavaScriptCallback is set to true, the iframe will use JavaScript to post a message to the parent window to notify the merchant's site when the iframe completed. This allows for more control over the user experience on the merchant's site."},"formConfig":{"allOf":[{"$ref":"#/components/schemas/FormConfig"}],"description":"Optional form configuration. Omit to use payment method defaults. If supplied, billingInfoCaptureLevel is required."},"accountHolder":{"allOf":[{"$ref":"#/components/schemas/AccountHolderRequest"}],"description":"Optional external customer identifier. Supported by virtual sale and virtual tokenization; ignored by virtual authorization."}}},"ReferenceIdForTokens":{"type":"string","maxLength":100,"description":"An optional custom reference ID to tag and track this token operation. Use a unique value per merchant. This field is not an idempotency key and reusing it does not replay the prior response. If not provided, a unique reference ID will be generated automatically by the system.\n"},"FormConfig":{"type":"object","description":"Optional form configuration. If omitted, the payment method defaults apply. With no configured default, billing capture is `Full` and 3D Secure is disabled. When you send this object, include `billingInfoCaptureLevel`; omitted optional fields inherit the payment method defaults.\n","properties":{"billingInfoCaptureLevel":{"allOf":[{"$ref":"#/components/schemas/BillingInfoCaptureLevel"}],"description":"Required when formConfig is supplied. Choose Full or Minimal."},"enable3DSecure":{"type":"boolean","description":"Optional. When `true`, the hosted payment form performs 3D Secure (3DS2) cardholder authentication during card tokenization. The issuer decides whether the transaction is authenticated frictionlessly or requires a cardholder challenge; when a challenge is required, it is rendered in an overlay on the hosted payment form and the SDK resumes automatically on completion.\n\nWhen `false`, 3DS is skipped and liability for fraudulent chargebacks remains with the merchant.\n\nThe resulting transaction exposes the authentication outcome in `threeDs.status` and additional authentication data in `threeDs` when available.\n\n**Card payment methods only.** 3DS is a card-network protocol and is not supported for ACH or EFT payment methods - setting `enable3DSecure: true` on a non-card payment method is rejected with a validation error.\n\nWhen omitted, this field inherits the payment method default.\n\n**Recommended:** Combine with `billingInfoCaptureLevel: Full` (the default) to maximize the likelihood of a frictionless flow. Full billing is not required for 3DS to function, but the risk engine uses address, email, and phone to score the transaction.\n"},"piiFields":{"type":"array","description":"Optional additional contact fields to collect. Omitted values inherit the payment method defaults; an empty array requests neither field.","items":{"type":"string","enum":["Email","Phone"]}}},"required":["billingInfoCaptureLevel"]},"BillingInfoCaptureLevel":{"type":"string","enum":["Minimal","Full"],"description":"Controls how much billing information is collected in the hosted payment form.\n * `Minimal` - Collects country and ZIP/postal code in a compact layout below the card fields. **Not supported for ACH payment methods.**\n * `Full` - (Fallback when no payment method default is configured) Collects complete billing address (street, city, state, country, ZIP). Required for ACH payment methods.\n"},"AccountHolderRequest":{"type":"object","description":"Account holder information for associating a transaction or tokenized payment method with a customer.\n\nWhen you provide an `externalId`, the system will either find an existing account holder with that ID or create a new one. This allows you to link payment methods and transactions to your own customer identifiers (e.g., CRM contact IDs, user IDs from your system).\n","properties":{"externalId":{"type":"string","maxLength":255,"description":"Your external identifier for this customer. This can be any unique identifier from your system.\n\nIf an account holder with this external ID already exists for your merchant account, it will be used. Otherwise, a new account holder will be created with this external ID.\n"}}}}}}
```

## The CNPVirtualResponse object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"CNPVirtualResponse":{"type":"object","description":"Represents the response to a Card Not Present sale or authorization using a hosted payment form / iframe.","properties":{"id":{"type":"string","description":"Identifier of the hosted session request (`ifr_` prefix). This is not a transaction ID."},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The payment method used for this Card Not Present transaction.","properties":{"id":{"type":"string"}}}]},"invoiceNumber":{"$ref":"#/components/schemas/InvoiceNumber"},"orderNumber":{"$ref":"#/components/schemas/OrderNumber"},"referenceId":{"$ref":"#/components/schemas/ReferenceIdForResponse"},"requestedAmount":{"type":"integer","description":"The amount sent in the transaction request. The amount is always a non-null positive integer in the smallest denomination of the currency (e.g. cents for USD or CAD)."},"sessionId":{"type":"string","description":"Opaque session token. Pass this exact unprefixed value to the SDK."},"iframeUrl":{"type":"string","description":"URL for the iframe to collect payment information, or null if iframe could not be created due to invalid credentials, etc."},"expirationTimestamp":{"type":"string","format":"date-time","description":"Absolute session expiry in UTC, 10 minutes after creation."},"status":{"type":"string","enum":["Pending","Completed","Expired","Error"],"description":"Status of the iframe session. When created, this will always be pending. The status values will be updated as the customer goes through the iframe process."}}},"PaymentMethodDetails":{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string","description":"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."},"dateDeleted":{"type":"string","format":"date-time","description":"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.\n\nThis field will be present in three scenarios:\n- As part of a successful Remove Token endpoint response\n- In token.removed webhook notifications\n- In List Transactions responses for transactions where the associated token was later removed\n\nWhen this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.\n"},"type":{"type":"string","enum":["Unknown","Physical","Virtual","VirtualAch","VirtualEft","Token"],"description":"The type of payment method:\n- `Physical` - A physical payment terminal for Card Present transactions\n- `Virtual` - A hosted payment form/iframe for Card Not Present transactions\n- `VirtualAch` - A hosted payment form/iframe for ACH (US) bank transfer transactions\n- `Token` - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions\n- `VirtualEft` - A virtual Canadian bank-transfer payment method, when configured.\n- `Unknown` - The payment method type is not known.\n"},"currency":{"type":"string","enum":["USD","CAD"],"description":"The currency of the payment method."},"description":{"type":"string","description":"A human-readable name for the payment method."},"billingContact":{"allOf":[{"$ref":"#/components/schemas/BillingContact"},{"type":"object","description":"Billing contact information. Only returned for tokenized payment methods from Card Not Present transactions."}]},"cardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"maskedCardNumber":{"type":"string","description":"The masked card number. The format may vary (e.g. ************0011, 4****0011, etc.)"},"cardExpDate":{"type":"string","description":"The expiration date of the card in MMYY format."},"accountType":{"type":"string","enum":["Credit","Debit","Checking","Savings"],"description":"Funding-source classification of this token-type payment method.\n- For card tokens: `Credit` or `Debit`.\n- For ACH tokens: `Checking` or `Savings`.\nMay be omitted for older tokens that pre-date this field, for non-token payment methods,\nor when the source did not provide a classification.\n"},"accountNumber":{"type":"string","description":"Masked bank account number, when available for a bank-account token."}},"required":["id","type","currency"]},"BillingContact":{"type":"object","description":"Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}},"InvoiceNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.\n"},"OrderNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.\n"},"ReferenceIdForResponse":{"type":"string","maxLength":100,"description":"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.\n"}}}}
```

## The PaymentMethodsListResponse object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"PaymentMethodsListResponse":{"type":"object","description":"Paginated response containing payment methods","properties":{"totalCount":{"type":"integer","description":"Total number of payment methods that match the filter criteria"},"page":{"type":"integer","description":"The current page number (starts at 1)"},"pageSize":{"type":"integer","description":"Number of items per page"},"totalPages":{"type":"integer","description":"Total number of pages available"},"hasNextPage":{"type":"boolean","description":"True if there are more pages of results available"},"hasPreviousPage":{"type":"boolean","description":"True if there are previous pages of results available"},"items":{"type":"array","description":"Array of payment methods for the current page","items":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","properties":{"type":{"type":"string","enum":["Physical","Virtual","VirtualAch","VirtualEft"]}}}]}}},"required":["totalCount","page","pageSize","totalPages","hasNextPage","hasPreviousPage","items"]},"PaymentMethodDetails":{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string","description":"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."},"dateDeleted":{"type":"string","format":"date-time","description":"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.\n\nThis field will be present in three scenarios:\n- As part of a successful Remove Token endpoint response\n- In token.removed webhook notifications\n- In List Transactions responses for transactions where the associated token was later removed\n\nWhen this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.\n"},"type":{"type":"string","enum":["Unknown","Physical","Virtual","VirtualAch","VirtualEft","Token"],"description":"The type of payment method:\n- `Physical` - A physical payment terminal for Card Present transactions\n- `Virtual` - A hosted payment form/iframe for Card Not Present transactions\n- `VirtualAch` - A hosted payment form/iframe for ACH (US) bank transfer transactions\n- `Token` - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions\n- `VirtualEft` - A virtual Canadian bank-transfer payment method, when configured.\n- `Unknown` - The payment method type is not known.\n"},"currency":{"type":"string","enum":["USD","CAD"],"description":"The currency of the payment method."},"description":{"type":"string","description":"A human-readable name for the payment method."},"billingContact":{"allOf":[{"$ref":"#/components/schemas/BillingContact"},{"type":"object","description":"Billing contact information. Only returned for tokenized payment methods from Card Not Present transactions."}]},"cardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"maskedCardNumber":{"type":"string","description":"The masked card number. The format may vary (e.g. ************0011, 4****0011, etc.)"},"cardExpDate":{"type":"string","description":"The expiration date of the card in MMYY format."},"accountType":{"type":"string","enum":["Credit","Debit","Checking","Savings"],"description":"Funding-source classification of this token-type payment method.\n- For card tokens: `Credit` or `Debit`.\n- For ACH tokens: `Checking` or `Savings`.\nMay be omitted for older tokens that pre-date this field, for non-token payment methods,\nor when the source did not provide a classification.\n"},"accountNumber":{"type":"string","description":"Masked bank account number, when available for a bank-account token."}},"required":["id","type","currency"]},"BillingContact":{"type":"object","description":"Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}}}}}
```

## The AccountHolderPaymentMethodsListResponse object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"AccountHolderPaymentMethodsListResponse":{"type":"object","description":"Paginated response containing account holder payment methods","properties":{"totalCount":{"type":"integer","description":"Total number of payment methods that match the filter criteria"},"page":{"type":"integer","description":"The current page number (starts at 1)"},"pageSize":{"type":"integer","description":"Number of items per page"},"totalPages":{"type":"integer","description":"Total number of pages available"},"hasNextPage":{"type":"boolean","description":"True if there are more pages of results available"},"hasPreviousPage":{"type":"boolean","description":"True if there are previous pages of results available"},"items":{"type":"array","description":"List of tokenized payment methods for the account holder","items":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","properties":{"type":{"type":"string","enum":["Token"]}}}]}}},"required":["totalCount","page","pageSize","totalPages","hasNextPage","hasPreviousPage","items"]},"PaymentMethodDetails":{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string","description":"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."},"dateDeleted":{"type":"string","format":"date-time","description":"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.\n\nThis field will be present in three scenarios:\n- As part of a successful Remove Token endpoint response\n- In token.removed webhook notifications\n- In List Transactions responses for transactions where the associated token was later removed\n\nWhen this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.\n"},"type":{"type":"string","enum":["Unknown","Physical","Virtual","VirtualAch","VirtualEft","Token"],"description":"The type of payment method:\n- `Physical` - A physical payment terminal for Card Present transactions\n- `Virtual` - A hosted payment form/iframe for Card Not Present transactions\n- `VirtualAch` - A hosted payment form/iframe for ACH (US) bank transfer transactions\n- `Token` - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions\n- `VirtualEft` - A virtual Canadian bank-transfer payment method, when configured.\n- `Unknown` - The payment method type is not known.\n"},"currency":{"type":"string","enum":["USD","CAD"],"description":"The currency of the payment method."},"description":{"type":"string","description":"A human-readable name for the payment method."},"billingContact":{"allOf":[{"$ref":"#/components/schemas/BillingContact"},{"type":"object","description":"Billing contact information. Only returned for tokenized payment methods from Card Not Present transactions."}]},"cardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"maskedCardNumber":{"type":"string","description":"The masked card number. The format may vary (e.g. ************0011, 4****0011, etc.)"},"cardExpDate":{"type":"string","description":"The expiration date of the card in MMYY format."},"accountType":{"type":"string","enum":["Credit","Debit","Checking","Savings"],"description":"Funding-source classification of this token-type payment method.\n- For card tokens: `Credit` or `Debit`.\n- For ACH tokens: `Checking` or `Savings`.\nMay be omitted for older tokens that pre-date this field, for non-token payment methods,\nor when the source did not provide a classification.\n"},"accountNumber":{"type":"string","description":"Masked bank account number, when available for a bank-account token."}},"required":["id","type","currency"]},"BillingContact":{"type":"object","description":"Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}}}}}
```

## The AccountHolder object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"AccountHolder":{"type":"object","description":"Account holder information associated with the transaction","properties":{"id":{"type":"string","description":"Account holder ID assigned by the API."},"externalId":{"type":"string","description":"External account holder ID assigned by the integrator."},"contact":{"type":"object","description":"Contact information for the account holder. Only returned for Card Not Present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}}},"required":["id","externalId"]}}}}
```

## The AccountHolderRequest object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"AccountHolderRequest":{"type":"object","description":"Account holder information for associating a transaction or tokenized payment method with a customer.\n\nWhen you provide an `externalId`, the system will either find an existing account holder with that ID or create a new one. This allows you to link payment methods and transactions to your own customer identifiers (e.g., CRM contact IDs, user IDs from your system).\n","properties":{"externalId":{"type":"string","maxLength":255,"description":"Your external identifier for this customer. This can be any unique identifier from your system.\n\nIf an account holder with this external ID already exists for your merchant account, it will be used. Otherwise, a new account holder will be created with this external ID.\n"}}}}}}
```

## The BillingContact object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"BillingContact":{"type":"object","description":"Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}}}}}
```

## The TransactionsListResponse object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"TransactionsListResponse":{"type":"object","description":"Paginated response containing transactions","properties":{"totalCount":{"type":"integer","description":"Total number of transactions that match the filter criteria"},"page":{"type":"integer","description":"The current page number (starts at 1)"},"pageSize":{"type":"integer","description":"Number of items per page"},"totalPages":{"type":"integer","description":"Total number of pages available"},"hasNextPage":{"type":"boolean","description":"True if there are more pages of results available"},"hasPreviousPage":{"type":"boolean","description":"True if there are previous pages of results available"},"items":{"type":"array","description":"Array of transactions for the current page","items":{"$ref":"#/components/schemas/TransactionResponseObject"}}},"required":["totalCount","page","pageSize","totalPages","hasNextPage","hasPreviousPage","items"]},"TransactionResponseObject":{"type":"object","description":"Represents the response to a sale or authorization transaction.","properties":{"id":{"type":"string","description":"Unique ID for this transaction."},"timestamp":{"type":"string","format":"date-time","description":"Transaction timestamp in UTC"},"type":{"type":"string","enum":["Sale","Auth","Capture","Refund","Void"],"description":"Type of transaction"},"status":{"$ref":"#/components/schemas/TransactionStatus"},"accountHolder":{"allOf":[{"$ref":"#/components/schemas/AccountHolder"},{"type":"object","description":"Account holder information, when available. Contact fields are omitted when they were not collected."}]},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The payment method used for this transaction. This could be:\n\n- The payment method used for this Card Present transaction.\n- The payment method used for this Card Not Present transaction.\n- The payment method used for this token transaction.\n\nIf a new card was tokenized during the transaction, the tokenized card ID and details will be returned in the `transactionResponses`'s `paymentMethod` object.\n","properties":{"id":{"type":"string"}}}]},"invoiceNumber":{"$ref":"#/components/schemas/InvoiceNumber"},"orderNumber":{"$ref":"#/components/schemas/OrderNumber"},"referenceId":{"$ref":"#/components/schemas/ReferenceIdForResponse"},"resultCode":{"$ref":"#/components/schemas/ResultCode"},"resultText":{"$ref":"#/components/schemas/ResultText"},"requestedAmount":{"type":"integer","description":"The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization."},"approvedAmount":{"type":"integer","description":"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."},"balanceAmount":{"type":"integer","description":"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)."},"refundableAmount":{"type":"integer","description":"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."},"transactionResponses":{"type":"array","description":"Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.","items":{"allOf":[{"$ref":"#/components/schemas/TransactionResponse"},{"type":"object","properties":{"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"If a new card was tokenized during the transaction, the tokenized card ID and details will be returned (`pmt_tkn_*`). This value should be stored in your system if you wish to use it for subsequent Card On File transactions.\n","properties":{"id":{"type":"string"}}}]}}}]}},"sourceId":{"type":"string","description":"Identifier of the session or other source that initiated the transaction."},"threeDs":{"$ref":"#/components/schemas/ThreeDsAuthentication"},"threeDsChallenge":{"$ref":"#/components/schemas/ThreeDsChallenge"}}},"TransactionStatus":{"type":"string","enum":["Unknown","Created","Pending","Submitted","Acknowledged","Processing","AwaitingSettlement","Completed","Failed","Abandoned"],"description":"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.\n"},"AccountHolder":{"type":"object","description":"Account holder information associated with the transaction","properties":{"id":{"type":"string","description":"Account holder ID assigned by the API."},"externalId":{"type":"string","description":"External account holder ID assigned by the integrator."},"contact":{"type":"object","description":"Contact information for the account holder. Only returned for Card Not Present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}}},"required":["id","externalId"]},"PaymentMethodDetails":{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string","description":"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."},"dateDeleted":{"type":"string","format":"date-time","description":"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.\n\nThis field will be present in three scenarios:\n- As part of a successful Remove Token endpoint response\n- In token.removed webhook notifications\n- In List Transactions responses for transactions where the associated token was later removed\n\nWhen this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.\n"},"type":{"type":"string","enum":["Unknown","Physical","Virtual","VirtualAch","VirtualEft","Token"],"description":"The type of payment method:\n- `Physical` - A physical payment terminal for Card Present transactions\n- `Virtual` - A hosted payment form/iframe for Card Not Present transactions\n- `VirtualAch` - A hosted payment form/iframe for ACH (US) bank transfer transactions\n- `Token` - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions\n- `VirtualEft` - A virtual Canadian bank-transfer payment method, when configured.\n- `Unknown` - The payment method type is not known.\n"},"currency":{"type":"string","enum":["USD","CAD"],"description":"The currency of the payment method."},"description":{"type":"string","description":"A human-readable name for the payment method."},"billingContact":{"allOf":[{"$ref":"#/components/schemas/BillingContact"},{"type":"object","description":"Billing contact information. Only returned for tokenized payment methods from Card Not Present transactions."}]},"cardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"maskedCardNumber":{"type":"string","description":"The masked card number. The format may vary (e.g. ************0011, 4****0011, etc.)"},"cardExpDate":{"type":"string","description":"The expiration date of the card in MMYY format."},"accountType":{"type":"string","enum":["Credit","Debit","Checking","Savings"],"description":"Funding-source classification of this token-type payment method.\n- For card tokens: `Credit` or `Debit`.\n- For ACH tokens: `Checking` or `Savings`.\nMay be omitted for older tokens that pre-date this field, for non-token payment methods,\nor when the source did not provide a classification.\n"},"accountNumber":{"type":"string","description":"Masked bank account number, when available for a bank-account token."}},"required":["id","type","currency"]},"BillingContact":{"type":"object","description":"Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}},"InvoiceNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.\n"},"OrderNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.\n"},"ReferenceIdForResponse":{"type":"string","maxLength":100,"description":"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.\n"},"ResultCode":{"type":"integer","enum":[0,55,1003,1005,1010,3000,3002,3005,3006,3009,3010,3011,3012,3013,3014,3020,4001,4100,6800,6801,6802,6900,6901,6902,9998,9999],"description":"Result codes:\n* `0` - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)\n* `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)\n* `1005` - The specified terminal could not be found.\n* `1010` - The transaction request is pending to become transaction.\n* `3000` - An unexpected error occurred. Please try again.\n* `3002` - The transaction could not be completed because the payment terminal could not find the related transaction.\n* `3005` - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.\n* `3006` - The transaction could not be completed because the payment terminal is low on battery.\n* `3009` - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.\n* `3010` - The transaction took too long and was cancelled by the application.\n* `3011` - Invalid transaction request. Please consult the documentation for valid transaction requests.\n* `3012` - Invalid transaction request. paymentMethodId is invalid.\n* `3013` - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.\n* `3014` - Invalid amount. Please try your transaction again with an amount greater than $0.\n* `3020` - An unsupported transaction result was received.\n* `4001` - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.\n* `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`. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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.\n* `6802` - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `6902` - The gateway reported no failure but returned no payment token. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `9998` - The system is not ready to process a transaction.\n* `9999` - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.\n* `1010` - The transaction request is pending customer interaction.\n* `4100` - Cardholder verification is required. Follow `threeDsChallenge.redirectUrl` and reconcile the final transaction outcome before retrying.\n* `55` - The customer cancelled the hosted payment attempt.\n"},"ResultText":{"type":"string","description":"A message describing the result code in more detail."},"TransactionResponse":{"type":"object","description":"A single Sale Transaction may result in multiple Responses.","properties":{"responseCode":{"$ref":"#/components/schemas/ResponseCode"},"authCode":{"type":"string","description":"The authorization code provided by the card issuer, confirming transaction approval."},"amountApproved":{"type":"integer","description":"The amount approved for this transaction response."},"approvedAmountBreakdown":{"$ref":"#/components/schemas/ApprovedAmountBreakdown"},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The payment method used for this transaction response."}]},"cardType":{"$ref":"#/components/schemas/CardType"},"avsResult":{"$ref":"#/components/schemas/AVSResult"},"cvvResult":{"$ref":"#/components/schemas/CVVResult"},"accountType":{"type":"string","description":"The funding-source classification associated with the payment method used in this\ntransaction.\n- For credit/debit cards: `Credit` or `Debit`. May be null when the classification is unavailable, including on older transactions.\n- For ACH/EFT bank accounts: `Checking` or `Savings`.\n\nThe immediate hosted ACH response uses lowercase `checking` or `savings`. Retrieved transaction responses normally use `Checking` or `Savings`.\n","enum":["Credit","Debit","Checking","Savings","checking","savings"]},"hostResponseText":{"type":"string","description":"A meaningful text explaining the response code from the host."},"receipt":{"$ref":"#/components/schemas/Receipt"}}},"ResponseCode":{"type":"integer","enum":[0,1,2,10,11,12,13,14,15,16,17,18,19,20,21,50,51,52,53,54,55,56,57],"description":"Response codes:\n * `0` - UNKNOWN\n * `1` - APPROVED - Transaction was approved\n * `2` - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.\n * `10` - DECLINED - Transaction was declined by the issuer or bank.  For Card-Present, the transaction can also be declined offline by the terminal.\n * `11` - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.\n * `12` - CARD_EXPIRED - The card used for the transaction has expired.\n * `13` - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.\n * `14` - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).\n * `15` - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).\n * `16` - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).\n * `17` - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.\n * `18` - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.\n * `19` - BATCH_EMPTY - Indicates that the batch for processing is empty.\n * `20` - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).\n * `21` - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.\n * `50` - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.\n * `51` - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.\n * `52` - NOT_SUPPORTED - Rejected because the requested operation is not supported.\n * `53` - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.\n * `54` - CANCELLED - Cancelled by the user or merchant.\n * `55` - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.\n * `56` - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.\n * `57` - PENDING - The transaction is awaiting an asynchronous outcome.\n"},"ApprovedAmountBreakdown":{"type":"object","description":"A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.","properties":{"amountGoodsAndServices":{"type":"integer","description":"The approved amount for goods and services."},"tax":{"type":"integer","description":"The approved tax amount."},"cashback":{"type":"integer","description":"The approved cashback amount."},"tip":{"type":"integer","description":"The approved tip amount."}}},"CardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"AVSResult":{"type":"string","enum":["A","E","N","R","S","U","G","W","X","Y","Z"],"description":"The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.\n * `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.\n * `E` - Ineligible transaction.\n * `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.\n * `R` - Retry (system unavailable or timed out).\n * `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.\n * `U` - Address information unavailable.\n * `G` - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.\n * `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.\n * `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.\n * `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.\n * `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.\n\nNOTE: 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.\n"},"CVVResult":{"type":"string","enum":["M","N","P","S","U"],"description":"The CVV verification result. Typically returned on Card Not Present transactions.\n * `M` - CVV Match\n * `N` - CVV No Match\n * `P` - Not Processed\n * `S` - CVV should be on the card but the merchant indicates it is not.\n * `U` - User is unregistered\n\nNOTE: 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.\n"},"Receipt":{"type":"object","description":"Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.","properties":{"lines":{"type":"array","items":{"type":"string"},"description":"The receipt lines."}},"required":["lines"]},"ThreeDsAuthentication":{"type":"object","description":"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.\n","properties":{"status":{"allOf":[{"$ref":"#/components/schemas/ThreeDsStatus"}],"description":"The authentication outcome to use in your integration. The other `threeDs` fields provide supporting authentication data.\n"},"cavv":{"type":"string","description":"Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions."},"eci":{"type":"string","description":"E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:\n * `02` / `05` - Fully authenticated (liability shift to issuer).\n * `01` / `06` - Attempted authentication (partial liability shift).\n * `00` / `07` - Not authenticated (no liability shift).\n"},"xid":{"type":"string","description":"3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility."},"dsTransId":{"type":"string","description":"Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction."},"threeDReasonId":{"type":"string","description":"Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use `status` to handle the outcome and `threeDReason` for the explanation.\n"},"threeDReason":{"type":"string","description":"Human-readable description matching `threeDReasonId`."}}},"ThreeDsStatus":{"type":"string","enum":["Authenticated","Attempted","NotAuthenticated","Failed","Unavailable","NotEnrolled"],"description":"Outcome classification of the 3D Secure check performed on a card transaction. Only present on transactions initiated with `formConfig.enable3DSecure: true`. Use this status to handle the authentication outcome; the other `threeDs` fields provide supporting authentication data.\n\n* `Authenticated` - Issuer fully authenticated the cardholder (ECI `02` / `05`). Full liability shift to the issuer for fraud chargebacks. Covers both frictionless and challenge-completed flows.\n* `Attempted` - Issuer attempted authentication but did not fully authenticate the cardholder (ECI `01` / `06`). Partial liability shift, scheme-dependent.\n* `NotAuthenticated` - 3DS completed but the issuer did not authenticate the cardholder (ECI `00` / `07`). No liability shift.\n* `Failed` - Issuer's ACS rejected the cardholder authentication. Transaction was declined. See `threeDReasonId` for the issuer's reason.\n* `Unavailable` - A technical issue prevented 3DS authentication from completing.\n* `NotEnrolled` - The card is not enrolled in 3DS.\n"},"ThreeDsChallenge":{"type":"object","description":"Present when a token payment requires a cardholder challenge (`resultCode: 4100`).","properties":{"redirectUrl":{"type":"string","format":"uri","description":"Hosted URL where the cardholder completes the challenge."},"followUpToken":{"type":"string","description":"Opaque token identifying the pending challenge."}},"required":["redirectUrl","followUpToken"]}}}}
```

## The TransactionResponseObject object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"TransactionResponseObject":{"type":"object","description":"Represents the response to a sale or authorization transaction.","properties":{"id":{"type":"string","description":"Unique ID for this transaction."},"timestamp":{"type":"string","format":"date-time","description":"Transaction timestamp in UTC"},"type":{"type":"string","enum":["Sale","Auth","Capture","Refund","Void"],"description":"Type of transaction"},"status":{"$ref":"#/components/schemas/TransactionStatus"},"accountHolder":{"allOf":[{"$ref":"#/components/schemas/AccountHolder"},{"type":"object","description":"Account holder information, when available. Contact fields are omitted when they were not collected."}]},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The payment method used for this transaction. This could be:\n\n- The payment method used for this Card Present transaction.\n- The payment method used for this Card Not Present transaction.\n- The payment method used for this token transaction.\n\nIf a new card was tokenized during the transaction, the tokenized card ID and details will be returned in the `transactionResponses`'s `paymentMethod` object.\n","properties":{"id":{"type":"string"}}}]},"invoiceNumber":{"$ref":"#/components/schemas/InvoiceNumber"},"orderNumber":{"$ref":"#/components/schemas/OrderNumber"},"referenceId":{"$ref":"#/components/schemas/ReferenceIdForResponse"},"resultCode":{"$ref":"#/components/schemas/ResultCode"},"resultText":{"$ref":"#/components/schemas/ResultText"},"requestedAmount":{"type":"integer","description":"The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization."},"approvedAmount":{"type":"integer","description":"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."},"balanceAmount":{"type":"integer","description":"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)."},"refundableAmount":{"type":"integer","description":"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."},"transactionResponses":{"type":"array","description":"Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.","items":{"allOf":[{"$ref":"#/components/schemas/TransactionResponse"},{"type":"object","properties":{"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"If a new card was tokenized during the transaction, the tokenized card ID and details will be returned (`pmt_tkn_*`). This value should be stored in your system if you wish to use it for subsequent Card On File transactions.\n","properties":{"id":{"type":"string"}}}]}}}]}},"sourceId":{"type":"string","description":"Identifier of the session or other source that initiated the transaction."},"threeDs":{"$ref":"#/components/schemas/ThreeDsAuthentication"},"threeDsChallenge":{"$ref":"#/components/schemas/ThreeDsChallenge"}}},"TransactionStatus":{"type":"string","enum":["Unknown","Created","Pending","Submitted","Acknowledged","Processing","AwaitingSettlement","Completed","Failed","Abandoned"],"description":"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.\n"},"AccountHolder":{"type":"object","description":"Account holder information associated with the transaction","properties":{"id":{"type":"string","description":"Account holder ID assigned by the API."},"externalId":{"type":"string","description":"External account holder ID assigned by the integrator."},"contact":{"type":"object","description":"Contact information for the account holder. Only returned for Card Not Present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}}},"required":["id","externalId"]},"PaymentMethodDetails":{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string","description":"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."},"dateDeleted":{"type":"string","format":"date-time","description":"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.\n\nThis field will be present in three scenarios:\n- As part of a successful Remove Token endpoint response\n- In token.removed webhook notifications\n- In List Transactions responses for transactions where the associated token was later removed\n\nWhen this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.\n"},"type":{"type":"string","enum":["Unknown","Physical","Virtual","VirtualAch","VirtualEft","Token"],"description":"The type of payment method:\n- `Physical` - A physical payment terminal for Card Present transactions\n- `Virtual` - A hosted payment form/iframe for Card Not Present transactions\n- `VirtualAch` - A hosted payment form/iframe for ACH (US) bank transfer transactions\n- `Token` - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions\n- `VirtualEft` - A virtual Canadian bank-transfer payment method, when configured.\n- `Unknown` - The payment method type is not known.\n"},"currency":{"type":"string","enum":["USD","CAD"],"description":"The currency of the payment method."},"description":{"type":"string","description":"A human-readable name for the payment method."},"billingContact":{"allOf":[{"$ref":"#/components/schemas/BillingContact"},{"type":"object","description":"Billing contact information. Only returned for tokenized payment methods from Card Not Present transactions."}]},"cardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"maskedCardNumber":{"type":"string","description":"The masked card number. The format may vary (e.g. ************0011, 4****0011, etc.)"},"cardExpDate":{"type":"string","description":"The expiration date of the card in MMYY format."},"accountType":{"type":"string","enum":["Credit","Debit","Checking","Savings"],"description":"Funding-source classification of this token-type payment method.\n- For card tokens: `Credit` or `Debit`.\n- For ACH tokens: `Checking` or `Savings`.\nMay be omitted for older tokens that pre-date this field, for non-token payment methods,\nor when the source did not provide a classification.\n"},"accountNumber":{"type":"string","description":"Masked bank account number, when available for a bank-account token."}},"required":["id","type","currency"]},"BillingContact":{"type":"object","description":"Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}},"InvoiceNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.\n"},"OrderNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.\n"},"ReferenceIdForResponse":{"type":"string","maxLength":100,"description":"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.\n"},"ResultCode":{"type":"integer","enum":[0,55,1003,1005,1010,3000,3002,3005,3006,3009,3010,3011,3012,3013,3014,3020,4001,4100,6800,6801,6802,6900,6901,6902,9998,9999],"description":"Result codes:\n* `0` - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)\n* `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)\n* `1005` - The specified terminal could not be found.\n* `1010` - The transaction request is pending to become transaction.\n* `3000` - An unexpected error occurred. Please try again.\n* `3002` - The transaction could not be completed because the payment terminal could not find the related transaction.\n* `3005` - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.\n* `3006` - The transaction could not be completed because the payment terminal is low on battery.\n* `3009` - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.\n* `3010` - The transaction took too long and was cancelled by the application.\n* `3011` - Invalid transaction request. Please consult the documentation for valid transaction requests.\n* `3012` - Invalid transaction request. paymentMethodId is invalid.\n* `3013` - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.\n* `3014` - Invalid amount. Please try your transaction again with an amount greater than $0.\n* `3020` - An unsupported transaction result was received.\n* `4001` - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.\n* `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`. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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.\n* `6802` - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `6902` - The gateway reported no failure but returned no payment token. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `9998` - The system is not ready to process a transaction.\n* `9999` - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.\n* `1010` - The transaction request is pending customer interaction.\n* `4100` - Cardholder verification is required. Follow `threeDsChallenge.redirectUrl` and reconcile the final transaction outcome before retrying.\n* `55` - The customer cancelled the hosted payment attempt.\n"},"ResultText":{"type":"string","description":"A message describing the result code in more detail."},"TransactionResponse":{"type":"object","description":"A single Sale Transaction may result in multiple Responses.","properties":{"responseCode":{"$ref":"#/components/schemas/ResponseCode"},"authCode":{"type":"string","description":"The authorization code provided by the card issuer, confirming transaction approval."},"amountApproved":{"type":"integer","description":"The amount approved for this transaction response."},"approvedAmountBreakdown":{"$ref":"#/components/schemas/ApprovedAmountBreakdown"},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The payment method used for this transaction response."}]},"cardType":{"$ref":"#/components/schemas/CardType"},"avsResult":{"$ref":"#/components/schemas/AVSResult"},"cvvResult":{"$ref":"#/components/schemas/CVVResult"},"accountType":{"type":"string","description":"The funding-source classification associated with the payment method used in this\ntransaction.\n- For credit/debit cards: `Credit` or `Debit`. May be null when the classification is unavailable, including on older transactions.\n- For ACH/EFT bank accounts: `Checking` or `Savings`.\n\nThe immediate hosted ACH response uses lowercase `checking` or `savings`. Retrieved transaction responses normally use `Checking` or `Savings`.\n","enum":["Credit","Debit","Checking","Savings","checking","savings"]},"hostResponseText":{"type":"string","description":"A meaningful text explaining the response code from the host."},"receipt":{"$ref":"#/components/schemas/Receipt"}}},"ResponseCode":{"type":"integer","enum":[0,1,2,10,11,12,13,14,15,16,17,18,19,20,21,50,51,52,53,54,55,56,57],"description":"Response codes:\n * `0` - UNKNOWN\n * `1` - APPROVED - Transaction was approved\n * `2` - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.\n * `10` - DECLINED - Transaction was declined by the issuer or bank.  For Card-Present, the transaction can also be declined offline by the terminal.\n * `11` - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.\n * `12` - CARD_EXPIRED - The card used for the transaction has expired.\n * `13` - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.\n * `14` - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).\n * `15` - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).\n * `16` - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).\n * `17` - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.\n * `18` - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.\n * `19` - BATCH_EMPTY - Indicates that the batch for processing is empty.\n * `20` - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).\n * `21` - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.\n * `50` - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.\n * `51` - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.\n * `52` - NOT_SUPPORTED - Rejected because the requested operation is not supported.\n * `53` - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.\n * `54` - CANCELLED - Cancelled by the user or merchant.\n * `55` - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.\n * `56` - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.\n * `57` - PENDING - The transaction is awaiting an asynchronous outcome.\n"},"ApprovedAmountBreakdown":{"type":"object","description":"A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.","properties":{"amountGoodsAndServices":{"type":"integer","description":"The approved amount for goods and services."},"tax":{"type":"integer","description":"The approved tax amount."},"cashback":{"type":"integer","description":"The approved cashback amount."},"tip":{"type":"integer","description":"The approved tip amount."}}},"CardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"AVSResult":{"type":"string","enum":["A","E","N","R","S","U","G","W","X","Y","Z"],"description":"The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.\n * `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.\n * `E` - Ineligible transaction.\n * `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.\n * `R` - Retry (system unavailable or timed out).\n * `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.\n * `U` - Address information unavailable.\n * `G` - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.\n * `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.\n * `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.\n * `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.\n * `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.\n\nNOTE: 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.\n"},"CVVResult":{"type":"string","enum":["M","N","P","S","U"],"description":"The CVV verification result. Typically returned on Card Not Present transactions.\n * `M` - CVV Match\n * `N` - CVV No Match\n * `P` - Not Processed\n * `S` - CVV should be on the card but the merchant indicates it is not.\n * `U` - User is unregistered\n\nNOTE: 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.\n"},"Receipt":{"type":"object","description":"Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.","properties":{"lines":{"type":"array","items":{"type":"string"},"description":"The receipt lines."}},"required":["lines"]},"ThreeDsAuthentication":{"type":"object","description":"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.\n","properties":{"status":{"allOf":[{"$ref":"#/components/schemas/ThreeDsStatus"}],"description":"The authentication outcome to use in your integration. The other `threeDs` fields provide supporting authentication data.\n"},"cavv":{"type":"string","description":"Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions."},"eci":{"type":"string","description":"E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:\n * `02` / `05` - Fully authenticated (liability shift to issuer).\n * `01` / `06` - Attempted authentication (partial liability shift).\n * `00` / `07` - Not authenticated (no liability shift).\n"},"xid":{"type":"string","description":"3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility."},"dsTransId":{"type":"string","description":"Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction."},"threeDReasonId":{"type":"string","description":"Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use `status` to handle the outcome and `threeDReason` for the explanation.\n"},"threeDReason":{"type":"string","description":"Human-readable description matching `threeDReasonId`."}}},"ThreeDsStatus":{"type":"string","enum":["Authenticated","Attempted","NotAuthenticated","Failed","Unavailable","NotEnrolled"],"description":"Outcome classification of the 3D Secure check performed on a card transaction. Only present on transactions initiated with `formConfig.enable3DSecure: true`. Use this status to handle the authentication outcome; the other `threeDs` fields provide supporting authentication data.\n\n* `Authenticated` - Issuer fully authenticated the cardholder (ECI `02` / `05`). Full liability shift to the issuer for fraud chargebacks. Covers both frictionless and challenge-completed flows.\n* `Attempted` - Issuer attempted authentication but did not fully authenticate the cardholder (ECI `01` / `06`). Partial liability shift, scheme-dependent.\n* `NotAuthenticated` - 3DS completed but the issuer did not authenticate the cardholder (ECI `00` / `07`). No liability shift.\n* `Failed` - Issuer's ACS rejected the cardholder authentication. Transaction was declined. See `threeDReasonId` for the issuer's reason.\n* `Unavailable` - A technical issue prevented 3DS authentication from completing.\n* `NotEnrolled` - The card is not enrolled in 3DS.\n"},"ThreeDsChallenge":{"type":"object","description":"Present when a token payment requires a cardholder challenge (`resultCode: 4100`).","properties":{"redirectUrl":{"type":"string","format":"uri","description":"Hosted URL where the cardholder completes the challenge."},"followUpToken":{"type":"string","description":"Opaque token identifying the pending challenge."}},"required":["redirectUrl","followUpToken"]}}}}
```

## The CNPTransactionResponse object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"CNPTransactionResponse":{"type":"object","description":"Represents the response to a Card Not Present sale or authorization using a previously tokenized card.","properties":{"id":{"type":"string","description":"Unique ID for this transaction."},"sourceId":{"type":"string","description":"The source ID of the transaction."},"timestamp":{"type":"string","format":"date-time","description":"Transaction timestamp in UTC"},"type":{"type":"string","enum":["Sale","Auth","Capture","Refund","Void"],"description":"Type of transaction"},"status":{"$ref":"#/components/schemas/TransactionStatus"},"accountHolder":{"allOf":[{"$ref":"#/components/schemas/AccountHolder"},{"type":"object","description":"Account holder information, when available. Contact fields are omitted when they were not collected."}]},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string"}}}]},"invoiceNumber":{"$ref":"#/components/schemas/InvoiceNumber"},"orderNumber":{"$ref":"#/components/schemas/OrderNumber"},"referenceId":{"$ref":"#/components/schemas/ReferenceIdForResponse"},"resultCode":{"$ref":"#/components/schemas/ResultCode"},"resultText":{"$ref":"#/components/schemas/ResultText"},"requestedAmount":{"type":"integer","description":"The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization."},"approvedAmount":{"type":"integer","description":"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."},"balanceAmount":{"type":"integer","description":"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)."},"refundableAmount":{"type":"integer","description":"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."},"transactionResponses":{"type":"array","description":"Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.","items":{"$ref":"#/components/schemas/TransactionResponse"}},"threeDs":{"allOf":[{"$ref":"#/components/schemas/ThreeDsAuthentication"}],"description":"3D Secure authentication data returned by the issuer. Populated when the transaction was initiated with `formConfig.enable3DSecure: true`. Null on non-3DS transactions or when no authentication data is available.\n"},"threeDsChallenge":{"$ref":"#/components/schemas/ThreeDsChallenge"}}},"TransactionStatus":{"type":"string","enum":["Unknown","Created","Pending","Submitted","Acknowledged","Processing","AwaitingSettlement","Completed","Failed","Abandoned"],"description":"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.\n"},"AccountHolder":{"type":"object","description":"Account holder information associated with the transaction","properties":{"id":{"type":"string","description":"Account holder ID assigned by the API."},"externalId":{"type":"string","description":"External account holder ID assigned by the integrator."},"contact":{"type":"object","description":"Contact information for the account holder. Only returned for Card Not Present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}}},"required":["id","externalId"]},"PaymentMethodDetails":{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string","description":"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."},"dateDeleted":{"type":"string","format":"date-time","description":"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.\n\nThis field will be present in three scenarios:\n- As part of a successful Remove Token endpoint response\n- In token.removed webhook notifications\n- In List Transactions responses for transactions where the associated token was later removed\n\nWhen this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.\n"},"type":{"type":"string","enum":["Unknown","Physical","Virtual","VirtualAch","VirtualEft","Token"],"description":"The type of payment method:\n- `Physical` - A physical payment terminal for Card Present transactions\n- `Virtual` - A hosted payment form/iframe for Card Not Present transactions\n- `VirtualAch` - A hosted payment form/iframe for ACH (US) bank transfer transactions\n- `Token` - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions\n- `VirtualEft` - A virtual Canadian bank-transfer payment method, when configured.\n- `Unknown` - The payment method type is not known.\n"},"currency":{"type":"string","enum":["USD","CAD"],"description":"The currency of the payment method."},"description":{"type":"string","description":"A human-readable name for the payment method."},"billingContact":{"allOf":[{"$ref":"#/components/schemas/BillingContact"},{"type":"object","description":"Billing contact information. Only returned for tokenized payment methods from Card Not Present transactions."}]},"cardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"maskedCardNumber":{"type":"string","description":"The masked card number. The format may vary (e.g. ************0011, 4****0011, etc.)"},"cardExpDate":{"type":"string","description":"The expiration date of the card in MMYY format."},"accountType":{"type":"string","enum":["Credit","Debit","Checking","Savings"],"description":"Funding-source classification of this token-type payment method.\n- For card tokens: `Credit` or `Debit`.\n- For ACH tokens: `Checking` or `Savings`.\nMay be omitted for older tokens that pre-date this field, for non-token payment methods,\nor when the source did not provide a classification.\n"},"accountNumber":{"type":"string","description":"Masked bank account number, when available for a bank-account token."}},"required":["id","type","currency"]},"BillingContact":{"type":"object","description":"Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}},"InvoiceNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.\n"},"OrderNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.\n"},"ReferenceIdForResponse":{"type":"string","maxLength":100,"description":"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.\n"},"ResultCode":{"type":"integer","enum":[0,55,1003,1005,1010,3000,3002,3005,3006,3009,3010,3011,3012,3013,3014,3020,4001,4100,6800,6801,6802,6900,6901,6902,9998,9999],"description":"Result codes:\n* `0` - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)\n* `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)\n* `1005` - The specified terminal could not be found.\n* `1010` - The transaction request is pending to become transaction.\n* `3000` - An unexpected error occurred. Please try again.\n* `3002` - The transaction could not be completed because the payment terminal could not find the related transaction.\n* `3005` - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.\n* `3006` - The transaction could not be completed because the payment terminal is low on battery.\n* `3009` - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.\n* `3010` - The transaction took too long and was cancelled by the application.\n* `3011` - Invalid transaction request. Please consult the documentation for valid transaction requests.\n* `3012` - Invalid transaction request. paymentMethodId is invalid.\n* `3013` - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.\n* `3014` - Invalid amount. Please try your transaction again with an amount greater than $0.\n* `3020` - An unsupported transaction result was received.\n* `4001` - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.\n* `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`. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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.\n* `6802` - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `6902` - The gateway reported no failure but returned no payment token. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `9998` - The system is not ready to process a transaction.\n* `9999` - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.\n* `1010` - The transaction request is pending customer interaction.\n* `4100` - Cardholder verification is required. Follow `threeDsChallenge.redirectUrl` and reconcile the final transaction outcome before retrying.\n* `55` - The customer cancelled the hosted payment attempt.\n"},"ResultText":{"type":"string","description":"A message describing the result code in more detail."},"TransactionResponse":{"type":"object","description":"A single Sale Transaction may result in multiple Responses.","properties":{"responseCode":{"$ref":"#/components/schemas/ResponseCode"},"authCode":{"type":"string","description":"The authorization code provided by the card issuer, confirming transaction approval."},"amountApproved":{"type":"integer","description":"The amount approved for this transaction response."},"approvedAmountBreakdown":{"$ref":"#/components/schemas/ApprovedAmountBreakdown"},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The payment method used for this transaction response."}]},"cardType":{"$ref":"#/components/schemas/CardType"},"avsResult":{"$ref":"#/components/schemas/AVSResult"},"cvvResult":{"$ref":"#/components/schemas/CVVResult"},"accountType":{"type":"string","description":"The funding-source classification associated with the payment method used in this\ntransaction.\n- For credit/debit cards: `Credit` or `Debit`. May be null when the classification is unavailable, including on older transactions.\n- For ACH/EFT bank accounts: `Checking` or `Savings`.\n\nThe immediate hosted ACH response uses lowercase `checking` or `savings`. Retrieved transaction responses normally use `Checking` or `Savings`.\n","enum":["Credit","Debit","Checking","Savings","checking","savings"]},"hostResponseText":{"type":"string","description":"A meaningful text explaining the response code from the host."},"receipt":{"$ref":"#/components/schemas/Receipt"}}},"ResponseCode":{"type":"integer","enum":[0,1,2,10,11,12,13,14,15,16,17,18,19,20,21,50,51,52,53,54,55,56,57],"description":"Response codes:\n * `0` - UNKNOWN\n * `1` - APPROVED - Transaction was approved\n * `2` - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.\n * `10` - DECLINED - Transaction was declined by the issuer or bank.  For Card-Present, the transaction can also be declined offline by the terminal.\n * `11` - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.\n * `12` - CARD_EXPIRED - The card used for the transaction has expired.\n * `13` - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.\n * `14` - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).\n * `15` - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).\n * `16` - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).\n * `17` - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.\n * `18` - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.\n * `19` - BATCH_EMPTY - Indicates that the batch for processing is empty.\n * `20` - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).\n * `21` - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.\n * `50` - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.\n * `51` - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.\n * `52` - NOT_SUPPORTED - Rejected because the requested operation is not supported.\n * `53` - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.\n * `54` - CANCELLED - Cancelled by the user or merchant.\n * `55` - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.\n * `56` - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.\n * `57` - PENDING - The transaction is awaiting an asynchronous outcome.\n"},"ApprovedAmountBreakdown":{"type":"object","description":"A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.","properties":{"amountGoodsAndServices":{"type":"integer","description":"The approved amount for goods and services."},"tax":{"type":"integer","description":"The approved tax amount."},"cashback":{"type":"integer","description":"The approved cashback amount."},"tip":{"type":"integer","description":"The approved tip amount."}}},"CardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"AVSResult":{"type":"string","enum":["A","E","N","R","S","U","G","W","X","Y","Z"],"description":"The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.\n * `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.\n * `E` - Ineligible transaction.\n * `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.\n * `R` - Retry (system unavailable or timed out).\n * `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.\n * `U` - Address information unavailable.\n * `G` - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.\n * `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.\n * `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.\n * `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.\n * `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.\n\nNOTE: 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.\n"},"CVVResult":{"type":"string","enum":["M","N","P","S","U"],"description":"The CVV verification result. Typically returned on Card Not Present transactions.\n * `M` - CVV Match\n * `N` - CVV No Match\n * `P` - Not Processed\n * `S` - CVV should be on the card but the merchant indicates it is not.\n * `U` - User is unregistered\n\nNOTE: 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.\n"},"Receipt":{"type":"object","description":"Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.","properties":{"lines":{"type":"array","items":{"type":"string"},"description":"The receipt lines."}},"required":["lines"]},"ThreeDsAuthentication":{"type":"object","description":"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.\n","properties":{"status":{"allOf":[{"$ref":"#/components/schemas/ThreeDsStatus"}],"description":"The authentication outcome to use in your integration. The other `threeDs` fields provide supporting authentication data.\n"},"cavv":{"type":"string","description":"Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions."},"eci":{"type":"string","description":"E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:\n * `02` / `05` - Fully authenticated (liability shift to issuer).\n * `01` / `06` - Attempted authentication (partial liability shift).\n * `00` / `07` - Not authenticated (no liability shift).\n"},"xid":{"type":"string","description":"3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility."},"dsTransId":{"type":"string","description":"Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction."},"threeDReasonId":{"type":"string","description":"Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use `status` to handle the outcome and `threeDReason` for the explanation.\n"},"threeDReason":{"type":"string","description":"Human-readable description matching `threeDReasonId`."}}},"ThreeDsStatus":{"type":"string","enum":["Authenticated","Attempted","NotAuthenticated","Failed","Unavailable","NotEnrolled"],"description":"Outcome classification of the 3D Secure check performed on a card transaction. Only present on transactions initiated with `formConfig.enable3DSecure: true`. Use this status to handle the authentication outcome; the other `threeDs` fields provide supporting authentication data.\n\n* `Authenticated` - Issuer fully authenticated the cardholder (ECI `02` / `05`). Full liability shift to the issuer for fraud chargebacks. Covers both frictionless and challenge-completed flows.\n* `Attempted` - Issuer attempted authentication but did not fully authenticate the cardholder (ECI `01` / `06`). Partial liability shift, scheme-dependent.\n* `NotAuthenticated` - 3DS completed but the issuer did not authenticate the cardholder (ECI `00` / `07`). No liability shift.\n* `Failed` - Issuer's ACS rejected the cardholder authentication. Transaction was declined. See `threeDReasonId` for the issuer's reason.\n* `Unavailable` - A technical issue prevented 3DS authentication from completing.\n* `NotEnrolled` - The card is not enrolled in 3DS.\n"},"ThreeDsChallenge":{"type":"object","description":"Present when a token payment requires a cardholder challenge (`resultCode: 4100`).","properties":{"redirectUrl":{"type":"string","format":"uri","description":"Hosted URL where the cardholder completes the challenge."},"followUpToken":{"type":"string","description":"Opaque token identifying the pending challenge."}},"required":["redirectUrl","followUpToken"]}}}}
```

## The CaptureResponse object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"CaptureResponse":{"type":"object","description":"Represents the response to a capture request.","properties":{"id":{"type":"string","description":"Unique ID for this capture transaction."},"timestamp":{"type":"string","format":"date-time","description":"Transaction timestamp in UTC"},"type":{"type":"string","enum":["Sale","Auth","Capture","Refund","Void"],"description":"Type of transaction"},"status":{"$ref":"#/components/schemas/TransactionStatus"},"accountHolder":{"allOf":[{"$ref":"#/components/schemas/AccountHolder"},{"type":"object","description":"Account holder information, when available. Contact fields are omitted when they were not collected."}]},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string"}}}]},"invoiceNumber":{"$ref":"#/components/schemas/InvoiceNumber"},"orderNumber":{"$ref":"#/components/schemas/OrderNumber"},"referenceId":{"$ref":"#/components/schemas/ReferenceIdForResponse"},"resultCode":{"$ref":"#/components/schemas/ResultCode"},"resultText":{"$ref":"#/components/schemas/ResultText"},"requestedAmount":{"type":"integer","description":"The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization."},"approvedAmount":{"type":"integer","description":"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."},"transactionResponses":{"type":"array","description":"Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.","items":{"$ref":"#/components/schemas/TransactionResponse"}},"sourceId":{"type":"string","description":"Identifier of the session or other source that initiated the transaction."},"threeDs":{"$ref":"#/components/schemas/ThreeDsAuthentication"},"threeDsChallenge":{"$ref":"#/components/schemas/ThreeDsChallenge"},"balanceAmount":{"type":"integer","description":"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)."},"refundableAmount":{"type":"integer","description":"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."}}},"TransactionStatus":{"type":"string","enum":["Unknown","Created","Pending","Submitted","Acknowledged","Processing","AwaitingSettlement","Completed","Failed","Abandoned"],"description":"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.\n"},"AccountHolder":{"type":"object","description":"Account holder information associated with the transaction","properties":{"id":{"type":"string","description":"Account holder ID assigned by the API."},"externalId":{"type":"string","description":"External account holder ID assigned by the integrator."},"contact":{"type":"object","description":"Contact information for the account holder. Only returned for Card Not Present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}}},"required":["id","externalId"]},"PaymentMethodDetails":{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string","description":"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."},"dateDeleted":{"type":"string","format":"date-time","description":"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.\n\nThis field will be present in three scenarios:\n- As part of a successful Remove Token endpoint response\n- In token.removed webhook notifications\n- In List Transactions responses for transactions where the associated token was later removed\n\nWhen this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.\n"},"type":{"type":"string","enum":["Unknown","Physical","Virtual","VirtualAch","VirtualEft","Token"],"description":"The type of payment method:\n- `Physical` - A physical payment terminal for Card Present transactions\n- `Virtual` - A hosted payment form/iframe for Card Not Present transactions\n- `VirtualAch` - A hosted payment form/iframe for ACH (US) bank transfer transactions\n- `Token` - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions\n- `VirtualEft` - A virtual Canadian bank-transfer payment method, when configured.\n- `Unknown` - The payment method type is not known.\n"},"currency":{"type":"string","enum":["USD","CAD"],"description":"The currency of the payment method."},"description":{"type":"string","description":"A human-readable name for the payment method."},"billingContact":{"allOf":[{"$ref":"#/components/schemas/BillingContact"},{"type":"object","description":"Billing contact information. Only returned for tokenized payment methods from Card Not Present transactions."}]},"cardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"maskedCardNumber":{"type":"string","description":"The masked card number. The format may vary (e.g. ************0011, 4****0011, etc.)"},"cardExpDate":{"type":"string","description":"The expiration date of the card in MMYY format."},"accountType":{"type":"string","enum":["Credit","Debit","Checking","Savings"],"description":"Funding-source classification of this token-type payment method.\n- For card tokens: `Credit` or `Debit`.\n- For ACH tokens: `Checking` or `Savings`.\nMay be omitted for older tokens that pre-date this field, for non-token payment methods,\nor when the source did not provide a classification.\n"},"accountNumber":{"type":"string","description":"Masked bank account number, when available for a bank-account token."}},"required":["id","type","currency"]},"BillingContact":{"type":"object","description":"Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}},"InvoiceNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.\n"},"OrderNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.\n"},"ReferenceIdForResponse":{"type":"string","maxLength":100,"description":"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.\n"},"ResultCode":{"type":"integer","enum":[0,55,1003,1005,1010,3000,3002,3005,3006,3009,3010,3011,3012,3013,3014,3020,4001,4100,6800,6801,6802,6900,6901,6902,9998,9999],"description":"Result codes:\n* `0` - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)\n* `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)\n* `1005` - The specified terminal could not be found.\n* `1010` - The transaction request is pending to become transaction.\n* `3000` - An unexpected error occurred. Please try again.\n* `3002` - The transaction could not be completed because the payment terminal could not find the related transaction.\n* `3005` - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.\n* `3006` - The transaction could not be completed because the payment terminal is low on battery.\n* `3009` - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.\n* `3010` - The transaction took too long and was cancelled by the application.\n* `3011` - Invalid transaction request. Please consult the documentation for valid transaction requests.\n* `3012` - Invalid transaction request. paymentMethodId is invalid.\n* `3013` - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.\n* `3014` - Invalid amount. Please try your transaction again with an amount greater than $0.\n* `3020` - An unsupported transaction result was received.\n* `4001` - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.\n* `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`. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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.\n* `6802` - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `6902` - The gateway reported no failure but returned no payment token. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `9998` - The system is not ready to process a transaction.\n* `9999` - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.\n* `1010` - The transaction request is pending customer interaction.\n* `4100` - Cardholder verification is required. Follow `threeDsChallenge.redirectUrl` and reconcile the final transaction outcome before retrying.\n* `55` - The customer cancelled the hosted payment attempt.\n"},"ResultText":{"type":"string","description":"A message describing the result code in more detail."},"TransactionResponse":{"type":"object","description":"A single Sale Transaction may result in multiple Responses.","properties":{"responseCode":{"$ref":"#/components/schemas/ResponseCode"},"authCode":{"type":"string","description":"The authorization code provided by the card issuer, confirming transaction approval."},"amountApproved":{"type":"integer","description":"The amount approved for this transaction response."},"approvedAmountBreakdown":{"$ref":"#/components/schemas/ApprovedAmountBreakdown"},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The payment method used for this transaction response."}]},"cardType":{"$ref":"#/components/schemas/CardType"},"avsResult":{"$ref":"#/components/schemas/AVSResult"},"cvvResult":{"$ref":"#/components/schemas/CVVResult"},"accountType":{"type":"string","description":"The funding-source classification associated with the payment method used in this\ntransaction.\n- For credit/debit cards: `Credit` or `Debit`. May be null when the classification is unavailable, including on older transactions.\n- For ACH/EFT bank accounts: `Checking` or `Savings`.\n\nThe immediate hosted ACH response uses lowercase `checking` or `savings`. Retrieved transaction responses normally use `Checking` or `Savings`.\n","enum":["Credit","Debit","Checking","Savings","checking","savings"]},"hostResponseText":{"type":"string","description":"A meaningful text explaining the response code from the host."},"receipt":{"$ref":"#/components/schemas/Receipt"}}},"ResponseCode":{"type":"integer","enum":[0,1,2,10,11,12,13,14,15,16,17,18,19,20,21,50,51,52,53,54,55,56,57],"description":"Response codes:\n * `0` - UNKNOWN\n * `1` - APPROVED - Transaction was approved\n * `2` - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.\n * `10` - DECLINED - Transaction was declined by the issuer or bank.  For Card-Present, the transaction can also be declined offline by the terminal.\n * `11` - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.\n * `12` - CARD_EXPIRED - The card used for the transaction has expired.\n * `13` - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.\n * `14` - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).\n * `15` - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).\n * `16` - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).\n * `17` - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.\n * `18` - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.\n * `19` - BATCH_EMPTY - Indicates that the batch for processing is empty.\n * `20` - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).\n * `21` - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.\n * `50` - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.\n * `51` - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.\n * `52` - NOT_SUPPORTED - Rejected because the requested operation is not supported.\n * `53` - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.\n * `54` - CANCELLED - Cancelled by the user or merchant.\n * `55` - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.\n * `56` - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.\n * `57` - PENDING - The transaction is awaiting an asynchronous outcome.\n"},"ApprovedAmountBreakdown":{"type":"object","description":"A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.","properties":{"amountGoodsAndServices":{"type":"integer","description":"The approved amount for goods and services."},"tax":{"type":"integer","description":"The approved tax amount."},"cashback":{"type":"integer","description":"The approved cashback amount."},"tip":{"type":"integer","description":"The approved tip amount."}}},"CardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"AVSResult":{"type":"string","enum":["A","E","N","R","S","U","G","W","X","Y","Z"],"description":"The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.\n * `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.\n * `E` - Ineligible transaction.\n * `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.\n * `R` - Retry (system unavailable or timed out).\n * `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.\n * `U` - Address information unavailable.\n * `G` - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.\n * `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.\n * `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.\n * `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.\n * `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.\n\nNOTE: 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.\n"},"CVVResult":{"type":"string","enum":["M","N","P","S","U"],"description":"The CVV verification result. Typically returned on Card Not Present transactions.\n * `M` - CVV Match\n * `N` - CVV No Match\n * `P` - Not Processed\n * `S` - CVV should be on the card but the merchant indicates it is not.\n * `U` - User is unregistered\n\nNOTE: 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.\n"},"Receipt":{"type":"object","description":"Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.","properties":{"lines":{"type":"array","items":{"type":"string"},"description":"The receipt lines."}},"required":["lines"]},"ThreeDsAuthentication":{"type":"object","description":"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.\n","properties":{"status":{"allOf":[{"$ref":"#/components/schemas/ThreeDsStatus"}],"description":"The authentication outcome to use in your integration. The other `threeDs` fields provide supporting authentication data.\n"},"cavv":{"type":"string","description":"Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions."},"eci":{"type":"string","description":"E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:\n * `02` / `05` - Fully authenticated (liability shift to issuer).\n * `01` / `06` - Attempted authentication (partial liability shift).\n * `00` / `07` - Not authenticated (no liability shift).\n"},"xid":{"type":"string","description":"3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility."},"dsTransId":{"type":"string","description":"Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction."},"threeDReasonId":{"type":"string","description":"Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use `status` to handle the outcome and `threeDReason` for the explanation.\n"},"threeDReason":{"type":"string","description":"Human-readable description matching `threeDReasonId`."}}},"ThreeDsStatus":{"type":"string","enum":["Authenticated","Attempted","NotAuthenticated","Failed","Unavailable","NotEnrolled"],"description":"Outcome classification of the 3D Secure check performed on a card transaction. Only present on transactions initiated with `formConfig.enable3DSecure: true`. Use this status to handle the authentication outcome; the other `threeDs` fields provide supporting authentication data.\n\n* `Authenticated` - Issuer fully authenticated the cardholder (ECI `02` / `05`). Full liability shift to the issuer for fraud chargebacks. Covers both frictionless and challenge-completed flows.\n* `Attempted` - Issuer attempted authentication but did not fully authenticate the cardholder (ECI `01` / `06`). Partial liability shift, scheme-dependent.\n* `NotAuthenticated` - 3DS completed but the issuer did not authenticate the cardholder (ECI `00` / `07`). No liability shift.\n* `Failed` - Issuer's ACS rejected the cardholder authentication. Transaction was declined. See `threeDReasonId` for the issuer's reason.\n* `Unavailable` - A technical issue prevented 3DS authentication from completing.\n* `NotEnrolled` - The card is not enrolled in 3DS.\n"},"ThreeDsChallenge":{"type":"object","description":"Present when a token payment requires a cardholder challenge (`resultCode: 4100`).","properties":{"redirectUrl":{"type":"string","format":"uri","description":"Hosted URL where the cardholder completes the challenge."},"followUpToken":{"type":"string","description":"Opaque token identifying the pending challenge."}},"required":["redirectUrl","followUpToken"]}}}}
```

## The RefundResponse object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"RefundResponse":{"type":"object","description":"Represents the response to a refund request.","properties":{"id":{"type":"string","description":"Unique ID for this refund transaction."},"timestamp":{"type":"string","format":"date-time","description":"Transaction timestamp in UTC"},"type":{"type":"string","enum":["Sale","Auth","Capture","Refund","Void"],"description":"Type of transaction"},"status":{"$ref":"#/components/schemas/TransactionStatus"},"accountHolder":{"allOf":[{"$ref":"#/components/schemas/AccountHolder"},{"type":"object","description":"Account holder information, when available. Contact fields are omitted when they were not collected."}]},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string"}}}]},"invoiceNumber":{"$ref":"#/components/schemas/InvoiceNumber"},"orderNumber":{"$ref":"#/components/schemas/OrderNumber"},"referenceId":{"$ref":"#/components/schemas/ReferenceIdForResponse"},"resultCode":{"$ref":"#/components/schemas/ResultCode"},"resultText":{"$ref":"#/components/schemas/ResultText"},"requestedAmount":{"type":"integer","description":"The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization."},"approvedAmount":{"type":"integer","description":"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."},"refundableAmount":{"type":"integer","description":"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."},"transactionResponses":{"type":"array","description":"Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.","items":{"$ref":"#/components/schemas/TransactionResponse"}},"sourceId":{"type":"string","description":"Identifier of the session or other source that initiated the transaction."},"threeDs":{"$ref":"#/components/schemas/ThreeDsAuthentication"},"threeDsChallenge":{"$ref":"#/components/schemas/ThreeDsChallenge"},"balanceAmount":{"type":"integer","description":"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)."}}},"TransactionStatus":{"type":"string","enum":["Unknown","Created","Pending","Submitted","Acknowledged","Processing","AwaitingSettlement","Completed","Failed","Abandoned"],"description":"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.\n"},"AccountHolder":{"type":"object","description":"Account holder information associated with the transaction","properties":{"id":{"type":"string","description":"Account holder ID assigned by the API."},"externalId":{"type":"string","description":"External account holder ID assigned by the integrator."},"contact":{"type":"object","description":"Contact information for the account holder. Only returned for Card Not Present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}}},"required":["id","externalId"]},"PaymentMethodDetails":{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string","description":"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."},"dateDeleted":{"type":"string","format":"date-time","description":"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.\n\nThis field will be present in three scenarios:\n- As part of a successful Remove Token endpoint response\n- In token.removed webhook notifications\n- In List Transactions responses for transactions where the associated token was later removed\n\nWhen this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.\n"},"type":{"type":"string","enum":["Unknown","Physical","Virtual","VirtualAch","VirtualEft","Token"],"description":"The type of payment method:\n- `Physical` - A physical payment terminal for Card Present transactions\n- `Virtual` - A hosted payment form/iframe for Card Not Present transactions\n- `VirtualAch` - A hosted payment form/iframe for ACH (US) bank transfer transactions\n- `Token` - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions\n- `VirtualEft` - A virtual Canadian bank-transfer payment method, when configured.\n- `Unknown` - The payment method type is not known.\n"},"currency":{"type":"string","enum":["USD","CAD"],"description":"The currency of the payment method."},"description":{"type":"string","description":"A human-readable name for the payment method."},"billingContact":{"allOf":[{"$ref":"#/components/schemas/BillingContact"},{"type":"object","description":"Billing contact information. Only returned for tokenized payment methods from Card Not Present transactions."}]},"cardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"maskedCardNumber":{"type":"string","description":"The masked card number. The format may vary (e.g. ************0011, 4****0011, etc.)"},"cardExpDate":{"type":"string","description":"The expiration date of the card in MMYY format."},"accountType":{"type":"string","enum":["Credit","Debit","Checking","Savings"],"description":"Funding-source classification of this token-type payment method.\n- For card tokens: `Credit` or `Debit`.\n- For ACH tokens: `Checking` or `Savings`.\nMay be omitted for older tokens that pre-date this field, for non-token payment methods,\nor when the source did not provide a classification.\n"},"accountNumber":{"type":"string","description":"Masked bank account number, when available for a bank-account token."}},"required":["id","type","currency"]},"BillingContact":{"type":"object","description":"Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}},"InvoiceNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.\n"},"OrderNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.\n"},"ReferenceIdForResponse":{"type":"string","maxLength":100,"description":"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.\n"},"ResultCode":{"type":"integer","enum":[0,55,1003,1005,1010,3000,3002,3005,3006,3009,3010,3011,3012,3013,3014,3020,4001,4100,6800,6801,6802,6900,6901,6902,9998,9999],"description":"Result codes:\n* `0` - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)\n* `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)\n* `1005` - The specified terminal could not be found.\n* `1010` - The transaction request is pending to become transaction.\n* `3000` - An unexpected error occurred. Please try again.\n* `3002` - The transaction could not be completed because the payment terminal could not find the related transaction.\n* `3005` - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.\n* `3006` - The transaction could not be completed because the payment terminal is low on battery.\n* `3009` - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.\n* `3010` - The transaction took too long and was cancelled by the application.\n* `3011` - Invalid transaction request. Please consult the documentation for valid transaction requests.\n* `3012` - Invalid transaction request. paymentMethodId is invalid.\n* `3013` - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.\n* `3014` - Invalid amount. Please try your transaction again with an amount greater than $0.\n* `3020` - An unsupported transaction result was received.\n* `4001` - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.\n* `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`. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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.\n* `6802` - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `6902` - The gateway reported no failure but returned no payment token. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `9998` - The system is not ready to process a transaction.\n* `9999` - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.\n* `1010` - The transaction request is pending customer interaction.\n* `4100` - Cardholder verification is required. Follow `threeDsChallenge.redirectUrl` and reconcile the final transaction outcome before retrying.\n* `55` - The customer cancelled the hosted payment attempt.\n"},"ResultText":{"type":"string","description":"A message describing the result code in more detail."},"TransactionResponse":{"type":"object","description":"A single Sale Transaction may result in multiple Responses.","properties":{"responseCode":{"$ref":"#/components/schemas/ResponseCode"},"authCode":{"type":"string","description":"The authorization code provided by the card issuer, confirming transaction approval."},"amountApproved":{"type":"integer","description":"The amount approved for this transaction response."},"approvedAmountBreakdown":{"$ref":"#/components/schemas/ApprovedAmountBreakdown"},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The payment method used for this transaction response."}]},"cardType":{"$ref":"#/components/schemas/CardType"},"avsResult":{"$ref":"#/components/schemas/AVSResult"},"cvvResult":{"$ref":"#/components/schemas/CVVResult"},"accountType":{"type":"string","description":"The funding-source classification associated with the payment method used in this\ntransaction.\n- For credit/debit cards: `Credit` or `Debit`. May be null when the classification is unavailable, including on older transactions.\n- For ACH/EFT bank accounts: `Checking` or `Savings`.\n\nThe immediate hosted ACH response uses lowercase `checking` or `savings`. Retrieved transaction responses normally use `Checking` or `Savings`.\n","enum":["Credit","Debit","Checking","Savings","checking","savings"]},"hostResponseText":{"type":"string","description":"A meaningful text explaining the response code from the host."},"receipt":{"$ref":"#/components/schemas/Receipt"}}},"ResponseCode":{"type":"integer","enum":[0,1,2,10,11,12,13,14,15,16,17,18,19,20,21,50,51,52,53,54,55,56,57],"description":"Response codes:\n * `0` - UNKNOWN\n * `1` - APPROVED - Transaction was approved\n * `2` - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.\n * `10` - DECLINED - Transaction was declined by the issuer or bank.  For Card-Present, the transaction can also be declined offline by the terminal.\n * `11` - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.\n * `12` - CARD_EXPIRED - The card used for the transaction has expired.\n * `13` - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.\n * `14` - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).\n * `15` - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).\n * `16` - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).\n * `17` - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.\n * `18` - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.\n * `19` - BATCH_EMPTY - Indicates that the batch for processing is empty.\n * `20` - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).\n * `21` - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.\n * `50` - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.\n * `51` - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.\n * `52` - NOT_SUPPORTED - Rejected because the requested operation is not supported.\n * `53` - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.\n * `54` - CANCELLED - Cancelled by the user or merchant.\n * `55` - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.\n * `56` - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.\n * `57` - PENDING - The transaction is awaiting an asynchronous outcome.\n"},"ApprovedAmountBreakdown":{"type":"object","description":"A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.","properties":{"amountGoodsAndServices":{"type":"integer","description":"The approved amount for goods and services."},"tax":{"type":"integer","description":"The approved tax amount."},"cashback":{"type":"integer","description":"The approved cashback amount."},"tip":{"type":"integer","description":"The approved tip amount."}}},"CardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"AVSResult":{"type":"string","enum":["A","E","N","R","S","U","G","W","X","Y","Z"],"description":"The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.\n * `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.\n * `E` - Ineligible transaction.\n * `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.\n * `R` - Retry (system unavailable or timed out).\n * `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.\n * `U` - Address information unavailable.\n * `G` - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.\n * `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.\n * `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.\n * `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.\n * `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.\n\nNOTE: 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.\n"},"CVVResult":{"type":"string","enum":["M","N","P","S","U"],"description":"The CVV verification result. Typically returned on Card Not Present transactions.\n * `M` - CVV Match\n * `N` - CVV No Match\n * `P` - Not Processed\n * `S` - CVV should be on the card but the merchant indicates it is not.\n * `U` - User is unregistered\n\nNOTE: 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.\n"},"Receipt":{"type":"object","description":"Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.","properties":{"lines":{"type":"array","items":{"type":"string"},"description":"The receipt lines."}},"required":["lines"]},"ThreeDsAuthentication":{"type":"object","description":"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.\n","properties":{"status":{"allOf":[{"$ref":"#/components/schemas/ThreeDsStatus"}],"description":"The authentication outcome to use in your integration. The other `threeDs` fields provide supporting authentication data.\n"},"cavv":{"type":"string","description":"Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions."},"eci":{"type":"string","description":"E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:\n * `02` / `05` - Fully authenticated (liability shift to issuer).\n * `01` / `06` - Attempted authentication (partial liability shift).\n * `00` / `07` - Not authenticated (no liability shift).\n"},"xid":{"type":"string","description":"3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility."},"dsTransId":{"type":"string","description":"Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction."},"threeDReasonId":{"type":"string","description":"Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use `status` to handle the outcome and `threeDReason` for the explanation.\n"},"threeDReason":{"type":"string","description":"Human-readable description matching `threeDReasonId`."}}},"ThreeDsStatus":{"type":"string","enum":["Authenticated","Attempted","NotAuthenticated","Failed","Unavailable","NotEnrolled"],"description":"Outcome classification of the 3D Secure check performed on a card transaction. Only present on transactions initiated with `formConfig.enable3DSecure: true`. Use this status to handle the authentication outcome; the other `threeDs` fields provide supporting authentication data.\n\n* `Authenticated` - Issuer fully authenticated the cardholder (ECI `02` / `05`). Full liability shift to the issuer for fraud chargebacks. Covers both frictionless and challenge-completed flows.\n* `Attempted` - Issuer attempted authentication but did not fully authenticate the cardholder (ECI `01` / `06`). Partial liability shift, scheme-dependent.\n* `NotAuthenticated` - 3DS completed but the issuer did not authenticate the cardholder (ECI `00` / `07`). No liability shift.\n* `Failed` - Issuer's ACS rejected the cardholder authentication. Transaction was declined. See `threeDReasonId` for the issuer's reason.\n* `Unavailable` - A technical issue prevented 3DS authentication from completing.\n* `NotEnrolled` - The card is not enrolled in 3DS.\n"},"ThreeDsChallenge":{"type":"object","description":"Present when a token payment requires a cardholder challenge (`resultCode: 4100`).","properties":{"redirectUrl":{"type":"string","format":"uri","description":"Hosted URL where the cardholder completes the challenge."},"followUpToken":{"type":"string","description":"Opaque token identifying the pending challenge."}},"required":["redirectUrl","followUpToken"]}}}}
```

## The VoidResponse object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"VoidResponse":{"type":"object","description":"Represents the response to a void request.","properties":{"id":{"type":"string","description":"Unique ID for this void transaction."},"timestamp":{"type":"string","format":"date-time","description":"Transaction timestamp in UTC"},"type":{"type":"string","enum":["Sale","Auth","Capture","Refund","Void"],"description":"Type of transaction"},"status":{"$ref":"#/components/schemas/TransactionStatus"},"accountHolder":{"allOf":[{"$ref":"#/components/schemas/AccountHolder"},{"type":"object","description":"Account holder information, when available. Contact fields are omitted when they were not collected."}]},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string"}}}]},"invoiceNumber":{"$ref":"#/components/schemas/InvoiceNumber"},"orderNumber":{"$ref":"#/components/schemas/OrderNumber"},"referenceId":{"$ref":"#/components/schemas/ReferenceIdForResponse"},"resultCode":{"$ref":"#/components/schemas/ResultCode"},"resultText":{"$ref":"#/components/schemas/ResultText"},"requestedAmount":{"type":"integer","description":"The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization."},"approvedAmount":{"type":"integer","description":"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."},"transactionResponses":{"type":"array","description":"Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.","items":{"$ref":"#/components/schemas/TransactionResponse"}},"sourceId":{"type":"string","description":"Identifier of the session or other source that initiated the transaction."},"threeDs":{"$ref":"#/components/schemas/ThreeDsAuthentication"},"threeDsChallenge":{"$ref":"#/components/schemas/ThreeDsChallenge"},"balanceAmount":{"type":"integer","description":"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)."}}},"TransactionStatus":{"type":"string","enum":["Unknown","Created","Pending","Submitted","Acknowledged","Processing","AwaitingSettlement","Completed","Failed","Abandoned"],"description":"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.\n"},"AccountHolder":{"type":"object","description":"Account holder information associated with the transaction","properties":{"id":{"type":"string","description":"Account holder ID assigned by the API."},"externalId":{"type":"string","description":"External account holder ID assigned by the integrator."},"contact":{"type":"object","description":"Contact information for the account holder. Only returned for Card Not Present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}}},"required":["id","externalId"]},"PaymentMethodDetails":{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string","description":"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."},"dateDeleted":{"type":"string","format":"date-time","description":"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.\n\nThis field will be present in three scenarios:\n- As part of a successful Remove Token endpoint response\n- In token.removed webhook notifications\n- In List Transactions responses for transactions where the associated token was later removed\n\nWhen this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.\n"},"type":{"type":"string","enum":["Unknown","Physical","Virtual","VirtualAch","VirtualEft","Token"],"description":"The type of payment method:\n- `Physical` - A physical payment terminal for Card Present transactions\n- `Virtual` - A hosted payment form/iframe for Card Not Present transactions\n- `VirtualAch` - A hosted payment form/iframe for ACH (US) bank transfer transactions\n- `Token` - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions\n- `VirtualEft` - A virtual Canadian bank-transfer payment method, when configured.\n- `Unknown` - The payment method type is not known.\n"},"currency":{"type":"string","enum":["USD","CAD"],"description":"The currency of the payment method."},"description":{"type":"string","description":"A human-readable name for the payment method."},"billingContact":{"allOf":[{"$ref":"#/components/schemas/BillingContact"},{"type":"object","description":"Billing contact information. Only returned for tokenized payment methods from Card Not Present transactions."}]},"cardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"maskedCardNumber":{"type":"string","description":"The masked card number. The format may vary (e.g. ************0011, 4****0011, etc.)"},"cardExpDate":{"type":"string","description":"The expiration date of the card in MMYY format."},"accountType":{"type":"string","enum":["Credit","Debit","Checking","Savings"],"description":"Funding-source classification of this token-type payment method.\n- For card tokens: `Credit` or `Debit`.\n- For ACH tokens: `Checking` or `Savings`.\nMay be omitted for older tokens that pre-date this field, for non-token payment methods,\nor when the source did not provide a classification.\n"},"accountNumber":{"type":"string","description":"Masked bank account number, when available for a bank-account token."}},"required":["id","type","currency"]},"BillingContact":{"type":"object","description":"Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}},"InvoiceNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.\n"},"OrderNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.\n"},"ReferenceIdForResponse":{"type":"string","maxLength":100,"description":"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.\n"},"ResultCode":{"type":"integer","enum":[0,55,1003,1005,1010,3000,3002,3005,3006,3009,3010,3011,3012,3013,3014,3020,4001,4100,6800,6801,6802,6900,6901,6902,9998,9999],"description":"Result codes:\n* `0` - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)\n* `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)\n* `1005` - The specified terminal could not be found.\n* `1010` - The transaction request is pending to become transaction.\n* `3000` - An unexpected error occurred. Please try again.\n* `3002` - The transaction could not be completed because the payment terminal could not find the related transaction.\n* `3005` - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.\n* `3006` - The transaction could not be completed because the payment terminal is low on battery.\n* `3009` - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.\n* `3010` - The transaction took too long and was cancelled by the application.\n* `3011` - Invalid transaction request. Please consult the documentation for valid transaction requests.\n* `3012` - Invalid transaction request. paymentMethodId is invalid.\n* `3013` - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.\n* `3014` - Invalid amount. Please try your transaction again with an amount greater than $0.\n* `3020` - An unsupported transaction result was received.\n* `4001` - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.\n* `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`. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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.\n* `6802` - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `6902` - The gateway reported no failure but returned no payment token. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `9998` - The system is not ready to process a transaction.\n* `9999` - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.\n* `1010` - The transaction request is pending customer interaction.\n* `4100` - Cardholder verification is required. Follow `threeDsChallenge.redirectUrl` and reconcile the final transaction outcome before retrying.\n* `55` - The customer cancelled the hosted payment attempt.\n"},"ResultText":{"type":"string","description":"A message describing the result code in more detail."},"TransactionResponse":{"type":"object","description":"A single Sale Transaction may result in multiple Responses.","properties":{"responseCode":{"$ref":"#/components/schemas/ResponseCode"},"authCode":{"type":"string","description":"The authorization code provided by the card issuer, confirming transaction approval."},"amountApproved":{"type":"integer","description":"The amount approved for this transaction response."},"approvedAmountBreakdown":{"$ref":"#/components/schemas/ApprovedAmountBreakdown"},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The payment method used for this transaction response."}]},"cardType":{"$ref":"#/components/schemas/CardType"},"avsResult":{"$ref":"#/components/schemas/AVSResult"},"cvvResult":{"$ref":"#/components/schemas/CVVResult"},"accountType":{"type":"string","description":"The funding-source classification associated with the payment method used in this\ntransaction.\n- For credit/debit cards: `Credit` or `Debit`. May be null when the classification is unavailable, including on older transactions.\n- For ACH/EFT bank accounts: `Checking` or `Savings`.\n\nThe immediate hosted ACH response uses lowercase `checking` or `savings`. Retrieved transaction responses normally use `Checking` or `Savings`.\n","enum":["Credit","Debit","Checking","Savings","checking","savings"]},"hostResponseText":{"type":"string","description":"A meaningful text explaining the response code from the host."},"receipt":{"$ref":"#/components/schemas/Receipt"}}},"ResponseCode":{"type":"integer","enum":[0,1,2,10,11,12,13,14,15,16,17,18,19,20,21,50,51,52,53,54,55,56,57],"description":"Response codes:\n * `0` - UNKNOWN\n * `1` - APPROVED - Transaction was approved\n * `2` - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.\n * `10` - DECLINED - Transaction was declined by the issuer or bank.  For Card-Present, the transaction can also be declined offline by the terminal.\n * `11` - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.\n * `12` - CARD_EXPIRED - The card used for the transaction has expired.\n * `13` - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.\n * `14` - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).\n * `15` - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).\n * `16` - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).\n * `17` - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.\n * `18` - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.\n * `19` - BATCH_EMPTY - Indicates that the batch for processing is empty.\n * `20` - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).\n * `21` - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.\n * `50` - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.\n * `51` - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.\n * `52` - NOT_SUPPORTED - Rejected because the requested operation is not supported.\n * `53` - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.\n * `54` - CANCELLED - Cancelled by the user or merchant.\n * `55` - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.\n * `56` - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.\n * `57` - PENDING - The transaction is awaiting an asynchronous outcome.\n"},"ApprovedAmountBreakdown":{"type":"object","description":"A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.","properties":{"amountGoodsAndServices":{"type":"integer","description":"The approved amount for goods and services."},"tax":{"type":"integer","description":"The approved tax amount."},"cashback":{"type":"integer","description":"The approved cashback amount."},"tip":{"type":"integer","description":"The approved tip amount."}}},"CardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"AVSResult":{"type":"string","enum":["A","E","N","R","S","U","G","W","X","Y","Z"],"description":"The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.\n * `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.\n * `E` - Ineligible transaction.\n * `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.\n * `R` - Retry (system unavailable or timed out).\n * `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.\n * `U` - Address information unavailable.\n * `G` - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.\n * `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.\n * `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.\n * `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.\n * `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.\n\nNOTE: 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.\n"},"CVVResult":{"type":"string","enum":["M","N","P","S","U"],"description":"The CVV verification result. Typically returned on Card Not Present transactions.\n * `M` - CVV Match\n * `N` - CVV No Match\n * `P` - Not Processed\n * `S` - CVV should be on the card but the merchant indicates it is not.\n * `U` - User is unregistered\n\nNOTE: 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.\n"},"Receipt":{"type":"object","description":"Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.","properties":{"lines":{"type":"array","items":{"type":"string"},"description":"The receipt lines."}},"required":["lines"]},"ThreeDsAuthentication":{"type":"object","description":"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.\n","properties":{"status":{"allOf":[{"$ref":"#/components/schemas/ThreeDsStatus"}],"description":"The authentication outcome to use in your integration. The other `threeDs` fields provide supporting authentication data.\n"},"cavv":{"type":"string","description":"Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions."},"eci":{"type":"string","description":"E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:\n * `02` / `05` - Fully authenticated (liability shift to issuer).\n * `01` / `06` - Attempted authentication (partial liability shift).\n * `00` / `07` - Not authenticated (no liability shift).\n"},"xid":{"type":"string","description":"3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility."},"dsTransId":{"type":"string","description":"Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction."},"threeDReasonId":{"type":"string","description":"Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use `status` to handle the outcome and `threeDReason` for the explanation.\n"},"threeDReason":{"type":"string","description":"Human-readable description matching `threeDReasonId`."}}},"ThreeDsStatus":{"type":"string","enum":["Authenticated","Attempted","NotAuthenticated","Failed","Unavailable","NotEnrolled"],"description":"Outcome classification of the 3D Secure check performed on a card transaction. Only present on transactions initiated with `formConfig.enable3DSecure: true`. Use this status to handle the authentication outcome; the other `threeDs` fields provide supporting authentication data.\n\n* `Authenticated` - Issuer fully authenticated the cardholder (ECI `02` / `05`). Full liability shift to the issuer for fraud chargebacks. Covers both frictionless and challenge-completed flows.\n* `Attempted` - Issuer attempted authentication but did not fully authenticate the cardholder (ECI `01` / `06`). Partial liability shift, scheme-dependent.\n* `NotAuthenticated` - 3DS completed but the issuer did not authenticate the cardholder (ECI `00` / `07`). No liability shift.\n* `Failed` - Issuer's ACS rejected the cardholder authentication. Transaction was declined. See `threeDReasonId` for the issuer's reason.\n* `Unavailable` - A technical issue prevented 3DS authentication from completing.\n* `NotEnrolled` - The card is not enrolled in 3DS.\n"},"ThreeDsChallenge":{"type":"object","description":"Present when a token payment requires a cardholder challenge (`resultCode: 4100`).","properties":{"redirectUrl":{"type":"string","format":"uri","description":"Hosted URL where the cardholder completes the challenge."},"followUpToken":{"type":"string","description":"Opaque token identifying the pending challenge."}},"required":["redirectUrl","followUpToken"]}}}}
```

## The CardOnFileAddResponse object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"CardOnFileAddResponse":{"type":"object","description":"Represents the response to a physical card tokenization request.","properties":{"id":{"type":"string","description":"Unique ID for this card tokenization transaction."},"timestamp":{"type":"string","format":"date-time","description":"Transaction timestamp in UTC"},"type":{"type":"string","enum":["Sale","Auth","Capture","Refund","Void"],"description":"Type of transaction"},"status":{"$ref":"#/components/schemas/TransactionStatus"},"accountHolder":{"allOf":[{"$ref":"#/components/schemas/AccountHolder"},{"type":"object","description":"Account holder information, when available. Contact fields are omitted when they were not collected."}]},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The physical terminal used to create the token. Read `transactionResponses[].paymentMethod` for the resulting token.","properties":{"id":{"type":"string"}}}]},"referenceId":{"$ref":"#/components/schemas/ReferenceIdForResponse"},"resultCode":{"$ref":"#/components/schemas/ResultCode"},"resultText":{"$ref":"#/components/schemas/ResultText"},"requestedAmount":{"type":"integer","description":"The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization."},"approvedAmount":{"type":"integer","description":"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."},"transactionResponses":{"type":"array","description":"Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.","items":{"$ref":"#/components/schemas/TransactionResponse"}},"sourceId":{"type":"string","description":"Identifier of the session or other source that initiated the transaction."},"threeDs":{"$ref":"#/components/schemas/ThreeDsAuthentication"},"threeDsChallenge":{"$ref":"#/components/schemas/ThreeDsChallenge"},"balanceAmount":{"type":"integer","description":"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)."},"invoiceNumber":{"$ref":"#/components/schemas/InvoiceNumber"},"orderNumber":{"$ref":"#/components/schemas/OrderNumber"}}},"TransactionStatus":{"type":"string","enum":["Unknown","Created","Pending","Submitted","Acknowledged","Processing","AwaitingSettlement","Completed","Failed","Abandoned"],"description":"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.\n"},"AccountHolder":{"type":"object","description":"Account holder information associated with the transaction","properties":{"id":{"type":"string","description":"Account holder ID assigned by the API."},"externalId":{"type":"string","description":"External account holder ID assigned by the integrator."},"contact":{"type":"object","description":"Contact information for the account holder. Only returned for Card Not Present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}}},"required":["id","externalId"]},"PaymentMethodDetails":{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string","description":"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."},"dateDeleted":{"type":"string","format":"date-time","description":"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.\n\nThis field will be present in three scenarios:\n- As part of a successful Remove Token endpoint response\n- In token.removed webhook notifications\n- In List Transactions responses for transactions where the associated token was later removed\n\nWhen this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.\n"},"type":{"type":"string","enum":["Unknown","Physical","Virtual","VirtualAch","VirtualEft","Token"],"description":"The type of payment method:\n- `Physical` - A physical payment terminal for Card Present transactions\n- `Virtual` - A hosted payment form/iframe for Card Not Present transactions\n- `VirtualAch` - A hosted payment form/iframe for ACH (US) bank transfer transactions\n- `Token` - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions\n- `VirtualEft` - A virtual Canadian bank-transfer payment method, when configured.\n- `Unknown` - The payment method type is not known.\n"},"currency":{"type":"string","enum":["USD","CAD"],"description":"The currency of the payment method."},"description":{"type":"string","description":"A human-readable name for the payment method."},"billingContact":{"allOf":[{"$ref":"#/components/schemas/BillingContact"},{"type":"object","description":"Billing contact information. Only returned for tokenized payment methods from Card Not Present transactions."}]},"cardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"maskedCardNumber":{"type":"string","description":"The masked card number. The format may vary (e.g. ************0011, 4****0011, etc.)"},"cardExpDate":{"type":"string","description":"The expiration date of the card in MMYY format."},"accountType":{"type":"string","enum":["Credit","Debit","Checking","Savings"],"description":"Funding-source classification of this token-type payment method.\n- For card tokens: `Credit` or `Debit`.\n- For ACH tokens: `Checking` or `Savings`.\nMay be omitted for older tokens that pre-date this field, for non-token payment methods,\nor when the source did not provide a classification.\n"},"accountNumber":{"type":"string","description":"Masked bank account number, when available for a bank-account token."}},"required":["id","type","currency"]},"BillingContact":{"type":"object","description":"Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}},"ReferenceIdForResponse":{"type":"string","maxLength":100,"description":"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.\n"},"ResultCode":{"type":"integer","enum":[0,55,1003,1005,1010,3000,3002,3005,3006,3009,3010,3011,3012,3013,3014,3020,4001,4100,6800,6801,6802,6900,6901,6902,9998,9999],"description":"Result codes:\n* `0` - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)\n* `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)\n* `1005` - The specified terminal could not be found.\n* `1010` - The transaction request is pending to become transaction.\n* `3000` - An unexpected error occurred. Please try again.\n* `3002` - The transaction could not be completed because the payment terminal could not find the related transaction.\n* `3005` - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.\n* `3006` - The transaction could not be completed because the payment terminal is low on battery.\n* `3009` - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.\n* `3010` - The transaction took too long and was cancelled by the application.\n* `3011` - Invalid transaction request. Please consult the documentation for valid transaction requests.\n* `3012` - Invalid transaction request. paymentMethodId is invalid.\n* `3013` - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.\n* `3014` - Invalid amount. Please try your transaction again with an amount greater than $0.\n* `3020` - An unsupported transaction result was received.\n* `4001` - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.\n* `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`. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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.\n* `6802` - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `6902` - The gateway reported no failure but returned no payment token. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `9998` - The system is not ready to process a transaction.\n* `9999` - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.\n* `1010` - The transaction request is pending customer interaction.\n* `4100` - Cardholder verification is required. Follow `threeDsChallenge.redirectUrl` and reconcile the final transaction outcome before retrying.\n* `55` - The customer cancelled the hosted payment attempt.\n"},"ResultText":{"type":"string","description":"A message describing the result code in more detail."},"TransactionResponse":{"type":"object","description":"A single Sale Transaction may result in multiple Responses.","properties":{"responseCode":{"$ref":"#/components/schemas/ResponseCode"},"authCode":{"type":"string","description":"The authorization code provided by the card issuer, confirming transaction approval."},"amountApproved":{"type":"integer","description":"The amount approved for this transaction response."},"approvedAmountBreakdown":{"$ref":"#/components/schemas/ApprovedAmountBreakdown"},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The payment method used for this transaction response."}]},"cardType":{"$ref":"#/components/schemas/CardType"},"avsResult":{"$ref":"#/components/schemas/AVSResult"},"cvvResult":{"$ref":"#/components/schemas/CVVResult"},"accountType":{"type":"string","description":"The funding-source classification associated with the payment method used in this\ntransaction.\n- For credit/debit cards: `Credit` or `Debit`. May be null when the classification is unavailable, including on older transactions.\n- For ACH/EFT bank accounts: `Checking` or `Savings`.\n\nThe immediate hosted ACH response uses lowercase `checking` or `savings`. Retrieved transaction responses normally use `Checking` or `Savings`.\n","enum":["Credit","Debit","Checking","Savings","checking","savings"]},"hostResponseText":{"type":"string","description":"A meaningful text explaining the response code from the host."},"receipt":{"$ref":"#/components/schemas/Receipt"}}},"ResponseCode":{"type":"integer","enum":[0,1,2,10,11,12,13,14,15,16,17,18,19,20,21,50,51,52,53,54,55,56,57],"description":"Response codes:\n * `0` - UNKNOWN\n * `1` - APPROVED - Transaction was approved\n * `2` - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.\n * `10` - DECLINED - Transaction was declined by the issuer or bank.  For Card-Present, the transaction can also be declined offline by the terminal.\n * `11` - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.\n * `12` - CARD_EXPIRED - The card used for the transaction has expired.\n * `13` - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.\n * `14` - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).\n * `15` - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).\n * `16` - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).\n * `17` - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.\n * `18` - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.\n * `19` - BATCH_EMPTY - Indicates that the batch for processing is empty.\n * `20` - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).\n * `21` - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.\n * `50` - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.\n * `51` - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.\n * `52` - NOT_SUPPORTED - Rejected because the requested operation is not supported.\n * `53` - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.\n * `54` - CANCELLED - Cancelled by the user or merchant.\n * `55` - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.\n * `56` - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.\n * `57` - PENDING - The transaction is awaiting an asynchronous outcome.\n"},"ApprovedAmountBreakdown":{"type":"object","description":"A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.","properties":{"amountGoodsAndServices":{"type":"integer","description":"The approved amount for goods and services."},"tax":{"type":"integer","description":"The approved tax amount."},"cashback":{"type":"integer","description":"The approved cashback amount."},"tip":{"type":"integer","description":"The approved tip amount."}}},"CardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"AVSResult":{"type":"string","enum":["A","E","N","R","S","U","G","W","X","Y","Z"],"description":"The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.\n * `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.\n * `E` - Ineligible transaction.\n * `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.\n * `R` - Retry (system unavailable or timed out).\n * `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.\n * `U` - Address information unavailable.\n * `G` - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.\n * `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.\n * `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.\n * `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.\n * `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.\n\nNOTE: 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.\n"},"CVVResult":{"type":"string","enum":["M","N","P","S","U"],"description":"The CVV verification result. Typically returned on Card Not Present transactions.\n * `M` - CVV Match\n * `N` - CVV No Match\n * `P` - Not Processed\n * `S` - CVV should be on the card but the merchant indicates it is not.\n * `U` - User is unregistered\n\nNOTE: 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.\n"},"Receipt":{"type":"object","description":"Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.","properties":{"lines":{"type":"array","items":{"type":"string"},"description":"The receipt lines."}},"required":["lines"]},"ThreeDsAuthentication":{"type":"object","description":"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.\n","properties":{"status":{"allOf":[{"$ref":"#/components/schemas/ThreeDsStatus"}],"description":"The authentication outcome to use in your integration. The other `threeDs` fields provide supporting authentication data.\n"},"cavv":{"type":"string","description":"Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions."},"eci":{"type":"string","description":"E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:\n * `02` / `05` - Fully authenticated (liability shift to issuer).\n * `01` / `06` - Attempted authentication (partial liability shift).\n * `00` / `07` - Not authenticated (no liability shift).\n"},"xid":{"type":"string","description":"3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility."},"dsTransId":{"type":"string","description":"Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction."},"threeDReasonId":{"type":"string","description":"Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use `status` to handle the outcome and `threeDReason` for the explanation.\n"},"threeDReason":{"type":"string","description":"Human-readable description matching `threeDReasonId`."}}},"ThreeDsStatus":{"type":"string","enum":["Authenticated","Attempted","NotAuthenticated","Failed","Unavailable","NotEnrolled"],"description":"Outcome classification of the 3D Secure check performed on a card transaction. Only present on transactions initiated with `formConfig.enable3DSecure: true`. Use this status to handle the authentication outcome; the other `threeDs` fields provide supporting authentication data.\n\n* `Authenticated` - Issuer fully authenticated the cardholder (ECI `02` / `05`). Full liability shift to the issuer for fraud chargebacks. Covers both frictionless and challenge-completed flows.\n* `Attempted` - Issuer attempted authentication but did not fully authenticate the cardholder (ECI `01` / `06`). Partial liability shift, scheme-dependent.\n* `NotAuthenticated` - 3DS completed but the issuer did not authenticate the cardholder (ECI `00` / `07`). No liability shift.\n* `Failed` - Issuer's ACS rejected the cardholder authentication. Transaction was declined. See `threeDReasonId` for the issuer's reason.\n* `Unavailable` - A technical issue prevented 3DS authentication from completing.\n* `NotEnrolled` - The card is not enrolled in 3DS.\n"},"ThreeDsChallenge":{"type":"object","description":"Present when a token payment requires a cardholder challenge (`resultCode: 4100`).","properties":{"redirectUrl":{"type":"string","format":"uri","description":"Hosted URL where the cardholder completes the challenge."},"followUpToken":{"type":"string","description":"Opaque token identifying the pending challenge."}},"required":["redirectUrl","followUpToken"]},"InvoiceNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.\n"},"OrderNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.\n"}}}}
```

## The CardOnFileVirtualAddResponse object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"CardOnFileVirtualAddResponse":{"type":"object","description":"Represents the response to a hosted payment form / iframe card tokenization request.","properties":{"id":{"type":"string","description":"Identifier of the hosted session request (`ifr_` prefix). This is not a transaction ID."},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string"}}}]},"referenceId":{"$ref":"#/components/schemas/ReferenceIdForResponse"},"requestedAmount":{"type":"integer","description":"Always 0 when creating a virtual tokenization session."},"sessionId":{"type":"string","description":"Opaque session token. Pass this exact unprefixed value to the SDK."},"iframeUrl":{"type":"string","description":"URL for the iframe to collect payment information, or null if iframe could not be created due to invalid credentials, etc."},"expirationTimestamp":{"type":"string","format":"date-time","description":"Absolute session expiry in UTC, 10 minutes after creation."},"status":{"type":"string","enum":["Pending","Completed","Expired","Error"],"description":"Status of the iframe session. When created, this will always be pending. The status values will be updated as the customer goes through the iframe process."}}},"PaymentMethodDetails":{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string","description":"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."},"dateDeleted":{"type":"string","format":"date-time","description":"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.\n\nThis field will be present in three scenarios:\n- As part of a successful Remove Token endpoint response\n- In token.removed webhook notifications\n- In List Transactions responses for transactions where the associated token was later removed\n\nWhen this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.\n"},"type":{"type":"string","enum":["Unknown","Physical","Virtual","VirtualAch","VirtualEft","Token"],"description":"The type of payment method:\n- `Physical` - A physical payment terminal for Card Present transactions\n- `Virtual` - A hosted payment form/iframe for Card Not Present transactions\n- `VirtualAch` - A hosted payment form/iframe for ACH (US) bank transfer transactions\n- `Token` - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions\n- `VirtualEft` - A virtual Canadian bank-transfer payment method, when configured.\n- `Unknown` - The payment method type is not known.\n"},"currency":{"type":"string","enum":["USD","CAD"],"description":"The currency of the payment method."},"description":{"type":"string","description":"A human-readable name for the payment method."},"billingContact":{"allOf":[{"$ref":"#/components/schemas/BillingContact"},{"type":"object","description":"Billing contact information. Only returned for tokenized payment methods from Card Not Present transactions."}]},"cardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"maskedCardNumber":{"type":"string","description":"The masked card number. The format may vary (e.g. ************0011, 4****0011, etc.)"},"cardExpDate":{"type":"string","description":"The expiration date of the card in MMYY format."},"accountType":{"type":"string","enum":["Credit","Debit","Checking","Savings"],"description":"Funding-source classification of this token-type payment method.\n- For card tokens: `Credit` or `Debit`.\n- For ACH tokens: `Checking` or `Savings`.\nMay be omitted for older tokens that pre-date this field, for non-token payment methods,\nor when the source did not provide a classification.\n"},"accountNumber":{"type":"string","description":"Masked bank account number, when available for a bank-account token."}},"required":["id","type","currency"]},"BillingContact":{"type":"object","description":"Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}},"ReferenceIdForResponse":{"type":"string","maxLength":100,"description":"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.\n"}}}}
```

## The CardOnFileRemoveResponse object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"CardOnFileRemoveResponse":{"type":"object","description":"Represents the response to a tokenized card removal request.","properties":{"id":{"type":"string","description":"Unique ID for this payment-method operation (`ops_` prefix)."},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The tokenized card that was removed.","properties":{"id":{"type":"string"}}}]},"referenceId":{"$ref":"#/components/schemas/ReferenceIdForResponse"},"resultCode":{"$ref":"#/components/schemas/ResultCode"},"resultText":{"$ref":"#/components/schemas/ResultText"}}},"PaymentMethodDetails":{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string","description":"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."},"dateDeleted":{"type":"string","format":"date-time","description":"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.\n\nThis field will be present in three scenarios:\n- As part of a successful Remove Token endpoint response\n- In token.removed webhook notifications\n- In List Transactions responses for transactions where the associated token was later removed\n\nWhen this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.\n"},"type":{"type":"string","enum":["Unknown","Physical","Virtual","VirtualAch","VirtualEft","Token"],"description":"The type of payment method:\n- `Physical` - A physical payment terminal for Card Present transactions\n- `Virtual` - A hosted payment form/iframe for Card Not Present transactions\n- `VirtualAch` - A hosted payment form/iframe for ACH (US) bank transfer transactions\n- `Token` - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions\n- `VirtualEft` - A virtual Canadian bank-transfer payment method, when configured.\n- `Unknown` - The payment method type is not known.\n"},"currency":{"type":"string","enum":["USD","CAD"],"description":"The currency of the payment method."},"description":{"type":"string","description":"A human-readable name for the payment method."},"billingContact":{"allOf":[{"$ref":"#/components/schemas/BillingContact"},{"type":"object","description":"Billing contact information. Only returned for tokenized payment methods from Card Not Present transactions."}]},"cardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"maskedCardNumber":{"type":"string","description":"The masked card number. The format may vary (e.g. ************0011, 4****0011, etc.)"},"cardExpDate":{"type":"string","description":"The expiration date of the card in MMYY format."},"accountType":{"type":"string","enum":["Credit","Debit","Checking","Savings"],"description":"Funding-source classification of this token-type payment method.\n- For card tokens: `Credit` or `Debit`.\n- For ACH tokens: `Checking` or `Savings`.\nMay be omitted for older tokens that pre-date this field, for non-token payment methods,\nor when the source did not provide a classification.\n"},"accountNumber":{"type":"string","description":"Masked bank account number, when available for a bank-account token."}},"required":["id","type","currency"]},"BillingContact":{"type":"object","description":"Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}},"ReferenceIdForResponse":{"type":"string","maxLength":100,"description":"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.\n"},"ResultCode":{"type":"integer","enum":[0,55,1003,1005,1010,3000,3002,3005,3006,3009,3010,3011,3012,3013,3014,3020,4001,4100,6800,6801,6802,6900,6901,6902,9998,9999],"description":"Result codes:\n* `0` - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)\n* `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)\n* `1005` - The specified terminal could not be found.\n* `1010` - The transaction request is pending to become transaction.\n* `3000` - An unexpected error occurred. Please try again.\n* `3002` - The transaction could not be completed because the payment terminal could not find the related transaction.\n* `3005` - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.\n* `3006` - The transaction could not be completed because the payment terminal is low on battery.\n* `3009` - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.\n* `3010` - The transaction took too long and was cancelled by the application.\n* `3011` - Invalid transaction request. Please consult the documentation for valid transaction requests.\n* `3012` - Invalid transaction request. paymentMethodId is invalid.\n* `3013` - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.\n* `3014` - Invalid amount. Please try your transaction again with an amount greater than $0.\n* `3020` - An unsupported transaction result was received.\n* `4001` - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.\n* `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`. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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.\n* `6802` - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `6902` - The gateway reported no failure but returned no payment token. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `9998` - The system is not ready to process a transaction.\n* `9999` - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.\n* `1010` - The transaction request is pending customer interaction.\n* `4100` - Cardholder verification is required. Follow `threeDsChallenge.redirectUrl` and reconcile the final transaction outcome before retrying.\n* `55` - The customer cancelled the hosted payment attempt.\n"},"ResultText":{"type":"string","description":"A message describing the result code in more detail."}}}}
```

## The WebhookEvent object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"WebhookEvent":{"type":"object","description":"Webhook event details.","properties":{"id":{"type":"string","description":"Unique ID for this webhook event."},"type":{"type":"string","description":"The type of event that occurred."},"timestamp":{"type":"string","format":"date-time","description":"The time when the event was triggered (UTC)."},"merchantId":{"type":"string","description":"The merchant that owns the transaction or token."}},"required":["id","type","timestamp","merchantId"]}}}}
```

## The SaleCompletedWebhook object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"SaleCompletedWebhook":{"type":"object","description":"Represents the webhook triggered when a financial transaction is processed and completed.","properties":{"event":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"type":{"type":"string"}}}]},"originalResponse":{"$ref":"#/components/schemas/TransactionResponseObject"}},"required":["event","originalResponse"]},"WebhookEvent":{"type":"object","description":"Webhook event details.","properties":{"id":{"type":"string","description":"Unique ID for this webhook event."},"type":{"type":"string","description":"The type of event that occurred."},"timestamp":{"type":"string","format":"date-time","description":"The time when the event was triggered (UTC)."},"merchantId":{"type":"string","description":"The merchant that owns the transaction or token."}},"required":["id","type","timestamp","merchantId"]},"TransactionResponseObject":{"type":"object","description":"Represents the response to a sale or authorization transaction.","properties":{"id":{"type":"string","description":"Unique ID for this transaction."},"timestamp":{"type":"string","format":"date-time","description":"Transaction timestamp in UTC"},"type":{"type":"string","enum":["Sale","Auth","Capture","Refund","Void"],"description":"Type of transaction"},"status":{"$ref":"#/components/schemas/TransactionStatus"},"accountHolder":{"allOf":[{"$ref":"#/components/schemas/AccountHolder"},{"type":"object","description":"Account holder information, when available. Contact fields are omitted when they were not collected."}]},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The payment method used for this transaction. This could be:\n\n- The payment method used for this Card Present transaction.\n- The payment method used for this Card Not Present transaction.\n- The payment method used for this token transaction.\n\nIf a new card was tokenized during the transaction, the tokenized card ID and details will be returned in the `transactionResponses`'s `paymentMethod` object.\n","properties":{"id":{"type":"string"}}}]},"invoiceNumber":{"$ref":"#/components/schemas/InvoiceNumber"},"orderNumber":{"$ref":"#/components/schemas/OrderNumber"},"referenceId":{"$ref":"#/components/schemas/ReferenceIdForResponse"},"resultCode":{"$ref":"#/components/schemas/ResultCode"},"resultText":{"$ref":"#/components/schemas/ResultText"},"requestedAmount":{"type":"integer","description":"The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization."},"approvedAmount":{"type":"integer","description":"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."},"balanceAmount":{"type":"integer","description":"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)."},"refundableAmount":{"type":"integer","description":"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."},"transactionResponses":{"type":"array","description":"Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.","items":{"allOf":[{"$ref":"#/components/schemas/TransactionResponse"},{"type":"object","properties":{"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"If a new card was tokenized during the transaction, the tokenized card ID and details will be returned (`pmt_tkn_*`). This value should be stored in your system if you wish to use it for subsequent Card On File transactions.\n","properties":{"id":{"type":"string"}}}]}}}]}},"sourceId":{"type":"string","description":"Identifier of the session or other source that initiated the transaction."},"threeDs":{"$ref":"#/components/schemas/ThreeDsAuthentication"},"threeDsChallenge":{"$ref":"#/components/schemas/ThreeDsChallenge"}}},"TransactionStatus":{"type":"string","enum":["Unknown","Created","Pending","Submitted","Acknowledged","Processing","AwaitingSettlement","Completed","Failed","Abandoned"],"description":"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.\n"},"AccountHolder":{"type":"object","description":"Account holder information associated with the transaction","properties":{"id":{"type":"string","description":"Account holder ID assigned by the API."},"externalId":{"type":"string","description":"External account holder ID assigned by the integrator."},"contact":{"type":"object","description":"Contact information for the account holder. Only returned for Card Not Present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}}},"required":["id","externalId"]},"PaymentMethodDetails":{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string","description":"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."},"dateDeleted":{"type":"string","format":"date-time","description":"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.\n\nThis field will be present in three scenarios:\n- As part of a successful Remove Token endpoint response\n- In token.removed webhook notifications\n- In List Transactions responses for transactions where the associated token was later removed\n\nWhen this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.\n"},"type":{"type":"string","enum":["Unknown","Physical","Virtual","VirtualAch","VirtualEft","Token"],"description":"The type of payment method:\n- `Physical` - A physical payment terminal for Card Present transactions\n- `Virtual` - A hosted payment form/iframe for Card Not Present transactions\n- `VirtualAch` - A hosted payment form/iframe for ACH (US) bank transfer transactions\n- `Token` - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions\n- `VirtualEft` - A virtual Canadian bank-transfer payment method, when configured.\n- `Unknown` - The payment method type is not known.\n"},"currency":{"type":"string","enum":["USD","CAD"],"description":"The currency of the payment method."},"description":{"type":"string","description":"A human-readable name for the payment method."},"billingContact":{"allOf":[{"$ref":"#/components/schemas/BillingContact"},{"type":"object","description":"Billing contact information. Only returned for tokenized payment methods from Card Not Present transactions."}]},"cardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"maskedCardNumber":{"type":"string","description":"The masked card number. The format may vary (e.g. ************0011, 4****0011, etc.)"},"cardExpDate":{"type":"string","description":"The expiration date of the card in MMYY format."},"accountType":{"type":"string","enum":["Credit","Debit","Checking","Savings"],"description":"Funding-source classification of this token-type payment method.\n- For card tokens: `Credit` or `Debit`.\n- For ACH tokens: `Checking` or `Savings`.\nMay be omitted for older tokens that pre-date this field, for non-token payment methods,\nor when the source did not provide a classification.\n"},"accountNumber":{"type":"string","description":"Masked bank account number, when available for a bank-account token."}},"required":["id","type","currency"]},"BillingContact":{"type":"object","description":"Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}},"InvoiceNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.\n"},"OrderNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.\n"},"ReferenceIdForResponse":{"type":"string","maxLength":100,"description":"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.\n"},"ResultCode":{"type":"integer","enum":[0,55,1003,1005,1010,3000,3002,3005,3006,3009,3010,3011,3012,3013,3014,3020,4001,4100,6800,6801,6802,6900,6901,6902,9998,9999],"description":"Result codes:\n* `0` - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)\n* `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)\n* `1005` - The specified terminal could not be found.\n* `1010` - The transaction request is pending to become transaction.\n* `3000` - An unexpected error occurred. Please try again.\n* `3002` - The transaction could not be completed because the payment terminal could not find the related transaction.\n* `3005` - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.\n* `3006` - The transaction could not be completed because the payment terminal is low on battery.\n* `3009` - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.\n* `3010` - The transaction took too long and was cancelled by the application.\n* `3011` - Invalid transaction request. Please consult the documentation for valid transaction requests.\n* `3012` - Invalid transaction request. paymentMethodId is invalid.\n* `3013` - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.\n* `3014` - Invalid amount. Please try your transaction again with an amount greater than $0.\n* `3020` - An unsupported transaction result was received.\n* `4001` - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.\n* `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`. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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.\n* `6802` - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `6902` - The gateway reported no failure but returned no payment token. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `9998` - The system is not ready to process a transaction.\n* `9999` - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.\n* `1010` - The transaction request is pending customer interaction.\n* `4100` - Cardholder verification is required. Follow `threeDsChallenge.redirectUrl` and reconcile the final transaction outcome before retrying.\n* `55` - The customer cancelled the hosted payment attempt.\n"},"ResultText":{"type":"string","description":"A message describing the result code in more detail."},"TransactionResponse":{"type":"object","description":"A single Sale Transaction may result in multiple Responses.","properties":{"responseCode":{"$ref":"#/components/schemas/ResponseCode"},"authCode":{"type":"string","description":"The authorization code provided by the card issuer, confirming transaction approval."},"amountApproved":{"type":"integer","description":"The amount approved for this transaction response."},"approvedAmountBreakdown":{"$ref":"#/components/schemas/ApprovedAmountBreakdown"},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The payment method used for this transaction response."}]},"cardType":{"$ref":"#/components/schemas/CardType"},"avsResult":{"$ref":"#/components/schemas/AVSResult"},"cvvResult":{"$ref":"#/components/schemas/CVVResult"},"accountType":{"type":"string","description":"The funding-source classification associated with the payment method used in this\ntransaction.\n- For credit/debit cards: `Credit` or `Debit`. May be null when the classification is unavailable, including on older transactions.\n- For ACH/EFT bank accounts: `Checking` or `Savings`.\n\nThe immediate hosted ACH response uses lowercase `checking` or `savings`. Retrieved transaction responses normally use `Checking` or `Savings`.\n","enum":["Credit","Debit","Checking","Savings","checking","savings"]},"hostResponseText":{"type":"string","description":"A meaningful text explaining the response code from the host."},"receipt":{"$ref":"#/components/schemas/Receipt"}}},"ResponseCode":{"type":"integer","enum":[0,1,2,10,11,12,13,14,15,16,17,18,19,20,21,50,51,52,53,54,55,56,57],"description":"Response codes:\n * `0` - UNKNOWN\n * `1` - APPROVED - Transaction was approved\n * `2` - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.\n * `10` - DECLINED - Transaction was declined by the issuer or bank.  For Card-Present, the transaction can also be declined offline by the terminal.\n * `11` - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.\n * `12` - CARD_EXPIRED - The card used for the transaction has expired.\n * `13` - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.\n * `14` - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).\n * `15` - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).\n * `16` - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).\n * `17` - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.\n * `18` - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.\n * `19` - BATCH_EMPTY - Indicates that the batch for processing is empty.\n * `20` - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).\n * `21` - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.\n * `50` - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.\n * `51` - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.\n * `52` - NOT_SUPPORTED - Rejected because the requested operation is not supported.\n * `53` - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.\n * `54` - CANCELLED - Cancelled by the user or merchant.\n * `55` - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.\n * `56` - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.\n * `57` - PENDING - The transaction is awaiting an asynchronous outcome.\n"},"ApprovedAmountBreakdown":{"type":"object","description":"A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.","properties":{"amountGoodsAndServices":{"type":"integer","description":"The approved amount for goods and services."},"tax":{"type":"integer","description":"The approved tax amount."},"cashback":{"type":"integer","description":"The approved cashback amount."},"tip":{"type":"integer","description":"The approved tip amount."}}},"CardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"AVSResult":{"type":"string","enum":["A","E","N","R","S","U","G","W","X","Y","Z"],"description":"The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.\n * `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.\n * `E` - Ineligible transaction.\n * `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.\n * `R` - Retry (system unavailable or timed out).\n * `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.\n * `U` - Address information unavailable.\n * `G` - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.\n * `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.\n * `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.\n * `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.\n * `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.\n\nNOTE: 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.\n"},"CVVResult":{"type":"string","enum":["M","N","P","S","U"],"description":"The CVV verification result. Typically returned on Card Not Present transactions.\n * `M` - CVV Match\n * `N` - CVV No Match\n * `P` - Not Processed\n * `S` - CVV should be on the card but the merchant indicates it is not.\n * `U` - User is unregistered\n\nNOTE: 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.\n"},"Receipt":{"type":"object","description":"Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.","properties":{"lines":{"type":"array","items":{"type":"string"},"description":"The receipt lines."}},"required":["lines"]},"ThreeDsAuthentication":{"type":"object","description":"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.\n","properties":{"status":{"allOf":[{"$ref":"#/components/schemas/ThreeDsStatus"}],"description":"The authentication outcome to use in your integration. The other `threeDs` fields provide supporting authentication data.\n"},"cavv":{"type":"string","description":"Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions."},"eci":{"type":"string","description":"E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:\n * `02` / `05` - Fully authenticated (liability shift to issuer).\n * `01` / `06` - Attempted authentication (partial liability shift).\n * `00` / `07` - Not authenticated (no liability shift).\n"},"xid":{"type":"string","description":"3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility."},"dsTransId":{"type":"string","description":"Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction."},"threeDReasonId":{"type":"string","description":"Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use `status` to handle the outcome and `threeDReason` for the explanation.\n"},"threeDReason":{"type":"string","description":"Human-readable description matching `threeDReasonId`."}}},"ThreeDsStatus":{"type":"string","enum":["Authenticated","Attempted","NotAuthenticated","Failed","Unavailable","NotEnrolled"],"description":"Outcome classification of the 3D Secure check performed on a card transaction. Only present on transactions initiated with `formConfig.enable3DSecure: true`. Use this status to handle the authentication outcome; the other `threeDs` fields provide supporting authentication data.\n\n* `Authenticated` - Issuer fully authenticated the cardholder (ECI `02` / `05`). Full liability shift to the issuer for fraud chargebacks. Covers both frictionless and challenge-completed flows.\n* `Attempted` - Issuer attempted authentication but did not fully authenticate the cardholder (ECI `01` / `06`). Partial liability shift, scheme-dependent.\n* `NotAuthenticated` - 3DS completed but the issuer did not authenticate the cardholder (ECI `00` / `07`). No liability shift.\n* `Failed` - Issuer's ACS rejected the cardholder authentication. Transaction was declined. See `threeDReasonId` for the issuer's reason.\n* `Unavailable` - A technical issue prevented 3DS authentication from completing.\n* `NotEnrolled` - The card is not enrolled in 3DS.\n"},"ThreeDsChallenge":{"type":"object","description":"Present when a token payment requires a cardholder challenge (`resultCode: 4100`).","properties":{"redirectUrl":{"type":"string","format":"uri","description":"Hosted URL where the cardholder completes the challenge."},"followUpToken":{"type":"string","description":"Opaque token identifying the pending challenge."}},"required":["redirectUrl","followUpToken"]}}}}
```

## The AuthCompletedWebhook object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"AuthCompletedWebhook":{"type":"object","description":"Represents the webhook triggered when a transaction authorization is completed.","properties":{"event":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"type":{"type":"string"}}}]},"originalResponse":{"$ref":"#/components/schemas/TransactionResponseObject"}},"required":["event","originalResponse"]},"WebhookEvent":{"type":"object","description":"Webhook event details.","properties":{"id":{"type":"string","description":"Unique ID for this webhook event."},"type":{"type":"string","description":"The type of event that occurred."},"timestamp":{"type":"string","format":"date-time","description":"The time when the event was triggered (UTC)."},"merchantId":{"type":"string","description":"The merchant that owns the transaction or token."}},"required":["id","type","timestamp","merchantId"]},"TransactionResponseObject":{"type":"object","description":"Represents the response to a sale or authorization transaction.","properties":{"id":{"type":"string","description":"Unique ID for this transaction."},"timestamp":{"type":"string","format":"date-time","description":"Transaction timestamp in UTC"},"type":{"type":"string","enum":["Sale","Auth","Capture","Refund","Void"],"description":"Type of transaction"},"status":{"$ref":"#/components/schemas/TransactionStatus"},"accountHolder":{"allOf":[{"$ref":"#/components/schemas/AccountHolder"},{"type":"object","description":"Account holder information, when available. Contact fields are omitted when they were not collected."}]},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The payment method used for this transaction. This could be:\n\n- The payment method used for this Card Present transaction.\n- The payment method used for this Card Not Present transaction.\n- The payment method used for this token transaction.\n\nIf a new card was tokenized during the transaction, the tokenized card ID and details will be returned in the `transactionResponses`'s `paymentMethod` object.\n","properties":{"id":{"type":"string"}}}]},"invoiceNumber":{"$ref":"#/components/schemas/InvoiceNumber"},"orderNumber":{"$ref":"#/components/schemas/OrderNumber"},"referenceId":{"$ref":"#/components/schemas/ReferenceIdForResponse"},"resultCode":{"$ref":"#/components/schemas/ResultCode"},"resultText":{"$ref":"#/components/schemas/ResultText"},"requestedAmount":{"type":"integer","description":"The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization."},"approvedAmount":{"type":"integer","description":"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."},"balanceAmount":{"type":"integer","description":"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)."},"refundableAmount":{"type":"integer","description":"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."},"transactionResponses":{"type":"array","description":"Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.","items":{"allOf":[{"$ref":"#/components/schemas/TransactionResponse"},{"type":"object","properties":{"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"If a new card was tokenized during the transaction, the tokenized card ID and details will be returned (`pmt_tkn_*`). This value should be stored in your system if you wish to use it for subsequent Card On File transactions.\n","properties":{"id":{"type":"string"}}}]}}}]}},"sourceId":{"type":"string","description":"Identifier of the session or other source that initiated the transaction."},"threeDs":{"$ref":"#/components/schemas/ThreeDsAuthentication"},"threeDsChallenge":{"$ref":"#/components/schemas/ThreeDsChallenge"}}},"TransactionStatus":{"type":"string","enum":["Unknown","Created","Pending","Submitted","Acknowledged","Processing","AwaitingSettlement","Completed","Failed","Abandoned"],"description":"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.\n"},"AccountHolder":{"type":"object","description":"Account holder information associated with the transaction","properties":{"id":{"type":"string","description":"Account holder ID assigned by the API."},"externalId":{"type":"string","description":"External account holder ID assigned by the integrator."},"contact":{"type":"object","description":"Contact information for the account holder. Only returned for Card Not Present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}}},"required":["id","externalId"]},"PaymentMethodDetails":{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string","description":"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."},"dateDeleted":{"type":"string","format":"date-time","description":"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.\n\nThis field will be present in three scenarios:\n- As part of a successful Remove Token endpoint response\n- In token.removed webhook notifications\n- In List Transactions responses for transactions where the associated token was later removed\n\nWhen this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.\n"},"type":{"type":"string","enum":["Unknown","Physical","Virtual","VirtualAch","VirtualEft","Token"],"description":"The type of payment method:\n- `Physical` - A physical payment terminal for Card Present transactions\n- `Virtual` - A hosted payment form/iframe for Card Not Present transactions\n- `VirtualAch` - A hosted payment form/iframe for ACH (US) bank transfer transactions\n- `Token` - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions\n- `VirtualEft` - A virtual Canadian bank-transfer payment method, when configured.\n- `Unknown` - The payment method type is not known.\n"},"currency":{"type":"string","enum":["USD","CAD"],"description":"The currency of the payment method."},"description":{"type":"string","description":"A human-readable name for the payment method."},"billingContact":{"allOf":[{"$ref":"#/components/schemas/BillingContact"},{"type":"object","description":"Billing contact information. Only returned for tokenized payment methods from Card Not Present transactions."}]},"cardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"maskedCardNumber":{"type":"string","description":"The masked card number. The format may vary (e.g. ************0011, 4****0011, etc.)"},"cardExpDate":{"type":"string","description":"The expiration date of the card in MMYY format."},"accountType":{"type":"string","enum":["Credit","Debit","Checking","Savings"],"description":"Funding-source classification of this token-type payment method.\n- For card tokens: `Credit` or `Debit`.\n- For ACH tokens: `Checking` or `Savings`.\nMay be omitted for older tokens that pre-date this field, for non-token payment methods,\nor when the source did not provide a classification.\n"},"accountNumber":{"type":"string","description":"Masked bank account number, when available for a bank-account token."}},"required":["id","type","currency"]},"BillingContact":{"type":"object","description":"Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}},"InvoiceNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.\n"},"OrderNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.\n"},"ReferenceIdForResponse":{"type":"string","maxLength":100,"description":"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.\n"},"ResultCode":{"type":"integer","enum":[0,55,1003,1005,1010,3000,3002,3005,3006,3009,3010,3011,3012,3013,3014,3020,4001,4100,6800,6801,6802,6900,6901,6902,9998,9999],"description":"Result codes:\n* `0` - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)\n* `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)\n* `1005` - The specified terminal could not be found.\n* `1010` - The transaction request is pending to become transaction.\n* `3000` - An unexpected error occurred. Please try again.\n* `3002` - The transaction could not be completed because the payment terminal could not find the related transaction.\n* `3005` - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.\n* `3006` - The transaction could not be completed because the payment terminal is low on battery.\n* `3009` - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.\n* `3010` - The transaction took too long and was cancelled by the application.\n* `3011` - Invalid transaction request. Please consult the documentation for valid transaction requests.\n* `3012` - Invalid transaction request. paymentMethodId is invalid.\n* `3013` - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.\n* `3014` - Invalid amount. Please try your transaction again with an amount greater than $0.\n* `3020` - An unsupported transaction result was received.\n* `4001` - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.\n* `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`. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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.\n* `6802` - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `6902` - The gateway reported no failure but returned no payment token. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `9998` - The system is not ready to process a transaction.\n* `9999` - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.\n* `1010` - The transaction request is pending customer interaction.\n* `4100` - Cardholder verification is required. Follow `threeDsChallenge.redirectUrl` and reconcile the final transaction outcome before retrying.\n* `55` - The customer cancelled the hosted payment attempt.\n"},"ResultText":{"type":"string","description":"A message describing the result code in more detail."},"TransactionResponse":{"type":"object","description":"A single Sale Transaction may result in multiple Responses.","properties":{"responseCode":{"$ref":"#/components/schemas/ResponseCode"},"authCode":{"type":"string","description":"The authorization code provided by the card issuer, confirming transaction approval."},"amountApproved":{"type":"integer","description":"The amount approved for this transaction response."},"approvedAmountBreakdown":{"$ref":"#/components/schemas/ApprovedAmountBreakdown"},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The payment method used for this transaction response."}]},"cardType":{"$ref":"#/components/schemas/CardType"},"avsResult":{"$ref":"#/components/schemas/AVSResult"},"cvvResult":{"$ref":"#/components/schemas/CVVResult"},"accountType":{"type":"string","description":"The funding-source classification associated with the payment method used in this\ntransaction.\n- For credit/debit cards: `Credit` or `Debit`. May be null when the classification is unavailable, including on older transactions.\n- For ACH/EFT bank accounts: `Checking` or `Savings`.\n\nThe immediate hosted ACH response uses lowercase `checking` or `savings`. Retrieved transaction responses normally use `Checking` or `Savings`.\n","enum":["Credit","Debit","Checking","Savings","checking","savings"]},"hostResponseText":{"type":"string","description":"A meaningful text explaining the response code from the host."},"receipt":{"$ref":"#/components/schemas/Receipt"}}},"ResponseCode":{"type":"integer","enum":[0,1,2,10,11,12,13,14,15,16,17,18,19,20,21,50,51,52,53,54,55,56,57],"description":"Response codes:\n * `0` - UNKNOWN\n * `1` - APPROVED - Transaction was approved\n * `2` - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.\n * `10` - DECLINED - Transaction was declined by the issuer or bank.  For Card-Present, the transaction can also be declined offline by the terminal.\n * `11` - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.\n * `12` - CARD_EXPIRED - The card used for the transaction has expired.\n * `13` - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.\n * `14` - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).\n * `15` - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).\n * `16` - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).\n * `17` - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.\n * `18` - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.\n * `19` - BATCH_EMPTY - Indicates that the batch for processing is empty.\n * `20` - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).\n * `21` - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.\n * `50` - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.\n * `51` - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.\n * `52` - NOT_SUPPORTED - Rejected because the requested operation is not supported.\n * `53` - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.\n * `54` - CANCELLED - Cancelled by the user or merchant.\n * `55` - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.\n * `56` - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.\n * `57` - PENDING - The transaction is awaiting an asynchronous outcome.\n"},"ApprovedAmountBreakdown":{"type":"object","description":"A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.","properties":{"amountGoodsAndServices":{"type":"integer","description":"The approved amount for goods and services."},"tax":{"type":"integer","description":"The approved tax amount."},"cashback":{"type":"integer","description":"The approved cashback amount."},"tip":{"type":"integer","description":"The approved tip amount."}}},"CardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"AVSResult":{"type":"string","enum":["A","E","N","R","S","U","G","W","X","Y","Z"],"description":"The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.\n * `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.\n * `E` - Ineligible transaction.\n * `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.\n * `R` - Retry (system unavailable or timed out).\n * `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.\n * `U` - Address information unavailable.\n * `G` - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.\n * `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.\n * `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.\n * `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.\n * `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.\n\nNOTE: 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.\n"},"CVVResult":{"type":"string","enum":["M","N","P","S","U"],"description":"The CVV verification result. Typically returned on Card Not Present transactions.\n * `M` - CVV Match\n * `N` - CVV No Match\n * `P` - Not Processed\n * `S` - CVV should be on the card but the merchant indicates it is not.\n * `U` - User is unregistered\n\nNOTE: 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.\n"},"Receipt":{"type":"object","description":"Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.","properties":{"lines":{"type":"array","items":{"type":"string"},"description":"The receipt lines."}},"required":["lines"]},"ThreeDsAuthentication":{"type":"object","description":"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.\n","properties":{"status":{"allOf":[{"$ref":"#/components/schemas/ThreeDsStatus"}],"description":"The authentication outcome to use in your integration. The other `threeDs` fields provide supporting authentication data.\n"},"cavv":{"type":"string","description":"Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions."},"eci":{"type":"string","description":"E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:\n * `02` / `05` - Fully authenticated (liability shift to issuer).\n * `01` / `06` - Attempted authentication (partial liability shift).\n * `00` / `07` - Not authenticated (no liability shift).\n"},"xid":{"type":"string","description":"3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility."},"dsTransId":{"type":"string","description":"Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction."},"threeDReasonId":{"type":"string","description":"Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use `status` to handle the outcome and `threeDReason` for the explanation.\n"},"threeDReason":{"type":"string","description":"Human-readable description matching `threeDReasonId`."}}},"ThreeDsStatus":{"type":"string","enum":["Authenticated","Attempted","NotAuthenticated","Failed","Unavailable","NotEnrolled"],"description":"Outcome classification of the 3D Secure check performed on a card transaction. Only present on transactions initiated with `formConfig.enable3DSecure: true`. Use this status to handle the authentication outcome; the other `threeDs` fields provide supporting authentication data.\n\n* `Authenticated` - Issuer fully authenticated the cardholder (ECI `02` / `05`). Full liability shift to the issuer for fraud chargebacks. Covers both frictionless and challenge-completed flows.\n* `Attempted` - Issuer attempted authentication but did not fully authenticate the cardholder (ECI `01` / `06`). Partial liability shift, scheme-dependent.\n* `NotAuthenticated` - 3DS completed but the issuer did not authenticate the cardholder (ECI `00` / `07`). No liability shift.\n* `Failed` - Issuer's ACS rejected the cardholder authentication. Transaction was declined. See `threeDReasonId` for the issuer's reason.\n* `Unavailable` - A technical issue prevented 3DS authentication from completing.\n* `NotEnrolled` - The card is not enrolled in 3DS.\n"},"ThreeDsChallenge":{"type":"object","description":"Present when a token payment requires a cardholder challenge (`resultCode: 4100`).","properties":{"redirectUrl":{"type":"string","format":"uri","description":"Hosted URL where the cardholder completes the challenge."},"followUpToken":{"type":"string","description":"Opaque token identifying the pending challenge."}},"required":["redirectUrl","followUpToken"]}}}}
```

## The CaptureCompletedWebhook object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"CaptureCompletedWebhook":{"type":"object","description":"Represents the webhook triggered when a transaction capture for a previously authorized transaction is completed.","properties":{"event":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"type":{"type":"string"}}}]},"originalResponse":{"$ref":"#/components/schemas/CaptureResponse"}},"required":["event","originalResponse"]},"WebhookEvent":{"type":"object","description":"Webhook event details.","properties":{"id":{"type":"string","description":"Unique ID for this webhook event."},"type":{"type":"string","description":"The type of event that occurred."},"timestamp":{"type":"string","format":"date-time","description":"The time when the event was triggered (UTC)."},"merchantId":{"type":"string","description":"The merchant that owns the transaction or token."}},"required":["id","type","timestamp","merchantId"]},"CaptureResponse":{"type":"object","description":"Represents the response to a capture request.","properties":{"id":{"type":"string","description":"Unique ID for this capture transaction."},"timestamp":{"type":"string","format":"date-time","description":"Transaction timestamp in UTC"},"type":{"type":"string","enum":["Sale","Auth","Capture","Refund","Void"],"description":"Type of transaction"},"status":{"$ref":"#/components/schemas/TransactionStatus"},"accountHolder":{"allOf":[{"$ref":"#/components/schemas/AccountHolder"},{"type":"object","description":"Account holder information, when available. Contact fields are omitted when they were not collected."}]},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string"}}}]},"invoiceNumber":{"$ref":"#/components/schemas/InvoiceNumber"},"orderNumber":{"$ref":"#/components/schemas/OrderNumber"},"referenceId":{"$ref":"#/components/schemas/ReferenceIdForResponse"},"resultCode":{"$ref":"#/components/schemas/ResultCode"},"resultText":{"$ref":"#/components/schemas/ResultText"},"requestedAmount":{"type":"integer","description":"The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization."},"approvedAmount":{"type":"integer","description":"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."},"transactionResponses":{"type":"array","description":"Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.","items":{"$ref":"#/components/schemas/TransactionResponse"}},"sourceId":{"type":"string","description":"Identifier of the session or other source that initiated the transaction."},"threeDs":{"$ref":"#/components/schemas/ThreeDsAuthentication"},"threeDsChallenge":{"$ref":"#/components/schemas/ThreeDsChallenge"},"balanceAmount":{"type":"integer","description":"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)."},"refundableAmount":{"type":"integer","description":"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."}}},"TransactionStatus":{"type":"string","enum":["Unknown","Created","Pending","Submitted","Acknowledged","Processing","AwaitingSettlement","Completed","Failed","Abandoned"],"description":"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.\n"},"AccountHolder":{"type":"object","description":"Account holder information associated with the transaction","properties":{"id":{"type":"string","description":"Account holder ID assigned by the API."},"externalId":{"type":"string","description":"External account holder ID assigned by the integrator."},"contact":{"type":"object","description":"Contact information for the account holder. Only returned for Card Not Present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}}},"required":["id","externalId"]},"PaymentMethodDetails":{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string","description":"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."},"dateDeleted":{"type":"string","format":"date-time","description":"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.\n\nThis field will be present in three scenarios:\n- As part of a successful Remove Token endpoint response\n- In token.removed webhook notifications\n- In List Transactions responses for transactions where the associated token was later removed\n\nWhen this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.\n"},"type":{"type":"string","enum":["Unknown","Physical","Virtual","VirtualAch","VirtualEft","Token"],"description":"The type of payment method:\n- `Physical` - A physical payment terminal for Card Present transactions\n- `Virtual` - A hosted payment form/iframe for Card Not Present transactions\n- `VirtualAch` - A hosted payment form/iframe for ACH (US) bank transfer transactions\n- `Token` - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions\n- `VirtualEft` - A virtual Canadian bank-transfer payment method, when configured.\n- `Unknown` - The payment method type is not known.\n"},"currency":{"type":"string","enum":["USD","CAD"],"description":"The currency of the payment method."},"description":{"type":"string","description":"A human-readable name for the payment method."},"billingContact":{"allOf":[{"$ref":"#/components/schemas/BillingContact"},{"type":"object","description":"Billing contact information. Only returned for tokenized payment methods from Card Not Present transactions."}]},"cardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"maskedCardNumber":{"type":"string","description":"The masked card number. The format may vary (e.g. ************0011, 4****0011, etc.)"},"cardExpDate":{"type":"string","description":"The expiration date of the card in MMYY format."},"accountType":{"type":"string","enum":["Credit","Debit","Checking","Savings"],"description":"Funding-source classification of this token-type payment method.\n- For card tokens: `Credit` or `Debit`.\n- For ACH tokens: `Checking` or `Savings`.\nMay be omitted for older tokens that pre-date this field, for non-token payment methods,\nor when the source did not provide a classification.\n"},"accountNumber":{"type":"string","description":"Masked bank account number, when available for a bank-account token."}},"required":["id","type","currency"]},"BillingContact":{"type":"object","description":"Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}},"InvoiceNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.\n"},"OrderNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.\n"},"ReferenceIdForResponse":{"type":"string","maxLength":100,"description":"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.\n"},"ResultCode":{"type":"integer","enum":[0,55,1003,1005,1010,3000,3002,3005,3006,3009,3010,3011,3012,3013,3014,3020,4001,4100,6800,6801,6802,6900,6901,6902,9998,9999],"description":"Result codes:\n* `0` - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)\n* `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)\n* `1005` - The specified terminal could not be found.\n* `1010` - The transaction request is pending to become transaction.\n* `3000` - An unexpected error occurred. Please try again.\n* `3002` - The transaction could not be completed because the payment terminal could not find the related transaction.\n* `3005` - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.\n* `3006` - The transaction could not be completed because the payment terminal is low on battery.\n* `3009` - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.\n* `3010` - The transaction took too long and was cancelled by the application.\n* `3011` - Invalid transaction request. Please consult the documentation for valid transaction requests.\n* `3012` - Invalid transaction request. paymentMethodId is invalid.\n* `3013` - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.\n* `3014` - Invalid amount. Please try your transaction again with an amount greater than $0.\n* `3020` - An unsupported transaction result was received.\n* `4001` - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.\n* `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`. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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.\n* `6802` - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `6902` - The gateway reported no failure but returned no payment token. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `9998` - The system is not ready to process a transaction.\n* `9999` - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.\n* `1010` - The transaction request is pending customer interaction.\n* `4100` - Cardholder verification is required. Follow `threeDsChallenge.redirectUrl` and reconcile the final transaction outcome before retrying.\n* `55` - The customer cancelled the hosted payment attempt.\n"},"ResultText":{"type":"string","description":"A message describing the result code in more detail."},"TransactionResponse":{"type":"object","description":"A single Sale Transaction may result in multiple Responses.","properties":{"responseCode":{"$ref":"#/components/schemas/ResponseCode"},"authCode":{"type":"string","description":"The authorization code provided by the card issuer, confirming transaction approval."},"amountApproved":{"type":"integer","description":"The amount approved for this transaction response."},"approvedAmountBreakdown":{"$ref":"#/components/schemas/ApprovedAmountBreakdown"},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The payment method used for this transaction response."}]},"cardType":{"$ref":"#/components/schemas/CardType"},"avsResult":{"$ref":"#/components/schemas/AVSResult"},"cvvResult":{"$ref":"#/components/schemas/CVVResult"},"accountType":{"type":"string","description":"The funding-source classification associated with the payment method used in this\ntransaction.\n- For credit/debit cards: `Credit` or `Debit`. May be null when the classification is unavailable, including on older transactions.\n- For ACH/EFT bank accounts: `Checking` or `Savings`.\n\nThe immediate hosted ACH response uses lowercase `checking` or `savings`. Retrieved transaction responses normally use `Checking` or `Savings`.\n","enum":["Credit","Debit","Checking","Savings","checking","savings"]},"hostResponseText":{"type":"string","description":"A meaningful text explaining the response code from the host."},"receipt":{"$ref":"#/components/schemas/Receipt"}}},"ResponseCode":{"type":"integer","enum":[0,1,2,10,11,12,13,14,15,16,17,18,19,20,21,50,51,52,53,54,55,56,57],"description":"Response codes:\n * `0` - UNKNOWN\n * `1` - APPROVED - Transaction was approved\n * `2` - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.\n * `10` - DECLINED - Transaction was declined by the issuer or bank.  For Card-Present, the transaction can also be declined offline by the terminal.\n * `11` - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.\n * `12` - CARD_EXPIRED - The card used for the transaction has expired.\n * `13` - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.\n * `14` - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).\n * `15` - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).\n * `16` - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).\n * `17` - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.\n * `18` - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.\n * `19` - BATCH_EMPTY - Indicates that the batch for processing is empty.\n * `20` - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).\n * `21` - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.\n * `50` - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.\n * `51` - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.\n * `52` - NOT_SUPPORTED - Rejected because the requested operation is not supported.\n * `53` - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.\n * `54` - CANCELLED - Cancelled by the user or merchant.\n * `55` - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.\n * `56` - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.\n * `57` - PENDING - The transaction is awaiting an asynchronous outcome.\n"},"ApprovedAmountBreakdown":{"type":"object","description":"A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.","properties":{"amountGoodsAndServices":{"type":"integer","description":"The approved amount for goods and services."},"tax":{"type":"integer","description":"The approved tax amount."},"cashback":{"type":"integer","description":"The approved cashback amount."},"tip":{"type":"integer","description":"The approved tip amount."}}},"CardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"AVSResult":{"type":"string","enum":["A","E","N","R","S","U","G","W","X","Y","Z"],"description":"The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.\n * `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.\n * `E` - Ineligible transaction.\n * `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.\n * `R` - Retry (system unavailable or timed out).\n * `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.\n * `U` - Address information unavailable.\n * `G` - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.\n * `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.\n * `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.\n * `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.\n * `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.\n\nNOTE: 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.\n"},"CVVResult":{"type":"string","enum":["M","N","P","S","U"],"description":"The CVV verification result. Typically returned on Card Not Present transactions.\n * `M` - CVV Match\n * `N` - CVV No Match\n * `P` - Not Processed\n * `S` - CVV should be on the card but the merchant indicates it is not.\n * `U` - User is unregistered\n\nNOTE: 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.\n"},"Receipt":{"type":"object","description":"Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.","properties":{"lines":{"type":"array","items":{"type":"string"},"description":"The receipt lines."}},"required":["lines"]},"ThreeDsAuthentication":{"type":"object","description":"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.\n","properties":{"status":{"allOf":[{"$ref":"#/components/schemas/ThreeDsStatus"}],"description":"The authentication outcome to use in your integration. The other `threeDs` fields provide supporting authentication data.\n"},"cavv":{"type":"string","description":"Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions."},"eci":{"type":"string","description":"E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:\n * `02` / `05` - Fully authenticated (liability shift to issuer).\n * `01` / `06` - Attempted authentication (partial liability shift).\n * `00` / `07` - Not authenticated (no liability shift).\n"},"xid":{"type":"string","description":"3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility."},"dsTransId":{"type":"string","description":"Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction."},"threeDReasonId":{"type":"string","description":"Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use `status` to handle the outcome and `threeDReason` for the explanation.\n"},"threeDReason":{"type":"string","description":"Human-readable description matching `threeDReasonId`."}}},"ThreeDsStatus":{"type":"string","enum":["Authenticated","Attempted","NotAuthenticated","Failed","Unavailable","NotEnrolled"],"description":"Outcome classification of the 3D Secure check performed on a card transaction. Only present on transactions initiated with `formConfig.enable3DSecure: true`. Use this status to handle the authentication outcome; the other `threeDs` fields provide supporting authentication data.\n\n* `Authenticated` - Issuer fully authenticated the cardholder (ECI `02` / `05`). Full liability shift to the issuer for fraud chargebacks. Covers both frictionless and challenge-completed flows.\n* `Attempted` - Issuer attempted authentication but did not fully authenticate the cardholder (ECI `01` / `06`). Partial liability shift, scheme-dependent.\n* `NotAuthenticated` - 3DS completed but the issuer did not authenticate the cardholder (ECI `00` / `07`). No liability shift.\n* `Failed` - Issuer's ACS rejected the cardholder authentication. Transaction was declined. See `threeDReasonId` for the issuer's reason.\n* `Unavailable` - A technical issue prevented 3DS authentication from completing.\n* `NotEnrolled` - The card is not enrolled in 3DS.\n"},"ThreeDsChallenge":{"type":"object","description":"Present when a token payment requires a cardholder challenge (`resultCode: 4100`).","properties":{"redirectUrl":{"type":"string","format":"uri","description":"Hosted URL where the cardholder completes the challenge."},"followUpToken":{"type":"string","description":"Opaque token identifying the pending challenge."}},"required":["redirectUrl","followUpToken"]}}}}
```

## The RefundCompletedWebhook object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"RefundCompletedWebhook":{"type":"object","description":"Represents the webhook triggered when a transaction void or refund for a previously completed transaction is completed.","properties":{"event":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"type":{"type":"string"}}}]},"originalResponse":{"$ref":"#/components/schemas/RefundResponse"}},"required":["event","originalResponse"]},"WebhookEvent":{"type":"object","description":"Webhook event details.","properties":{"id":{"type":"string","description":"Unique ID for this webhook event."},"type":{"type":"string","description":"The type of event that occurred."},"timestamp":{"type":"string","format":"date-time","description":"The time when the event was triggered (UTC)."},"merchantId":{"type":"string","description":"The merchant that owns the transaction or token."}},"required":["id","type","timestamp","merchantId"]},"RefundResponse":{"type":"object","description":"Represents the response to a refund request.","properties":{"id":{"type":"string","description":"Unique ID for this refund transaction."},"timestamp":{"type":"string","format":"date-time","description":"Transaction timestamp in UTC"},"type":{"type":"string","enum":["Sale","Auth","Capture","Refund","Void"],"description":"Type of transaction"},"status":{"$ref":"#/components/schemas/TransactionStatus"},"accountHolder":{"allOf":[{"$ref":"#/components/schemas/AccountHolder"},{"type":"object","description":"Account holder information, when available. Contact fields are omitted when they were not collected."}]},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string"}}}]},"invoiceNumber":{"$ref":"#/components/schemas/InvoiceNumber"},"orderNumber":{"$ref":"#/components/schemas/OrderNumber"},"referenceId":{"$ref":"#/components/schemas/ReferenceIdForResponse"},"resultCode":{"$ref":"#/components/schemas/ResultCode"},"resultText":{"$ref":"#/components/schemas/ResultText"},"requestedAmount":{"type":"integer","description":"The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization."},"approvedAmount":{"type":"integer","description":"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."},"refundableAmount":{"type":"integer","description":"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."},"transactionResponses":{"type":"array","description":"Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.","items":{"$ref":"#/components/schemas/TransactionResponse"}},"sourceId":{"type":"string","description":"Identifier of the session or other source that initiated the transaction."},"threeDs":{"$ref":"#/components/schemas/ThreeDsAuthentication"},"threeDsChallenge":{"$ref":"#/components/schemas/ThreeDsChallenge"},"balanceAmount":{"type":"integer","description":"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)."}}},"TransactionStatus":{"type":"string","enum":["Unknown","Created","Pending","Submitted","Acknowledged","Processing","AwaitingSettlement","Completed","Failed","Abandoned"],"description":"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.\n"},"AccountHolder":{"type":"object","description":"Account holder information associated with the transaction","properties":{"id":{"type":"string","description":"Account holder ID assigned by the API."},"externalId":{"type":"string","description":"External account holder ID assigned by the integrator."},"contact":{"type":"object","description":"Contact information for the account holder. Only returned for Card Not Present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}}},"required":["id","externalId"]},"PaymentMethodDetails":{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string","description":"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."},"dateDeleted":{"type":"string","format":"date-time","description":"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.\n\nThis field will be present in three scenarios:\n- As part of a successful Remove Token endpoint response\n- In token.removed webhook notifications\n- In List Transactions responses for transactions where the associated token was later removed\n\nWhen this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.\n"},"type":{"type":"string","enum":["Unknown","Physical","Virtual","VirtualAch","VirtualEft","Token"],"description":"The type of payment method:\n- `Physical` - A physical payment terminal for Card Present transactions\n- `Virtual` - A hosted payment form/iframe for Card Not Present transactions\n- `VirtualAch` - A hosted payment form/iframe for ACH (US) bank transfer transactions\n- `Token` - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions\n- `VirtualEft` - A virtual Canadian bank-transfer payment method, when configured.\n- `Unknown` - The payment method type is not known.\n"},"currency":{"type":"string","enum":["USD","CAD"],"description":"The currency of the payment method."},"description":{"type":"string","description":"A human-readable name for the payment method."},"billingContact":{"allOf":[{"$ref":"#/components/schemas/BillingContact"},{"type":"object","description":"Billing contact information. Only returned for tokenized payment methods from Card Not Present transactions."}]},"cardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"maskedCardNumber":{"type":"string","description":"The masked card number. The format may vary (e.g. ************0011, 4****0011, etc.)"},"cardExpDate":{"type":"string","description":"The expiration date of the card in MMYY format."},"accountType":{"type":"string","enum":["Credit","Debit","Checking","Savings"],"description":"Funding-source classification of this token-type payment method.\n- For card tokens: `Credit` or `Debit`.\n- For ACH tokens: `Checking` or `Savings`.\nMay be omitted for older tokens that pre-date this field, for non-token payment methods,\nor when the source did not provide a classification.\n"},"accountNumber":{"type":"string","description":"Masked bank account number, when available for a bank-account token."}},"required":["id","type","currency"]},"BillingContact":{"type":"object","description":"Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}},"InvoiceNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.\n"},"OrderNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.\n"},"ReferenceIdForResponse":{"type":"string","maxLength":100,"description":"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.\n"},"ResultCode":{"type":"integer","enum":[0,55,1003,1005,1010,3000,3002,3005,3006,3009,3010,3011,3012,3013,3014,3020,4001,4100,6800,6801,6802,6900,6901,6902,9998,9999],"description":"Result codes:\n* `0` - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)\n* `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)\n* `1005` - The specified terminal could not be found.\n* `1010` - The transaction request is pending to become transaction.\n* `3000` - An unexpected error occurred. Please try again.\n* `3002` - The transaction could not be completed because the payment terminal could not find the related transaction.\n* `3005` - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.\n* `3006` - The transaction could not be completed because the payment terminal is low on battery.\n* `3009` - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.\n* `3010` - The transaction took too long and was cancelled by the application.\n* `3011` - Invalid transaction request. Please consult the documentation for valid transaction requests.\n* `3012` - Invalid transaction request. paymentMethodId is invalid.\n* `3013` - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.\n* `3014` - Invalid amount. Please try your transaction again with an amount greater than $0.\n* `3020` - An unsupported transaction result was received.\n* `4001` - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.\n* `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`. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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.\n* `6802` - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `6902` - The gateway reported no failure but returned no payment token. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `9998` - The system is not ready to process a transaction.\n* `9999` - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.\n* `1010` - The transaction request is pending customer interaction.\n* `4100` - Cardholder verification is required. Follow `threeDsChallenge.redirectUrl` and reconcile the final transaction outcome before retrying.\n* `55` - The customer cancelled the hosted payment attempt.\n"},"ResultText":{"type":"string","description":"A message describing the result code in more detail."},"TransactionResponse":{"type":"object","description":"A single Sale Transaction may result in multiple Responses.","properties":{"responseCode":{"$ref":"#/components/schemas/ResponseCode"},"authCode":{"type":"string","description":"The authorization code provided by the card issuer, confirming transaction approval."},"amountApproved":{"type":"integer","description":"The amount approved for this transaction response."},"approvedAmountBreakdown":{"$ref":"#/components/schemas/ApprovedAmountBreakdown"},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The payment method used for this transaction response."}]},"cardType":{"$ref":"#/components/schemas/CardType"},"avsResult":{"$ref":"#/components/schemas/AVSResult"},"cvvResult":{"$ref":"#/components/schemas/CVVResult"},"accountType":{"type":"string","description":"The funding-source classification associated with the payment method used in this\ntransaction.\n- For credit/debit cards: `Credit` or `Debit`. May be null when the classification is unavailable, including on older transactions.\n- For ACH/EFT bank accounts: `Checking` or `Savings`.\n\nThe immediate hosted ACH response uses lowercase `checking` or `savings`. Retrieved transaction responses normally use `Checking` or `Savings`.\n","enum":["Credit","Debit","Checking","Savings","checking","savings"]},"hostResponseText":{"type":"string","description":"A meaningful text explaining the response code from the host."},"receipt":{"$ref":"#/components/schemas/Receipt"}}},"ResponseCode":{"type":"integer","enum":[0,1,2,10,11,12,13,14,15,16,17,18,19,20,21,50,51,52,53,54,55,56,57],"description":"Response codes:\n * `0` - UNKNOWN\n * `1` - APPROVED - Transaction was approved\n * `2` - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.\n * `10` - DECLINED - Transaction was declined by the issuer or bank.  For Card-Present, the transaction can also be declined offline by the terminal.\n * `11` - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.\n * `12` - CARD_EXPIRED - The card used for the transaction has expired.\n * `13` - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.\n * `14` - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).\n * `15` - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).\n * `16` - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).\n * `17` - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.\n * `18` - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.\n * `19` - BATCH_EMPTY - Indicates that the batch for processing is empty.\n * `20` - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).\n * `21` - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.\n * `50` - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.\n * `51` - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.\n * `52` - NOT_SUPPORTED - Rejected because the requested operation is not supported.\n * `53` - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.\n * `54` - CANCELLED - Cancelled by the user or merchant.\n * `55` - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.\n * `56` - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.\n * `57` - PENDING - The transaction is awaiting an asynchronous outcome.\n"},"ApprovedAmountBreakdown":{"type":"object","description":"A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.","properties":{"amountGoodsAndServices":{"type":"integer","description":"The approved amount for goods and services."},"tax":{"type":"integer","description":"The approved tax amount."},"cashback":{"type":"integer","description":"The approved cashback amount."},"tip":{"type":"integer","description":"The approved tip amount."}}},"CardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"AVSResult":{"type":"string","enum":["A","E","N","R","S","U","G","W","X","Y","Z"],"description":"The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.\n * `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.\n * `E` - Ineligible transaction.\n * `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.\n * `R` - Retry (system unavailable or timed out).\n * `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.\n * `U` - Address information unavailable.\n * `G` - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.\n * `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.\n * `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.\n * `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.\n * `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.\n\nNOTE: 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.\n"},"CVVResult":{"type":"string","enum":["M","N","P","S","U"],"description":"The CVV verification result. Typically returned on Card Not Present transactions.\n * `M` - CVV Match\n * `N` - CVV No Match\n * `P` - Not Processed\n * `S` - CVV should be on the card but the merchant indicates it is not.\n * `U` - User is unregistered\n\nNOTE: 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.\n"},"Receipt":{"type":"object","description":"Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.","properties":{"lines":{"type":"array","items":{"type":"string"},"description":"The receipt lines."}},"required":["lines"]},"ThreeDsAuthentication":{"type":"object","description":"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.\n","properties":{"status":{"allOf":[{"$ref":"#/components/schemas/ThreeDsStatus"}],"description":"The authentication outcome to use in your integration. The other `threeDs` fields provide supporting authentication data.\n"},"cavv":{"type":"string","description":"Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions."},"eci":{"type":"string","description":"E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:\n * `02` / `05` - Fully authenticated (liability shift to issuer).\n * `01` / `06` - Attempted authentication (partial liability shift).\n * `00` / `07` - Not authenticated (no liability shift).\n"},"xid":{"type":"string","description":"3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility."},"dsTransId":{"type":"string","description":"Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction."},"threeDReasonId":{"type":"string","description":"Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use `status` to handle the outcome and `threeDReason` for the explanation.\n"},"threeDReason":{"type":"string","description":"Human-readable description matching `threeDReasonId`."}}},"ThreeDsStatus":{"type":"string","enum":["Authenticated","Attempted","NotAuthenticated","Failed","Unavailable","NotEnrolled"],"description":"Outcome classification of the 3D Secure check performed on a card transaction. Only present on transactions initiated with `formConfig.enable3DSecure: true`. Use this status to handle the authentication outcome; the other `threeDs` fields provide supporting authentication data.\n\n* `Authenticated` - Issuer fully authenticated the cardholder (ECI `02` / `05`). Full liability shift to the issuer for fraud chargebacks. Covers both frictionless and challenge-completed flows.\n* `Attempted` - Issuer attempted authentication but did not fully authenticate the cardholder (ECI `01` / `06`). Partial liability shift, scheme-dependent.\n* `NotAuthenticated` - 3DS completed but the issuer did not authenticate the cardholder (ECI `00` / `07`). No liability shift.\n* `Failed` - Issuer's ACS rejected the cardholder authentication. Transaction was declined. See `threeDReasonId` for the issuer's reason.\n* `Unavailable` - A technical issue prevented 3DS authentication from completing.\n* `NotEnrolled` - The card is not enrolled in 3DS.\n"},"ThreeDsChallenge":{"type":"object","description":"Present when a token payment requires a cardholder challenge (`resultCode: 4100`).","properties":{"redirectUrl":{"type":"string","format":"uri","description":"Hosted URL where the cardholder completes the challenge."},"followUpToken":{"type":"string","description":"Opaque token identifying the pending challenge."}},"required":["redirectUrl","followUpToken"]}}}}
```

## The VoidCompletedWebhook object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"VoidCompletedWebhook":{"type":"object","description":"Represents the webhook triggered when a transaction void for a previously completed transaction is completed.","properties":{"event":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"type":{"type":"string"}}}]},"originalResponse":{"$ref":"#/components/schemas/VoidResponse"}},"required":["event","originalResponse"]},"WebhookEvent":{"type":"object","description":"Webhook event details.","properties":{"id":{"type":"string","description":"Unique ID for this webhook event."},"type":{"type":"string","description":"The type of event that occurred."},"timestamp":{"type":"string","format":"date-time","description":"The time when the event was triggered (UTC)."},"merchantId":{"type":"string","description":"The merchant that owns the transaction or token."}},"required":["id","type","timestamp","merchantId"]},"VoidResponse":{"type":"object","description":"Represents the response to a void request.","properties":{"id":{"type":"string","description":"Unique ID for this void transaction."},"timestamp":{"type":"string","format":"date-time","description":"Transaction timestamp in UTC"},"type":{"type":"string","enum":["Sale","Auth","Capture","Refund","Void"],"description":"Type of transaction"},"status":{"$ref":"#/components/schemas/TransactionStatus"},"accountHolder":{"allOf":[{"$ref":"#/components/schemas/AccountHolder"},{"type":"object","description":"Account holder information, when available. Contact fields are omitted when they were not collected."}]},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string"}}}]},"invoiceNumber":{"$ref":"#/components/schemas/InvoiceNumber"},"orderNumber":{"$ref":"#/components/schemas/OrderNumber"},"referenceId":{"$ref":"#/components/schemas/ReferenceIdForResponse"},"resultCode":{"$ref":"#/components/schemas/ResultCode"},"resultText":{"$ref":"#/components/schemas/ResultText"},"requestedAmount":{"type":"integer","description":"The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization."},"approvedAmount":{"type":"integer","description":"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."},"transactionResponses":{"type":"array","description":"Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.","items":{"$ref":"#/components/schemas/TransactionResponse"}},"sourceId":{"type":"string","description":"Identifier of the session or other source that initiated the transaction."},"threeDs":{"$ref":"#/components/schemas/ThreeDsAuthentication"},"threeDsChallenge":{"$ref":"#/components/schemas/ThreeDsChallenge"},"balanceAmount":{"type":"integer","description":"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)."}}},"TransactionStatus":{"type":"string","enum":["Unknown","Created","Pending","Submitted","Acknowledged","Processing","AwaitingSettlement","Completed","Failed","Abandoned"],"description":"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.\n"},"AccountHolder":{"type":"object","description":"Account holder information associated with the transaction","properties":{"id":{"type":"string","description":"Account holder ID assigned by the API."},"externalId":{"type":"string","description":"External account holder ID assigned by the integrator."},"contact":{"type":"object","description":"Contact information for the account holder. Only returned for Card Not Present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}}},"required":["id","externalId"]},"PaymentMethodDetails":{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string","description":"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."},"dateDeleted":{"type":"string","format":"date-time","description":"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.\n\nThis field will be present in three scenarios:\n- As part of a successful Remove Token endpoint response\n- In token.removed webhook notifications\n- In List Transactions responses for transactions where the associated token was later removed\n\nWhen this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.\n"},"type":{"type":"string","enum":["Unknown","Physical","Virtual","VirtualAch","VirtualEft","Token"],"description":"The type of payment method:\n- `Physical` - A physical payment terminal for Card Present transactions\n- `Virtual` - A hosted payment form/iframe for Card Not Present transactions\n- `VirtualAch` - A hosted payment form/iframe for ACH (US) bank transfer transactions\n- `Token` - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions\n- `VirtualEft` - A virtual Canadian bank-transfer payment method, when configured.\n- `Unknown` - The payment method type is not known.\n"},"currency":{"type":"string","enum":["USD","CAD"],"description":"The currency of the payment method."},"description":{"type":"string","description":"A human-readable name for the payment method."},"billingContact":{"allOf":[{"$ref":"#/components/schemas/BillingContact"},{"type":"object","description":"Billing contact information. Only returned for tokenized payment methods from Card Not Present transactions."}]},"cardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"maskedCardNumber":{"type":"string","description":"The masked card number. The format may vary (e.g. ************0011, 4****0011, etc.)"},"cardExpDate":{"type":"string","description":"The expiration date of the card in MMYY format."},"accountType":{"type":"string","enum":["Credit","Debit","Checking","Savings"],"description":"Funding-source classification of this token-type payment method.\n- For card tokens: `Credit` or `Debit`.\n- For ACH tokens: `Checking` or `Savings`.\nMay be omitted for older tokens that pre-date this field, for non-token payment methods,\nor when the source did not provide a classification.\n"},"accountNumber":{"type":"string","description":"Masked bank account number, when available for a bank-account token."}},"required":["id","type","currency"]},"BillingContact":{"type":"object","description":"Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}},"InvoiceNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.\n"},"OrderNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.\n"},"ReferenceIdForResponse":{"type":"string","maxLength":100,"description":"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.\n"},"ResultCode":{"type":"integer","enum":[0,55,1003,1005,1010,3000,3002,3005,3006,3009,3010,3011,3012,3013,3014,3020,4001,4100,6800,6801,6802,6900,6901,6902,9998,9999],"description":"Result codes:\n* `0` - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)\n* `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)\n* `1005` - The specified terminal could not be found.\n* `1010` - The transaction request is pending to become transaction.\n* `3000` - An unexpected error occurred. Please try again.\n* `3002` - The transaction could not be completed because the payment terminal could not find the related transaction.\n* `3005` - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.\n* `3006` - The transaction could not be completed because the payment terminal is low on battery.\n* `3009` - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.\n* `3010` - The transaction took too long and was cancelled by the application.\n* `3011` - Invalid transaction request. Please consult the documentation for valid transaction requests.\n* `3012` - Invalid transaction request. paymentMethodId is invalid.\n* `3013` - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.\n* `3014` - Invalid amount. Please try your transaction again with an amount greater than $0.\n* `3020` - An unsupported transaction result was received.\n* `4001` - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.\n* `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`. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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.\n* `6802` - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `6902` - The gateway reported no failure but returned no payment token. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `9998` - The system is not ready to process a transaction.\n* `9999` - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.\n* `1010` - The transaction request is pending customer interaction.\n* `4100` - Cardholder verification is required. Follow `threeDsChallenge.redirectUrl` and reconcile the final transaction outcome before retrying.\n* `55` - The customer cancelled the hosted payment attempt.\n"},"ResultText":{"type":"string","description":"A message describing the result code in more detail."},"TransactionResponse":{"type":"object","description":"A single Sale Transaction may result in multiple Responses.","properties":{"responseCode":{"$ref":"#/components/schemas/ResponseCode"},"authCode":{"type":"string","description":"The authorization code provided by the card issuer, confirming transaction approval."},"amountApproved":{"type":"integer","description":"The amount approved for this transaction response."},"approvedAmountBreakdown":{"$ref":"#/components/schemas/ApprovedAmountBreakdown"},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The payment method used for this transaction response."}]},"cardType":{"$ref":"#/components/schemas/CardType"},"avsResult":{"$ref":"#/components/schemas/AVSResult"},"cvvResult":{"$ref":"#/components/schemas/CVVResult"},"accountType":{"type":"string","description":"The funding-source classification associated with the payment method used in this\ntransaction.\n- For credit/debit cards: `Credit` or `Debit`. May be null when the classification is unavailable, including on older transactions.\n- For ACH/EFT bank accounts: `Checking` or `Savings`.\n\nThe immediate hosted ACH response uses lowercase `checking` or `savings`. Retrieved transaction responses normally use `Checking` or `Savings`.\n","enum":["Credit","Debit","Checking","Savings","checking","savings"]},"hostResponseText":{"type":"string","description":"A meaningful text explaining the response code from the host."},"receipt":{"$ref":"#/components/schemas/Receipt"}}},"ResponseCode":{"type":"integer","enum":[0,1,2,10,11,12,13,14,15,16,17,18,19,20,21,50,51,52,53,54,55,56,57],"description":"Response codes:\n * `0` - UNKNOWN\n * `1` - APPROVED - Transaction was approved\n * `2` - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.\n * `10` - DECLINED - Transaction was declined by the issuer or bank.  For Card-Present, the transaction can also be declined offline by the terminal.\n * `11` - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.\n * `12` - CARD_EXPIRED - The card used for the transaction has expired.\n * `13` - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.\n * `14` - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).\n * `15` - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).\n * `16` - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).\n * `17` - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.\n * `18` - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.\n * `19` - BATCH_EMPTY - Indicates that the batch for processing is empty.\n * `20` - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).\n * `21` - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.\n * `50` - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.\n * `51` - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.\n * `52` - NOT_SUPPORTED - Rejected because the requested operation is not supported.\n * `53` - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.\n * `54` - CANCELLED - Cancelled by the user or merchant.\n * `55` - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.\n * `56` - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.\n * `57` - PENDING - The transaction is awaiting an asynchronous outcome.\n"},"ApprovedAmountBreakdown":{"type":"object","description":"A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.","properties":{"amountGoodsAndServices":{"type":"integer","description":"The approved amount for goods and services."},"tax":{"type":"integer","description":"The approved tax amount."},"cashback":{"type":"integer","description":"The approved cashback amount."},"tip":{"type":"integer","description":"The approved tip amount."}}},"CardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"AVSResult":{"type":"string","enum":["A","E","N","R","S","U","G","W","X","Y","Z"],"description":"The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.\n * `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.\n * `E` - Ineligible transaction.\n * `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.\n * `R` - Retry (system unavailable or timed out).\n * `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.\n * `U` - Address information unavailable.\n * `G` - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.\n * `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.\n * `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.\n * `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.\n * `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.\n\nNOTE: 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.\n"},"CVVResult":{"type":"string","enum":["M","N","P","S","U"],"description":"The CVV verification result. Typically returned on Card Not Present transactions.\n * `M` - CVV Match\n * `N` - CVV No Match\n * `P` - Not Processed\n * `S` - CVV should be on the card but the merchant indicates it is not.\n * `U` - User is unregistered\n\nNOTE: 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.\n"},"Receipt":{"type":"object","description":"Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.","properties":{"lines":{"type":"array","items":{"type":"string"},"description":"The receipt lines."}},"required":["lines"]},"ThreeDsAuthentication":{"type":"object","description":"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.\n","properties":{"status":{"allOf":[{"$ref":"#/components/schemas/ThreeDsStatus"}],"description":"The authentication outcome to use in your integration. The other `threeDs` fields provide supporting authentication data.\n"},"cavv":{"type":"string","description":"Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions."},"eci":{"type":"string","description":"E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:\n * `02` / `05` - Fully authenticated (liability shift to issuer).\n * `01` / `06` - Attempted authentication (partial liability shift).\n * `00` / `07` - Not authenticated (no liability shift).\n"},"xid":{"type":"string","description":"3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility."},"dsTransId":{"type":"string","description":"Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction."},"threeDReasonId":{"type":"string","description":"Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use `status` to handle the outcome and `threeDReason` for the explanation.\n"},"threeDReason":{"type":"string","description":"Human-readable description matching `threeDReasonId`."}}},"ThreeDsStatus":{"type":"string","enum":["Authenticated","Attempted","NotAuthenticated","Failed","Unavailable","NotEnrolled"],"description":"Outcome classification of the 3D Secure check performed on a card transaction. Only present on transactions initiated with `formConfig.enable3DSecure: true`. Use this status to handle the authentication outcome; the other `threeDs` fields provide supporting authentication data.\n\n* `Authenticated` - Issuer fully authenticated the cardholder (ECI `02` / `05`). Full liability shift to the issuer for fraud chargebacks. Covers both frictionless and challenge-completed flows.\n* `Attempted` - Issuer attempted authentication but did not fully authenticate the cardholder (ECI `01` / `06`). Partial liability shift, scheme-dependent.\n* `NotAuthenticated` - 3DS completed but the issuer did not authenticate the cardholder (ECI `00` / `07`). No liability shift.\n* `Failed` - Issuer's ACS rejected the cardholder authentication. Transaction was declined. See `threeDReasonId` for the issuer's reason.\n* `Unavailable` - A technical issue prevented 3DS authentication from completing.\n* `NotEnrolled` - The card is not enrolled in 3DS.\n"},"ThreeDsChallenge":{"type":"object","description":"Present when a token payment requires a cardholder challenge (`resultCode: 4100`).","properties":{"redirectUrl":{"type":"string","format":"uri","description":"Hosted URL where the cardholder completes the challenge."},"followUpToken":{"type":"string","description":"Opaque token identifying the pending challenge."}},"required":["redirectUrl","followUpToken"]}}}}
```

## The TokenCreatedWebhook object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"TokenCreatedWebhook":{"type":"object","description":"Represents the webhook triggered when a card is tokenized and stored as a payment method.","properties":{"event":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"type":{"type":"string"}}}]},"originalResponse":{"allOf":[{"$ref":"#/components/schemas/CardOnFileAddResponse"},{"type":"object"}]}},"required":["event","originalResponse"]},"WebhookEvent":{"type":"object","description":"Webhook event details.","properties":{"id":{"type":"string","description":"Unique ID for this webhook event."},"type":{"type":"string","description":"The type of event that occurred."},"timestamp":{"type":"string","format":"date-time","description":"The time when the event was triggered (UTC)."},"merchantId":{"type":"string","description":"The merchant that owns the transaction or token."}},"required":["id","type","timestamp","merchantId"]},"CardOnFileAddResponse":{"type":"object","description":"Represents the response to a physical card tokenization request.","properties":{"id":{"type":"string","description":"Unique ID for this card tokenization transaction."},"timestamp":{"type":"string","format":"date-time","description":"Transaction timestamp in UTC"},"type":{"type":"string","enum":["Sale","Auth","Capture","Refund","Void"],"description":"Type of transaction"},"status":{"$ref":"#/components/schemas/TransactionStatus"},"accountHolder":{"allOf":[{"$ref":"#/components/schemas/AccountHolder"},{"type":"object","description":"Account holder information, when available. Contact fields are omitted when they were not collected."}]},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The physical terminal used to create the token. Read `transactionResponses[].paymentMethod` for the resulting token.","properties":{"id":{"type":"string"}}}]},"referenceId":{"$ref":"#/components/schemas/ReferenceIdForResponse"},"resultCode":{"$ref":"#/components/schemas/ResultCode"},"resultText":{"$ref":"#/components/schemas/ResultText"},"requestedAmount":{"type":"integer","description":"The requested amount in minor units. Virtual tokenization uses 0; physical tokenization uses a 1-unit authorization."},"approvedAmount":{"type":"integer","description":"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."},"transactionResponses":{"type":"array","description":"Individual gateway responses, with receipts under each entry. The array can be empty while processing is incomplete.","items":{"$ref":"#/components/schemas/TransactionResponse"}},"sourceId":{"type":"string","description":"Identifier of the session or other source that initiated the transaction."},"threeDs":{"$ref":"#/components/schemas/ThreeDsAuthentication"},"threeDsChallenge":{"$ref":"#/components/schemas/ThreeDsChallenge"},"balanceAmount":{"type":"integer","description":"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)."},"invoiceNumber":{"$ref":"#/components/schemas/InvoiceNumber"},"orderNumber":{"$ref":"#/components/schemas/OrderNumber"}}},"TransactionStatus":{"type":"string","enum":["Unknown","Created","Pending","Submitted","Acknowledged","Processing","AwaitingSettlement","Completed","Failed","Abandoned"],"description":"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.\n"},"AccountHolder":{"type":"object","description":"Account holder information associated with the transaction","properties":{"id":{"type":"string","description":"Account holder ID assigned by the API."},"externalId":{"type":"string","description":"External account holder ID assigned by the integrator."},"contact":{"type":"object","description":"Contact information for the account holder. Only returned for Card Not Present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}}},"required":["id","externalId"]},"PaymentMethodDetails":{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string","description":"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."},"dateDeleted":{"type":"string","format":"date-time","description":"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.\n\nThis field will be present in three scenarios:\n- As part of a successful Remove Token endpoint response\n- In token.removed webhook notifications\n- In List Transactions responses for transactions where the associated token was later removed\n\nWhen this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.\n"},"type":{"type":"string","enum":["Unknown","Physical","Virtual","VirtualAch","VirtualEft","Token"],"description":"The type of payment method:\n- `Physical` - A physical payment terminal for Card Present transactions\n- `Virtual` - A hosted payment form/iframe for Card Not Present transactions\n- `VirtualAch` - A hosted payment form/iframe for ACH (US) bank transfer transactions\n- `Token` - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions\n- `VirtualEft` - A virtual Canadian bank-transfer payment method, when configured.\n- `Unknown` - The payment method type is not known.\n"},"currency":{"type":"string","enum":["USD","CAD"],"description":"The currency of the payment method."},"description":{"type":"string","description":"A human-readable name for the payment method."},"billingContact":{"allOf":[{"$ref":"#/components/schemas/BillingContact"},{"type":"object","description":"Billing contact information. Only returned for tokenized payment methods from Card Not Present transactions."}]},"cardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"maskedCardNumber":{"type":"string","description":"The masked card number. The format may vary (e.g. ************0011, 4****0011, etc.)"},"cardExpDate":{"type":"string","description":"The expiration date of the card in MMYY format."},"accountType":{"type":"string","enum":["Credit","Debit","Checking","Savings"],"description":"Funding-source classification of this token-type payment method.\n- For card tokens: `Credit` or `Debit`.\n- For ACH tokens: `Checking` or `Savings`.\nMay be omitted for older tokens that pre-date this field, for non-token payment methods,\nor when the source did not provide a classification.\n"},"accountNumber":{"type":"string","description":"Masked bank account number, when available for a bank-account token."}},"required":["id","type","currency"]},"BillingContact":{"type":"object","description":"Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}},"ReferenceIdForResponse":{"type":"string","maxLength":100,"description":"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.\n"},"ResultCode":{"type":"integer","enum":[0,55,1003,1005,1010,3000,3002,3005,3006,3009,3010,3011,3012,3013,3014,3020,4001,4100,6800,6801,6802,6900,6901,6902,9998,9999],"description":"Result codes:\n* `0` - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)\n* `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)\n* `1005` - The specified terminal could not be found.\n* `1010` - The transaction request is pending to become transaction.\n* `3000` - An unexpected error occurred. Please try again.\n* `3002` - The transaction could not be completed because the payment terminal could not find the related transaction.\n* `3005` - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.\n* `3006` - The transaction could not be completed because the payment terminal is low on battery.\n* `3009` - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.\n* `3010` - The transaction took too long and was cancelled by the application.\n* `3011` - Invalid transaction request. Please consult the documentation for valid transaction requests.\n* `3012` - Invalid transaction request. paymentMethodId is invalid.\n* `3013` - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.\n* `3014` - Invalid amount. Please try your transaction again with an amount greater than $0.\n* `3020` - An unsupported transaction result was received.\n* `4001` - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.\n* `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`. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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.\n* `6802` - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `6902` - The gateway reported no failure but returned no payment token. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `9998` - The system is not ready to process a transaction.\n* `9999` - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.\n* `1010` - The transaction request is pending customer interaction.\n* `4100` - Cardholder verification is required. Follow `threeDsChallenge.redirectUrl` and reconcile the final transaction outcome before retrying.\n* `55` - The customer cancelled the hosted payment attempt.\n"},"ResultText":{"type":"string","description":"A message describing the result code in more detail."},"TransactionResponse":{"type":"object","description":"A single Sale Transaction may result in multiple Responses.","properties":{"responseCode":{"$ref":"#/components/schemas/ResponseCode"},"authCode":{"type":"string","description":"The authorization code provided by the card issuer, confirming transaction approval."},"amountApproved":{"type":"integer","description":"The amount approved for this transaction response."},"approvedAmountBreakdown":{"$ref":"#/components/schemas/ApprovedAmountBreakdown"},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The payment method used for this transaction response."}]},"cardType":{"$ref":"#/components/schemas/CardType"},"avsResult":{"$ref":"#/components/schemas/AVSResult"},"cvvResult":{"$ref":"#/components/schemas/CVVResult"},"accountType":{"type":"string","description":"The funding-source classification associated with the payment method used in this\ntransaction.\n- For credit/debit cards: `Credit` or `Debit`. May be null when the classification is unavailable, including on older transactions.\n- For ACH/EFT bank accounts: `Checking` or `Savings`.\n\nThe immediate hosted ACH response uses lowercase `checking` or `savings`. Retrieved transaction responses normally use `Checking` or `Savings`.\n","enum":["Credit","Debit","Checking","Savings","checking","savings"]},"hostResponseText":{"type":"string","description":"A meaningful text explaining the response code from the host."},"receipt":{"$ref":"#/components/schemas/Receipt"}}},"ResponseCode":{"type":"integer","enum":[0,1,2,10,11,12,13,14,15,16,17,18,19,20,21,50,51,52,53,54,55,56,57],"description":"Response codes:\n * `0` - UNKNOWN\n * `1` - APPROVED - Transaction was approved\n * `2` - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.\n * `10` - DECLINED - Transaction was declined by the issuer or bank.  For Card-Present, the transaction can also be declined offline by the terminal.\n * `11` - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.\n * `12` - CARD_EXPIRED - The card used for the transaction has expired.\n * `13` - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.\n * `14` - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).\n * `15` - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).\n * `16` - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).\n * `17` - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.\n * `18` - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.\n * `19` - BATCH_EMPTY - Indicates that the batch for processing is empty.\n * `20` - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).\n * `21` - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.\n * `50` - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.\n * `51` - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.\n * `52` - NOT_SUPPORTED - Rejected because the requested operation is not supported.\n * `53` - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.\n * `54` - CANCELLED - Cancelled by the user or merchant.\n * `55` - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.\n * `56` - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.\n * `57` - PENDING - The transaction is awaiting an asynchronous outcome.\n"},"ApprovedAmountBreakdown":{"type":"object","description":"A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.","properties":{"amountGoodsAndServices":{"type":"integer","description":"The approved amount for goods and services."},"tax":{"type":"integer","description":"The approved tax amount."},"cashback":{"type":"integer","description":"The approved cashback amount."},"tip":{"type":"integer","description":"The approved tip amount."}}},"CardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"AVSResult":{"type":"string","enum":["A","E","N","R","S","U","G","W","X","Y","Z"],"description":"The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.\n * `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.\n * `E` - Ineligible transaction.\n * `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.\n * `R` - Retry (system unavailable or timed out).\n * `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.\n * `U` - Address information unavailable.\n * `G` - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.\n * `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.\n * `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.\n * `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.\n * `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.\n\nNOTE: 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.\n"},"CVVResult":{"type":"string","enum":["M","N","P","S","U"],"description":"The CVV verification result. Typically returned on Card Not Present transactions.\n * `M` - CVV Match\n * `N` - CVV No Match\n * `P` - Not Processed\n * `S` - CVV should be on the card but the merchant indicates it is not.\n * `U` - User is unregistered\n\nNOTE: 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.\n"},"Receipt":{"type":"object","description":"Receipt lines for this transaction response. Card-present responses can contain printable receipt lines; other responses can return an empty lines array.","properties":{"lines":{"type":"array","items":{"type":"string"},"description":"The receipt lines."}},"required":["lines"]},"ThreeDsAuthentication":{"type":"object","description":"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.\n","properties":{"status":{"allOf":[{"$ref":"#/components/schemas/ThreeDsStatus"}],"description":"The authentication outcome to use in your integration. The other `threeDs` fields provide supporting authentication data.\n"},"cavv":{"type":"string","description":"Cardholder Authentication Verification Value. Cryptographic proof that 3DS authentication was performed. Present on frictionless and challenge-completed transactions."},"eci":{"type":"string","description":"E-commerce Indicator. Indicates 3DS liability-shift status per card scheme:\n * `02` / `05` - Fully authenticated (liability shift to issuer).\n * `01` / `06` - Attempted authentication (partial liability shift).\n * `00` / `07` - Not authenticated (no liability shift).\n"},"xid":{"type":"string","description":"3DS1 transaction identifier. Some issuers still return this under 3DS2 for backward compatibility."},"dsTransId":{"type":"string","description":"Directory Server transaction ID (3DS2). Identifies the authentication associated with this card transaction."},"threeDReasonId":{"type":"string","description":"Issuer-provided reason code when 3DS authentication failed. Populated only on declines. Use `status` to handle the outcome and `threeDReason` for the explanation.\n"},"threeDReason":{"type":"string","description":"Human-readable description matching `threeDReasonId`."}}},"ThreeDsStatus":{"type":"string","enum":["Authenticated","Attempted","NotAuthenticated","Failed","Unavailable","NotEnrolled"],"description":"Outcome classification of the 3D Secure check performed on a card transaction. Only present on transactions initiated with `formConfig.enable3DSecure: true`. Use this status to handle the authentication outcome; the other `threeDs` fields provide supporting authentication data.\n\n* `Authenticated` - Issuer fully authenticated the cardholder (ECI `02` / `05`). Full liability shift to the issuer for fraud chargebacks. Covers both frictionless and challenge-completed flows.\n* `Attempted` - Issuer attempted authentication but did not fully authenticate the cardholder (ECI `01` / `06`). Partial liability shift, scheme-dependent.\n* `NotAuthenticated` - 3DS completed but the issuer did not authenticate the cardholder (ECI `00` / `07`). No liability shift.\n* `Failed` - Issuer's ACS rejected the cardholder authentication. Transaction was declined. See `threeDReasonId` for the issuer's reason.\n* `Unavailable` - A technical issue prevented 3DS authentication from completing.\n* `NotEnrolled` - The card is not enrolled in 3DS.\n"},"ThreeDsChallenge":{"type":"object","description":"Present when a token payment requires a cardholder challenge (`resultCode: 4100`).","properties":{"redirectUrl":{"type":"string","format":"uri","description":"Hosted URL where the cardholder completes the challenge."},"followUpToken":{"type":"string","description":"Opaque token identifying the pending challenge."}},"required":["redirectUrl","followUpToken"]},"InvoiceNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.\n"},"OrderNumber":{"type":"string","maxLength":100,"description":"An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.\n"}}}}
```

## The TokenRemovedWebhook object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"TokenRemovedWebhook":{"type":"object","description":"Represents the webhook triggered when a previously tokenized card is removed from the system.","properties":{"event":{"allOf":[{"$ref":"#/components/schemas/WebhookEvent"},{"type":"object","properties":{"type":{"type":"string"}}}]},"originalResponse":{"$ref":"#/components/schemas/CardOnFileRemoveResponse"}},"required":["event","originalResponse"]},"WebhookEvent":{"type":"object","description":"Webhook event details.","properties":{"id":{"type":"string","description":"Unique ID for this webhook event."},"type":{"type":"string","description":"The type of event that occurred."},"timestamp":{"type":"string","format":"date-time","description":"The time when the event was triggered (UTC)."},"merchantId":{"type":"string","description":"The merchant that owns the transaction or token."}},"required":["id","type","timestamp","merchantId"]},"CardOnFileRemoveResponse":{"type":"object","description":"Represents the response to a tokenized card removal request.","properties":{"id":{"type":"string","description":"Unique ID for this payment-method operation (`ops_` prefix)."},"paymentMethod":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodDetails"},{"type":"object","description":"The tokenized card that was removed.","properties":{"id":{"type":"string"}}}]},"referenceId":{"$ref":"#/components/schemas/ReferenceIdForResponse"},"resultCode":{"$ref":"#/components/schemas/ResultCode"},"resultText":{"$ref":"#/components/schemas/ResultText"}}},"PaymentMethodDetails":{"type":"object","description":"The payment method used for this transaction.","properties":{"id":{"type":"string","description":"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."},"dateDeleted":{"type":"string","format":"date-time","description":"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.\n\nThis field will be present in three scenarios:\n- As part of a successful Remove Token endpoint response\n- In token.removed webhook notifications\n- In List Transactions responses for transactions where the associated token was later removed\n\nWhen this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.\n"},"type":{"type":"string","enum":["Unknown","Physical","Virtual","VirtualAch","VirtualEft","Token"],"description":"The type of payment method:\n- `Physical` - A physical payment terminal for Card Present transactions\n- `Virtual` - A hosted payment form/iframe for Card Not Present transactions\n- `VirtualAch` - A hosted payment form/iframe for ACH (US) bank transfer transactions\n- `Token` - A stored payment method (a card or an ACH bank account) for card-on-file and recurring transactions\n- `VirtualEft` - A virtual Canadian bank-transfer payment method, when configured.\n- `Unknown` - The payment method type is not known.\n"},"currency":{"type":"string","enum":["USD","CAD"],"description":"The currency of the payment method."},"description":{"type":"string","description":"A human-readable name for the payment method."},"billingContact":{"allOf":[{"$ref":"#/components/schemas/BillingContact"},{"type":"object","description":"Billing contact information. Only returned for tokenized payment methods from Card Not Present transactions."}]},"cardType":{"type":"string","enum":["UNKNOWN","DEBIT","VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","GIFT","CASH","EBT","INTERAC","OTHER"],"description":"The type of card used for this transaction:\n * `UNKNOWN` - The card type is unknown\n * `DEBIT` - Debit Card\n * `VISA` - Visa Credit Card\n * `MASTERCARD` - MasterCard Credit Card\n * `AMEX` - American Express Credit Card\n * `DINERS` - Diners Club Credit Card\n * `DISCOVER` - Discover Credit Card\n * `JCB` - JCB Credit Card\n * `UNIONPAY` - UnionPay Credit Card\n * `MAESTRO` - Maestro Debit Card\n * `GIFT` - Gift Card\n * `CASH` - All-cash Transaction\n * `EBT` - Electronic Benefits Transfer Card\n * `INTERAC` - Interac (Canadian PIN-debit network), Card Present only\n * `OTHER` - Other tender types\n"},"maskedCardNumber":{"type":"string","description":"The masked card number. The format may vary (e.g. ************0011, 4****0011, etc.)"},"cardExpDate":{"type":"string","description":"The expiration date of the card in MMYY format."},"accountType":{"type":"string","enum":["Credit","Debit","Checking","Savings"],"description":"Funding-source classification of this token-type payment method.\n- For card tokens: `Credit` or `Debit`.\n- For ACH tokens: `Checking` or `Savings`.\nMay be omitted for older tokens that pre-date this field, for non-token payment methods,\nor when the source did not provide a classification.\n"},"accountNumber":{"type":"string","description":"Masked bank account number, when available for a bank-account token."}},"required":["id","type","currency"]},"BillingContact":{"type":"object","description":"Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.","properties":{"name":{"type":"string"},"countryCode":{"type":"string"},"zipCode":{"type":"string"},"address":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"address2":{"type":"string","description":"Additional address information, when supplied."}}},"ReferenceIdForResponse":{"type":"string","maxLength":100,"description":"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.\n"},"ResultCode":{"type":"integer","enum":[0,55,1003,1005,1010,3000,3002,3005,3006,3009,3010,3011,3012,3013,3014,3020,4001,4100,6800,6801,6802,6900,6901,6902,9998,9999],"description":"Result codes:\n* `0` - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)\n* `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)\n* `1005` - The specified terminal could not be found.\n* `1010` - The transaction request is pending to become transaction.\n* `3000` - An unexpected error occurred. Please try again.\n* `3002` - The transaction could not be completed because the payment terminal could not find the related transaction.\n* `3005` - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.\n* `3006` - The transaction could not be completed because the payment terminal is low on battery.\n* `3009` - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.\n* `3010` - The transaction took too long and was cancelled by the application.\n* `3011` - Invalid transaction request. Please consult the documentation for valid transaction requests.\n* `3012` - Invalid transaction request. paymentMethodId is invalid.\n* `3013` - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.\n* `3014` - Invalid amount. Please try your transaction again with an amount greater than $0.\n* `3020` - An unsupported transaction result was received.\n* `4001` - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.\n* `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`. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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.\n* `6802` - The card is not enrolled in 3D Secure. Retry without 3DS only if merchant policy allows; approval is not guaranteed.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `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](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `6902` - The gateway reported no failure but returned no payment token. See [SDK Error Codes](https://fiska.gitbook.io/omni-payment-api/payment-sdk/error-codes) for guidance.\n* `9998` - The system is not ready to process a transaction.\n* `9999` - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.\n* `1010` - The transaction request is pending customer interaction.\n* `4100` - Cardholder verification is required. Follow `threeDsChallenge.redirectUrl` and reconcile the final transaction outcome before retrying.\n* `55` - The customer cancelled the hosted payment attempt.\n"},"ResultText":{"type":"string","description":"A message describing the result code in more detail."}}}}
```

## The MerchantLifecycleWebhookEvent object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"MerchantLifecycleWebhookEvent":{"type":"object","description":"Webhook event details for merchant lifecycle events. Extends the standard event envelope with the merchant the event relates to, once a merchant record exists.","properties":{"id":{"type":"string","description":"Unique ID for this webhook event. A bare ULID - unlike transaction events, merchant lifecycle event ids carry no `evt_` prefix."},"type":{"type":"string","description":"The type of event that occurred."},"timestamp":{"type":"string","format":"date-time","description":"The time when the event was triggered (UTC)."},"merchantId":{"type":["string","null"],"description":"The merchant this event relates to. Null for events that occur before a merchant record exists (e.g. application progress events)."}},"required":["id","type","timestamp","merchantId"]}}}}
```

## The MerchantLifecycleWebhookData object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"MerchantLifecycleWebhookData":{"type":"object","description":"Details for a merchant lifecycle event. Every field is always present; fields that do not apply to the event type are null. Payloads are PII-safe by design - they never carry underwriting documents, bank details, or tax identifiers.","properties":{"isvId":{"type":"string","description":"Your ISV id."},"merchantName":{"type":["string","null"],"description":"The merchant's business display name, when known."},"applicationId":{"type":["string","null"],"description":"The merchant onboarding application this event relates to."},"fromStatus":{"type":["string","null"],"description":"The application status before the transition, for application progress events."},"toStatus":{"type":["string","null"],"description":"The application status after the transition, for application progress events."},"reason":{"type":["string","null"],"description":"Human-readable reason accompanying a rejection decision, when one was provided."},"templateName":{"type":["string","null"],"description":"The pricing template name, for pricing template decision events."},"templateRegion":{"type":["string","null"],"description":"The pricing template region (`US` or `CA`), for pricing template decision events."},"templateVersion":{"type":["string","null"],"description":"The pricing template version, for pricing template decision events."},"portalLink":{"type":"string","format":"uri","description":"Deep link into the Fiska Partner Portal page for this event."}},"required":["isvId","merchantName","applicationId","fromStatus","toStatus","reason","templateName","templateRegion","templateVersion","portalLink"]}}}}
```

## The MerchantApplicationStartedWebhook object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"MerchantApplicationStartedWebhook":{"type":"object","description":"Represents the webhook triggered when a merchant begins filling out their onboarding application.","properties":{"event":{"allOf":[{"$ref":"#/components/schemas/MerchantLifecycleWebhookEvent"},{"type":"object","properties":{"type":{"type":"string"}}}]},"data":{"$ref":"#/components/schemas/MerchantLifecycleWebhookData"}},"required":["event","data"]},"MerchantLifecycleWebhookEvent":{"type":"object","description":"Webhook event details for merchant lifecycle events. Extends the standard event envelope with the merchant the event relates to, once a merchant record exists.","properties":{"id":{"type":"string","description":"Unique ID for this webhook event. A bare ULID - unlike transaction events, merchant lifecycle event ids carry no `evt_` prefix."},"type":{"type":"string","description":"The type of event that occurred."},"timestamp":{"type":"string","format":"date-time","description":"The time when the event was triggered (UTC)."},"merchantId":{"type":["string","null"],"description":"The merchant this event relates to. Null for events that occur before a merchant record exists (e.g. application progress events)."}},"required":["id","type","timestamp","merchantId"]},"MerchantLifecycleWebhookData":{"type":"object","description":"Details for a merchant lifecycle event. Every field is always present; fields that do not apply to the event type are null. Payloads are PII-safe by design - they never carry underwriting documents, bank details, or tax identifiers.","properties":{"isvId":{"type":"string","description":"Your ISV id."},"merchantName":{"type":["string","null"],"description":"The merchant's business display name, when known."},"applicationId":{"type":["string","null"],"description":"The merchant onboarding application this event relates to."},"fromStatus":{"type":["string","null"],"description":"The application status before the transition, for application progress events."},"toStatus":{"type":["string","null"],"description":"The application status after the transition, for application progress events."},"reason":{"type":["string","null"],"description":"Human-readable reason accompanying a rejection decision, when one was provided."},"templateName":{"type":["string","null"],"description":"The pricing template name, for pricing template decision events."},"templateRegion":{"type":["string","null"],"description":"The pricing template region (`US` or `CA`), for pricing template decision events."},"templateVersion":{"type":["string","null"],"description":"The pricing template version, for pricing template decision events."},"portalLink":{"type":"string","format":"uri","description":"Deep link into the Fiska Partner Portal page for this event."}},"required":["isvId","merchantName","applicationId","fromStatus","toStatus","reason","templateName","templateRegion","templateVersion","portalLink"]}}}}
```

## The MerchantApplicationSubmittedWebhook object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"MerchantApplicationSubmittedWebhook":{"type":"object","description":"Represents the webhook triggered when a merchant submits their onboarding application for review.","properties":{"event":{"allOf":[{"$ref":"#/components/schemas/MerchantLifecycleWebhookEvent"},{"type":"object","properties":{"type":{"type":"string"}}}]},"data":{"$ref":"#/components/schemas/MerchantLifecycleWebhookData"}},"required":["event","data"]},"MerchantLifecycleWebhookEvent":{"type":"object","description":"Webhook event details for merchant lifecycle events. Extends the standard event envelope with the merchant the event relates to, once a merchant record exists.","properties":{"id":{"type":"string","description":"Unique ID for this webhook event. A bare ULID - unlike transaction events, merchant lifecycle event ids carry no `evt_` prefix."},"type":{"type":"string","description":"The type of event that occurred."},"timestamp":{"type":"string","format":"date-time","description":"The time when the event was triggered (UTC)."},"merchantId":{"type":["string","null"],"description":"The merchant this event relates to. Null for events that occur before a merchant record exists (e.g. application progress events)."}},"required":["id","type","timestamp","merchantId"]},"MerchantLifecycleWebhookData":{"type":"object","description":"Details for a merchant lifecycle event. Every field is always present; fields that do not apply to the event type are null. Payloads are PII-safe by design - they never carry underwriting documents, bank details, or tax identifiers.","properties":{"isvId":{"type":"string","description":"Your ISV id."},"merchantName":{"type":["string","null"],"description":"The merchant's business display name, when known."},"applicationId":{"type":["string","null"],"description":"The merchant onboarding application this event relates to."},"fromStatus":{"type":["string","null"],"description":"The application status before the transition, for application progress events."},"toStatus":{"type":["string","null"],"description":"The application status after the transition, for application progress events."},"reason":{"type":["string","null"],"description":"Human-readable reason accompanying a rejection decision, when one was provided."},"templateName":{"type":["string","null"],"description":"The pricing template name, for pricing template decision events."},"templateRegion":{"type":["string","null"],"description":"The pricing template region (`US` or `CA`), for pricing template decision events."},"templateVersion":{"type":["string","null"],"description":"The pricing template version, for pricing template decision events."},"portalLink":{"type":"string","format":"uri","description":"Deep link into the Fiska Partner Portal page for this event."}},"required":["isvId","merchantName","applicationId","fromStatus","toStatus","reason","templateName","templateRegion","templateVersion","portalLink"]}}}}
```

## The MerchantApplicationStatusChangedWebhook object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"MerchantApplicationStatusChangedWebhook":{"type":"object","description":"Represents the webhook triggered when a merchant application moves between review stages (e.g. into Underwriting or Onboarding).","properties":{"event":{"allOf":[{"$ref":"#/components/schemas/MerchantLifecycleWebhookEvent"},{"type":"object","properties":{"type":{"type":"string"}}}]},"data":{"$ref":"#/components/schemas/MerchantLifecycleWebhookData"}},"required":["event","data"]},"MerchantLifecycleWebhookEvent":{"type":"object","description":"Webhook event details for merchant lifecycle events. Extends the standard event envelope with the merchant the event relates to, once a merchant record exists.","properties":{"id":{"type":"string","description":"Unique ID for this webhook event. A bare ULID - unlike transaction events, merchant lifecycle event ids carry no `evt_` prefix."},"type":{"type":"string","description":"The type of event that occurred."},"timestamp":{"type":"string","format":"date-time","description":"The time when the event was triggered (UTC)."},"merchantId":{"type":["string","null"],"description":"The merchant this event relates to. Null for events that occur before a merchant record exists (e.g. application progress events)."}},"required":["id","type","timestamp","merchantId"]},"MerchantLifecycleWebhookData":{"type":"object","description":"Details for a merchant lifecycle event. Every field is always present; fields that do not apply to the event type are null. Payloads are PII-safe by design - they never carry underwriting documents, bank details, or tax identifiers.","properties":{"isvId":{"type":"string","description":"Your ISV id."},"merchantName":{"type":["string","null"],"description":"The merchant's business display name, when known."},"applicationId":{"type":["string","null"],"description":"The merchant onboarding application this event relates to."},"fromStatus":{"type":["string","null"],"description":"The application status before the transition, for application progress events."},"toStatus":{"type":["string","null"],"description":"The application status after the transition, for application progress events."},"reason":{"type":["string","null"],"description":"Human-readable reason accompanying a rejection decision, when one was provided."},"templateName":{"type":["string","null"],"description":"The pricing template name, for pricing template decision events."},"templateRegion":{"type":["string","null"],"description":"The pricing template region (`US` or `CA`), for pricing template decision events."},"templateVersion":{"type":["string","null"],"description":"The pricing template version, for pricing template decision events."},"portalLink":{"type":"string","format":"uri","description":"Deep link into the Fiska Partner Portal page for this event."}},"required":["isvId","merchantName","applicationId","fromStatus","toStatus","reason","templateName","templateRegion","templateVersion","portalLink"]}}}}
```

## The MerchantApplicationRequiresActionWebhook object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"MerchantApplicationRequiresActionWebhook":{"type":"object","description":"Represents the webhook triggered when a merchant application needs more information or documents from the merchant before review can continue.","properties":{"event":{"allOf":[{"$ref":"#/components/schemas/MerchantLifecycleWebhookEvent"},{"type":"object","properties":{"type":{"type":"string"}}}]},"data":{"$ref":"#/components/schemas/MerchantLifecycleWebhookData"}},"required":["event","data"]},"MerchantLifecycleWebhookEvent":{"type":"object","description":"Webhook event details for merchant lifecycle events. Extends the standard event envelope with the merchant the event relates to, once a merchant record exists.","properties":{"id":{"type":"string","description":"Unique ID for this webhook event. A bare ULID - unlike transaction events, merchant lifecycle event ids carry no `evt_` prefix."},"type":{"type":"string","description":"The type of event that occurred."},"timestamp":{"type":"string","format":"date-time","description":"The time when the event was triggered (UTC)."},"merchantId":{"type":["string","null"],"description":"The merchant this event relates to. Null for events that occur before a merchant record exists (e.g. application progress events)."}},"required":["id","type","timestamp","merchantId"]},"MerchantLifecycleWebhookData":{"type":"object","description":"Details for a merchant lifecycle event. Every field is always present; fields that do not apply to the event type are null. Payloads are PII-safe by design - they never carry underwriting documents, bank details, or tax identifiers.","properties":{"isvId":{"type":"string","description":"Your ISV id."},"merchantName":{"type":["string","null"],"description":"The merchant's business display name, when known."},"applicationId":{"type":["string","null"],"description":"The merchant onboarding application this event relates to."},"fromStatus":{"type":["string","null"],"description":"The application status before the transition, for application progress events."},"toStatus":{"type":["string","null"],"description":"The application status after the transition, for application progress events."},"reason":{"type":["string","null"],"description":"Human-readable reason accompanying a rejection decision, when one was provided."},"templateName":{"type":["string","null"],"description":"The pricing template name, for pricing template decision events."},"templateRegion":{"type":["string","null"],"description":"The pricing template region (`US` or `CA`), for pricing template decision events."},"templateVersion":{"type":["string","null"],"description":"The pricing template version, for pricing template decision events."},"portalLink":{"type":"string","format":"uri","description":"Deep link into the Fiska Partner Portal page for this event."}},"required":["isvId","merchantName","applicationId","fromStatus","toStatus","reason","templateName","templateRegion","templateVersion","portalLink"]}}}}
```

## The MerchantApplicationInfoUploadedWebhook object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"MerchantApplicationInfoUploadedWebhook":{"type":"object","description":"Represents the webhook triggered when a merchant provides the requested information or documents on an application that required action.","properties":{"event":{"allOf":[{"$ref":"#/components/schemas/MerchantLifecycleWebhookEvent"},{"type":"object","properties":{"type":{"type":"string"}}}]},"data":{"$ref":"#/components/schemas/MerchantLifecycleWebhookData"}},"required":["event","data"]},"MerchantLifecycleWebhookEvent":{"type":"object","description":"Webhook event details for merchant lifecycle events. Extends the standard event envelope with the merchant the event relates to, once a merchant record exists.","properties":{"id":{"type":"string","description":"Unique ID for this webhook event. A bare ULID - unlike transaction events, merchant lifecycle event ids carry no `evt_` prefix."},"type":{"type":"string","description":"The type of event that occurred."},"timestamp":{"type":"string","format":"date-time","description":"The time when the event was triggered (UTC)."},"merchantId":{"type":["string","null"],"description":"The merchant this event relates to. Null for events that occur before a merchant record exists (e.g. application progress events)."}},"required":["id","type","timestamp","merchantId"]},"MerchantLifecycleWebhookData":{"type":"object","description":"Details for a merchant lifecycle event. Every field is always present; fields that do not apply to the event type are null. Payloads are PII-safe by design - they never carry underwriting documents, bank details, or tax identifiers.","properties":{"isvId":{"type":"string","description":"Your ISV id."},"merchantName":{"type":["string","null"],"description":"The merchant's business display name, when known."},"applicationId":{"type":["string","null"],"description":"The merchant onboarding application this event relates to."},"fromStatus":{"type":["string","null"],"description":"The application status before the transition, for application progress events."},"toStatus":{"type":["string","null"],"description":"The application status after the transition, for application progress events."},"reason":{"type":["string","null"],"description":"Human-readable reason accompanying a rejection decision, when one was provided."},"templateName":{"type":["string","null"],"description":"The pricing template name, for pricing template decision events."},"templateRegion":{"type":["string","null"],"description":"The pricing template region (`US` or `CA`), for pricing template decision events."},"templateVersion":{"type":["string","null"],"description":"The pricing template version, for pricing template decision events."},"portalLink":{"type":"string","format":"uri","description":"Deep link into the Fiska Partner Portal page for this event."}},"required":["isvId","merchantName","applicationId","fromStatus","toStatus","reason","templateName","templateRegion","templateVersion","portalLink"]}}}}
```

## The MerchantApprovedWebhook object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"MerchantApprovedWebhook":{"type":"object","description":"Represents the webhook triggered when a merchant application is approved and the merchant account is created.","properties":{"event":{"allOf":[{"$ref":"#/components/schemas/MerchantLifecycleWebhookEvent"},{"type":"object","properties":{"type":{"type":"string"}}}]},"data":{"$ref":"#/components/schemas/MerchantLifecycleWebhookData"}},"required":["event","data"]},"MerchantLifecycleWebhookEvent":{"type":"object","description":"Webhook event details for merchant lifecycle events. Extends the standard event envelope with the merchant the event relates to, once a merchant record exists.","properties":{"id":{"type":"string","description":"Unique ID for this webhook event. A bare ULID - unlike transaction events, merchant lifecycle event ids carry no `evt_` prefix."},"type":{"type":"string","description":"The type of event that occurred."},"timestamp":{"type":"string","format":"date-time","description":"The time when the event was triggered (UTC)."},"merchantId":{"type":["string","null"],"description":"The merchant this event relates to. Null for events that occur before a merchant record exists (e.g. application progress events)."}},"required":["id","type","timestamp","merchantId"]},"MerchantLifecycleWebhookData":{"type":"object","description":"Details for a merchant lifecycle event. Every field is always present; fields that do not apply to the event type are null. Payloads are PII-safe by design - they never carry underwriting documents, bank details, or tax identifiers.","properties":{"isvId":{"type":"string","description":"Your ISV id."},"merchantName":{"type":["string","null"],"description":"The merchant's business display name, when known."},"applicationId":{"type":["string","null"],"description":"The merchant onboarding application this event relates to."},"fromStatus":{"type":["string","null"],"description":"The application status before the transition, for application progress events."},"toStatus":{"type":["string","null"],"description":"The application status after the transition, for application progress events."},"reason":{"type":["string","null"],"description":"Human-readable reason accompanying a rejection decision, when one was provided."},"templateName":{"type":["string","null"],"description":"The pricing template name, for pricing template decision events."},"templateRegion":{"type":["string","null"],"description":"The pricing template region (`US` or `CA`), for pricing template decision events."},"templateVersion":{"type":["string","null"],"description":"The pricing template version, for pricing template decision events."},"portalLink":{"type":"string","format":"uri","description":"Deep link into the Fiska Partner Portal page for this event."}},"required":["isvId","merchantName","applicationId","fromStatus","toStatus","reason","templateName","templateRegion","templateVersion","portalLink"]}}}}
```

## The MerchantRejectedWebhook object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"MerchantRejectedWebhook":{"type":"object","description":"Represents the webhook triggered when a merchant application is rejected during review.","properties":{"event":{"allOf":[{"$ref":"#/components/schemas/MerchantLifecycleWebhookEvent"},{"type":"object","properties":{"type":{"type":"string"}}}]},"data":{"$ref":"#/components/schemas/MerchantLifecycleWebhookData"}},"required":["event","data"]},"MerchantLifecycleWebhookEvent":{"type":"object","description":"Webhook event details for merchant lifecycle events. Extends the standard event envelope with the merchant the event relates to, once a merchant record exists.","properties":{"id":{"type":"string","description":"Unique ID for this webhook event. A bare ULID - unlike transaction events, merchant lifecycle event ids carry no `evt_` prefix."},"type":{"type":"string","description":"The type of event that occurred."},"timestamp":{"type":"string","format":"date-time","description":"The time when the event was triggered (UTC)."},"merchantId":{"type":["string","null"],"description":"The merchant this event relates to. Null for events that occur before a merchant record exists (e.g. application progress events)."}},"required":["id","type","timestamp","merchantId"]},"MerchantLifecycleWebhookData":{"type":"object","description":"Details for a merchant lifecycle event. Every field is always present; fields that do not apply to the event type are null. Payloads are PII-safe by design - they never carry underwriting documents, bank details, or tax identifiers.","properties":{"isvId":{"type":"string","description":"Your ISV id."},"merchantName":{"type":["string","null"],"description":"The merchant's business display name, when known."},"applicationId":{"type":["string","null"],"description":"The merchant onboarding application this event relates to."},"fromStatus":{"type":["string","null"],"description":"The application status before the transition, for application progress events."},"toStatus":{"type":["string","null"],"description":"The application status after the transition, for application progress events."},"reason":{"type":["string","null"],"description":"Human-readable reason accompanying a rejection decision, when one was provided."},"templateName":{"type":["string","null"],"description":"The pricing template name, for pricing template decision events."},"templateRegion":{"type":["string","null"],"description":"The pricing template region (`US` or `CA`), for pricing template decision events."},"templateVersion":{"type":["string","null"],"description":"The pricing template version, for pricing template decision events."},"portalLink":{"type":"string","format":"uri","description":"Deep link into the Fiska Partner Portal page for this event."}},"required":["isvId","merchantName","applicationId","fromStatus","toStatus","reason","templateName","templateRegion","templateVersion","portalLink"]}}}}
```

## The PricingTemplateApprovedWebhook object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"PricingTemplateApprovedWebhook":{"type":"object","description":"Represents the webhook triggered when a submitted pricing template is approved by Fiska review and its onboarding links become active.","properties":{"event":{"allOf":[{"$ref":"#/components/schemas/MerchantLifecycleWebhookEvent"},{"type":"object","properties":{"type":{"type":"string"}}}]},"data":{"$ref":"#/components/schemas/MerchantLifecycleWebhookData"}},"required":["event","data"]},"MerchantLifecycleWebhookEvent":{"type":"object","description":"Webhook event details for merchant lifecycle events. Extends the standard event envelope with the merchant the event relates to, once a merchant record exists.","properties":{"id":{"type":"string","description":"Unique ID for this webhook event. A bare ULID - unlike transaction events, merchant lifecycle event ids carry no `evt_` prefix."},"type":{"type":"string","description":"The type of event that occurred."},"timestamp":{"type":"string","format":"date-time","description":"The time when the event was triggered (UTC)."},"merchantId":{"type":["string","null"],"description":"The merchant this event relates to. Null for events that occur before a merchant record exists (e.g. application progress events)."}},"required":["id","type","timestamp","merchantId"]},"MerchantLifecycleWebhookData":{"type":"object","description":"Details for a merchant lifecycle event. Every field is always present; fields that do not apply to the event type are null. Payloads are PII-safe by design - they never carry underwriting documents, bank details, or tax identifiers.","properties":{"isvId":{"type":"string","description":"Your ISV id."},"merchantName":{"type":["string","null"],"description":"The merchant's business display name, when known."},"applicationId":{"type":["string","null"],"description":"The merchant onboarding application this event relates to."},"fromStatus":{"type":["string","null"],"description":"The application status before the transition, for application progress events."},"toStatus":{"type":["string","null"],"description":"The application status after the transition, for application progress events."},"reason":{"type":["string","null"],"description":"Human-readable reason accompanying a rejection decision, when one was provided."},"templateName":{"type":["string","null"],"description":"The pricing template name, for pricing template decision events."},"templateRegion":{"type":["string","null"],"description":"The pricing template region (`US` or `CA`), for pricing template decision events."},"templateVersion":{"type":["string","null"],"description":"The pricing template version, for pricing template decision events."},"portalLink":{"type":"string","format":"uri","description":"Deep link into the Fiska Partner Portal page for this event."}},"required":["isvId","merchantName","applicationId","fromStatus","toStatus","reason","templateName","templateRegion","templateVersion","portalLink"]}}}}
```

## The PricingTemplateRejectedWebhook object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"PricingTemplateRejectedWebhook":{"type":"object","description":"Represents the webhook triggered when a submitted pricing template is declined by Fiska review.","properties":{"event":{"allOf":[{"$ref":"#/components/schemas/MerchantLifecycleWebhookEvent"},{"type":"object","properties":{"type":{"type":"string"}}}]},"data":{"$ref":"#/components/schemas/MerchantLifecycleWebhookData"}},"required":["event","data"]},"MerchantLifecycleWebhookEvent":{"type":"object","description":"Webhook event details for merchant lifecycle events. Extends the standard event envelope with the merchant the event relates to, once a merchant record exists.","properties":{"id":{"type":"string","description":"Unique ID for this webhook event. A bare ULID - unlike transaction events, merchant lifecycle event ids carry no `evt_` prefix."},"type":{"type":"string","description":"The type of event that occurred."},"timestamp":{"type":"string","format":"date-time","description":"The time when the event was triggered (UTC)."},"merchantId":{"type":["string","null"],"description":"The merchant this event relates to. Null for events that occur before a merchant record exists (e.g. application progress events)."}},"required":["id","type","timestamp","merchantId"]},"MerchantLifecycleWebhookData":{"type":"object","description":"Details for a merchant lifecycle event. Every field is always present; fields that do not apply to the event type are null. Payloads are PII-safe by design - they never carry underwriting documents, bank details, or tax identifiers.","properties":{"isvId":{"type":"string","description":"Your ISV id."},"merchantName":{"type":["string","null"],"description":"The merchant's business display name, when known."},"applicationId":{"type":["string","null"],"description":"The merchant onboarding application this event relates to."},"fromStatus":{"type":["string","null"],"description":"The application status before the transition, for application progress events."},"toStatus":{"type":["string","null"],"description":"The application status after the transition, for application progress events."},"reason":{"type":["string","null"],"description":"Human-readable reason accompanying a rejection decision, when one was provided."},"templateName":{"type":["string","null"],"description":"The pricing template name, for pricing template decision events."},"templateRegion":{"type":["string","null"],"description":"The pricing template region (`US` or `CA`), for pricing template decision events."},"templateVersion":{"type":["string","null"],"description":"The pricing template version, for pricing template decision events."},"portalLink":{"type":"string","format":"uri","description":"Deep link into the Fiska Partner Portal page for this event."}},"required":["isvId","merchantName","applicationId","fromStatus","toStatus","reason","templateName","templateRegion","templateVersion","portalLink"]}}}}
```

## The SettlementFeeBreakdown object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"SettlementFeeBreakdown":{"type":"object","description":"Optional breakdown of the components of a fee charge. Only the components that apply to a given fee are present.\n Components are signed integers in minor units; positive values are charges and negative values are credits.\n","properties":{"discountFee":{"type":"integer","description":"Processing/discount fee component, smallest denomination."},"originationFee":{"type":"integer","description":"ACH origination fee, smallest denomination."},"returnFee":{"type":"integer","description":"ACH return fee - charged when a transaction is returned/reversed post-settlement. Smallest denomination."},"interchangeFee":{"type":"integer","description":"Card-network interchange fee, in minor units."},"otherFee":{"type":"integer","description":"Provider-specific catch-all for fee components not otherwise modeled."}}}}}}
```

## The SettlementSummary object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"SettlementSummary":{"type":"object","description":"A summary of a processor-reported transfer of payment proceeds to the merchant's bank account. It identifies the activity grouped into one deposit and reports its date, currency, total amount, rail, and funding type. See [Settlement](https://fiska.gitbook.io/omni-payment-api/glossary/settlement-and-fees#settlement) in the glossary.","properties":{"id":{"type":"string","description":"The settlement ID, prefixed with `stl_`."},"type":{"type":"string","enum":["Card","Ach"],"description":"The kind of settlement: `Card` for card payments or `Ach` for ACH bank transfers.\n\nRead this field together with `fundingType`. Card Net is `type: Card` with `fundingType: Net`; Card Gross is `type: Card` with `fundingType: Gross`. These are combinations of existing fields, not additional `type` values. ACH also supports both funding types.\n"},"settlementDate":{"type":"string","format":"date","description":"The date the settlement was deposited to the merchant's bank account."},"currency":{"type":"string","enum":["USD","CAD"]},"amount":{"type":"integer","description":"The processor-reported deposit total in minor units. Signed: refunds, fees, and adjustments can produce a negative deposit.\n\nFor Card Net, the deposit includes deductions for withheld interchange and discount fees. For Card Gross, those fees are billed separately. Reserve holds and transfers can change the deposited amount in either card funding model. Card transaction lines retain their full settled amounts before these deposit-level deductions.\n\nFor ACH, `fundingType` states whether fees are withheld from the deposit or billed separately.\n"},"fundingType":{"type":"string","enum":["Net","Gross"],"description":"Whether the payment provider withholds its fees from deposits or bills them separately. Read together with `type`; card and ACH funding terms can differ for the same merchant.\n\n**Net**: the deposit is after withheld fees. For Card Net, interchange and discount fees apply at the deposit level; the individual card lines remain before those deductions.\n\n**Gross**: fees are billed separately and do not reduce this deposit. For Card Gross, reserve holds and transfers can still change `amount`, so it need not equal the sum of card transaction amounts.\n\nFunding type does not determine the fee billing schedule. Use each [fee charge](https://fiska.gitbook.io/omni-payment-api/settlement-reporting/fee-charges)'s `source` and `chargeDate`; monthly billing produces `StatementOnly` charges. An `amount` is always returned with a `fundingType` in scope.\n"},"netAmount":{"type":"integer","deprecated":true,"description":"**Deprecated - read `amount` instead.** This member mirrors `amount` exactly and cannot hold a different figure. `fundingType` on this payload states whether that figure is the gross deposit or one already net of withheld fees, and is the only authoritative reading of it. Deprecated on 2026-08-21 and removed one month later in its own release, at which point `netAmount` also stops being accepted as a filter or sort field.\n\nIts value changed when `amount` was introduced: for a gross-funded merchant it now reports the gross deposit - the figure that actually reached the bank - so despite its name it is not necessarily a net figure.\n"},"transactionCount":{"type":"integer","description":"Number of settled-transaction line items in the settlement. Always equal to the length of the `lineItems` array returned by [`GET /settlements/{settlementId}`](https://fiska.gitbook.io/omni-payment-api/settlement-reporting/settlements), which withholds no line.\n"},"status":{"type":"string","enum":["Settled","Adjusted"],"description":"Status of the settlement.\n\n**Settled**: The settlement has been deposited to the merchant's bank account.\n\n**Adjusted**: Reserved value; not currently returned.\n"}},"required":["id","type","settlementDate","currency","amount","fundingType","netAmount","transactionCount","status"]}}}}
```

## The SettlementLineItem object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"SettlementLineItem":{"type":"object","description":"A processor-reported line showing how one sale, capture, refund, or failed payout contributes to a merchant deposit. It records the activity's amount and processor identifiers, plus the Fiska transaction ID when matched. See [Settled transaction](https://fiska.gitbook.io/omni-payment-api/glossary/settlement-and-fees#settled-transaction) in the glossary.","properties":{"transactionId":{"type":"string","description":"The transaction ID, prefixed with `trx_`. Absent when `matchStatus` is `Unmatched` - look it up via [`GET /transactions`](https://fiska.gitbook.io/omni-payment-api/payments/transaction-retrieval) (e.g. `?filters=id==trx_...`) for full transaction detail.\n"},"transactionType":{"type":"string","enum":["Sale","Refund","Capture","Return"],"description":"The kind of settled transaction.\n\n**Sale**: A sale that deposited funds to the merchant.\n\n**Refund**: A refund/credit returned to the cardholder or payer (reduces the net deposit).\n\n**Capture**: The capture/settlement of a previously authorized transaction.\n\n**Return**: A payout the provider tried to make and could not - for ACH, typically a closed or invalid bank account - so no money reached the merchant. The line exists because the attempt still cost a fee: nothing was disbursed, so for a net-funded rail `amount` is that fee as a negative, and for a gross-funded one it is zero and the fee is billed separately. Unlike a **Refund**, no money moved in the first place, so nothing is deducted from the deposit beyond that fee.\n"},"gatewayTransactionId":{"type":"string","description":"The gateway's own transaction ID."},"batchId":{"type":"string","description":"The processor's own batch number this transaction was settled in (informational). Present for card settlements; absent for providers with no native batch concept (e.g. ACH)."},"matchStatus":{"type":"string","enum":["Unmatched","Matched","ManuallyMatched"],"description":"Whether the settled transaction has been matched to a Fiska transaction.\n\n**Unmatched**: No Fiska transaction has been identified for this settled line; `transactionId` is absent.\n\n**Matched**: Automatically matched to a Fiska transaction.\n\n**ManuallyMatched**: Matched to a Fiska transaction by manual reconciliation.\n"},"invoiceNumber":{"type":"string","description":"Populated from the matched Fiska transaction, when one exists."},"paymentType":{"type":"string","description":"Populated from the matched Fiska transaction's card type, when one exists."},"transactionDate":{"type":"string","format":"date-time","description":"The date the underlying transaction was processed, when reported."},"amount":{"type":"integer","description":"The settled line amount in minor units. Signed: refunds are negative.\n\n**Card Net and Card Gross**: the full settled transaction amount before deposit-level fees and reserve adjustments. Card fees are not allocated to individual transaction lines, so `fundingType: Net` does not make a card line's amount net of those fees.\n\n**ACH Net**: the disbursed amount less any fees withheld from this line. A zero-disbursement `Return` can therefore have a negative amount equal to its fee. **ACH Gross**: the disbursed amount without subtracting separately billed fees; a zero-disbursement line remains zero.\n\nWithheld fees are also itemized by [GET /fee-charges](https://fiska.gitbook.io/omni-payment-api/settlement-reporting/fee-charges). Do not subtract them again from amounts that already include the deduction.\n"},"netAmount":{"type":"integer","deprecated":true,"description":"**Deprecated - read `amount` instead.** This member mirrors `amount` exactly. The enclosing settlement's `type` and `fundingType` explain the line amount: card lines retain their full settled amounts under both Card Net and Card Gross; ACH Net lines reflect any fees withheld from that line.\n\nDeprecated on 2026-08-21 and removed one month later in its own release, at which point `netAmount` also stops being accepted as a filter or sort field. Despite its name, it does not necessarily represent an amount after fees.\n"},"currency":{"type":"string","enum":["USD","CAD"]}},"required":["transactionType","gatewayTransactionId","matchStatus","amount","netAmount","currency"]}}}}
```

## The SettlementDetailResponse object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"SettlementDetailResponse":{"allOf":[{"$ref":"#/components/schemas/SettlementSummary"},{"type":"object","description":"Full detail of a single settlement, including its settled-transaction line items.","properties":{"merchantId":{"type":"string","description":"The ID of the merchant the settlement was deposited to, prefixed with `mer_`."},"lineItems":{"type":"array","items":{"$ref":"#/components/schemas/SettlementLineItem"}}},"required":["merchantId","lineItems"]}]},"SettlementSummary":{"type":"object","description":"A summary of a processor-reported transfer of payment proceeds to the merchant's bank account. It identifies the activity grouped into one deposit and reports its date, currency, total amount, rail, and funding type. See [Settlement](https://fiska.gitbook.io/omni-payment-api/glossary/settlement-and-fees#settlement) in the glossary.","properties":{"id":{"type":"string","description":"The settlement ID, prefixed with `stl_`."},"type":{"type":"string","enum":["Card","Ach"],"description":"The kind of settlement: `Card` for card payments or `Ach` for ACH bank transfers.\n\nRead this field together with `fundingType`. Card Net is `type: Card` with `fundingType: Net`; Card Gross is `type: Card` with `fundingType: Gross`. These are combinations of existing fields, not additional `type` values. ACH also supports both funding types.\n"},"settlementDate":{"type":"string","format":"date","description":"The date the settlement was deposited to the merchant's bank account."},"currency":{"type":"string","enum":["USD","CAD"]},"amount":{"type":"integer","description":"The processor-reported deposit total in minor units. Signed: refunds, fees, and adjustments can produce a negative deposit.\n\nFor Card Net, the deposit includes deductions for withheld interchange and discount fees. For Card Gross, those fees are billed separately. Reserve holds and transfers can change the deposited amount in either card funding model. Card transaction lines retain their full settled amounts before these deposit-level deductions.\n\nFor ACH, `fundingType` states whether fees are withheld from the deposit or billed separately.\n"},"fundingType":{"type":"string","enum":["Net","Gross"],"description":"Whether the payment provider withholds its fees from deposits or bills them separately. Read together with `type`; card and ACH funding terms can differ for the same merchant.\n\n**Net**: the deposit is after withheld fees. For Card Net, interchange and discount fees apply at the deposit level; the individual card lines remain before those deductions.\n\n**Gross**: fees are billed separately and do not reduce this deposit. For Card Gross, reserve holds and transfers can still change `amount`, so it need not equal the sum of card transaction amounts.\n\nFunding type does not determine the fee billing schedule. Use each [fee charge](https://fiska.gitbook.io/omni-payment-api/settlement-reporting/fee-charges)'s `source` and `chargeDate`; monthly billing produces `StatementOnly` charges. An `amount` is always returned with a `fundingType` in scope.\n"},"netAmount":{"type":"integer","deprecated":true,"description":"**Deprecated - read `amount` instead.** This member mirrors `amount` exactly and cannot hold a different figure. `fundingType` on this payload states whether that figure is the gross deposit or one already net of withheld fees, and is the only authoritative reading of it. Deprecated on 2026-08-21 and removed one month later in its own release, at which point `netAmount` also stops being accepted as a filter or sort field.\n\nIts value changed when `amount` was introduced: for a gross-funded merchant it now reports the gross deposit - the figure that actually reached the bank - so despite its name it is not necessarily a net figure.\n"},"transactionCount":{"type":"integer","description":"Number of settled-transaction line items in the settlement. Always equal to the length of the `lineItems` array returned by [`GET /settlements/{settlementId}`](https://fiska.gitbook.io/omni-payment-api/settlement-reporting/settlements), which withholds no line.\n"},"status":{"type":"string","enum":["Settled","Adjusted"],"description":"Status of the settlement.\n\n**Settled**: The settlement has been deposited to the merchant's bank account.\n\n**Adjusted**: Reserved value; not currently returned.\n"}},"required":["id","type","settlementDate","currency","amount","fundingType","netAmount","transactionCount","status"]},"SettlementLineItem":{"type":"object","description":"A processor-reported line showing how one sale, capture, refund, or failed payout contributes to a merchant deposit. It records the activity's amount and processor identifiers, plus the Fiska transaction ID when matched. See [Settled transaction](https://fiska.gitbook.io/omni-payment-api/glossary/settlement-and-fees#settled-transaction) in the glossary.","properties":{"transactionId":{"type":"string","description":"The transaction ID, prefixed with `trx_`. Absent when `matchStatus` is `Unmatched` - look it up via [`GET /transactions`](https://fiska.gitbook.io/omni-payment-api/payments/transaction-retrieval) (e.g. `?filters=id==trx_...`) for full transaction detail.\n"},"transactionType":{"type":"string","enum":["Sale","Refund","Capture","Return"],"description":"The kind of settled transaction.\n\n**Sale**: A sale that deposited funds to the merchant.\n\n**Refund**: A refund/credit returned to the cardholder or payer (reduces the net deposit).\n\n**Capture**: The capture/settlement of a previously authorized transaction.\n\n**Return**: A payout the provider tried to make and could not - for ACH, typically a closed or invalid bank account - so no money reached the merchant. The line exists because the attempt still cost a fee: nothing was disbursed, so for a net-funded rail `amount` is that fee as a negative, and for a gross-funded one it is zero and the fee is billed separately. Unlike a **Refund**, no money moved in the first place, so nothing is deducted from the deposit beyond that fee.\n"},"gatewayTransactionId":{"type":"string","description":"The gateway's own transaction ID."},"batchId":{"type":"string","description":"The processor's own batch number this transaction was settled in (informational). Present for card settlements; absent for providers with no native batch concept (e.g. ACH)."},"matchStatus":{"type":"string","enum":["Unmatched","Matched","ManuallyMatched"],"description":"Whether the settled transaction has been matched to a Fiska transaction.\n\n**Unmatched**: No Fiska transaction has been identified for this settled line; `transactionId` is absent.\n\n**Matched**: Automatically matched to a Fiska transaction.\n\n**ManuallyMatched**: Matched to a Fiska transaction by manual reconciliation.\n"},"invoiceNumber":{"type":"string","description":"Populated from the matched Fiska transaction, when one exists."},"paymentType":{"type":"string","description":"Populated from the matched Fiska transaction's card type, when one exists."},"transactionDate":{"type":"string","format":"date-time","description":"The date the underlying transaction was processed, when reported."},"amount":{"type":"integer","description":"The settled line amount in minor units. Signed: refunds are negative.\n\n**Card Net and Card Gross**: the full settled transaction amount before deposit-level fees and reserve adjustments. Card fees are not allocated to individual transaction lines, so `fundingType: Net` does not make a card line's amount net of those fees.\n\n**ACH Net**: the disbursed amount less any fees withheld from this line. A zero-disbursement `Return` can therefore have a negative amount equal to its fee. **ACH Gross**: the disbursed amount without subtracting separately billed fees; a zero-disbursement line remains zero.\n\nWithheld fees are also itemized by [GET /fee-charges](https://fiska.gitbook.io/omni-payment-api/settlement-reporting/fee-charges). Do not subtract them again from amounts that already include the deduction.\n"},"netAmount":{"type":"integer","deprecated":true,"description":"**Deprecated - read `amount` instead.** This member mirrors `amount` exactly. The enclosing settlement's `type` and `fundingType` explain the line amount: card lines retain their full settled amounts under both Card Net and Card Gross; ACH Net lines reflect any fees withheld from that line.\n\nDeprecated on 2026-08-21 and removed one month later in its own release, at which point `netAmount` also stops being accepted as a filter or sort field. Despite its name, it does not necessarily represent an amount after fees.\n"},"currency":{"type":"string","enum":["USD","CAD"]}},"required":["transactionType","gatewayTransactionId","matchStatus","amount","netAmount","currency"]}}}}
```

## The SettlementsListResponse object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"SettlementsListResponse":{"type":"object","description":"Paginated response containing settlements","properties":{"totalCount":{"type":"integer","description":"Total number of settlements that match the filter criteria"},"page":{"type":"integer","description":"The current page number (starts at 1)"},"pageSize":{"type":"integer","description":"Number of items per page"},"totalPages":{"type":"integer","description":"Total number of pages available"},"hasNextPage":{"type":"boolean","description":"True if there are more pages of results available"},"hasPreviousPage":{"type":"boolean","description":"True if there are previous pages of results available"},"items":{"type":"array","description":"Array of settlements for the current page","items":{"$ref":"#/components/schemas/SettlementSummary"}}},"required":["totalCount","page","pageSize","totalPages","hasNextPage","hasPreviousPage","items"]},"SettlementSummary":{"type":"object","description":"A summary of a processor-reported transfer of payment proceeds to the merchant's bank account. It identifies the activity grouped into one deposit and reports its date, currency, total amount, rail, and funding type. See [Settlement](https://fiska.gitbook.io/omni-payment-api/glossary/settlement-and-fees#settlement) in the glossary.","properties":{"id":{"type":"string","description":"The settlement ID, prefixed with `stl_`."},"type":{"type":"string","enum":["Card","Ach"],"description":"The kind of settlement: `Card` for card payments or `Ach` for ACH bank transfers.\n\nRead this field together with `fundingType`. Card Net is `type: Card` with `fundingType: Net`; Card Gross is `type: Card` with `fundingType: Gross`. These are combinations of existing fields, not additional `type` values. ACH also supports both funding types.\n"},"settlementDate":{"type":"string","format":"date","description":"The date the settlement was deposited to the merchant's bank account."},"currency":{"type":"string","enum":["USD","CAD"]},"amount":{"type":"integer","description":"The processor-reported deposit total in minor units. Signed: refunds, fees, and adjustments can produce a negative deposit.\n\nFor Card Net, the deposit includes deductions for withheld interchange and discount fees. For Card Gross, those fees are billed separately. Reserve holds and transfers can change the deposited amount in either card funding model. Card transaction lines retain their full settled amounts before these deposit-level deductions.\n\nFor ACH, `fundingType` states whether fees are withheld from the deposit or billed separately.\n"},"fundingType":{"type":"string","enum":["Net","Gross"],"description":"Whether the payment provider withholds its fees from deposits or bills them separately. Read together with `type`; card and ACH funding terms can differ for the same merchant.\n\n**Net**: the deposit is after withheld fees. For Card Net, interchange and discount fees apply at the deposit level; the individual card lines remain before those deductions.\n\n**Gross**: fees are billed separately and do not reduce this deposit. For Card Gross, reserve holds and transfers can still change `amount`, so it need not equal the sum of card transaction amounts.\n\nFunding type does not determine the fee billing schedule. Use each [fee charge](https://fiska.gitbook.io/omni-payment-api/settlement-reporting/fee-charges)'s `source` and `chargeDate`; monthly billing produces `StatementOnly` charges. An `amount` is always returned with a `fundingType` in scope.\n"},"netAmount":{"type":"integer","deprecated":true,"description":"**Deprecated - read `amount` instead.** This member mirrors `amount` exactly and cannot hold a different figure. `fundingType` on this payload states whether that figure is the gross deposit or one already net of withheld fees, and is the only authoritative reading of it. Deprecated on 2026-08-21 and removed one month later in its own release, at which point `netAmount` also stops being accepted as a filter or sort field.\n\nIts value changed when `amount` was introduced: for a gross-funded merchant it now reports the gross deposit - the figure that actually reached the bank - so despite its name it is not necessarily a net figure.\n"},"transactionCount":{"type":"integer","description":"Number of settled-transaction line items in the settlement. Always equal to the length of the `lineItems` array returned by [`GET /settlements/{settlementId}`](https://fiska.gitbook.io/omni-payment-api/settlement-reporting/settlements), which withholds no line.\n"},"status":{"type":"string","enum":["Settled","Adjusted"],"description":"Status of the settlement.\n\n**Settled**: The settlement has been deposited to the merchant's bank account.\n\n**Adjusted**: Reserved value; not currently returned.\n"}},"required":["id","type","settlementDate","currency","amount","fundingType","netAmount","transactionCount","status"]}}}}
```

## The SettlementTransaction object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"SettlementTransaction":{"type":"object","description":"A processor-reported line showing how one sale, capture, refund, or failed payout contributes to a merchant deposit. This list representation includes the parent settlement's summary so the line can be interpreted with its deposit, rail, and funding type. See [Settled transaction](https://fiska.gitbook.io/omni-payment-api/glossary/settlement-and-fees#settled-transaction) in the glossary.\n","properties":{"settlement":{"$ref":"#/components/schemas/SettlementSummary"},"transactionId":{"type":"string","description":"The Fiska transaction ID, prefixed with `trx_`. Absent when `matchStatus` is `Unmatched` - look it up via [`GET /transactions`](https://fiska.gitbook.io/omni-payment-api/payments/transaction-retrieval) (e.g. `?filters=id==trx_...`) for full transaction detail.\n"},"transactionType":{"type":"string","enum":["Sale","Refund","Capture","Return"],"description":"The kind of settled transaction.\n\n**Sale**: A sale that deposited funds to the merchant.\n\n**Refund**: A refund/credit returned to the cardholder or payer (reduces the net deposit).\n\n**Capture**: The capture/settlement of a previously authorized transaction.\n\n**Return**: A payout the provider tried to make and could not - for ACH, typically a closed or invalid bank account - so no money reached the merchant. The line exists because the attempt still cost a fee: nothing was disbursed, so for a net-funded rail `amount` is that fee as a negative, and for a gross-funded one it is zero and the fee is billed separately. Unlike a **Refund**, no money moved in the first place, so nothing is deducted from the deposit beyond that fee.\n"},"gatewayTransactionId":{"type":"string","description":"The gateway's own transaction ID."},"batchId":{"type":"string","description":"The processor's own batch number this transaction was settled in (informational). Present for card settlements; absent for providers with no native batch concept (e.g. ACH)."},"matchStatus":{"type":"string","enum":["Unmatched","Matched","ManuallyMatched"],"description":"Whether the settled transaction has been matched to a Fiska transaction.\n\n**Unmatched**: No Fiska transaction has been identified for this settled line; `transactionId` is absent.\n\n**Matched**: Automatically matched to a Fiska transaction.\n\n**ManuallyMatched**: Matched to a Fiska transaction by manual reconciliation.\n"},"invoiceNumber":{"type":"string","description":"Populated from the matched Fiska transaction, when one exists."},"paymentType":{"type":"string","description":"Populated from the matched Fiska transaction's card type, when one exists."},"settlementDate":{"type":"string","format":"date","description":"The date the transaction was settled - the parent settlement's deposit date."},"transactionDate":{"type":"string","format":"date-time","description":"The date the underlying transaction was processed, when reported."},"amount":{"type":"integer","description":"The settled line amount in minor units. Signed: refunds are negative.\n\n**Card Net and Card Gross**: the full settled transaction amount before deposit-level fees and reserve adjustments. Card fees are not allocated to individual transaction lines, so `fundingType: Net` does not make a card line's amount net of those fees.\n\n**ACH Net**: the disbursed amount less any fees withheld from this line. A zero-disbursement `Return` can therefore have a negative amount equal to its fee. **ACH Gross**: the disbursed amount without subtracting separately billed fees; a zero-disbursement line remains zero.\n\nWithheld fees are also itemized by [GET /fee-charges](https://fiska.gitbook.io/omni-payment-api/settlement-reporting/fee-charges). Do not subtract them again from amounts that already include the deduction.\n"},"fundingType":{"type":"string","enum":["Net","Gross"],"description":"The parent settlement's funding type, repeated on this line. Read with `settlement.type`.\n\nFor Card Net and Card Gross, this field describes deposit-level fee withholding; the line's `amount` remains the full settled transaction amount. For ACH Net, line-level fees are withheld where applicable; for ACH Gross, they are billed separately. Funding type alone does not determine fee billing dates.\n"},"netAmount":{"type":"integer","deprecated":true,"description":"**Deprecated - read `amount` instead.** This member mirrors `amount` exactly. The enclosing settlement's `type` and `fundingType` explain the line amount: card lines retain their full settled amounts under both Card Net and Card Gross; ACH Net lines reflect any fees withheld from that line.\n\nDeprecated on 2026-08-21 and removed one month later in its own release, at which point `netAmount` also stops being accepted as a filter or sort field. Despite its name, it does not necessarily represent an amount after fees.\n"},"currency":{"type":"string","enum":["USD","CAD"]}},"required":["settlement","transactionType","gatewayTransactionId","matchStatus","settlementDate","amount","fundingType","netAmount","currency"]},"SettlementSummary":{"type":"object","description":"A summary of a processor-reported transfer of payment proceeds to the merchant's bank account. It identifies the activity grouped into one deposit and reports its date, currency, total amount, rail, and funding type. See [Settlement](https://fiska.gitbook.io/omni-payment-api/glossary/settlement-and-fees#settlement) in the glossary.","properties":{"id":{"type":"string","description":"The settlement ID, prefixed with `stl_`."},"type":{"type":"string","enum":["Card","Ach"],"description":"The kind of settlement: `Card` for card payments or `Ach` for ACH bank transfers.\n\nRead this field together with `fundingType`. Card Net is `type: Card` with `fundingType: Net`; Card Gross is `type: Card` with `fundingType: Gross`. These are combinations of existing fields, not additional `type` values. ACH also supports both funding types.\n"},"settlementDate":{"type":"string","format":"date","description":"The date the settlement was deposited to the merchant's bank account."},"currency":{"type":"string","enum":["USD","CAD"]},"amount":{"type":"integer","description":"The processor-reported deposit total in minor units. Signed: refunds, fees, and adjustments can produce a negative deposit.\n\nFor Card Net, the deposit includes deductions for withheld interchange and discount fees. For Card Gross, those fees are billed separately. Reserve holds and transfers can change the deposited amount in either card funding model. Card transaction lines retain their full settled amounts before these deposit-level deductions.\n\nFor ACH, `fundingType` states whether fees are withheld from the deposit or billed separately.\n"},"fundingType":{"type":"string","enum":["Net","Gross"],"description":"Whether the payment provider withholds its fees from deposits or bills them separately. Read together with `type`; card and ACH funding terms can differ for the same merchant.\n\n**Net**: the deposit is after withheld fees. For Card Net, interchange and discount fees apply at the deposit level; the individual card lines remain before those deductions.\n\n**Gross**: fees are billed separately and do not reduce this deposit. For Card Gross, reserve holds and transfers can still change `amount`, so it need not equal the sum of card transaction amounts.\n\nFunding type does not determine the fee billing schedule. Use each [fee charge](https://fiska.gitbook.io/omni-payment-api/settlement-reporting/fee-charges)'s `source` and `chargeDate`; monthly billing produces `StatementOnly` charges. An `amount` is always returned with a `fundingType` in scope.\n"},"netAmount":{"type":"integer","deprecated":true,"description":"**Deprecated - read `amount` instead.** This member mirrors `amount` exactly and cannot hold a different figure. `fundingType` on this payload states whether that figure is the gross deposit or one already net of withheld fees, and is the only authoritative reading of it. Deprecated on 2026-08-21 and removed one month later in its own release, at which point `netAmount` also stops being accepted as a filter or sort field.\n\nIts value changed when `amount` was introduced: for a gross-funded merchant it now reports the gross deposit - the figure that actually reached the bank - so despite its name it is not necessarily a net figure.\n"},"transactionCount":{"type":"integer","description":"Number of settled-transaction line items in the settlement. Always equal to the length of the `lineItems` array returned by [`GET /settlements/{settlementId}`](https://fiska.gitbook.io/omni-payment-api/settlement-reporting/settlements), which withholds no line.\n"},"status":{"type":"string","enum":["Settled","Adjusted"],"description":"Status of the settlement.\n\n**Settled**: The settlement has been deposited to the merchant's bank account.\n\n**Adjusted**: Reserved value; not currently returned.\n"}},"required":["id","type","settlementDate","currency","amount","fundingType","netAmount","transactionCount","status"]}}}}
```

## The SettledTransactionsListResponse object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"SettledTransactionsListResponse":{"type":"object","description":"Paginated response containing settled transactions","properties":{"totalCount":{"type":"integer","description":"Total number of settled transactions that match the filter criteria"},"page":{"type":"integer","description":"The current page number (starts at 1)"},"pageSize":{"type":"integer","description":"Number of items per page"},"totalPages":{"type":"integer","description":"Total number of pages available"},"hasNextPage":{"type":"boolean","description":"True if there are more pages of results available"},"hasPreviousPage":{"type":"boolean","description":"True if there are previous pages of results available"},"items":{"type":"array","description":"Array of settled transactions for the current page","items":{"$ref":"#/components/schemas/SettlementTransaction"}}},"required":["totalCount","page","pageSize","totalPages","hasNextPage","hasPreviousPage","items"]},"SettlementTransaction":{"type":"object","description":"A processor-reported line showing how one sale, capture, refund, or failed payout contributes to a merchant deposit. This list representation includes the parent settlement's summary so the line can be interpreted with its deposit, rail, and funding type. See [Settled transaction](https://fiska.gitbook.io/omni-payment-api/glossary/settlement-and-fees#settled-transaction) in the glossary.\n","properties":{"settlement":{"$ref":"#/components/schemas/SettlementSummary"},"transactionId":{"type":"string","description":"The Fiska transaction ID, prefixed with `trx_`. Absent when `matchStatus` is `Unmatched` - look it up via [`GET /transactions`](https://fiska.gitbook.io/omni-payment-api/payments/transaction-retrieval) (e.g. `?filters=id==trx_...`) for full transaction detail.\n"},"transactionType":{"type":"string","enum":["Sale","Refund","Capture","Return"],"description":"The kind of settled transaction.\n\n**Sale**: A sale that deposited funds to the merchant.\n\n**Refund**: A refund/credit returned to the cardholder or payer (reduces the net deposit).\n\n**Capture**: The capture/settlement of a previously authorized transaction.\n\n**Return**: A payout the provider tried to make and could not - for ACH, typically a closed or invalid bank account - so no money reached the merchant. The line exists because the attempt still cost a fee: nothing was disbursed, so for a net-funded rail `amount` is that fee as a negative, and for a gross-funded one it is zero and the fee is billed separately. Unlike a **Refund**, no money moved in the first place, so nothing is deducted from the deposit beyond that fee.\n"},"gatewayTransactionId":{"type":"string","description":"The gateway's own transaction ID."},"batchId":{"type":"string","description":"The processor's own batch number this transaction was settled in (informational). Present for card settlements; absent for providers with no native batch concept (e.g. ACH)."},"matchStatus":{"type":"string","enum":["Unmatched","Matched","ManuallyMatched"],"description":"Whether the settled transaction has been matched to a Fiska transaction.\n\n**Unmatched**: No Fiska transaction has been identified for this settled line; `transactionId` is absent.\n\n**Matched**: Automatically matched to a Fiska transaction.\n\n**ManuallyMatched**: Matched to a Fiska transaction by manual reconciliation.\n"},"invoiceNumber":{"type":"string","description":"Populated from the matched Fiska transaction, when one exists."},"paymentType":{"type":"string","description":"Populated from the matched Fiska transaction's card type, when one exists."},"settlementDate":{"type":"string","format":"date","description":"The date the transaction was settled - the parent settlement's deposit date."},"transactionDate":{"type":"string","format":"date-time","description":"The date the underlying transaction was processed, when reported."},"amount":{"type":"integer","description":"The settled line amount in minor units. Signed: refunds are negative.\n\n**Card Net and Card Gross**: the full settled transaction amount before deposit-level fees and reserve adjustments. Card fees are not allocated to individual transaction lines, so `fundingType: Net` does not make a card line's amount net of those fees.\n\n**ACH Net**: the disbursed amount less any fees withheld from this line. A zero-disbursement `Return` can therefore have a negative amount equal to its fee. **ACH Gross**: the disbursed amount without subtracting separately billed fees; a zero-disbursement line remains zero.\n\nWithheld fees are also itemized by [GET /fee-charges](https://fiska.gitbook.io/omni-payment-api/settlement-reporting/fee-charges). Do not subtract them again from amounts that already include the deduction.\n"},"fundingType":{"type":"string","enum":["Net","Gross"],"description":"The parent settlement's funding type, repeated on this line. Read with `settlement.type`.\n\nFor Card Net and Card Gross, this field describes deposit-level fee withholding; the line's `amount` remains the full settled transaction amount. For ACH Net, line-level fees are withheld where applicable; for ACH Gross, they are billed separately. Funding type alone does not determine fee billing dates.\n"},"netAmount":{"type":"integer","deprecated":true,"description":"**Deprecated - read `amount` instead.** This member mirrors `amount` exactly. The enclosing settlement's `type` and `fundingType` explain the line amount: card lines retain their full settled amounts under both Card Net and Card Gross; ACH Net lines reflect any fees withheld from that line.\n\nDeprecated on 2026-08-21 and removed one month later in its own release, at which point `netAmount` also stops being accepted as a filter or sort field. Despite its name, it does not necessarily represent an amount after fees.\n"},"currency":{"type":"string","enum":["USD","CAD"]}},"required":["settlement","transactionType","gatewayTransactionId","matchStatus","settlementDate","amount","fundingType","netAmount","currency"]},"SettlementSummary":{"type":"object","description":"A summary of a processor-reported transfer of payment proceeds to the merchant's bank account. It identifies the activity grouped into one deposit and reports its date, currency, total amount, rail, and funding type. See [Settlement](https://fiska.gitbook.io/omni-payment-api/glossary/settlement-and-fees#settlement) in the glossary.","properties":{"id":{"type":"string","description":"The settlement ID, prefixed with `stl_`."},"type":{"type":"string","enum":["Card","Ach"],"description":"The kind of settlement: `Card` for card payments or `Ach` for ACH bank transfers.\n\nRead this field together with `fundingType`. Card Net is `type: Card` with `fundingType: Net`; Card Gross is `type: Card` with `fundingType: Gross`. These are combinations of existing fields, not additional `type` values. ACH also supports both funding types.\n"},"settlementDate":{"type":"string","format":"date","description":"The date the settlement was deposited to the merchant's bank account."},"currency":{"type":"string","enum":["USD","CAD"]},"amount":{"type":"integer","description":"The processor-reported deposit total in minor units. Signed: refunds, fees, and adjustments can produce a negative deposit.\n\nFor Card Net, the deposit includes deductions for withheld interchange and discount fees. For Card Gross, those fees are billed separately. Reserve holds and transfers can change the deposited amount in either card funding model. Card transaction lines retain their full settled amounts before these deposit-level deductions.\n\nFor ACH, `fundingType` states whether fees are withheld from the deposit or billed separately.\n"},"fundingType":{"type":"string","enum":["Net","Gross"],"description":"Whether the payment provider withholds its fees from deposits or bills them separately. Read together with `type`; card and ACH funding terms can differ for the same merchant.\n\n**Net**: the deposit is after withheld fees. For Card Net, interchange and discount fees apply at the deposit level; the individual card lines remain before those deductions.\n\n**Gross**: fees are billed separately and do not reduce this deposit. For Card Gross, reserve holds and transfers can still change `amount`, so it need not equal the sum of card transaction amounts.\n\nFunding type does not determine the fee billing schedule. Use each [fee charge](https://fiska.gitbook.io/omni-payment-api/settlement-reporting/fee-charges)'s `source` and `chargeDate`; monthly billing produces `StatementOnly` charges. An `amount` is always returned with a `fundingType` in scope.\n"},"netAmount":{"type":"integer","deprecated":true,"description":"**Deprecated - read `amount` instead.** This member mirrors `amount` exactly and cannot hold a different figure. `fundingType` on this payload states whether that figure is the gross deposit or one already net of withheld fees, and is the only authoritative reading of it. Deprecated on 2026-08-21 and removed one month later in its own release, at which point `netAmount` also stops being accepted as a filter or sort field.\n\nIts value changed when `amount` was introduced: for a gross-funded merchant it now reports the gross deposit - the figure that actually reached the bank - so despite its name it is not necessarily a net figure.\n"},"transactionCount":{"type":"integer","description":"Number of settled-transaction line items in the settlement. Always equal to the length of the `lineItems` array returned by [`GET /settlements/{settlementId}`](https://fiska.gitbook.io/omni-payment-api/settlement-reporting/settlements), which withholds no line.\n"},"status":{"type":"string","enum":["Settled","Adjusted"],"description":"Status of the settlement.\n\n**Settled**: The settlement has been deposited to the merchant's bank account.\n\n**Adjusted**: Reserved value; not currently returned.\n"}},"required":["id","type","settlementDate","currency","amount","fundingType","netAmount","transactionCount","status"]}}}}
```

## The SettledTransactionReference object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"SettledTransactionReference":{"type":"object","description":"The settled transaction a per-transaction fee applies to, mirroring that transaction's identity. Present only on per-transaction fees. Combine `gatewayTransactionId` with the fee's `settlementId` to locate the settled line via `GET /settlements/{settlementId}`.\n","properties":{"transactionId":{"type":"string","description":"The Fiska transaction ID (`trx_`) of the settled transaction, when that line is matched to a Fiska transaction. Absent when `matchStatus` is `Unmatched`."},"gatewayTransactionId":{"type":"string","description":"The gateway's own transaction ID of the settled transaction. Always present."},"matchStatus":{"type":"string","enum":["Unmatched","Matched","ManuallyMatched"],"description":"The match status of the settled transaction - the same `matchStatus` reported on that settled transaction.\n\n**Unmatched**: The settled transaction has no identified Fiska transaction; `transactionId` is absent.\n\n**Matched**: Automatically matched to a Fiska transaction.\n\n**ManuallyMatched**: Matched to a Fiska transaction by manual reconciliation.\n"}},"required":["gatewayTransactionId","matchStatus"]}}}}
```

## The FeeCharge object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"FeeCharge":{"type":"object","description":"A record of an individual cost billed to a merchant for payment processing or related account services. It states the amount, currency, category, charge date, and description of that cost, whether collected from a deposit or billed separately. Examples include transaction processing, daily discount, monthly service, equipment, and one-time setup fees. See [Fee charge](https://fiska.gitbook.io/omni-payment-api/glossary/settlement-and-fees#fee-charge) in the glossary.\n\nA fee associated with a settlement identifies the related deposit through `settlementId`.\n\nPer-transaction fees also carry a `settledTransaction` object mirroring the settled line it applies to (its `gatewayTransactionId`, `matchStatus`, and `transactionId` when matched).\n","properties":{"id":{"type":"string","description":"The fee charge ID, prefixed with `mfc_`."},"category":{"type":"string","description":"What kind of fee this is. An **open set of strings, not a closed enum**. A fee can use a specific fee name or one of the general categories below. New values can be added without an API version change. Treat a value you do not recognise exactly as you treat `Other`: read `description`, which carries the wording the provider printed. Do not fail on an unknown value.\n\n**General fee categories:**\n\n- `MonthlyService` - fees for maintaining the merchant account and related payment services, such as statements, reporting, and gateway services.\n- `PciCompliance` - fees related to Payment Card Industry (PCI) compliance, including compliance services and non-compliance assessments.\n- `OneTimeSetup` - one-time fees for setting up a service, such as an account, gateway, or wireless connection.\n- `NetworkAssessment` - card-network charges passed through to the merchant, such as registration or network participation fees.\n- `Equipment` - fees for payment terminals and related hardware, including charges for equipment that was not returned.\n- `Other` - fees with no more specific classification. Read `description` for the reported fee wording.\n\n**Transaction and settlement fees** (`source` is `SettlementLinked` under daily billing, or `StatementOnly` under monthly billing):\n\n- `DailyDiscountFee` - the daily discount fee assessed against a card settlement.\n- `DailyInterchangeFee` - the daily interchange fee assessed against a card settlement.\n- `TransactionFee` - a per-transaction settlement fee, e.g. an ACH transaction's processing fee.\n- `ReturnFee` - charged when a payout could not be completed; for ACH, typically a closed or invalid bank account, so no money reached the merchant and this fee is the only thing the attempt produced. Its settled line has a `transactionType` of `Return`.\n- `PerSettlementFee` - a flat fee a merchant's pricing applies once to a settlement, independent of what settled in it. Assessed against the deposit rather than any one line, so it carries a `settlementId` and no `settledTransaction`.\n\n**Fees billed on a monthly statement or invoice** (`source` is `StatementOnly`). Representative examples by general category:\n\n- `MonthlyService`: `GatewayService`, `StatementFee`, `WebReportsAlerts`.\n- `PciCompliance`: `PciFee`, `NonComplianceAssessment`, `SaqScanIncomplete`.\n- `OneTimeSetup`: `ApplicationFee`, `GatewaySetup`, `WirelessActivation`.\n- `NetworkAssessment`: `VisaRegistrationFee`, `McRegistrationFee`, `PinBasedDebitNetworkFee`.\n- `Equipment`: `UnreturnedEquipment`.\n- `Other`: an unclassified fee or unrecognized statement wording; read `description`.\n\nA named fee uses its specific value in `category`, such as `GatewayService`, rather than the group name `MonthlyService`. The examples are not an exhaustive list. See [Fee examples by category](https://fiska.gitbook.io/omni-payment-api/settlement-reporting/fee-charges#fees-billed-on-a-monthly-statement-or-invoice) and use each charge's `description` for its reported wording.\n\n**Derived:**\n\n- `InterchangeAndPassthrough` - interchange and other costs a card statement passes through without naming them individually. Its amount is the statement's total deducted fees minus the sum of named fees. It has `source: StatementOnly`.\n"},"source":{"type":"string","enum":["SettlementLinked","StatementOnly"],"description":"How the fee is reported and billed. Funding type controls whether fees reduce the deposit; the billing schedule separately determines `source` and `chargeDate`.\n\n**SettlementLinked**: a fee associated with a transaction or settlement, charged on its assessment date under daily billing.\n\n**StatementOnly**: a fee billed on a monthly statement or invoice, including transaction and settlement fees scheduled for monthly billing. For fees assessed daily but billed monthly, `chargeDate` is the first of the following month and the assessment date appears in `periodStart` and `periodEnd`. A `StatementOnly` fee can carry a `settlementId`.\n\nCard Net and Card Gross can both have separately reported fee charges. For Card Net, do not deduct a withheld fee from the deposit amount again. For Card Gross, reconcile the separately billed fee using its charge date.\n"},"status":{"type":"string","enum":["Posted","Held","Reversed"],"description":"Whether the entry was charged to the merchant. This endpoint returns only `Posted` fees. Held and reversed entries are excluded, as are reserve movements that do not represent a fee.\n"},"currency":{"type":"string","enum":["USD","CAD"]},"amount":{"type":"integer","minimum":0,"description":"The fee amount, smallest denomination."},"chargeDate":{"type":"string","format":"date","description":"The date the fee is charged. For transaction and settlement fees assessed daily, this is the settlement date under daily billing or the first of the following month under monthly billing."},"periodStart":{"type":"string","format":"date","description":"Start of the period the fee covers, for recurring fees."},"periodEnd":{"type":"string","format":"date","description":"End of the period the fee covers, for recurring fees."},"description":{"type":"string","description":"Human-readable description of the fee."},"settlementId":{"type":"string","description":"The related deposit ID, prefixed with stl_, when linked. Can be present for both SettlementLinked and StatementOnly fees; this link alone does not mean the fee was withheld from the deposit."},"settledTransaction":{"$ref":"#/components/schemas/SettledTransactionReference"},"feeBreakdown":{"$ref":"#/components/schemas/SettlementFeeBreakdown"}},"required":["id","category","currency","amount","chargeDate"]},"SettledTransactionReference":{"type":"object","description":"The settled transaction a per-transaction fee applies to, mirroring that transaction's identity. Present only on per-transaction fees. Combine `gatewayTransactionId` with the fee's `settlementId` to locate the settled line via `GET /settlements/{settlementId}`.\n","properties":{"transactionId":{"type":"string","description":"The Fiska transaction ID (`trx_`) of the settled transaction, when that line is matched to a Fiska transaction. Absent when `matchStatus` is `Unmatched`."},"gatewayTransactionId":{"type":"string","description":"The gateway's own transaction ID of the settled transaction. Always present."},"matchStatus":{"type":"string","enum":["Unmatched","Matched","ManuallyMatched"],"description":"The match status of the settled transaction - the same `matchStatus` reported on that settled transaction.\n\n**Unmatched**: The settled transaction has no identified Fiska transaction; `transactionId` is absent.\n\n**Matched**: Automatically matched to a Fiska transaction.\n\n**ManuallyMatched**: Matched to a Fiska transaction by manual reconciliation.\n"}},"required":["gatewayTransactionId","matchStatus"]},"SettlementFeeBreakdown":{"type":"object","description":"Optional breakdown of the components of a fee charge. Only the components that apply to a given fee are present.\n Components are signed integers in minor units; positive values are charges and negative values are credits.\n","properties":{"discountFee":{"type":"integer","description":"Processing/discount fee component, smallest denomination."},"originationFee":{"type":"integer","description":"ACH origination fee, smallest denomination."},"returnFee":{"type":"integer","description":"ACH return fee - charged when a transaction is returned/reversed post-settlement. Smallest denomination."},"interchangeFee":{"type":"integer","description":"Card-network interchange fee, in minor units."},"otherFee":{"type":"integer","description":"Provider-specific catch-all for fee components not otherwise modeled."}}}}}}
```

## The FeeChargesListResponse object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"FeeChargesListResponse":{"type":"object","description":"Paginated response containing merchant fee charges","properties":{"totalCount":{"type":"integer","description":"Total number of fee charges that match the filter criteria"},"page":{"type":"integer","description":"The current page number (starts at 1)"},"pageSize":{"type":"integer","description":"Number of items per page"},"totalPages":{"type":"integer","description":"Total number of pages available"},"hasNextPage":{"type":"boolean","description":"True if there are more pages of results available"},"hasPreviousPage":{"type":"boolean","description":"True if there are previous pages of results available"},"items":{"type":"array","description":"Array of fee charges for the current page","items":{"$ref":"#/components/schemas/FeeCharge"}}},"required":["totalCount","page","pageSize","totalPages","hasNextPage","hasPreviousPage","items"]},"FeeCharge":{"type":"object","description":"A record of an individual cost billed to a merchant for payment processing or related account services. It states the amount, currency, category, charge date, and description of that cost, whether collected from a deposit or billed separately. Examples include transaction processing, daily discount, monthly service, equipment, and one-time setup fees. See [Fee charge](https://fiska.gitbook.io/omni-payment-api/glossary/settlement-and-fees#fee-charge) in the glossary.\n\nA fee associated with a settlement identifies the related deposit through `settlementId`.\n\nPer-transaction fees also carry a `settledTransaction` object mirroring the settled line it applies to (its `gatewayTransactionId`, `matchStatus`, and `transactionId` when matched).\n","properties":{"id":{"type":"string","description":"The fee charge ID, prefixed with `mfc_`."},"category":{"type":"string","description":"What kind of fee this is. An **open set of strings, not a closed enum**. A fee can use a specific fee name or one of the general categories below. New values can be added without an API version change. Treat a value you do not recognise exactly as you treat `Other`: read `description`, which carries the wording the provider printed. Do not fail on an unknown value.\n\n**General fee categories:**\n\n- `MonthlyService` - fees for maintaining the merchant account and related payment services, such as statements, reporting, and gateway services.\n- `PciCompliance` - fees related to Payment Card Industry (PCI) compliance, including compliance services and non-compliance assessments.\n- `OneTimeSetup` - one-time fees for setting up a service, such as an account, gateway, or wireless connection.\n- `NetworkAssessment` - card-network charges passed through to the merchant, such as registration or network participation fees.\n- `Equipment` - fees for payment terminals and related hardware, including charges for equipment that was not returned.\n- `Other` - fees with no more specific classification. Read `description` for the reported fee wording.\n\n**Transaction and settlement fees** (`source` is `SettlementLinked` under daily billing, or `StatementOnly` under monthly billing):\n\n- `DailyDiscountFee` - the daily discount fee assessed against a card settlement.\n- `DailyInterchangeFee` - the daily interchange fee assessed against a card settlement.\n- `TransactionFee` - a per-transaction settlement fee, e.g. an ACH transaction's processing fee.\n- `ReturnFee` - charged when a payout could not be completed; for ACH, typically a closed or invalid bank account, so no money reached the merchant and this fee is the only thing the attempt produced. Its settled line has a `transactionType` of `Return`.\n- `PerSettlementFee` - a flat fee a merchant's pricing applies once to a settlement, independent of what settled in it. Assessed against the deposit rather than any one line, so it carries a `settlementId` and no `settledTransaction`.\n\n**Fees billed on a monthly statement or invoice** (`source` is `StatementOnly`). Representative examples by general category:\n\n- `MonthlyService`: `GatewayService`, `StatementFee`, `WebReportsAlerts`.\n- `PciCompliance`: `PciFee`, `NonComplianceAssessment`, `SaqScanIncomplete`.\n- `OneTimeSetup`: `ApplicationFee`, `GatewaySetup`, `WirelessActivation`.\n- `NetworkAssessment`: `VisaRegistrationFee`, `McRegistrationFee`, `PinBasedDebitNetworkFee`.\n- `Equipment`: `UnreturnedEquipment`.\n- `Other`: an unclassified fee or unrecognized statement wording; read `description`.\n\nA named fee uses its specific value in `category`, such as `GatewayService`, rather than the group name `MonthlyService`. The examples are not an exhaustive list. See [Fee examples by category](https://fiska.gitbook.io/omni-payment-api/settlement-reporting/fee-charges#fees-billed-on-a-monthly-statement-or-invoice) and use each charge's `description` for its reported wording.\n\n**Derived:**\n\n- `InterchangeAndPassthrough` - interchange and other costs a card statement passes through without naming them individually. Its amount is the statement's total deducted fees minus the sum of named fees. It has `source: StatementOnly`.\n"},"source":{"type":"string","enum":["SettlementLinked","StatementOnly"],"description":"How the fee is reported and billed. Funding type controls whether fees reduce the deposit; the billing schedule separately determines `source` and `chargeDate`.\n\n**SettlementLinked**: a fee associated with a transaction or settlement, charged on its assessment date under daily billing.\n\n**StatementOnly**: a fee billed on a monthly statement or invoice, including transaction and settlement fees scheduled for monthly billing. For fees assessed daily but billed monthly, `chargeDate` is the first of the following month and the assessment date appears in `periodStart` and `periodEnd`. A `StatementOnly` fee can carry a `settlementId`.\n\nCard Net and Card Gross can both have separately reported fee charges. For Card Net, do not deduct a withheld fee from the deposit amount again. For Card Gross, reconcile the separately billed fee using its charge date.\n"},"status":{"type":"string","enum":["Posted","Held","Reversed"],"description":"Whether the entry was charged to the merchant. This endpoint returns only `Posted` fees. Held and reversed entries are excluded, as are reserve movements that do not represent a fee.\n"},"currency":{"type":"string","enum":["USD","CAD"]},"amount":{"type":"integer","minimum":0,"description":"The fee amount, smallest denomination."},"chargeDate":{"type":"string","format":"date","description":"The date the fee is charged. For transaction and settlement fees assessed daily, this is the settlement date under daily billing or the first of the following month under monthly billing."},"periodStart":{"type":"string","format":"date","description":"Start of the period the fee covers, for recurring fees."},"periodEnd":{"type":"string","format":"date","description":"End of the period the fee covers, for recurring fees."},"description":{"type":"string","description":"Human-readable description of the fee."},"settlementId":{"type":"string","description":"The related deposit ID, prefixed with stl_, when linked. Can be present for both SettlementLinked and StatementOnly fees; this link alone does not mean the fee was withheld from the deposit."},"settledTransaction":{"$ref":"#/components/schemas/SettledTransactionReference"},"feeBreakdown":{"$ref":"#/components/schemas/SettlementFeeBreakdown"}},"required":["id","category","currency","amount","chargeDate"]},"SettledTransactionReference":{"type":"object","description":"The settled transaction a per-transaction fee applies to, mirroring that transaction's identity. Present only on per-transaction fees. Combine `gatewayTransactionId` with the fee's `settlementId` to locate the settled line via `GET /settlements/{settlementId}`.\n","properties":{"transactionId":{"type":"string","description":"The Fiska transaction ID (`trx_`) of the settled transaction, when that line is matched to a Fiska transaction. Absent when `matchStatus` is `Unmatched`."},"gatewayTransactionId":{"type":"string","description":"The gateway's own transaction ID of the settled transaction. Always present."},"matchStatus":{"type":"string","enum":["Unmatched","Matched","ManuallyMatched"],"description":"The match status of the settled transaction - the same `matchStatus` reported on that settled transaction.\n\n**Unmatched**: The settled transaction has no identified Fiska transaction; `transactionId` is absent.\n\n**Matched**: Automatically matched to a Fiska transaction.\n\n**ManuallyMatched**: Matched to a Fiska transaction by manual reconciliation.\n"}},"required":["gatewayTransactionId","matchStatus"]},"SettlementFeeBreakdown":{"type":"object","description":"Optional breakdown of the components of a fee charge. Only the components that apply to a given fee are present.\n Components are signed integers in minor units; positive values are charges and negative values are credits.\n","properties":{"discountFee":{"type":"integer","description":"Processing/discount fee component, smallest denomination."},"originationFee":{"type":"integer","description":"ACH origination fee, smallest denomination."},"returnFee":{"type":"integer","description":"ACH return fee - charged when a transaction is returned/reversed post-settlement. Smallest denomination."},"interchangeFee":{"type":"integer","description":"Card-network interchange fee, in minor units."},"otherFee":{"type":"integer","description":"Provider-specific catch-all for fee components not otherwise modeled."}}}}}}
```

## The TransactionStatus object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"TransactionStatus":{"type":"string","enum":["Unknown","Created","Pending","Submitted","Acknowledged","Processing","AwaitingSettlement","Completed","Failed","Abandoned"],"description":"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.\n"}}}}
```

## The ThreeDsChallenge object

```json
{"openapi":"3.1.0","info":{"title":"Integrated Commerce Omni-Channel Payment API","version":"2026.08.03"},"components":{"schemas":{"ThreeDsChallenge":{"type":"object","description":"Present when a token payment requires a cardholder challenge (`resultCode: 4100`).","properties":{"redirectUrl":{"type":"string","format":"uri","description":"Hosted URL where the cardholder completes the challenge."},"followUpToken":{"type":"string","description":"Opaque token identifying the pending challenge."}},"required":["redirectUrl","followUpToken"]}}}}
```