---
title: "Create one-time-use token"
method: POST
path: "/pay/v3/token"
tags: ["Ecommerce"]
---

# Create one-time-use token

`POST /pay/v3/token`

Use this endpoint to generate a temporary token prior to loading an ecommerce iframe. The available and required parameters differ based on the iframe to be loaded. See the dropdown below to determinee which parameters are available and required for each iframe. All processing options and UI options for your iframes must be sent in the body of this request. 

If you want to have the system pre-fill an iframe form, you must include that data (for example, card or customer information) in the request for this endpoint. <b>Any parameter included here will be overwritten if the same parameter is included in the iframe’s event body.</b>

For more information about the parameters that continue from the one-time-use token to the saved card token and beyond, see [What data is saved with tokens?](https://docs.nexiopay.com/docs/what-data-is-saved-with-tokens) in Guides.

<!-- theme: info -->
> 📘 Note
> 
> Once a token has been used to submit an iframe it cannot be used to load another. You must request a new one-time-use token prior to submitting each iframe.

<Callout icon="📘" theme="info">
 Note

 Once a token has been used to submit an iframe it cannot be used to load another. You must request a new one-time-use token prior to submitting each iframe.
</Callout>

<!-- theme: warning -->
> ⚠️ Try It
> 
> To use the Try It feature for this endpoint, you can use the credentials for your [Sandbox API user](https://docs.nexiopay.com/docs/sandbox-environments).<br/><br/>You can also use the following test account. Copy the value and paste it into the appropriate space in the Try It section to the right.
> username: `docs@nexiopay.com`
> password: `JZdzoXpdDeH6VA`<br/><br/>Include any other parameters that you need for the body of the request, depending on what you are using the one-time-use token for.


<div style={{ display: 'none' }}>

## Request parameters
- bank
- bank.accountHolderName
- bank.routingNumber
- card
- card.businessNumber
- card.cardHolderName
- card.cardType
- card.classification
- card.expirationMonth
- card.expirationYear
- card.password
- data
- data.allowedCardTypes
- data.amount
- data.currency
- data.customer
- data.customer.customerRef
- data.customer.orderNumber
- data.customer.orderDate
- data.customer.invoice
- data.customer.firstName
- data.customer.lastName
- data.customer.birthDate
- data.customer.nationalIdentificationNumber
- data.customer.billToAddressOne
- data.customer.billToAddressTwo
- data.customer.billToCity
- data.customer.billToCountry
- data.customer.billToPhone
- data.customer.billToPostal
- data.customer.billToState
- data.customer.birthDate
- data.customer.createdAtDate
- data.customer.email
- data.customer.phone
- data.customer.shipToAddressOne
- data.customer.shipToAddressTwo
- data.customer.shipToCity
- data.customer.shipToCountry
- data.customer.shipToPhone
- data.customer.shipToPostal
- data.customer.shipToState
- data.customFields
- data.customFields.exampleKey
- data.description
- data.descriptor
- data.descriptor.name
- data.descriptor.address
- data.descriptor.city
- data.descriptor.state
- data.descriptor.postal
- data.descriptor.country
- data.descriptor.phone
- data.descriptor.url
- data.descriptor.merchantId
- data.descriptor.mcc
- data.lodging
- data.lodging.advanceDeposit
- data.lodging.checkInDate
- data.lodging.checkOutDate
- data.lodging.noShow
- data.lodging.roomNumber
- data.lodging.roomRate
- data.surcharge
- installment
- installment.period
- isAuthOnly
- processingOptions
- processingOptions.checkFraud
- processingOptions.verboseResponse
- processingOptions.verifyAvs
- processingOptions.verifyCvc
- processingOptions.customerRedirectUrl
- processingOptions.merchantId
- processingOptions.paymentOptionTag
- processingOptions.saveCardToken
- processingOptions.shouldUseFingerprint
- shouldUpdateCard
- uiOptions
- uiOptions.css
- uiOptions.customTextUrl
- uiOptions.displaySubmitButton
- uiOptions.hideBilling
- uiOptions.hideBilling.hideAddressOne
- uiOptions.hideBilling.hideAddressTwo
- uiOptions.hideBilling.hideCity
- uiOptions.hideBilling.hideCountry
- uiOptions.hideBilling.hidePostal
- uiOptions.hideBilling.hidePhone
- uiOptions.hideBilling.hideState
- uiOptions.hideCvc
- uiOptions.limitCountriesTo
- uiOptions.requireCvc
- uiOptions.forceExpirationSelection


## Response parameters
- expiration
- fraudUrlc
- token

</div>

## Request body

- union
  - object — Save card token iframe.
    - `card` object — Card information. Typically, you only include the `cardHolderName`, `expirationMonth`, and `expirationYear`. The other possible parameters are only required for certain gateways or connections.
      - `cardHolderName` CardHolderName — unresolved $ref
      - `expirationMonth` ExpirationMonth — unresolved $ref
      - `expirationYear` ExpirationYear — unresolved $ref
      - `classification` 'business' | 'personal' — The card classification. This field is required by certain gateways. For information on gateway-specific required fields, see the [Connections](https://docs.nexiopay.com/docs/connections) documentation. This value is cached in the one-time-use token. When the value for this field is `business`, include values for `businessNumber` and `password`.
      - `businessNumber` string — A string containing 10 digits. This field is required by certain gateways. For information on gateway-specific required fields, see the [Connections](https://docs.nexiopay.com/docs/connections) documentation. This value is cached in the one-time-use token.<br/><br/> When the value for `classification` is `business`, include a value for this field.
      - `password` string — A string containing two digits. This field is required by certain gateways. For information on gateway-specific required fields, see the [Connections](https://docs.nexiopay.com/docs/connections) documentation. This value is cached in the one-time-use token. When the value for `classification` is `business`, include a value for this field.
    - `data` object — Additional optional data
      - `allowedCardTypes` string[] — If this array is nonempty, Card Number field will only accept the card types included in the array. This value is cached in the one-time-use token.
      - `currency` string — The [three-character ISO code](https://en.wikipedia.org/wiki/ISO_4217) for any currency supported by your merchant account. If you specify a currency that your account does not support, you will get an error response. If you do not include this parameter, the system uses the default of `USD`, but if your merchant account does not support USD, you will get an error response. This value is cached in the one-time-use token, but it is only used for pre-filling the iframe in the [Save card token with iframe](https://docs.nexiopay.com/reference/savecardtokeniframe) or [Run card transaction with iframe](https://docs.nexiopay.com/reference/runcardtransactioniframe) endpoints. Please note that the currency is not stored with the card token. Card tokens can be used to process through any MID on your account. They are not restricted to a specific merchant account or currency.
      - `customer` object — Customer information to be used in checking fraud or sent to the processing gateway, when applicable.
        - `orderNumber` string — The order number. This parameter is not required by the API (it is required for transactions where [decline recovery](https://docs.nexiopay.com/docs/recover) is used). **However, Nexio strongly recommends that you include this for every transaction. Ideally, this value should be unique to the merchant.** This value is cached in the one-time-use token. <!-- theme: warning --> > 🛑 Important > > If you run 3DS transactions and you do not use a unique order number, there will be payment flows that you won't be able to reconcile. Nexio recommends a format for the order number of a unique value that also includes an attempt number so that you can track attempts per order, such as when a payment attempt fails. For example, something like `[order_number]-[attempt_number]`.
        - `customerRef` CustomerRef — unresolved $ref
        - `orderDate` string — The date of the customer's order. This field is required by certain gateways. For information on gateway-specific required fields, see the [Connections](https://docs.nexiopay.com/docs/connections) documentation. This value is cached in the one-time-use token. Use any of the following formats for the date: - Four-digit year, two-digit month and day, separated with hyphens: YYYY-MM-DD.<br>For example, `2021-08-26`. - [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) date expressed in UTC. It must include the 3 decimal places for milliseconds.<br>For example, `2001-08-26T13:35:00.978Z` or `1990-12-05T00:00:00.000Z`. - UNIX date (as an integer representing seconds).<br>For example, `1630006518`. <!-- theme:info --> > #### Note > This is NOT a quick way to schedule a transaction. Specifying a date in the future does not cause the order to be run automatically at the indicated date or time.
        - `invoice` Invoice — unresolved $ref
        - `firstName` FirstName — unresolved $ref
        - `lastName` LastName — unresolved $ref
        - `birthDate` string — The customer's date of birth. This value is cached in the one-time-use token. Use any of the following formats for the date: - Four-digit year, two-digit month and day, separated with hyphens: YYYY-MM-DD.<br>For example, `2001-08-26`. - [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) date expressed in UTC. It must include the 3 decimal places for milliseconds.<br>For example, `2001-08-26T13:35:00.978Z` or `1990-12-05T00:00:00.000Z`. - UNIX date (as an integer representing seconds).<br>For example, `998854500`.
        - `nationalIdentificationNumber` string — The identification number issued by a national authority to the individual person, such as social security number. This value is cached in the one-time-use token. This field is required by certain gateways. For information on gateway-specific required fields, see the [Connections](https://docs.nexiopay.com/docs/connections) documentation. The following list provides information about potential identification sources: - **Brazil:** CPF or CNPJ. - **Chile:** RUN for individual users and RUT for companies - **Colombia:** For individual users CC (Cédula de ciudadanía), CE (Cédula de Extranjería) and TI (Targeta de Identidad) and for companies NIT - **Mexico:** RFC and CURP (individual user) and RFC (legal entity/company)
        - `email` Email — unresolved $ref
        - `phone` Phone — unresolved $ref
        - `billToAddressOne` BillToAddressOne — unresolved $ref
        - `billToAddressTwo` BillToAddressTwo — unresolved $ref
        - `billToCity` BillToCity — unresolved $ref
        - `billToState` BillToState — unresolved $ref
        - `billToPostal` BillToPostal — unresolved $ref
        - `billToCountry` BillToCountry — unresolved $ref
        - `billToPhone` BillToPhone — unresolved $ref
        - `shipToAddressOne` ShipToAddressOne — unresolved $ref
        - `shipToAddressTwo` ShipToAddressTwo — unresolved $ref
        - `shipToCity` ShipToCity — unresolved $ref
        - `shipToState` ShipToState — unresolved $ref
        - `shipToPostal` ShipToPostal — unresolved $ref
        - `shipToCountry` ShipToCountry — unresolved $ref
        - `shipToPhone` ShipToPhone — unresolved $ref
        - `createdAtDate` CreatedAtDate — unresolved $ref
      - `customFields` CustomFields — unresolved $ref
    - `shouldUpdateCard` ShouldUpdateCard — unresolved $ref
    - `processingOptions` object — Processing options for the request. <!-- [JJJ This is used in Run echeck transaction iframe, Save card token iframe, & Save card token API] -->
      - `checkFraud` boolean — Set to `false` to opt out of sending a request to Kount. This value is cached in the one-time-use token. <b>Note:</b> During testing you may trigger specific Kount responses by including any of the values shown in the [verification](https://docs.nexiopay.com/docs/testing-kount-verification#test-kount-verification-table) table.
      - `verifyAvs` integer — Specifies the setting to use with the Address Verification Service (AVS). See the [Settings for AVS](https://docs.nexiopay.com/docs/enabling-the-address-verification-service#settings-for-avs) table for a complete list of options. This value is cached in the one-time-use token. <!-- theme:info --> > #### Note > This parameter only applies to the [Save card token](https://docs.nexiopay.com/reference/savecardtoken) endpoint.
      - `verifyCvc` boolean — When `true`, an invalid security code will prevent the card from being saved. This value is cached in the one-time-use token. <!-- theme:info --> > #### Note > This parameter only applies to the [Save card](https://docs.nexiopay.com/reference/savecardtoken) endpoint.
      - `verboseResponse` VerboseResponse — unresolved $ref
    - `uiOptions` object — Used to customize the iframe's user interface.
      - `css` Css — unresolved $ref
      - `customTextUrl` string — The URL where your custom text JSON file is hosted. For more information, see the [Displaying translated or customized labels](displaying-translated-or-customized-labels) tutorial in Guides. This value is cached in the one-time-use token.
      - `displaySubmitButton` DisplaySubmitButton — unresolved $ref
      - `hideBilling` object — An object that allows you to hide one or more specific billing fields. Alternatively, pass a boolean value for `hideBilling` to hide or display all billing fields (the default is `false`, meaning to display all). This value is cached in the one-time-use token.
        - `hideAddressOne` boolean — Set to `true` to hide the first address field. This value is cached in the one-time-use token.
        - `hideAddressTwo` boolean — Set to `true` to hide the second address field. This value is cached in the one-time-use token.
        - `hideCity` boolean — Set to `true` to hide the city field. This value is cached in the one-time-use token.
        - `hideState` boolean — Set to `true` to hide the state field. This value is cached in the one-time-use token.
        - `hidePostal` boolean — Set to `true` to hide the postal code field. This value is cached in the one-time-use token.
        - `hideCountry` boolean — Set to `true` to hide the country field. This value is cached in the one-time-use token.
        - `hidePhone` boolean — Set to `false` to include a Billing Phone Number field to the iframe form. Any information provided by the user will be sent to the gateway. This value is cached in the one-time-use token. <!-- theme:info --> > #### Note > A billing phone number provided by the user will take precedence over the `data.customer.billToPhone` payload field.
      - `hideCvc` boolean — Set to `true` to hide the security code field. This value is cached in the one-time-use token.
      - `requireCvc` boolean — Set to false to allow form submission without requiring the security code. This value is cached in the one-time-use token.
      - `forceExpirationSelection` boolean — Specifies whether to have any default selections for the `expirationMonth` and `expirationYear` in the iframe, in order to potentially force the customer to make a specific selection for the card expiration date. This value is cached in the one-time-use token. The default behavior of `true` is to not have anything selected by default. Changing this parameter to `false` then uses any values sent in the request for the month and year as the default selection or, if no values are sent in the request, the selections default to the current month and year.
      - `limitCountriesTo` string[] — If this array is nonempty, the Country Dropdown field will be limited to the countries on the list. This value is cached in the one-time-use token. <!-- theme:info --> > #### Note > These must be the [two-character (Alpha-2) ISO country codes](https://www.iso.org/obp/ui/#search/code/).
  - object — Save echeck token iframe.
    - `bank` object — Bank account information
      - `accountHolderName` AccountHolderName — unresolved $ref
      - `routingNumber` RoutingNumber — unresolved $ref
    - `paymentMethod` 'card' | 'echeck' — Specifies the payment method to use. Set to `card` to run card transactions or `echeck` to run echeck transactions.
    - `data` object — Transaction and customer data.
      - `currency` Currency — unresolved $ref
      - `settlementCurrency` SettlementCurrency — unresolved $ref
      - `secCode` SecCode — unresolved $ref
      - `customer` Customer — unresolved $ref
      - `cart` Cart — unresolved $ref
      - `customFields` CustomFields — unresolved $ref
      - `description` Description — unresolved $ref
      - `lodging` Lodging — unresolved $ref
    - `processingOptions` object — Processing options to use for the request. <!-- [JJJ This is used in Save echeck token API & Save echeck token iframe] -->
      - `paymentOptionTag` PaymentOptionTag — unresolved $ref
      - `merchantId` MerchantId — unresolved $ref
      - `verboseResponse` VerboseResponse — unresolved $ref
    - `uiOptions` object — Used to customize the iframe's user interface.
      - `css` Css — unresolved $ref
      - `customTextUrl` CustomTextUrl — unresolved $ref
      - `displaySubmitButton` DisplaySubmitButton — unresolved $ref
      - `hideBilling` HideBilling — unresolved $ref
      - `limitCountriesTo` LimitCountriesTo — unresolved $ref
  - object — Run card transaction iframe.
    - `data` object, required — Transaction data
      - `amount` Amount, required — unresolved $ref
      - `currency` Currency, required — unresolved $ref
      - `surcharge` Surcharge — unresolved $ref
      - `allowedCardTypes` AllowedCardTypes — unresolved $ref
      - `customer` Customer — unresolved $ref
      - `cart` Cart — unresolved $ref
      - `customFields` CustomFields — unresolved $ref
      - `description` Description — unresolved $ref
      - `descriptor` Descriptor — unresolved $ref
      - `lodging` Lodging — unresolved $ref
    - `processingOptions` object, required — Processing options.
      - `paymentType` 'initialScheduled' | 'initialUnscheduled' | 'scheduled' | 'unscheduledCit' | 'unscheduledMit' | 'initialMoto', required — The type of transaction being processed using stored payment credentials. Use this parameter to properly flag initial and subsequent transactions. This value is cached in the one-time-use token. For more information about this parameter and when to use each option, see the [Payment type (paymentType) reference table](https://docs.nexiopay.com/docs/constant-transaction-values#payment-type-paymenttype) in Guides. **Note:** Cardholder authentication (3D Secure) may be required depending on card issuer requirements. For more information, see [3D Secure overview](https://docs.nexiopay.com/docs/3d-secure-1) in Guides.
      - `paymentOptionTag` PaymentOptionTag — unresolved $ref
      - `saveCardToken` boolean — Set to `false` if you do not need to use the card token in the future. This value is cached in the one-time-use token.
      - `retryOnSoftDecline` boolean — Specifies whether to enable the transaction for [decline recovery](https://docs.nexiopay.com/docs/recover). Set to `true` to flag the transaction as enabled for decline recovery. Eligible declined transactions are automatically scheduled for retry according to the recommendation engine. This value is cached in the one-time-use token.
      - `checkFraud` CheckFraud — unresolved $ref
      - `shouldUseFingerprint` boolean — This parameter applies when a [device fingerprint](https://docs.nexiopay.com/docs/device-fingerprinting) was created while saving a card token. The card's stored fingerprint will be used by default, but you may choose not to use it by setting this parameter to false. This value is cached in the one-time-use token. <!-- theme: info --> > #### Note > To change your merchant's default setting, contact [Integrations Support](https://docs.nexiopay.com/page/contact-us).
      - `check3ds` boolean — Integrations Support sets this flag to `true` for merchants by default on the backend when the merchant will be handling transactions in 3DS-mandated regions. If needed, you can override this value. When set to `true`, this indicates that your system is equipped to handle a 3DS (three-domain secure) redirect flow being returned from the request. This value is cached in the one-time-use token. When this value is set to `true`, the system returns a redirect response first. This response object includes a `redirectUrl` parameter for running the 3DS workflow and a `asyncTraceId` parameter for tracking progress and status of the workflow with the [View transaction async status](https://docs.nexiopay.com/reference/viewtransactionasyncstatus) endpoint.
      - `customerRedirectUrl` string — The URL to which the customer will be redirected after completing a [3D Secure](https://docs.nexiopay.com/docs/using-3ds-to-run-transactions) authentication. The customer will be sent here whether the transaction succeeds or fails. This URL must use the HTTPS protocol. This value is cached in the one-time-use token.
      - `merchantId` MerchantId — unresolved $ref
      - `verboseResponse` VerboseResponse — unresolved $ref
    - `card` Card — unresolved $ref
    - `installment` object — Creates an installment associated with the transaction. This is used with the `data.amount` and `data.currency` of the transaction by the gateway or connection to determine how much to charge per transaction. Nexio supports installments for the following gateways: - [Cybersource](https://docs.nexiopay.com/docs/cybersource-integration-guide) - [Openpay](https://docs.nexiopay.com/docs/openpay-integration-guide) For additional instruction, see [Setting up installments for a bank to handle the payment plan](https://docs.nexiopay.com/docs/setting-up-installments-for-a-bank-to-handle-the-payment-plan) or [Setting up installments for a bank to handle the subscription](https://docs.nexiopay.com/docs/setting-up-installments-for-a-bank-to-handle-the-subscription) in Guides.
      - `period` integer — Indicates the number of payments. The value to use depends on the gateway being used. This value is cached in the one-time-use token. The following values are possible for each gateway or connection: - [Cybersource](https://docs.nexiopay.com/docs/cybersource-integration-guide) - `period` can be 1-100, depending on the processor being used. Accepted values may depend on the currency, country, and processor used for the transaction. Contact [Integrations Support](https://docs.nexiopay.com/page/contact-us) for more information about possible options for your situation. - [Openpay](https://docs.nexiopay.com/docs/openpay-integration-guide) - `period` can be 3, 6, 9, 12, or 18. By default, the amount must be 300 and the currency must be MXN. The minimum amount can be changed by Openpay.
    - `isAuthOnly` IsAuthOnly — unresolved $ref
    - `uiOptions` UiOptions — unresolved $ref
  - object — Run echeck transaction iframe.
    - `data` object, required — Transaction and customer data.
      - `amount` Amount, required — unresolved $ref
      - `currency` Currency, required — unresolved $ref
      - `settlementCurrency` SettlementCurrency — unresolved $ref
      - `secCode` SecCode — unresolved $ref
      - `customer` Customer — unresolved $ref
      - `cart` Cart — unresolved $ref
      - `customFields` CustomFields — unresolved $ref
      - `description` Description — unresolved $ref
      - `lodging` Lodging — unresolved $ref
    - `bank` object — Bank account information
      - `accountHolderName` AccountHolderName — unresolved $ref
      - `routingNumber` RoutingNumber — unresolved $ref
    - `paymentMethod` PaymentMethod — unresolved $ref
    - `processingOptions` ProcessingOptions — unresolved $ref
    - `uiOptions` UiOptions — unresolved $ref
  - object — Save card token API request.
    - `data` object — Additional data.
      - `currency` Currency — unresolved $ref
    - `processingOptions` ProcessingOptions — unresolved $ref
  - object — Save echeck token API request.
    - `data` object — Additional optional data
      - `currency` Currency — unresolved $ref
    - `processingOptions` ProcessingOptions — unresolved $ref

## Response `200`

Success

- object — The one-time-use token
  - `expiration` string — The date and time at which the one-time-use token will expire, in [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
  - `fraudUrl` string — The URL to be used for device fingerprinting.
  - `token` string — Your [one-time-use token](https://docs.nexiopay.com/reference/createonetimeusetoken).

## Other responses

- `401` — Unauthorized. For help with this error and other error codes, see [Common errors](https://docs.nexiopay.com/docs/common-errors) in the Guides area.

---

[API](https://skmtc.dev/nexiopay/apis/payments-api-reference.md) · [All operations](https://skmtc.dev/nexiopay/apis/payments-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nexiopay/payments-api-reference/revisions/b414b73979e5/schema)