# Sale (Token)

**POST /transactions/token-sale**

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 `Pending` with result code `0`
- Transaction progresses through `Processing` status
- Final `Completed` or `Declined` status 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.



## Servers
- https://api.omni.integratedcommerce.io/v1: https://api.omni.integratedcommerce.io/v1 ()


## Authentication methods
- Api key header


## Parameters



### Body: application/json (object)
The request to process a Card On File transaction using a tokenized card or ACH payment method.
- **amount** (number(uint32))
  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).
- **amountBreakdown** (object)
  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).
- **paymentMethodId** (string)
  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
- **invoiceNumber** (string)
  An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.
- **orderNumber** (string)
  An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.
- **referenceId** (string)
  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.


## Responses
### 200
A successful Card On File sale response

#### Body: application/json (object)
- **id** (string)
  Unique ID for this transaction.
- **sourceId** (string)
  The source ID of the transaction.
- **timestamp** (string(date-time))
  Transaction timestamp in UTC
- **type** (string)
  Type of transaction
- **status** (string)
  The current status of the transaction
- **accountHolder** (object)

- **paymentMethod** (object)

- **invoiceNumber** (string)
  An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.
- **orderNumber** (string)
  An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.
- **referenceId** (string)
  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.
- **resultCode** (number)
  Result codes:
  * `0` - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)
  * `1003` - The payment terminal is busy or unavailable. (If this error persists, the user may need to close and re-open the Payment Application on the terminal or restart the terminal)
  * `1005` - The specified terminal could not be found.
  * `3000` - An unexpected error occurred. Please try again.
  * `3002` - The transaction could not be completed because the payment terminal could not find the related transaction.
  * `3005` - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.
  * `3006` - The transaction could not be completed because the payment terminal is low on battery.
  * `3009` - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.
  * `3010` - The transaction took too long and was cancelled by the application.
  * `3011` - Invalid transaction request. Please consult the documentation for valid transaction requests.
  * `3012` - Invalid transaction request. paymentMethodId is invalid.
  * `3013` - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.
  * `3014` - Invalid amount. Please try your transaction again with an amount greater than $0.
  * `3020` - An unsupported transaction result was received.
  * `4001` - The transaction is being processed. This is returned for asynchronous bank transfer payment methods (e.g. ACH) while awaiting a final outcome.
  * `9998` - The system is not ready to process a transaction.
  * `9999` - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.
- **resultText** (string)
  A message describing the result code in more detail.
- **requestedAmount** (number)
  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).
- **approvedAmount** (number)
  The amount approved. The approved amount is always a non-null positive integer in the smallest denomination of the currency (e.g. cents for USD or CAD).
- **balanceAmount** (number)
  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).
- **transactionResponses** (array[object])
  A list of all transaction responses received during the transaction. In most cases, there will be only one response.

### 400
Request Error

#### Body: application/json (object)
- **code** (number)
  Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

   * `0` - Unknown
   * `1000` - AuthenticationGenericError
   * `1001` - MerchantNotAuthorizedForResource
   * `2000` - RequestValidationGenericError
   * `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.
   * `2011` - InvalidTransactionType
   * `2012` - InvalidAmount
   * `2020` - InvalidPaymentMethodOwner
   * `2021` - InvalidAccountHolderOwner
   * `2100` - InvalidAccountHolderInformation
   * `2101` - InvalidCountryCode
   * `2102` - InvalidZipCode
   * `2103` - MissingCountryCodeOrZipCode
   * `2105` - InvalidEmailAddress
   * `2201` - MissingUniqueToken
   * `2202` - TransactionDeclinedError
   * `2900` - RequestValidationUnsupportedPayload
   * `2901` - RequestValidationWebhookMissingTypeAndDmnType
   * `2902` - RequestValidationUnsupportedWebhookTokenization
   * `2903` - RequestValidationUnsupportedWebhookType
   * `3000` - UnknownServerGenericError
   * `3201` - InvalidOrExpiredSession
   * `3202` - FailedToCreateSessionInAdapter
   * `3203` - ErrorWhileTokenizingCard
   * `3204` - FailedToLoadThirdPartySdk
   * `3205` - SessionExpired
   * `3299` - JavaScriptError
   * `3401` - TransactionNotCompleteYet
   * `3501` - CouldNotCreateBillingSubscription
   * `3502` - CouldNotCancelBillingSubscription
   * `3503` - BillingSubscriptionInvalidStatus
   * `4000` - ResourceNotFound
   * `4001` - TokenizedCardNotFound
   * `4002` - PaymentMethodNotFound
   * `4003` - AccountHolderNotFound
   * `4004` - BillingSubscriptionNotFound
   * `9000` - UnhandledGenericError
- **status** (string)
  Execution status of the request sent to the payment gateway.

   * Completed - The request completed successfully.
   * Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
   * 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.
   * Unknown
- **message** (string)
  Developer-facing error message.
- **traceId** (string)
  Unique trace identifier for tracking and debugging this request.
- **timestamp** (string(date-time))
  The timestamp when the error occurred (UTC).
- **errorDetails** (array[object])


### 401
Unauthorized response due to an invalid or missing API key.

#### Body: application/json (object)
- **code** (number)
  Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

   * `0` - Unknown
   * `1000` - AuthenticationGenericError
   * `1001` - MerchantNotAuthorizedForResource
   * `2000` - RequestValidationGenericError
   * `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.
   * `2011` - InvalidTransactionType
   * `2012` - InvalidAmount
   * `2020` - InvalidPaymentMethodOwner
   * `2021` - InvalidAccountHolderOwner
   * `2100` - InvalidAccountHolderInformation
   * `2101` - InvalidCountryCode
   * `2102` - InvalidZipCode
   * `2103` - MissingCountryCodeOrZipCode
   * `2105` - InvalidEmailAddress
   * `2201` - MissingUniqueToken
   * `2202` - TransactionDeclinedError
   * `2900` - RequestValidationUnsupportedPayload
   * `2901` - RequestValidationWebhookMissingTypeAndDmnType
   * `2902` - RequestValidationUnsupportedWebhookTokenization
   * `2903` - RequestValidationUnsupportedWebhookType
   * `3000` - UnknownServerGenericError
   * `3201` - InvalidOrExpiredSession
   * `3202` - FailedToCreateSessionInAdapter
   * `3203` - ErrorWhileTokenizingCard
   * `3204` - FailedToLoadThirdPartySdk
   * `3205` - SessionExpired
   * `3299` - JavaScriptError
   * `3401` - TransactionNotCompleteYet
   * `3501` - CouldNotCreateBillingSubscription
   * `3502` - CouldNotCancelBillingSubscription
   * `3503` - BillingSubscriptionInvalidStatus
   * `4000` - ResourceNotFound
   * `4001` - TokenizedCardNotFound
   * `4002` - PaymentMethodNotFound
   * `4003` - AccountHolderNotFound
   * `4004` - BillingSubscriptionNotFound
   * `9000` - UnhandledGenericError
- **status** (string)
  Execution status of the request sent to the payment gateway.

   * Completed - The request completed successfully.
   * Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
   * 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.
   * Unknown
- **message** (string)
  Developer-facing error message.
- **traceId** (string)
  Unique trace identifier for tracking and debugging this request.
- **timestamp** (string(date-time))
  The timestamp when the error occurred (UTC).
- **errorDetails** (array[object])



[Powered by Bump.sh](https://bump.sh)