Token API

Create and retrieve information about tokens. A token represents a credit or debit card. Once created, a token can be used to create a single charge or attached to a customer as a card to create multiple charges.

Attributes

Name	Type	Description
object	string	The string `token`.
id	string	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.
charge_status	string	Status of charge created using this token (if any). Value is one of allowed `charge.status` values or, no charge has been created, `unknown`.
created_at	string	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_no1t4tnemucod0e51mo",
  "livemode": false,
  "location": "https://vault.omise.co/tokens/tokn_test_no1t4tnemucod0e51mo",
  "used": false,
  "charge_status": "unknown",
  "card": {
    "object": "card",
    "id": "card_test_no1t4tnemucod0e51mo",
    "livemode": false,
    "location": null,
    "deleted": false,
    "street1": "1448/4 Praditmanutham Road",
    "street2": null,
    "city": "Bangkok",
    "state": null,
    "phone_number": "0123456789",
    "postal_code": "10320",
    "country": "th",
    "financing": "credit",
    "bank": "Bank of the Unbanked",
    "brand": "Visa",
    "fingerprint": "XjOdjaoHRvUGRfmZacMPcJtm0U3SEIIfkA7534dQeVw=",
    "first_digits": null,
    "last_digits": "4242",
    "name": "Somchai Prasert",
    "expiration_month": 12,
    "expiration_year": 2024,
    "security_code_check": true,
    "tokenization_method": null,
    "created_at": "2019-12-31T12:59:59Z"
  },
  "created_at": "2019-12-31T12:59:59Z"
}

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.

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. Supplying the cardholder's billing address improves your authorization rate for US, UK, and Canadian cardholders.
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. Supplying the cardholder's billing address improves your authorization rate for US, UK, and Canadian cardholders.
card[email]	string	(optional, but recommended) The email address of the customer.
card[phone_number]	string	(optional) Phone number.
card[postal_code]	string	(optional, but recommended) Card postal code. Supplying the cardholder's billing address improves your authorization rate for US, UK, and Canadian cardholders.
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. Supplying the cardholder's billing address improves your authorization rate for US, UK, and Canadian cardholders.
card[street1]	string	(optional, but recommended) Billing address street #1. Supplying the cardholder's billing address improves your authorization rate for US, UK, and Canadian cardholders.
card[street2]	string	(optional) Billing address street #2.

Example

Create a token

Omise.js
Android SDK
iOS SDK
curl
php
node.js
ruby
C#
java
python
go
elixir

Omise.setPublicKey("OMISE_PUBLIC_KEY");

Omise.createToken("card",
                  {
                    "expiration_month": 2,
                    "expiration_year": 2022,
                    "name": "Somchai Prasert",
                    "number": "4242424242424242",
                    "security_code": "123",
                    "street1": "476 Fifth Avenue",
                    "city": "New York",
                    "state": "NY",
                    "postal_code": "10320",
                    "country": "US"
                  },
                  function(statusCode, response) {
                    console.log(response["id"])
                  });

private val client = Client("pkey_test_123")

val cardParam = CardParam(
                name = "JOHN Doe",
                number = "4242424242424242",
                expirationMonth = 10,
                expirationYear = 2020,
                securityCode = "123"
                )

val request = Token.CreateTokenRequestBuilder(cardParam).build()

client.send(request, object: RequestListener<Token>{
   override fun onRequestSucceed(model: Token) {
      // you created a token
   }

    override fun onRequestFailed(throwable: Throwable) {
      // something bad happened
    }
})

let tokenParameter = Token.CreateParameter(
    name: "JOHN DOE",
    number: "4242424242424242",
    expirationMonth: 11,
    expirationYear: 2019,
    securityCode: "123"
)

let request = Request<Token>(parameter: tokenParameter)
let requestTask = client.requestTask(with: request, completionHandler: completionHandler)
requestTask.resume()

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]=2025" \
  -d "card[city]=Bangkok" \
  -d "card[postal_code]=10320" \
  -d "card[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
  )
));

const omise = require('omise')({
  publicKey: 'pkey_test_no1t4tnemucod0e51mo',
});

const token = await omise.tokens.create({
  card: {
    name: 'JOHN DOE',
    city: 'Bangkok',
    postal_code: 10320,
    number: '4242424242424242',
    expiration_month: 2,
    expiration_year: 2027,
    security_code: 123,
  },
});
console.log(token);

require "omise"

Omise.public_api_key = "pkey_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
})

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}");

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());

import omise

omise.api_public = "pkey_test_no1t4tnemucod0e51mo"

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

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Card{}

err := client.Do(result, &operations.CreateToken{
	Name:            "Somchai Prasert",
	Number:          "4242424242424242",
	ExpirationMonth: 10,
	ExpirationYear:  2025,

	City:         "Bangkok",
	PostalCode:   "10320",
	SecurityCode: "123",
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

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

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
php
node.js
ruby
C#
java
python
go
elixir

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

<?php

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

const omise = require('omise')({
  publicKey: 'pkey_test_no1t4tnemucod0e51mo',
});

const token = await omise.tokens.retrieve('tokn_test_5v3exp0j9e5s7oicmzs');
console.log(token);

require "omise"

Omise.public_api_key = "pkey_test_4xs8breq3htbkj03d2x"

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

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

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());

import omise

omise.api_public = "pkey_test_no1t4tnemucod0e51mo"

token = omise.Token.retrieve("tokn_test_no1t4tnemucod0e51mo")

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Token{}

err := client.Do(result, &operations.RetrieveToken{
	ID: "tokn_test_no1t4tnemucod0e51mo",
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(public_key: "pkey_test_56bywcp7sk1qselsyqb")

Omise.Token.retrieve("tokn_test_4xs9408a642a1htto8z")