---
title: "Create APM one-time-use token"
method: POST
path: "/apm/v3/token"
tags: ["Alternative Payment Methods"]
---

# Create APM one-time-use token

`POST /apm/v3/token`

A token from this endpoint is necessary prior to loading any of the Alternative Payment Method (APM) iframes or running a transaction using an APM.

Any data (amount, currency, and so forth) that you want to be sent to the alternate payment method must be included in the body of this request. For details about each APM, as well as test cards and accounts, see [Payment methods](https://docs.nexiopay.com/docs/payment-methods).

For a tutorial about how to make use of this endpoint, see the [Run a sale transaction](https://docs.nexiopay.com/docs/run-a-sale-transaction) topic.

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

<!-- 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 (that is connected with [PayPal](https://docs.nexiopay.com/docs/paypal-integration-guide)). 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, and which payment method you want to use. For details about each one, as well as test cards and accounts, see [Payment methods](https://docs.nexiopay.com/docs/payment-methods).

<div style="display:none;">

## Request parameters
- isAuthOnly
- data
- data.amount
- data.currency
- data.customer
- data.customer.email
- data.customer.firstName
- data.customer.lastName
- data.customer.customerRef
- data.customer.orderNumber
- 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.invoice
- data.customer.shipToAddressOne
- data.customer.shipToAddressTwo
- data.customer.shipToCity
- data.customer.shipToCountry
- data.customer.shipToPhone
- data.customer.shipToPostal
- data.customer.shipToState
- data.cart
- data.cart.items
- data.cart.items.item
- data.cart.items.description
- data.cart.items.quantity
- data.cart.items.price
- data.cart.items.type
- data.cart.items.imageUrl
- data.cart.items.productUrl
- 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.dueDate
- data.locale
- data.paymentMethod
- customerRedirectUrl
- processingOptions
- processingOptions.merchantId
- processingOptions.doNotProcessPayment
- processingOptions.paymentOptionTag
- processingOptions.saveRecurringToken
- uiOptions
- uiOptions.displaySubmitButton
- uiOptions.css

## Response parameters
- expiration
- token
- asyncTraceId
- expressIFrameUrl
- redirectUrls
- redirectUrls.paymentMethod
- redirectUrls.url
- buttonIFrameUrls
- buttonIFrameUrls.paymentMethod
- buttonIFrameUrls.url
</div>

## Request body

- object
  - `data` object, required — Transaction data for the APM. For a list of other required and optional parameters, see the guide for the appropriate [payment method](https://docs.nexiopay.com/docs/payment-methods).
    - `amount` Amount, required — unresolved $ref
    - `currency` string, required — The [three-character ISO code](https://en.wikipedia.org/wiki/ISO_4217) for the currency used in the transaction. For [Klarna](https://docs.nexiopay.com/docs/klarna-integration-guide) transactions (either `klarnaPayments` or `klarnaCheckout`), in order to display the payment popup page to the customer in a supported language, this currency value, the `data.locale`, and the `data.customer.billToCountry` must all match. For information about how they need to match, see the [Purchase country, locale, and currency](https://docs.klarna.com/klarna-payments/in-depth-knowledge/puchase-countries-currencies-locales/) page in the Klarna documentation.
    - `customer` object, required — Customer information to be passed along to the alternative payment method, when applicable. For a list of other required and optional parameters, see the integration guide for the [payment method](https://docs.nexiopay.com/docs/payment-methods).
      - `orderNumber` OrderNumber, required — unresolved $ref
      - `customerRef` string — Customer identifier. You can use this field to pass a customer ID to the APM or to manage user subscriptions.
      - `invoice` string — The invoice number.
      - `firstName` string — The customer's first name.
      - `lastName` string — The customer's last name.
      - `birthDate` BirthDate — unresolved $ref
      - `email` string — The customer's email address.
      - `billToAddressOne` string — The street address for the customer.
      - `billToAddressTwo` string — Additional street address information, if required.
      - `billToCity` string — The city for the address record.
      - `billToState` string — The state or province on file with the alternative payment method. (If in the US, this must be the [two-character state abbreviation](https://pe.usps.com/text/pub28/28apb.htm)).
      - `billToPostal` string — The postal code on file.
      - `billToCountry` string — The [two-character (Alpha-2) ISO country code](https://www.iso.org/obp/ui/#search/code/) for the address on file with the alternative payment method. For [Klarna](https://docs.nexiopay.com/docs/klarna-integration-guide) transactions (either `klarnaPayments` or `klarnaCheckout`), in order to display the payment popup page to the customer in a supported language, this country value, the `data.locale`, and the `data.currency` must all match. For information about how they need to match, see the [Purchase country, locale, and currency](https://docs.klarna.com/klarna-payments/in-depth-knowledge/puchase-countries-currencies-locales/) page in the Klarna documentation.
      - `billToPhone` string — The billing phone number.
      - `shipToAddressOne` string — The shipping address, if different from the billing address.
      - `shipToAddressTwo` string — Additional shipping address information, if required.
      - `shipToCity` string — The shipping city.
      - `shipToState` string — The shipping state or province. (If in the US, this must be the [two-character state abbreviation](https://pe.usps.com/text/pub28/28apb.htm).)
      - `shipToPostal` string — The shipping postal code.
      - `shipToCountry` string — The [two-character (Alpha-2) ISO](https://www.iso.org/obp/ui/#search/code/) shipping country code.
      - `shipToPhone` string — The shipping phone number.
    - `applePayDomain` string — Allows you to run a transaction through a verified domain other than the default. <!-- theme:info --> > #### Notes > - All domains must be [pre-verified through Apple Pay](https://docs.nexiopay.com/docs/apple-pay-integration-guide#verify-your-domain) > - Do not include `https://` > - Include the URL exactly as verified through Apple Pay
    - `cart` object — Items purchased in the transaction.
      - `items` object[] — Details about items in the shopping cart.
        - `item` string — Item number or code.
        - `description` string — A description of the item.
        - `quantity` integer — The quantity sold.
        - `price` number — The price per item.
        - `type` string — The type for the transaction. This should be either `sale` or `refund`. This value is cached in the one-time-use token.
        - `imageUrl` string — The URL to an image for the item. This parameter can only be used with [Klarna](https://docs.nexiopay.com/docs/klarna-integration-guide). The system sends the value to Klarna as part of the order lines. Klarna also uses this image for communications between the customer and Klarna. Klarna recommends that the resolution of the image be a minimum of 250x250 pixels (and ideally about 650x650 pixels or more) in order to look good in the Klarna application. If the resolution is less than 50x50 pixels, it will not even display. The image file size must not exceed 12MB. This value is cached in the one-time-use token.
        - `productUrl` string — The URL to the product on the merchant website. This parameter can only be used with [Klarna](https://docs.nexiopay.com/docs/klarna-integration-guide). The system sends the value to Klarna as part of the order lines. This value is cached in the one-time-use token.
    - `description` Description — unresolved $ref
    - `descriptor` string — Include this parameter to dynamically change the descriptor on the customer's statement. If this parameter is not included, the default descriptor (as set up on the merchant account that is originating the transactions) will be used. When applicable, this information will be passed along to the gateway. This value is cached in the one-time-use token. For some gateway connections, you can pass `descriptor` as an object with several potential parameters. For more information about these parameters, see the [NMI integration guide](https://docs.nexiopay.com/docs/nmi-integration-guide) or the [USAePay integration guide](https://docs.nexiopay.com/docs/usaepay-integration-guide). Contact [Integrations Support](https://docs.nexiopay.com/page/contact-us) if you have any questions about this parameter.
    - `dueDate` string — The date by which the customer must complete the payment. If the transaction is not settled before this date, it will be voided. If you do not provide a value, the system automatically sets the date to be 30 days from the current date. <b>Note:</b> Date cannot be more than 30 days in the future. 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, with as much of the time part as wanted.<br>For example, `2001-08-26T13:35:00Z` or `1990-12-05T00:00Z`. - UNIX date (as an integer representing seconds).<br>For example, `998854500`. This parameter only applies for the PayNet alternative payment method.
    - `locale` string — The [two-character ISO 639-1 code](https://en.wikipedia.org/wiki/ISO_639-1) for the language locale for this transaction, a hyphen, and the [two-character (Alpha-2) ISO country code](https://www.iso.org/obp/ui/#search/code/). This parameter can only be used with [Klarna](https://docs.nexiopay.com/docs/klarna-integration-guide) (either `klarnaPayments` or `klarnaCheckout`). The system uses this value to display the payment popup to the user in the specified language as long as this locale value, the `data.currency`, and the `data.customer.billToCountry` all match. For information about how they need to match, see the [Purchase country, locale, and currency](https://docs.klarna.com/klarna-payments/in-depth-knowledge/puchase-countries-currencies-locales/) page in the Klarna documentation.
    - `paymentMethod` PaymentMethod — unresolved $ref
  - `customerRedirectUrl` string — The URL to which the customer will be redirected after completing their payment. The customer will be sent here upon successful or failed payment. This URL must use the HTTPS protocol.
  - `isAuthOnly` boolean — Set to `true` to run an auth only transaction. <!-- theme:info --> > #### Note > Auth only transactions are not supported by all alternative payment methods. An error message is returned if you attempt an auth only transaction through an alternative payment method that does not support this feature.
  - `processingOptions` object — Processing options for the potential APM transaction.
    - `paymentOptionTag` string — A custom value used to route transactions to a specific gateway or merchant account. This value is cached in the one-time-use token. Contact [Integrations Support](https://docs.nexiopay.com/page/contact-us) to designate a `paymentOptionTag` for a given merchant account.
    - `doNotProcessPayment` boolean — Set to `true` when using the 'continue button' payment flow on a shopping cart page. This allows the consumer to log in to the APM and set address information, such as with Braintree PayPal.
    - `saveRecurringToken` boolean — Set to `true` to get a token in order to process merchant-initiated recurring transactions, such as with [PayPal (with Braintree)](https://docs.nexiopay.com/docs/paypal-with-braintree-integration-guide). For a tutorial for alternative payment methods, see the [Run a merchant-initiated recurring transaction](https://docs.nexiopay.com/docs/run-a-merchant-initiated-recurring-transaction) topic.
    - `merchantId` MerchantId — unresolved $ref
  - `uiOptions` object — Used to customize the iframe's user interface
    - `css` string — The URL where your custom CSS file is hosted. This value is cached in the one-time-use token.
    - `displaySubmitButton` boolean — Set to `true` to include a submit button in the iframe. This value is cached in the one-time-use token.

## Response `200`

Success

- object — The One-time-use Token
  - `expiration` Expiration — unresolved $ref
  - `token` Token — unresolved $ref
  - `asyncTraceId` string — The high-level ID of the unprocessed APM transaction for tracking progress and status. Use this value with the [View APM transaction async status](https://docs.nexiopay.com/reference/viewapmtransactionasyncstatus) endpoint to track the status of an APM transaction from loading the APM button or form and getting a response back from the payment provider.
  - `expressIFrameUrl` string — The Express APM redirect URL. Allows the shopper to choose from a list of available APMs before redirecting for payment. See the [Multi Iframe (Express APM)](https://docs.nexiopay.com/docs/multi-iframe-express-apm) tutorial in Guides for more information.
  - `redirectUrls` object[] — A collection of redirect URLs. Can be used to send a customer directly to a single APM. See the APM [Custom Redirect (Redirect URLs)](https://docs.nexiopay.com/docs/custom-redirect-redirect-urls) tutorial in Guides for more information.
    - `paymentMethod` string — The name of the [alternative payment method](https://docs.nexiopay.com/docs/payment-methods).
    - `url` string — The redirect URL. Will redirect the shopper to the alternative payment method for payment.
  - `buttonIFrameUrls` object[] — A collection of button iframe URLs. Each URL can be used to load a button that will redirect the shopper to the selected APM. See the APM [Individual Iframe (Button URLs)](https://docs.nexiopay.com/docs/individual-iframe-button-urls) tutorial in Guides for more information.
    - `paymentMethod` PaymentMethod — unresolved $ref
    - `url` string — The button iframe URL. Will load a button to redirect the shopper to the alternative payment method for payment.

## 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)