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.

The endpoints described on this page should only be used with test data. In production, tokens should be created and sent directly to our servers from the client using Omise.js, or, if on mobile, the iOS or Android SDKs.

Sending card data from server requires a valid PCI-DSS certification in order to be compliant. 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

{
  "object": "token",
  "id": "tokn_test_5fvso3he9xmo0buqmms",
  "livemode": false,
  "location": "https://vault.omise.co/tokens/tokn_test_5fvso3he9xmo0buqmms",
  "used": false,
  "card": {
    "object": "card",
    "id": "card_test_5fvso3hd5sdlh2n47u1",
    "livemode": false,
    "street1": null,
    "street2": null,
    "city": "Bangkok",
    "state": null,
    "postal_code": "10320",
    "country": "gb",
    "phone_number": null,
    "financing": "credit",
    "bank": "Bank of the Unbanked",
    "last_digits": "4242",
    "brand": "Visa",
    "expiration_month": 12,
    "expiration_year": 2022,
    "fingerprint": "XjOdjaoHRvUGRfmZacMPcJtm0U3SEIIfkA7534dQeVw=",
    "name": "Somchai Prasert",
    "security_code_check": true,
    "created_at": "2019-05-13T04:36:56Z"
  },
  "created_at": "2019-05-13T04:36:56Z"
}

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 our 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

curl
ruby
python
php
C#
node.js
java
go
elixir

curl https://vault.omise.co/tokens \
  -u $OMISE_PUBLIC_KEY: \
  -d "card[name]=Somchai Prasert" \
  -d "card[number]=4242424242424242" \
  -d "card[expiration_month]=10" \
  -d "card[expiration_year]=2022" \
  -d "card[city]=Bangkok" \
  -d "card[postal_code]=10320" \
  -d "card[security_code]=123"

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

token = Omise::Token.create(card: {
  name: "Somchai Prasert",
  number: "4242424242424242",
  expiration_month: 10,
  expiration_year: 2022,
  city: "Bangkok",
  postal_code: "10320",
  security_code: 123
})

import omise

omise.api_secret = 'skey_test_4xs8breq3htbkj03d2x'

token = omise.Token.create(
  name="Somchai Prasert",
  number="4242424242424242",
  expiration_month=10,
  expiration_year=2022,
  city="Bangkok",
  postal_code="10320",
  security_code=123
)

<?php

$token = OmiseToken::create(array(
  'card' => array(
    'name' => 'Somchai Prasert',
    'number' => '4242424242424242',
    'expiration_month' => 10,
    'expiration_year' => 2022,
    'city' => 'Bangkok',
    'postal_code' => '10320',
    'security_code' => 123
  )
));

var token = await Client.Tokens.Create(new CreateTokenRequest
{
    Name = "John Doe",
    Number = "4242424242424242",
    ExpirationMonth = 10,
    ExpirationYear = 2022,
    SecurityCode = "123",
});

Console.WriteLine($"created token: {token.Id}");

omise.tokens.create({
  'card':{
    'name': 'JOHN DOE',
    'city': 'Bangkok',
    'postal_code': 10320,
    'number': '4242424242424242',
    'expiration_month': 2,
    'expiration_year': 2022,
    'security_code': 123
  }
}, function(error, token) {
  /* Response. */
});

Request<Token> request = new Token.CreateRequestBuilder()
        .card(new Card.Create()
                .name("John Doe")
                .number("4242424242424242")
                .expirationMonth(10)
                .expirationYear(2022)
                .city("Casablanca")
                .postalCode("10420")
                .securityCode("123"))
        .build();
Token token = client().sendRequest(request);

System.out.printf("Created token: %s", token.getId());

card, createToken := &omise.Card{}, &operations.CreateToken{
	Name:            "Somchai Prasert",
	Number:          "4242424242424242",
	ExpirationMonth: 10,
	ExpirationYear:  2022,

	City:         "Bangkok",
	PostalCode:   "10320",
	SecurityCode: "123",
}

if e := client.Do(card, createToken); e != nil {
	log.Fatalln(e)
}

log.Printf("created card: %#v\n", card)

Omise.configure(public_key: "pkey_test_56bywcp7sk1qselsyqb")

Omise.Token.create(
  card: [
    name:             "Somchai Prasert",
    number:           "4242424242424242",
    expiration_month: 10,
    expiration_year:  2022,
    city:             "Bangkok",
    postal_code:      "10320",
    security_code:    123
  ]
)

Create a token using a US card

curl
ruby
python
php
C#
node.js
java
go
elixir

curl https://vault.omise.co/tokens \
  -u $OMISE_PUBLIC_KEY: \
  -d "card[name]=Somchai Prasert" \
  -d "card[number]=4242424242424242" \
  -d "card[expiration_month]=10" \
  -d "card[expiration_year]=2022" \
  -d "card[city]=New York City" \
  -d "card[state]=New York" \
  -d "card[street1]=476 5th Ave" \
  -d "card[country]=US" \
  -d "card[postal_code]=10018" \
  -d "card[security_code]=123"

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

curl
ruby
python
php
C#
node.js
java
go
elixir

curl https://vault.omise.co/tokens/tokn_test_5g5mep9yrko3vx2f0hx \
  -u $OMISE_PUBLIC_KEY:

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

token = Omise::Token.retrieve("tokn_test_4xs9408a642a1htto8z")

import omise

omise.api_secret = 'skey_test_4xs8breq3htbkj03d2x'

token = omise.Token.retrieve('tokn_test_4xs9408a642a1htto8z')

<?php

$token = OmiseToken::retrieve('tokn_test_4xs9408a642a1htto8z');

var tokenId = RetrieveTokenId();
var token = await Client.Tokens.Get(tokenId);
Console.WriteLine($"token already used? {token.Used}");

omise.tokens.retrieve('tokn_test_4xs9408a642a1htto8z', function(error, token) {
  /* Response. */
});

Request<Token> request = new Token.GetRequestBuilder("tokn_test_4xs9408a642a1htto8z").build();
Token token = client().sendRequest(request);

System.out.printf("token last digits: %s", token.getCard().getLastDigits());

token, retrieve := &omise.Token{}, &operations.RetrieveToken{
	ID: "tokn_test_4xs9408a642a1htto8z"
}

if e := client.Do(token, retrieve); e != nil {
	log.Fatalln(e)
}

log.Printf("retrieved token: %#v\n", token)

Omise.configure(public_key: "pkey_test_56bywcp7sk1qselsyqb")

Omise.Token.retrieve("tokn_test_4xs9408a642a1htto8z")