HiPay tokenization API
Everything you need to tokenize payment cards
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/hipay-tokenization-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
version: ''
title: HiPay Enterprise Tokenization API
description: 'We strongly recommend to use the JS SDK to tokenize a card, instead of the Tokenization API.
The Tokenization (Secure Vault) API allows merchants to retrieve and update data associated with their customers'' payment information stored in the HiPay Enterprise Secure Vault. Using Tokenization API, merchants eliminate the risk, liability and cost of storing sensitive data on their local servers and storage devices.
The Tokenization API aims to be used **alongside the HiPay Enterprise Gateway API**. In particular, with the Request New Order (`POST /order`) service of the Gateway API. In fact, when you need to make payments with credit or debit cards using the Gateway API, you first need to tokenize card numbers thanks to the Tokenization API.
This API integrates a BIN lookup tool. Every submitted card number is automatically searched in the BIN database to determine its issuing bank. When the BIN lookup succeeds, the response includes the card brand, the 2-letter country code where card was issued and when applicable the issuing bank name.
Note: this documentation describes the Tokenization API parameters and response fields and allows you to test the platform in real time.
## Tokenization API base URLs
| Environment | Base URL |
| --- | --- |
| Stage | https://stage-secure2-vault.hipay-tpp.com/rest/v2/token |
| Production | https://secure2-vault.hipay-tpp.com/rest/v2/token |
## Authentication
All requests to HiPay Enterprise API require you to authenticate using the HTTP *Basic Authentication* to convey your identity. Your API credentials can be found in your HiPay Enterprise back office in the Integration section. Most HTTP clients (including web-browsers) have built-in support for HTTP Basic Authentication. If not, the following header must be included in all HTTP requests.
`Authorization: Basic base64("<API login>:<API password>")`
'
servers:
- url: https://stage-secure2-vault.hipay-tpp.com/rest/v2/token/
tags:
- name: tokenization
description: Everything you need to tokenize payment cards
paths:
/create:
post:
tags:
- tokenization
summary: Performs credit or debit card tokenization
description: 'Performs credit or debit card tokenization. Once the card is tokenized, you can use the generated token to make payments thanks to the HiPay Enterprise Gateway API.
'
operationId: createToken
responses:
'201':
description: Token successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/Token'
'400':
description: The request was rejected due to a validation error.
content:
application/json:
schema:
type: object
required:
- code
- message
- description
properties:
code:
type: integer
message:
type: string
description:
type: string
'401':
description: An authentication error occurred/invalid credentials.
content:
application/json:
schema:
type: object
required:
- code
- message
- description
properties:
code:
type: integer
message:
type: string
description:
type: string
'403':
description: Access to this resource is fordidden.
content:
application/json:
schema:
type: object
required:
- code
- message
- description
properties:
code:
type: integer
message:
type: string
description:
type: string
security:
- basicAuth: []
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
card_number:
type: string
default: '4000000000000002'
description: The card number.
card_expiry_month:
type: integer
default: 12
description: The card expiry month.
card_expiry_year:
type: integer
default: 2025
description: The card expiry year.
card_holder:
type: string
default: Cathy Doe
description: The cardholder name as it appears on the card.
cvc:
type: string
default: '514'
pattern: '(\d{3})|(\d{4})
'
description: The 3 or 4 digit security code (called CVV2 or CID depending on the card brand) that appears on the credit card.
multi_use:
type: integer
enum:
- 0
- 1
default: 0
description: 'Indicates the tokenization module whether the payment card token should be generated either for a single-use or a multi-use.
Possible values:
- `0`: Generates a single-use token
- `1`: Generates a multi-use token
While a single-use token is typically generated for a short time and for processing a single transaction, multi-use tokens are generally generated.
'
generate_request_id:
type: integer
enum:
- 0
- 1
default: 0
description: Indicates if a request ID should be generated.
required:
- card_number
- card_expiry_month
- card_expiry_year
- card_holder
/{token}:
get:
tags:
- tokenization
summary: Gets the details of a credit card that you have previously tokenized
description: Gets the details of a credit card that you have previously tokenized.
operationId: lookupToken
parameters:
- name: token
description: The token to look for.
in: path
required: true
x-is-map: false
schema:
type: string
default: 85a934ff3621385cd1ee8fe4c29c15da9c0a9eede1ed5f3511329844d9bf1388
- name: request_id
description: The request ID linked to the card token.
in: query
required: true
x-is-map: false
schema:
type: string
default: '0'
responses:
'200':
description: Token successfully retrieved.
content:
application/json:
schema:
$ref: '#/components/schemas/Token'
'400':
description: The request was rejected due to a validation error.
content:
application/json:
schema:
type: object
required:
- code
- message
- description
properties:
code:
type: integer
message:
type: string
description:
type: string
'401':
description: An authentication error occurred/invalid credentials.
content:
application/json:
schema:
type: object
required:
- code
- message
- description
properties:
code:
type: integer
message:
type: string
description:
type: string
'403':
description: Access to this resource is fordidden.
content:
application/json:
schema:
type: object
required:
- code
- message
- description
properties:
code:
type: integer
message:
type: string
description:
type: string
'404':
description: Token was not found.
content:
application/json:
schema:
type: object
required:
- code
- message
- description
properties:
code:
type: integer
message:
type: string
description:
type: string
security:
- basicAuth: []
/:
delete:
tags:
- tokenization
summary: Delete a previously created token
description: Delete a previously created token
operationId: deleteToken
responses:
'204':
description: Token successfully deleted.
'400':
description: Invalid card token
content:
application/json:
schema:
type: object
required:
- code
- message
- description
properties:
code:
type: integer
example: 400
message:
type: string
example: Invalid cardToken
description:
type: object
example:
code: 400
message: Invalid cardToken
'401':
description: Incorrect Credentials _ Username and / or password is incorrect
content:
application/json:
schema:
type: object
required:
- code
- message
- description
properties:
code:
type: integer
example: 1000001
message:
type: string
example: Incorrect Credentials _ Username and / or password is incorrect
description:
type: object
example:
code: 1000001
message: Incorrect Credentials _ Username and / or password is incorrect
'403':
description: Forbidden
content:
application/json:
schema:
type: object
required:
- code
- message
properties:
code:
type: integer
example: 403
message:
type: string
example: Forbidden
'404':
description: Card token not found
content:
application/json:
schema:
type: object
required:
- code
- message
- description
properties:
code:
type: integer
example: 404
message:
type: string
example: Card token not found
description:
type: object
example:
code: 404
message: Card token not found
security:
- basicAuth: []
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
card_token:
type: string
description: The token to be deleted.
required:
- card_token
/update:
post:
tags:
- tokenization
summary: Updates the details of a previsouly tokenized credit or debit card
description: Updates the details of a previsouly tokenized credit or debit card.
operationId: updateToken
responses:
'200':
description: Token successfully updated.
content:
application/json:
schema:
type: object
required:
- token
- request_id
- card_holder
- card_expiry_month
- card_expiry_year
properties:
token:
type: string
example: 85a934ff3621385cd1ee8fe4c29c15da9c0a9eede1ed5f3511329844d9bf1388
request_id:
type: string
example: '0'
card_holder:
type: string
example: Cathy Doe
card_expiry_month:
type: string
example: '02'
card_expiry_year:
type: string
example: '2025'
'400':
description: The request was rejected due to a validation error.
content:
application/json:
schema:
type: object
required:
- code
- message
- description
properties:
code:
type: integer
message:
type: string
description:
type: string
'401':
description: An authentication error occurred/invalid credentials.
content:
application/json:
schema:
type: object
required:
- code
- message
- description
properties:
code:
type: integer
message:
type: string
description:
type: string
'403':
description: Access to this resource is fordidden.
content:
application/json:
schema:
type: object
required:
- code
- message
- description
properties:
code:
type: integer
message:
type: string
description:
type: string
'404':
description: Token was not found.
content:
application/json:
schema:
type: object
required:
- code
- message
- description
properties:
code:
type: integer
message:
type: string
description:
type: string
security:
- basicAuth: []
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
card_token:
type: string
default: 85a934ff3621385cd1ee8fe4c29c15da9c0a9eede1ed5f3511329844d9bf1388
description: The token to be updated.
request_id:
type: string
default: '0'
description: The request ID linked to the card token.
card_expiry_month:
type: integer
default: 12
description: The card expiry month.
card_expiry_year:
type: integer
default: 2025
description: The card expiry year.
card_holder:
type: string
default: Cathy Doe
description: The cardholder name as it appears on the card.
cvc:
type: string
default: '514'
pattern: '(\d{3})|(\d{4})
'
description: The 3 or 4 digit security code (called CVV2 or CID depending on the card brand) that appears on the credit card.
required:
- card_token
- request_id
- card_expiry_month
- card_expiry_year
- card_holder
components:
schemas:
Token:
type: object
required:
- token
- request_id
- card_hash
- card_id
- brand
- pan
- card_holder
- card_expiry_month
- card_expiry_year
- issuer
- country
properties:
token:
type: string
example: 85a934ff3621385cd1ee8fe4c29c15da9c0a9eede1ed5f3511329844d9bf1388
request_id:
description: The request ID linked to the token.
type: string
example: '0'
card_hash:
description: Card token in SHA1. Deprecated
type: string
example: ce5f096fa6bc05989c170e7c96f94432660491bd
card_id:
description: Unique card identifier.
type: string
example: 96ada09f-a844-4956-9593-cb758630dac2
brand:
description: Card brand. (e.g., Visa, MasterCard, American Express, JCB, Discover, Diners Club, Solo, Laser, Maestro).
type: string
example: VISA
pan:
description: Card number (up to 19 characters). Note that, due to the PCI DSS security standards, our system has to mask credit card numbers in any output (e.g., 549619******4769).
type: string
example: 400000xxxxxx0002
card_holder:
description: Cardholder name.
type: string
example: Cathy Doe
card_expiry_month:
description: Card expiry month (2 digits).
type: string
example: '12'
card_expiry_year:
description: Card expiry year (4 digits).
type: string
example: '2025'
issuer:
description: Card issuing bank name. Do not rely on this value to remain static over time. Bank names may change over time due to acquisitions and mergers.
type: string
example: BNP PARIBAS
country:
description: Bank country code where card was issued. This two-letter country code complies with ISO 3166-1 (alpha 2).
type: string
example: US
domestic_network:
description: Card domestic network (if applicable, e.g. “cb”).
type: string
example: cb
card_type:
description: Type of the card. (e.g.; Debit card, Credit card, Charge card, ATM card ...)
type: string
example: CREDIT
card_category:
description: Category of the card. (e.g., Classic, Business, Electron, Gold ...)
type: string
example: PURCHASING
forbidden_issuer_country:
description: Indicates whether the card country is authorized.
type: boolean
example: false
securitySchemes:
basicAuth:
type: http
scheme: basic