Process a financial transaction using a previously tokenized payment method. This endpoint supports both tokenized cards and tokenized ACH (bank transfer) payment methods.
ACH Token Sales
When processing a sale with an ACH token (payment method ID prefixed with pmt_ach_), the transaction will be processed as an ACH bank transfer. ACH transactions are asynchronous:
- Initial response will have status
Pendingwith result code0 - Transaction progresses through
Processingstatus - Final
CompletedorDeclinedstatus is delivered via webhook
Note: ACH tokens have restrictions. They cannot be used for authorization, void, or subscription transactions.
Webhook Events
The following webhook events will be triggered during the transaction process:
sale.completed- when a financial transaction is processed and completed.
Body
Required
The request to process a Card On File transaction using a tokenized card or ACH payment method.
-
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).
Minimum value is
1, maximum value is999999999. -
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).
-
The ID of the tokenized card that will be used for this Card On File transaction.
- Example format:
pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J - ALWAYS REQUIRED when using a tokenized card
- Example format:
-
An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.
Maximum length is
100. -
An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.
Maximum length is
100. -
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). If provided, this value must be unique per merchant. 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.
Maximum length is
100.
curl \
--request POST 'https://api.omni.integratedcommerce.io/v1/transactions/token-sale' \
--header "x-api-key: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"amount":1000,"orderNumber":"order_number_1234","referenceId":"ref_s192i49i","invoiceNumber":"inv_1234567890123456","amountBreakdown":{"tax":100,"tip":0,"cashback":0,"amountGoodsAndServices":900},"paymentMethodId":"pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"}'{
"amount": 1000,
"orderNumber": "order_number_1234",
"referenceId": "ref_s192i49i",
"invoiceNumber": "inv_1234567890123456",
"amountBreakdown": {
"tax": 100,
"tip": 0,
"cashback": 0,
"amountGoodsAndServices": 900
},
"paymentMethodId": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J"
}{
"id": "trx_01J2F0EKHC7HY2R93C8ENBD1FG",
"type": "Sale",
"status": "Completed",
"timestamp": "2025-05-27T18:49:31Z",
"resultCode": 0,
"resultText": "APPROVED",
"orderNumber": "order_number_1234",
"referenceId": "ref_s192i49i",
"accountHolder": {
"id": "aho_01JRZPRGFF4J2SZC3HMDBYEN2J",
"contact": {
"city": "Chicago",
"name": "John Doe",
"state": "IL",
"address": "300 S Wacker Dr",
"zipCode": "60606",
"countryCode": "US"
},
"externalId": "usr_1234567890123"
},
"balanceAmount": 0,
"invoiceNumber": "inv_1234567890123456",
"paymentMethod": {
"id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
"type": "Token",
"cardType": "AMEX",
"currency": "USD",
"cardExpDate": "1225",
"billingContact": {
"city": "Anytown",
"name": "John Doe",
"state": "NY",
"address": "123 Main St",
"zipCode": "12345",
"countryCode": "US"
},
"maskedCardNumber": "3****6452"
},
"approvedAmount": 1000,
"requestedAmount": 1000,
"transactionResponses": [
{
"receipt": {
"lines": []
},
"authCode": "123456",
"responseCode": 1,
"paymentMethod": {
"id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
"type": "Token",
"cardType": "AMEX",
"currency": "USD",
"cardExpDate": "1225",
"billingContact": {
"city": "Anytown",
"name": "John Doe",
"state": "NY",
"address": "123 Main St",
"zipCode": "12345",
"countryCode": "US"
},
"maskedCardNumber": "3****6452"
},
"amountApproved": 1000,
"approvedAmountBreakdown": {
"tax": 0,
"tip": 0,
"cashback": 0,
"amountGoodsAndServices": 1000
}
}
]
}{
"id": "trx_01KEQTZ0R2YC49PWP23E0AWW3C",
"type": "Sale",
"status": "Pending",
"sourceId": "trx_01KEQTZ0R2YC49PWP23E0AWW3C",
"timestamp": "2026-01-12T00:51:21.4869593Z",
"resultCode": 0,
"orderNumber": "ord_db06080f-0bf4-4812-869e-dc8408da4691",
"referenceId": "ref_2a624ceb-11cc-44c4-b616-f1753922cf3c",
"accountHolder": {
"id": "aho_01KEQ9JMQXGZKS4XME0K6N3H60",
"externalId": "01KEQ9JMQWKM99WRA67XAA9TB6"
},
"balanceAmount": 0,
"invoiceNumber": "inv_b8f12195-a160-4485-abc8-c2cdbadefc41",
"paymentMethod": {
"id": "pmt_tkn_01KEQ9JMXTVZHAE264BMAZ9QTW",
"type": "Token",
"currency": "USD",
"billingContact": {
"city": "North Jaydaland",
"name": "Sydnie Nolan",
"state": "WV",
"address": "392 Madie Alley",
"zipCode": "67317-9415",
"countryCode": "US"
}
},
"approvedAmount": 0,
"requestedAmount": 1000,
"transactionResponses": []
}{
"code": 2000,
"status": "Rejected",
"message": "One or more validation errors occurred.",
"traceId": "1-6838bcce-5c0074e82ac7170d4f990d87",
"timestamp": "2025-05-29T20:00:15.5752808Z",
"errorDetails": [
{
"code": 2000,
"field": "Amount",
"details": "The Amount field must be a positive number between 1 and 999999999.",
"message": "Request validation failed"
}
]
}{
"code": 1000,
"status": "Rejected",
"message": "API key cannot be empty",
"traceId": "1-6838be96-74c62f8e2804352739e63476",
"timestamp": "2025-05-29T20:07:50.4723483Z",
"errorDetails": []
}