Tokenize a card or ACH bank account using a hosted payment form/iframe. This POST request initiates a tokenization session and returns a short-lived iframe URL to embed in your 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 tokenization result will be delivered via the Token Created webhook.
Payment Method Types
This endpoint supports different payment method types based on the paymentMethodId provided:
- Virtual (Card): A $0 authorization will occur to validate the card. If valid, a tokenized card ID will be stored and a paymentMethodId will be returned for future Card On File transactions.
- VirtualAch (ACH Bank Account): The bank account information will be tokenized for future ACH transactions.
ACH Tokenization
When using an ACH payment method (VirtualAch):
- No verification is performed on the bank account during tokenization. The account details are stored as provided.
- Verification of account validity occurs only when a subsequent sale transaction is processed.
- The tokenized ACH payment method can be used for future token sales via the
/transactions/token-saleendpoint. - ACH tokens have restrictions and cannot be used for authorization, void, or subscription transactions.
Webhook Events
The following webhook events will be triggered during the tokenization process:
auth.completed- when a $0 authorization is processed and completed (card only).token.created- when a card or ACH account is tokenized and stored as a payment method.
Body
Required
The request to tokenize a card using a hosted payment form / iframe.
-
The ID of the payment method (hosted payment form/iframe) to use for adding a card.
- 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 payment method IDs for your account using the
GET /payment-methodsendpoint. - Example format:
-
An optional custom reference ID to tag and track this token operation. If provided, this value must be unique per merchant. 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/payment-methods/virtual' \
--header "x-api-key: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"referenceId":"ref_add_card_12345","paymentMethodId":"pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS","useJavaScriptCallback":true}'{
"referenceId": "ref_add_card_12345",
"paymentMethodId": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
"useJavaScriptCallback": true
}{
"formConfig": {
"billingInfoCaptureLevel": "Minimal"
},
"referenceId": "ref_add_card_12345",
"paymentMethodId": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
"useJavaScriptCallback": true
}{
"id": "ifr_01J2F0ZJ2JW5B63CJFPXRGAB1S",
"status": "Pending",
"iframeUrl": "https://hpf.integratedcommerce.io/session/01JSFAMY0AGW27QKP30C727512",
"sessionId": "ses_01JSFAMY0AGW27QKP30C727512",
"referenceId": "ref_add_card_12345",
"paymentMethod": {
"id": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
"type": "Virtual",
"currency": "USD",
"description": "Online Checkout Iframe"
},
"requestedAmount": 0,
"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": "paymentMethodId",
"details": "'PaymentMethodId' must not be empty.",
"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": []
}