Retrieve a Token

GEThttps://vault.omise.co/tokens/:id

Retrieve information about an existing token including its usage status and associated card details.

---

🔑API Credentials

▼

---

Request Parameters

Required - 1 fieldRequired Parameters

▼

`id`STRING(required)

The token ID to retrieve. Must start with tokn_ followed by test_ or live_ and a unique identifier.

Example:"tokn_test_5xuy4w91xqz7d1w9u0t"

Constraints:Must be a valid token ID, Pattern: tokn_(test|live)_[0-9a-z]+

---

Responses

200

Successful retrieval

Token retrieved successfully. Returns the token object with card details.

Response includes:

• id - Token identifier
• used - Whether token has been used (false if unused, true if used)
• charge_status - Status of charge created with token (null if unused)
• card - Card object with sanitized information
• card.brand - Card brand (Visa, Mastercard, JCB, etc.)
• card.last_digits - Last 4 digits of card number
• card.fingerprint - Unique card identifier
• card.security_code_check - Whether CVV was validated

401

Unauthorized

Authentication failed. Invalid or missing API key.

Common causes:

• Missing Authorization header
• Invalid public key
• Incorrect HTTP Basic Auth format

404

Not found

Token not found. The specified token ID does not exist.

Common causes:

• Invalid token ID format
• Token ID does not exist in your account
• Using test key to access live token (or vice versa)
• Typo in token ID

---

Code samples

cURL

curl https://vault.omise.co/tokens/tokn_test_5xuy4w91xqz7d1w9u0t \
  -u pkey_test_5xuy4w91xqz7d1w9u0t:

Ruby

require 'omise'

Omise.api_key = 'pkey_test_5xuy4w91xqz7d1w9u0t'

token = Omise::Token.retrieve('tokn_test_5xuy4w91xqz7d1w9u0t')

Python

import omise

omise.api_public = 'pkey_test_5xuy4w91xqz7d1w9u0t'

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

Node.js

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

const token = await omise.tokens.retrieve('tokn_test_5xuy4w91xqz7d1w9u0t');

PHP

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

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

Java

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

Token token = client.tokens().get("tokn_test_5xuy4w91xqz7d1w9u0t");

C#

var client = new Client("pkey_test_5xuy4w91xqz7d1w9u0t");

var token = await client.Tokens.Get("tokn_test_5xuy4w91xqz7d1w9u0t");

Go

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

token, _ := client.Tokens().Get("tokn_test_5xuy4w91xqz7d1w9u0t")

---

Error and result codes

Common Error Codes

Code	Description	Resolution
authentication_failure	Invalid API key	Verify your public key is correct
not_found	Token not found	Check token ID is valid and exists

Token Status

Field	Value	Description
used	false	Token is unused and available
used	true	Token has been used and cannot be reused
charge_status	null	Token not yet used
charge_status	successful	Token used for successful charge
charge_status	failed	Token used but charge failed
charge_status	pending	Token used, charge pending

---

Try it out

Required - 1 fields

▼

id(Required)