Token Management

Refresh token metadata

Re-run the issuer metadata inquiry for a Commerce token and return the updated token.

Issuer metadata is resolved once when the token is created. Use this endpoint when you need the token re-checked against the current issuer data — for example after a portfolio migration on the issuer side. The inquiry can update bank_name, segment, type, currency_code, country_code, issuer_identification_number and scheme.

Issuer metadata is only resolved if metadata inquiries are active for your account. If the inquiry does not return data, the card scheme is derived from the IIN and the remaining issuer fields keep their previous values.

POST

tokens

{id}

refresh-metadata

Refresh token metadata

curl --request POST \
  --url https://sandbox.hellgate.io/tokens/{id}/refresh-metadata \
  --header 'X-API-Key: <api-key>'

const options = {method: 'POST', headers: {'X-API-Key': '<api-key>'}};

fetch('https://sandbox.hellgate.io/tokens/{id}/refresh-metadata', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox.hellgate.io/tokens/{id}/refresh-metadata",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.hellgate.io/tokens/{id}/refresh-metadata"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://sandbox.hellgate.io/tokens/{id}/refresh-metadata")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "id": "5d6b2c9a-9b0b-4b0c-8c7d-9e9d5d7e9d5d",
  "cardholder_name": "John Doe",
  "card_art_url": "https://api.hellgate.io/tokens/card-art/374c911a-8125-40eb-acb8-a26efd25f02b",
  "created_at": "2023-10-01T00:00:00Z",
  "expiry_month": 4,
  "expiry_year": 2033,
  "expires_at": "2023-10-07T00:00:00Z",
  "issuer_identification_number": "424242",
  "masked_account_number": "424242******4242",
  "network_token_status": "active",
  "scheme": "VISA"
}

{
  "code": 401,
  "message": "No valid means of authentication was provided",
  "classifier": "UNAUTHORIZED"
}

{
  "code": 403,
  "message": "Not allowed to access this resource or feature",
  "classifier": "FORBIDDEN"
}

{
  "code": 404,
  "message": "The requested resource was not found.",
  "classifier": "NOT_FOUND"
}

Authorizations

X-API-Key

string

header

required

Path Parameters

string<uuid>

required

The ID of the Commerce token

Response

Success response

string<uuid>

required

The ID of the Commerce Token

Example:

"5d6b2c9a-9b0b-4b0c-8c7d-9e9d5d7e9d5d"

created_at

string<date-time>

required

The date-time the payment-method was created (following ISO 8601)

Example:

"2023-10-01T00:00:00Z"

expiry_month

integer

required

The number of month in a year (e.g. April is 4)

Example:

4

expiry_year

integer

required

The year given as four digit number (e.g. 2023)

Example:

2033

issuer_identification_number

string

required

The issuer idenfication number (IIN) - also known as BIN

Example:

"424242"

masked_account_number

string

required

The full lenght of the card number, but masked to conform to PCI DSS requirments

Example:

"424242******4242"

scheme

enum<string>

required

The scheme in which the card was issued

Available options:

VISA,

Mastercard,

American Express,

Discover,

Diners Club,

JCB,

UnionPay,

Unknown

cardholder_name

string

The name of the owner of the card

Example:

"John Doe"

card_art_url

string | null

The URL of the card art image for this token.

Use the URL as it is given to you. It needs no API key, so it can be rendered directly by a browser. It is null when the issuer provides no card art for the card.

Example:

"https://api.hellgate.io/tokens/card-art/374c911a-8125-40eb-acb8-a26efd25f02b"

expires_at

string<date-time>

The date-time when the token will expire. Applicable only for ephemeral tokens.

Example:

"2023-10-07T00:00:00Z"

invalidated_at

string | null

The time the Commerce Token was invalidated, because the underlying payment instrument was invalidated by the scheme.

Example:

null

account_number_last_four

string

Last four digits of the card number

Example:

"4242"

account_number_length

integer

The total number of digits in the card number

Example:

16

bank_name

string

The name of the issuing bank.

This information is present if metadata inquiries are active for your account.

Example:

"Example Bank"

segment

enum<string>

The segment or category of the card.

This information is present if metadata inquiries are active for your account.

Available options:

consumer,

commercial

Example:

"consumer"

status

enum<string>

The status of this Commerce token.

Available options:

active,

invalid

type

enum<string>

The funding type of the card.

This information is present if metadata inquiries are active for your account.

Available options:

credit,

debit,

prepaid,

charge,

deferred,

unknown

currency_code

string

The three letter currency code of the card. See: ISO-4217

This information is present if metadata inquiries are active for your account.

Required string length: 3

Example:

"EUR"

country_code

string

A two letter country code. ISO 3166-1 alpha-2

Example:

"US"

network_token_status

enum<string>

The status of the associated network token.

Status	Description
`active`	The network token is active and can be used.
`inactive`	The network token is inactive, which prevents using it. The reason can be for example suspended network token.
`pending`	A network token is currently being provisioned. As soon as this is available, the status is changed to `active`.
`failed`	A network token failed to be provisioned.
`deleted`	The network token is deleted and cannot be used again. It is also not possible to activate the network token again.
`not_available`	A network token can not be provisioned with the current configuration.

Available options:

active,

inactive,

pending,

deleted,

failed,

not_available

network_token_status_reason

object

Show child attributes

identity_and_verification

enum<string>

The type of ID&V submitted during the creation of the Commerce token..

Available options:

none,

checked,

skipped

Example:

"federated_id"

authentication_data

object

Show child attributes

supports_device_binding

boolean

Example:

true

business_key

string

This attribute holds the original business key under which the cardholder data was stored on the system from which it was imported to Commerce.

It can be used for reconciliation or reference purposes.

Example:

"cust-0042-card-1"

import_provider

string

The source from which the cardholder data was imported from.

The business_key attribute will refer to the original ID at this provider.

Example:

"legacy-vault"

Get card artGet the card art associated with the token, as a base64-encoded image. Card art is provided by the issuer through the network token. It is not available for every card. To embed the image directly in a browser instead, use the ready-made URL in the token's `card_art_url` attribute.

⌘I

Refresh token metadata

curl --request POST \
  --url https://sandbox.hellgate.io/tokens/{id}/refresh-metadata \
  --header 'X-API-Key: <api-key>'

const options = {method: 'POST', headers: {'X-API-Key': '<api-key>'}};

fetch('https://sandbox.hellgate.io/tokens/{id}/refresh-metadata', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox.hellgate.io/tokens/{id}/refresh-metadata",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.hellgate.io/tokens/{id}/refresh-metadata"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://sandbox.hellgate.io/tokens/{id}/refresh-metadata")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "id": "5d6b2c9a-9b0b-4b0c-8c7d-9e9d5d7e9d5d",
  "cardholder_name": "John Doe",
  "card_art_url": "https://api.hellgate.io/tokens/card-art/374c911a-8125-40eb-acb8-a26efd25f02b",
  "created_at": "2023-10-01T00:00:00Z",
  "expiry_month": 4,
  "expiry_year": 2033,
  "expires_at": "2023-10-07T00:00:00Z",
  "issuer_identification_number": "424242",
  "masked_account_number": "424242******4242",
  "network_token_status": "active",
  "scheme": "VISA"
}

{
  "code": 401,
  "message": "No valid means of authentication was provided",
  "classifier": "UNAUTHORIZED"
}

{
  "code": 403,
  "message": "Not allowed to access this resource or feature",
  "classifier": "FORBIDDEN"
}

{
  "code": 404,
  "message": "The requested resource was not found.",
  "classifier": "NOT_FOUND"
}

Getting Started

Payments

Authentications

Customer Data

Tokens

Configuration

Automation

Refresh token metadata

Authorizations

Path Parameters

Response