Process a financial transaction using a hosted payment form / iframe where the card is not physically present. This POST request initiates a payment session and returns a short-lived iframe URL to embed in your payment page, rather than using a static iframe URL.
When the customer submits their payment information, they will be redirected to the returnUrl (if provided) or a postMessage event will be sent to the parent window. The complete transaction result will be delivered via the Sale Completed webhook.
The payment method will be tokenized for future use.
Payment Method Types
This endpoint supports different payment method types based on the paymentMethodId provided:
- Virtual (Card): Standard card-not-present transaction with immediate processing
- VirtualAch (ACH Bank Transfer): ACH transactions for US bank transfers
ACH Transactions
When using an ACH payment method (VirtualAch), the transaction flow differs from card transactions:
- Initial response will have status
Pendingwith result code4001 - Transaction progresses through
Processingstatus as the bank transfer is executed - Final
CompletedorDeclinedstatus is delivered via webhook (typically 1-5 business days) - The ACH account will be tokenized for future token sales
Note: ACH tokens have restrictions - they cannot be used for void, authorization, 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.token.created- when a card or ACH account is tokenized and stored as a payment method.
Body
Required
The request to process a Card Not Present transaction using a hosted payment form / iframe.
-
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 hosted payment form / iframe that will collect card information for this Card Not Present transaction.
- Example format:
pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS - OPTIONAL ONLY if you have a single hosted payment form configured
- REQUIRED if you have multiple hosted payment forms configured
You can retrieve all available hosted payment form IDs for your account using the
GET /payment-methodsendpoint. - 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. -
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.
-
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.
-
Optional. Configuration for the hosted payment form. If not provided, defaults to full billing information capture.
curl \
--request POST 'https://api.omni.integratedcommerce.io/v1/transactions/virtual-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_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS","useJavaScriptCallback":true}'{
"amount": 1000,
"orderNumber": "order_number_1234",
"referenceId": "ref_s192i49i",
"invoiceNumber": "inv_1234567890123456",
"amountBreakdown": {
"tax": 100,
"tip": 0,
"cashback": 0,
"amountGoodsAndServices": 900
},
"paymentMethodId": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
"useJavaScriptCallback": true
}{
"amount": 1000,
"formConfig": {
"billingInfoCaptureLevel": "Minimal"
},
"invoiceNumber": "inv_1234567890123456",
"paymentMethodId": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
"useJavaScriptCallback": true
}{
"amount": 1000,
"formConfig": {
"billingInfoCaptureLevel": "Full"
},
"invoiceNumber": "inv_1234567890123456",
"paymentMethodId": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
"useJavaScriptCallback": true
}{
"id": "ifr_01J2F0EKHC7HY2R93C8ENBD1FG",
"status": "Pending",
"iframeUrl": "https://hpf.integratedcommerce.io/session/01JSFAMY0AGW27QKP30C727512",
"sessionId": "ses_01JSFAMY0AGW27QKP30C727512",
"orderNumber": "order_number_1234",
"referenceId": "ref_s192i49i",
"invoiceNumber": "inv_1234567890123456",
"paymentMethod": {
"id": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
"type": "Virtual",
"currency": "USD",
"description": "Online Checkout Iframe"
},
"requestedAmount": 1000,
"expirationTimestamp": "2025-04-17T14:19:03Z"
}{
"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": []
}