Token API

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

Attribute

Name	Type	Description
object	string	The string `token`.
id	string	The `TOKEN_ID`.
livemode	boolean	Whether this is a live (`true`) or test (`false`) token.
location	string	Path to retrieve the token.
used	boolean	Whether the token has been used or not. Tokens can be used only once to make a charge on their card or to associate the card to a customer.
card	card	A card object.
created	datetime	Creation date of the token in ISO 8601 format.

Example

Json Response

{
  "object": "token",
  "id": "tokn_test_5086xl7c9k5rnx35qba",
  "livemode": false,
  "location": "https://vault.omise.co/tokens/tokn_test_5086xl7c9k5rnx35qba",
  "used": false,
  "card": {
    "object": "card",
    "id": "card_test_5086xl7amxfysl0ac5l",
    "livemode": false,
    "country": "us",
    "city": "Bangkok",
    "postal_code": "10320",
    "financing": "",
    "bank": "Card Bank",
    "last_digits": "4242",
    "brand": "Visa",
    "expiration_month": 10,
    "expiration_year": 2018,
    "fingerprint": "mKleiBfwp+PoJWB/ipngANuECUmRKjyxROwFW5IO7TM=",
    "name": "Somchai Prasert",
    "security_code_check": true,
    "created": "2015-06-02T05:41:46Z"
  },
  "created": "2015-06-02T05:41:46Z"
}

Create a token

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

Request Parameter

Name	Type	Description
card[name]	string	The cardholder name as printed on the card.
card[number]	string	The card number. Note that the number you pass can contains spaces and dashes but will be stripped from the response.
card[expiration_month]	integer	The expiration month printed on the card in the format M or MM.
card[expiration_year]	integer	The expiration year printed on the card in the format YYYY.
card[security_code]	string	The security code (CVV, CVC, etc) printed on the back of the card.
card[city]	string	The city where the card was issued.
card[postal_code]	string	The postal code from the city where the card was issued.

Example

Create a token

curl
ruby
python
php
C#
node.js
java
go

curl https://vault.omise.co/tokens \
  -X POST \
  -u pkey_test_4xs8breq32civvobx15: \
  -d "card[name]=Somchai Prasert" \
  -d "card[number]=4242424242424242" \
  -d "card[expiration_month]=10" \
  -d "card[expiration_year]=2018" \
  -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: 2018,
  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=2018,
  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' => 2018,
    'city' => 'Bangkok',
    'postal_code' => '10320',
    'security_code' => 123
  )
));

var token = await Client.Tokens.Create(new CreateTokenRequest
{
    Name = "John Doe",
    Number = "4242424242424242",
    ExpirationMonth = 10,
    ExpirationYear = 2019,
    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': 2017,
    'security_code': 123
  }
}, function(error, token) {
  /* Response. */
});

Token token = client().tokens()
        .create(new Token.Create()
                .card(new Card.Create()
                        .name("Somchai Prasert")
                        .number("4242424242424242")
                        .expirationMonth(10)
                        .expirationYear(2018)
                        .city("Bangkok")
                        .postalCode("10320")
                        .securityCode("123")
                )
        );

System.out.println("created token: " + token.getId());

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

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

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

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

Retrieve a token

- GET https://vault.omise.co/tokens/TOKEN_ID

Example

Retrieve a token

curl
ruby
python
php
C#
node.js
java
go

curl https://vault.omise.co/tokens/tokn_test_4xs9408a642a1htto8z \
  -u pkey_test_4xs8breq32civvobx15:

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. */
});

Token token = client.tokens().get("tokn_test_4xs9408a642a1htto8z");
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)