Token API

The Token API allows you to create and retrieve information about tokens. A token represents a card and can only be used once in some places where a card is required. Once created, tokens can be converted to cards for attachment to customers for future charges.

Full credit card data should never go through your server.

Do not send the credit card data to Omise from your servers directly. You must send the card data from the client browser via Javascript (Omise-JS). The methods described on this page should only be used with fake data in test mode (e.g.: quickly creating some fake data, testing our API from a terminal, etc.). If you are PCI-DSS compliant, sending card data from server requires a valid PCI-DSS certification.

You can learn more about this in Security Best Practices.

Attributes

Name Type Description
object string

The string token.

id object_id

The token identifier matching /tokn(_test)?_[0-9a-z]+/.

livemode boolean

Whether this is a live (true) or test (false) token.

location string

API path to retrieve the current token object.

card card

Card containing details of card used to generate token.

created_at datetime

UTC datetime of token creation in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

used boolean

Whether token has been used. Tokens can be used only once either to make a charge or to associate as a new card on a customer.

Example

  • JSON Response

Create a token

- POST https://vault.omise.co/tokens

Creates and returns a new token.

  • Tokens are single-use only
  • This endpoint accepts public key authentication only
  • This endpoint is for testing. In production, use Omise.js to generate tokens
  • To get the most benefit from out automated fraud protection, it is highly recommended to capture billing address details, especially for customers from the United States and Canada.

Request Parameters

Name Type Description
card[expiration_month] integer

(required) Card expiration month (M or MM).

card[expiration_year] integer

(required) Card expiration year (YY or YYYY).

card[name] string

(required) Card owner name.

card[number] string

(required) Card number.

card[city] string

(optional, but recommended) Billing address city.

card[country] string

(optional, but recommended) Billing address country as two-letter ISO 3166 code. Note: if not supplied at token creation, value derived from issuer identification number (IIN) so may not be accurate.

card[phone_number] string

(optional, but recommended) Billing address phone number.

card[postal_code] string

(optional, but recommended) Card postal code.

card[security_code] string

(optional, but recommended) Card security code (CVV, CVC, etc). Printed on the back.

card[state] string

(optional, but recommended) Billing address state.

card[street1] string

(optional, but recommended) Billing address street #1.

card[street2] string

(optional, but recommended) Billing address street #2.

Example

  • Create a token

  • Create a token using a US card

Retrieve a token

- GET https://vault.omise.co/tokens/{id}

Returns the token matching :id. Note: this endpoint accepts only public key authentication.

Example

  • Retrieve a token