# Create Token (Card Not Present) **POST /payment-methods/virtual** Tokenize a card 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 card 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. 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. #### Webhook Events The following webhook events will be triggered during the tokenization process: - `auth.completed` - when the $0 authorization is processed and completed. - `token.created` - when a card is tokenized and stored as a payment method. ## 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 tokenize a card using a hosted payment form / iframe. - **paymentMethodId** (string) 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-methods` endpoint. - **referenceId** (string) 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. - **returnUrl** (string) 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. - **useJavaScriptCallback** (boolean) 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. ## Responses ### 200 A successful Card Not Present tokenization response #### Body: application/json (object) - **id** (string) Unique ID for this card tokenization transaction. - **paymentMethod** (object) - **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. - **requestedAmount** (number) Will be null or 0 for token creation. - **sessionId** (string) Session ID for the iframe transaction. - **iframeUrl** (string) URL for the iframe to collect payment information, or null if iframe could not be created due to invalid credentials, etc. - **expirationTimestamp** (string(date-time)) When the iframe session will expire (UTC). - **status** (string) 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. ### 400 Request Error #### Body: application/json (object) - **code** (number) Numeric error code. These are grouped into ranges for easier identification and troubleshooting. * `1000` - AuthenticationGenericError * `2000` - RequestValidationGenericError * `3000` - UnknownServerGenericError * `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. * `1000` - AuthenticationGenericError * `2000` - RequestValidationGenericError * `3000` - UnknownServerGenericError * `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)