Create a Token

POSThttps://vault.omise.co/tokens

Create a single-use token from credit card information. Tokens securely represent card data and can be used to create charges without handling sensitive card information on your servers.

---

🔑API Credentials

▼

---

Request Parameters

Required - 4 fieldsRequired Parameters

▼

`card[name]`STRING(required)

Cardholder name as it appears on the card.

Example:"JOHN DOE"

`card[number]`STRING(required)

Card number without spaces or dashes. 13-19 digits depending on card type.

Example:"4242424242424242"

Constraints:13-19 digits, Must pass Luhn check, No spaces or dashes

`card[expiration_month]`INTEGER(required)

Card expiration month in M or MM format.

Example:12

Constraints:Minimum: 1, Maximum: 12

`card[expiration_year]`INTEGER(required)

Card expiration year in YY or YYYY format.

Example:2025

Constraints:Must be current year or future, Accepts 2-digit or 4-digit format

Recommended - 7 fieldsRecommended Parameters

▼

Additional - 2 fieldsAdditional Parameters

▼

---

Responses

200

Successful transaction

Token created successfully. Use the token ID to create charges or attach to customers.

Response includes:

• id - Token ID (tokn_*) to use when creating charges
• used - Whether token has been used (false for new tokens)
• card - Card object with sanitized information (only last 4 digits)
• card.brand - Card brand (Visa, Mastercard, JCB, etc.)
• card.last_digits - Last 4 digits of card number
• card.security_code_check - Whether CVV was validated
• charge_status - Status of charge created with token (null if unused)

400

Bad request

Request validation failed. Check the error message for details.

Common causes:

• Missing required fields (card[name], card[number], card[expiration_month], card[expiration_year])
• Invalid card number format
• Invalid expiration date
• Card number contains spaces or dashes

401

Unauthorized

Authentication failed. Invalid or missing API key.

Common causes:

• Missing Authorization header
• Invalid public key
• Using secret key instead of public key
• Incorrect HTTP Basic Auth format

402

Payment required

Card validation failed.

Common causes:

• Card number failed Luhn validation
• Card is expired
• Invalid security code format
• Card brand not supported

---

Code samples

cURL

curl https://vault.omise.co/tokens \
  -u pkey_test_5xuy4w91xqz7d1w9u0t: \
  -d "card[name]=JOHN DOE" \
  -d "card[number]=4242424242424242" \
  -d "card[expiration_month]=12" \
  -d "card[expiration_year]=2025" \
  -d "card[security_code]=123"

Ruby

require 'omise'

Omise.api_key = 'pkey_test_5xuy4w91xqz7d1w9u0t'

token = Omise::Token.create({
  card: {
    name: 'JOHN DOE',
    number: '4242424242424242',
    expiration_month: 12,
    expiration_year: 2025,
    security_code: '123'
  }
})

Python

import omise

omise.api_public = 'pkey_test_5xuy4w91xqz7d1w9u0t'

token = omise.Token.create(
    card={
        'name': 'JOHN DOE',
        'number': '4242424242424242',
        'expiration_month': 12,
        'expiration_year': 2025,
        'security_code': '123'
    }
)

Node.js

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

const token = await omise.tokens.create({
  card: {
    name: 'JOHN DOE',
    number: '4242424242424242',
    expiration_month: 12,
    expiration_year: 2025,
    security_code: '123'
  }
});

PHP

<?php
define('OMISE_PUBLIC_KEY', 'pkey_test_5xuy4w91xqz7d1w9u0t');

$token = OmiseToken::create([
    'card' => [
        'name' => 'JOHN DOE',
        'number' => '4242424242424242',
        'expiration_month' => 12,
        'expiration_year' => 2025,
        'security_code' => '123'
    ]
]);

Java

Client client = new Client.Builder()
    .publicKey("pkey_test_5xuy4w91xqz7d1w9u0t")
    .build();

Token token = client.tokens().create()
    .card(new Card.Create()
        .name("JOHN DOE")
        .number("4242424242424242")
        .expirationMonth(12)
        .expirationYear(2025)
        .securityCode("123"))
    .send();

C#

var client = new Client("pkey_test_5xuy4w91xqz7d1w9u0t");

var token = await client.Tokens.Create(new CreateTokenRequest
{
    Card = new CardRequest
    {
        Name = "JOHN DOE",
        Number = "4242424242424242",
        ExpirationMonth = 12,
        ExpirationYear = 2025,
        SecurityCode = "123"
    }
});

Go

client, _ := omise.NewClient(
    "pkey_test_5xuy4w91xqz7d1w9u0t",
    "",
)

token, _ := client.Tokens().Create(&operations.CreateToken{
    Name:            "JOHN DOE",
    Number:          "4242424242424242",
    ExpirationMonth: 12,
    ExpirationYear:  2025,
    SecurityCode:    "123",
})

---

Error and result codes

Common Error Codes

Code	Description	Resolution
bad_request	Missing or invalid parameters	Check all required fields are provided
authentication_failure	Invalid API key	Verify your public key is correct
invalid_card	Card number is invalid	Check card number passes Luhn validation
invalid_expiration_date	Card is expired or date invalid	Verify expiration month and year
invalid_security_code	CVV format is invalid	Check CVV is 3-4 digits
used_token	Token already used	Create a new token for each charge

Test Card Numbers

Card Number	Brand	3D Secure
4242424242424242	Visa	No
4000000000003063	Visa	Yes
5555555555554444	Mastercard	No
4111111111111111	Visa	No

---

Try it out

Required - 4 fields

▼

card[name](Required)

card[number](Required)

card[expiration_month](Required)

card[expiration_year](Required)

Recommended - 7 fields

▼

Additional - 2 fields

▼