---
title: "Save card token"
method: POST
path: "/pay/v3/saveCard"
tags: ["Ecommerce"]
---

# Save card token

`POST /pay/v3/saveCard`

Allows you to securely save a card token [using your own form](https://docs.nexiopay.com/docs/creating-a-save-card-page-with-your-own-form) or [using the API directly](https://docs.nexiopay.com/docs/saving-a-card-token-with-the-api) (potentially without a web browser). You can use this endpoint to save a new card token or add pre-existing TokenEx tokens that you would like to start using through Nexio. 

You can use this saved card token to run a card transaction using the [Run card transaction with iframe](https://docs.nexiopay.com/reference/runcardtransactioniframe) or [Run card transaction](https://docs.nexiopay.com/reference/runcardtransaction) endpoint. 

Card tokens can be used to process transactions through any MID on your account. They are not restricted to a specific merchant account or currency.

For instructions on how to implement this endpoint, see [Creating a save card page with your own form](https://docs.nexiopay.com/docs/creating-a-save-card-page-with-your-own-form) or [Saving a card token with the API](https://docs.nexiopay.com/docs/saving-a-card-token-with-the-api). 

For a tutorial about running a transaction with the saved card token, see the [Creating a card checkout page with the iframe](https://docs.nexiopay.com/docs/creating-a-card-checkout-page-with-the-iframe), [Creating a card checkout page with your own form](https://docs.nexiopay.com/docs/creating-a-card-checkout-page-with-your-own-form), or [Running a card transaction with the API](https://docs.nexiopay.com/docs/running-a-card-transaction-with-the-api) topic.

<!-- theme: info -->
> 📘 Note 
> 
> Processing options must be sent in the request for a [one-time-use token](https://docs.nexiopay.com/reference/createonetimeusetoken). For more information, see [What data is saved with tokens?](https://docs.nexiopay.com/docs/what-data-is-saved-with-tokens) in Guides.

<!-- theme: warning -->
> ⚠️ Try It
> 
> To use the Try It feature for this endpoint, include at least the following in the body of the request:
> - A [one-time-use token](https://docs.nexiopay.com/reference/createonetimeusetoken) - this replaces the standard username/password and authentication header
> - `card.cardHolderName`
> - `card.expirationMonth`
> - `card.expirationYear`
> - Either `card.encryptedNumber` or `tokenex.token` (an existing TokenEx card token)
> For information about test card numbers and values you can use, see the documentation for the specific [gateway/connection integration guide](https://docs.nexiopay.com/docs/connections) or, if you are testing Account Updater, see the [Test cards for account updater](https://docs.nexiopay.com/docs/checking-a-cards-enrollment-tag#test-cards-for-account-updater) section of the "Checking a card's enrollment tag" topic.


<div style="display:none;">

## Request parameters
- card
- card.cardHolderName
- card.encryptedNumber
- card.expirationMonth
- card.expirationYear
- card.cardType
- card.securityCode
- card.firstSix
- card.lastFour
- token
- data
- data.customer
- 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.firstName
- data.customer.invoice
- data.customer.lastName
- data.customer.phone
- data.customer.shipToAddressOne
- data.customer.shipToAddressTwo
- data.customer.shipToCity
- data.customer.shipToCountry
- data.customer.shipToPhone
- data.customer.shipToPostal
- data.customer.shipToState
- shouldUpdateCard
- tokenex
- tokenex.token
- tokenex.firstSix
- tokenex.lastFour
- merchantId

## Response parameters
- card
- card.cardHolderName
- card.expirationMonth
- card.expirationYear
- card.cardType
- data
- data.customer
- 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.email
- data.customer.firstName
- data.customer.lastName
- data.customer.phone
- data.customer.shipToAddressOne
- data.customer.shipToAddressTwo
- data.customer.shipToCity
- data.customer.shipToCountry
- data.customer.shipToPhone
- data.customer.shipToPostal
- data.customer.shipToState
- kountResponse
- kountResponse.status
- kountResponse.rules
- merchantId
- shouldUpdateCard
- token
- token.token
- token.firstSix
- token.lastFour
- token.cardType
- cvcResults
- cvcResults.matchCvv
- cvcResults.error
- cvcResults.gatewayMessage
- cvcResults.gatewayMessage.cvvresponse
- cvcResults.gatewayMessage.message
- avsResults
- avsResults.matchAddress
- avsResults.matchPostal
- avsResults.error
- avsResults.gatewayMessage
- avsResults.gatewayMessage.avsresponse
- avsResults.gatewayMessage.message
- cardType

</div>

## Request body

- object
  - `token` string, required — A [one-time-use token](https://docs.nexiopay.com/reference/createonetimeusetoken). This value is saved in the card/echeck token as `key`.
  - `card` object, required — Card information.
    - `cardHolderName` CardHolderName, required — unresolved $ref
    - `expirationMonth` ExpirationMonth, required — unresolved $ref
    - `expirationYear` ExpirationYear, required — unresolved $ref
    - `encryptedNumber` string — The encrypted card number. **Conditionally required**. Either this or the `tokenex.token` parameter is required. For instructions on encrypting the card number, see **step 6** in the [Creating a save card page with your own form](https://docs.nexiopay.com/docs/creating-a-save-card-page-with-your-own-form) topic in Guides. For information about test card numbers and values you can use, see the documentation for the specific [gateway/connection integration guide](https://docs.nexiopay.com/docs/connections) or, if you are testing Account Updater, see the [Test cards for account updater](https://docs.nexiopay.com/docs/checking-a-cards-enrollment-tag#test-cards-for-account-updater) section of the "Checking a card's enrollment tag" topic.
    - `cardType` 'amex' | 'discover' | 'jcb' | 'mastercard' | 'visa' — The card type. **Conditionally required**. This information is required when [saving a card through your own form](https://docs.nexiopay.com/docs/creating-a-save-card-page-with-your-own-form). This value is saved in the card token (in `card.cardType`, `cardType`, and `tokenex.cardType`). You can specify any value for this parameter when saving to the card token, including the ones listed in this reference, but also other text such as "American Express" or "americanExpress" or "Diners Club". This information is saved to the card token. However, when using that saved card token to run a transaction, the system ignores the value and determines the type based on the card values used. When the card type is not one of the indicated options, the system returns unknown for the `cardType`, or returns `null` when using one of the View transaction endpoints. For a list of card types enabled for the merchant account, see the [View card types](https://docs.nexiopay.com/reference/viewcardtypes) endpoint.
    - `securityCode` string — The numeric code printed on the card for enhanced security. Because the code may start with a leading zero (0), you should send this as a string rather than an integer (even though both types are supported in the request). <!-- theme: warning --> > 🛑 Warning > > Storing this value on your servers is prohibited by the PCI-Data Security Standard. When included in the request, Nexio caches the value for up to 24 hours. Therefore, if you save the card token and then submit a transaction with that card token more than 24 hours later, you need to recapture the security code.
    - `firstSix` FirstSix — unresolved $ref
    - `lastFour` LastFour — unresolved $ref
  - `tokenex` object — TokenEx card token information.
    - `token` string — A previously saved TokenEx card token. **Conditionally required.** Either this or the `card.encryptedNumber` parameter is required. This value is saved in the card token. Use this parameter if you have pre-existing TokenEx tokens you would like to start using through Nexio. **Note:** You will get an error if you try to use a card token generated through Nexio. Card tokens can be used to process through any MID on your account. They are not restricted to a specific merchant account or currency.
    - `firstSix` FirstSix — unresolved $ref
    - `lastFour` LastFour — unresolved $ref
  - `data` object — Additional optional data
    - `customer` object — Customer information to be used in checking fraud or sent to the processing gateway, when applicable.
      - `invoice` string — The invoice number.
      - `firstName` string — The customer's first name, as it appears on the card or account. This value is saved in the card/echeck token.
      - `lastName` string — The customer's last name, as it appears on the card or account. This value is saved in the card/echeck token.
      - `birthDate` string — The customer's date of birth. This value is saved in the card/echeck 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`.
      - `email` string — The customer's email address. This value is saved in the card/echeck token.
      - `phone` string — The customer's phone number. This value is saved in the card/echeck token.
      - `billToAddressOne` string — The street address on file with the provider. This value is saved in the card/echeck token.
      - `billToAddressTwo` string — Additional street address information, if required. This value is saved in the card/echeck token.
      - `billToCity` string — The city on file with the provider. This value is saved in the card/echeck token.
      - `billToState` string — The state or province on file with the provider. (If in the US, this must be the [two-character state abbreviation](https://pe.usps.com/text/pub28/28apb.htm)). This value is saved in the card/echeck token.
      - `billToPostal` string — The postal code on file with the provider. This value is saved in the card/echeck token.
      - `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 provider. This value is saved in the card/echeck token.
      - `billToPhone` string — The billing phone number. This value is saved in the card/echeck token.
      - `shipToAddressOne` string — The shipping address, if different from the billing address. This value is saved in the card/echeck token.
      - `shipToAddressTwo` string — Additional shipping address information, if required. This value is saved in the card/echeck token.
      - `shipToCity` string — The shipping city. This value is saved in the card/echeck token.
      - `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).) This value is saved in the card/echeck token.
      - `shipToPostal` string — The shipping postal code. This value is saved in the card/echeck token.
      - `shipToCountry` string — The [two-character (Alpha-2) ISO](https://www.iso.org/obp/ui/#search/code/) shipping country code. This value is saved in the card/echeck token.
      - `shipToPhone` string — The shipping phone number. This value is saved in the card/echeck token.
      - `createdAtDate` CreatedAtDate — unresolved $ref
  - `shouldUpdateCard` boolean — The card's account updater [enrollment tag](https://docs.nexiopay.com/docs/checking-a-cards-enrollment-tag). This value is saved in the card token. When true, the card token is tagged for being sent to the account updater provider. <!-- theme:info --> > #### Note > The card will not be registered until the merchant account is enrolled. See the [Enrollment tag table](https://docs.nexiopay.com/docs/checking-a-cards-enrollment-tag#enrollment-tag-table) for more information.
  - `merchantId` string — The Nexio merchant ID (MID). Generally, you should avoid sending this value in the request because it may interfere with several Nexio features. The API user you use directs the transaction to the appropriate MID automatically. This value is saved in the card/echeck token.

## Response `200`

Success

- object
  - `token` object — Card token information
    - `token` string — The saved card token.
    - `firstSix` FirstSix — unresolved $ref
    - `lastFour` LastFour — unresolved $ref
    - `cardType` CardType — unresolved $ref
  - `card` object — Card information
    - `cardType` CardType — unresolved $ref
    - `cardHolderName` string — The cardholder's name as it appears on the card. This value is cached in the one-time-use token.
    - `expirationMonth` string — The one-digit or two-digit month in which the card expires. The system validates that the value is between 1 and 12. This value is cached in the one-time-use token.
    - `expirationYear` string — The two-digit year in which the card will expire. This value is cached in the one-time-use token.
    - `classification` 'business' | 'personal' — The card classification. Only returned when it is saved in the card token.
    - `businessNumber` string — A string containing 10 digits. Only returned when it is saved in the card token.
    - `password` string — A string containing two digits. Only returned when it is saved in the card token.
  - `cardType` 'amex' | 'discover' | 'jcb' | 'mastercard' | 'visa' — The card type.
  - `data` object — Additional data, if provided in the request
    - `customer` object — Customer information returned when checking fraud or from the processing gateway, when applicable.
      - `firstName` string — The customer's first name.
      - `lastName` string — The customer's last name.
      - `birthDate` string — The customer's date of birth. The format returned matches the format used in the request that [created the card token](https://docs.nexiopay.com/reference/savecardtoken).
      - `email` string — The customer's email address.
      - `phone` string — The customer's phone number.
      - `billToAddressOne` string — The street address on file with the card provider.
      - `billToAddressTwo` string — Additional street address information.
      - `billToCity` string — The city on file with the card provider.
      - `billToState` string — The state or province on file with the card provider. (If in the US, this is the [two-character state abbreviation](https://pe.usps.com/text/pub28/28apb.htm)).
      - `billToPostal` string — The postal code on file with the card provider.
      - `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 card provider.
      - `billToPhone` string — The billing phone number.
      - `shipToAddressOne` string — The shipping address.
      - `shipToAddressTwo` string — Additional shipping address information.
      - `shipToCity` string — The shipping city.
      - `shipToState` string — The shipping state or province. (If in the US, this is 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.
  - `merchantId` string — The merchant account under which the card token is saved.
  - `shouldUpdateCard` boolean — The card's account updater [enrollment tag](https://docs.nexiopay.com/docs/checking-a-cards-enrollment-tag). When the value is `true`, the card token was tagged for being sent to the account updater provider. <!-- theme:info --> > #### Note > The card is not registered until the merchant account is enrolled. For more information, see the [Enrollment tag table](https://docs.nexiopay.com/docs/checking-a-cards-enrollment-tag#enrollment-tag-table).
  - `kountResponse` object — Fraud data and rules
    - `status` string — Will be one of four possible statuses: `success`, `review`, `decline`, or `error`. See [Kount response status](https://docs.nexiopay.com/docs/understanding-the-kount-response) in Guides for more information.
    - `rules` string — Kount-specific information, including rules triggered. See our [Fraud tutorial](https://docs.nexiopay.com/docs/understanding-the-kount-response) in Guides for more information.
  - `avsResults` object — If a value for `verifyAvs` was specified in the request for a one-time use token, then the Save card token endpoint includes this object in the response. For information about interpreting the response, see the [Enabling the Address Verification Service](https://docs.nexiopay.com/docs/enabling-the-address-verification-service) topic in Guides.
    - `error` boolean — Specifies whether the `verifyAvs` check succeeded or failed. A value of `false` indicates that there was no error in processing the check (for either `matchAddress` or `matchPostal`). A value of `true` indicates that a problem occured when doing the check, but the card token was still saved.
    - `matchAddress` boolean — The results of the US-based address check. The result is `true` when the address provided matches the address on file with the card issuer. (In this case, 'address' refers to the street address portion of the billing address. For example, if the address provided were `123 Sesame St. Manhattan, NY 10128`, matchAddress would compare `123 Sesame St.` with the address on file.)
    - `matchPostal ` boolean — The results of the US-based postal code check. The result is `true` when the postal code provided matches the postal code on file with the card issuer. (For example, if the address provided were `123 Sesame St. Manhattan, NY 10128`, matchPostal would compare `10128` with the postal code on file.)
    - `gatewayMessage` object — Information from the verification provider about the `verifyAvs` request.
      - `avsresponse` string — The code provided by the verification provider. For more information about the response, see the [Understanding the AVS response](https://docs.nexiopay.com/docs/understanding-the-avs-response) topic in Guides.
      - `message` string — The message received from the verification provider. For more information about this response, see the [Understanding the AVS response](https://docs.nexiopay.com/docs/understanding-the-avs-response) topic in Guides.
  - `cvcResults` object — If `verifyCvc` was specified in the request for a one-time use token, then the Save card token endpoint includes this object in the response.
    - `matchCvv` boolean — Specifies whether the security code verification check process completed. If the security code check was successful, the response is `true`. If this is `false` or this parameter is not returned, then there was a problem. A value of `false` indicates that the verification check failed and the card token was not saved.
    - `error` boolean — Specifies whether the `verifyCvc` check succeeded or failed. A value of `false` indicates that there was no error in processing the check (whether the `matchCvv` was true or false). A value of `true` indicates that a problem occured when doing the check, but the card token was still saved.
    - `gatewayMessage` object — Information from the verification provider about the `verifyCvc` request.
      - `cvvresponse` 'M' | 'N' | 'P' | 'S' | 'U' | 'X' — The code provided by the verification provider. This may be an M, N, P, S, U, or X. A response of `M` indicates that the check of the security code was successful and it is valid for the card. For more information about these values, see the [Handling security code verification failures](https://docs.nexiopay.com/docs/handling-security-code-verification-failures) topic in Guides.
      - `message` string — The message received from the verification provider. For more information about possible strings, see the [Handling security code verification failures](https://docs.nexiopay.com/docs/handling-security-code-verification-failures) topic in Guides.

## Other responses

- `400` — Bad Request
- `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)