Payment Account Tokenization

Start a Project Start a Project API Overview API Overview API Reference API Reference
Navigate to...
keyboard_arrow_down

Token Requestor API

API Overview

This API is used by token requestors like financial institutions, central operators, fintech aggregators etc. to provision a token and perform life cycle management operations on it.

Available Endpoints

Endpoint Usage
/tokenize Used to tokenize an account.
/requestlifecyclemanagement Used to perform a state change operation on a Token.
/tokenstatusinquiry Used to enquire status of a token.
/updatetokenrestrictions Used to update restrictions of a token.

Message flows

The diagrams below provides an overview of the TR API message flows for Provisioning, Lifecycle Management, Token Status Inquiry and Update Token Restrictions.

Note that when the Token Requestor or Financial Institution state is disabled or closed, all API requests are rejected with statusCode 9136: TOKEN_REQUESTOR_INVALID_STATE or statusCode 9141: FINANCIAL_ INSTITUTION_INVALID_STATE.

Provision token with restrictions

Used to request a token for a real account number. Optionally, the following restrictions can be added to the requested token:

  • Counterparty account number
  • Token expiry date
  • Single-use token
  • Transaction maximum amount limit
  • Transaction currency code
  • Token account and counterparty account categories

The counterparty account number must be included if the real account numbers' financial institution has configured that the counterparty is required.

Also, the transaction currency code and maximum amount limit are validated against the financial institutions' token level restriction configuration.

Example of a provisioning scenario where the token request is invalid or the financial institution is not onboarded

PAT_TR_API_Tokenize_If_A_Token_Exists

Example of a provisioning scenario where the token does not exist and the domain restriction validation is successful

PAT_TR_API_Tokenize_If_A_Token_Does_Not_Exist_And_Domain_Restrictions_SUCCEED

Example of a provisioning scenario where the token does not exist and the domain restriction validation failed

PAT_TR_API_Tokenize_If_A_Token_Does_Not_Exist_And_Domain_Restrictions_FAILED

Provision token with attributes

During token provisioning, the request may include optional, configurable token attributes that must align with the supported attributes defined in PAT. When a transaction is validated through the Transaction API, these attributes can be checked against both transaction and token data according to configurable transaction rules. The validation outcome will determine whether the system advises to approve or decline the transaction.

Provision a token with configurable token attributes

PAT_TR_API_Tokenize_With_Configurable_Attribues

Supported token attributes are:

Lifecycle management

Lifecycle management operations allow for state changes and management of tokens throughout their lifecycle.

Token lifecycle management

PAT_TR_API_Lifecycle_Management

Token status inquiry

Token requestors can request additional information about the tokens including the token restrictions and attributes.

Token status inquiry

PAT_TR_API_TokenStatusInquiry

Update token restrictions

The following restrictions can be updated:

  • Expiry date
  • Counterparty
  • Multi use
  • Transaction maximum amount limit
  • Transaction currency code
  • Token account and counterparty account categories
  • Configurable attributes

For the restrictions counterparty (required or not), transaction maximum amount limit and transaction currency code, the financial institution can configure the required values per domain, token range and/or Token Requestor ID (TRID).

Update expiry date

A financial institution (or third-party) can update a token's expiry date (yyMM) with this restriction.

The earliest expiry date value must be equal to the current month plus one. Example: If the request is sent on September 2025, the token expiry date value should be October 2025 or later.

Update expiry date

PAT_TR_API_Update_Token_Expiry_Date

Update counterparty

A financial institution (or a third-party) can instruct PAT, through the token requestor interface, to update the tokens' counterparty routing number or real account number with this restriction.

For assigning a counterparty to a token, PAT will apply the following rules if the:

  • counterparty sent in the request is a (real) account (maintained by a financial institution which may or may not be onboarded), and PAT assigns this account as a counterparty to the requested token.
  • counterparty sent in the request is a token, and PAT detokenizes it and uses the real account as counterparty of the requested token.
  • financial institution has configured the counterparty as required, and the counterparty account number must be present in the request.

Update counterparty

PAT_TR_API_Update_Counterparty

Update multi use token

Used by the token requestor to update the multi use of an existing token.

The token becomes a single use token when the multiUseToken is set to false. The token can be used multiple times when set to true.

Update multi use token

PAT_TR_API_Update_Multi_Token_Use

Update transaction maximum amount limit

Used by the token requestor to update the transaction maximum amount limit of an existing token.

The maximum amount limit is validated against the token level restrictions configuration of the financial institution that owns the linked account number:

  • If the request contains a value that is <= the configured 'Maximum transaction amount' then the value assigned to the token will be the value supplied by the token requestor in the request.
  • If the request contains a value that is > the configured 'Maximum transaction amount' then the token request will be rejected with a new error code 'transactionMaxAmountLimit invalid'.

Update transaction maximum amount limit

PAT_TR_API_Update_Transaction_Maximum_Amount_Limit

Update token account category

Token requestor can assign one category restriction to the token during provisioning and restriction update. Supported categories are:

  • Consumer
  • Corporate

This restriction can be validated during a transaction where the category of the originating token is checked against the supported categories of the counterparty account category.

Update token account category

PAT_TR_API_Update_Token_Category

Update transaction currency code

Used by the token requestor to update the transaction currency code of an existing token.

The currency code is validated against the token level restrictions configuration of the financial institution that owns the linked account number.

Update transaction currency code

PAT_TR_API_Update_Transaction_Currency_Code

Update token counterparty account category

Token requestor can assign one or more category restrictions to the counterparty account of a token during provisioning and restriction update. Supported categories are:

  • Consumer
  • Corporate

This restriction is used during a transaction where the category of the originating token is checked against the supported categories of the counterparty account category.

For example, when the counterparty account category is 'Consumer, Corporate' and the token category is 'Consumer' then the restriction validation is successful.

Update token counterparty account category

PAT_TR_API_Update_Token_CounterParty_Category

Update configurable attributes

Token requesters can add or update configurable attributes on a already provisioned token. The following token attributes are supported:

  • ALLOWED_CURRENCIES - Allowed Currencies
  • COUNTERPARTY_ACCOUNT_NUMBER - Counterparty Account Number
  • COUNTERPARTY_COUNTRY - Counterparty Country
  • COUNTERPARTY_MAX_RISK_SCORE - Counterparty Maximum Risk score
  • COUNTERPARTY_TYPE - Counterparty Type
  • COUNTERPARTY_UNDER_POA - Counterparty under POA
  • COUNTERPARTY_VELOCITY - Counterparty Velocity
  • CURRENT_CUMULATIVE_TRANSACTION_AMOUNT_DAY - Current Cumulative Transaction Amount Day
  • CURRENT_CUMULATIVE_TRANSACTION_AMOUNT_WEEK - Current Cumulative Transaction Amount Week
  • CURRENT_CUMULATIVE_TRANSACTION_AMOUNT_MONTH - Current Cumulative Transaction Amount Month
  • MAX_CUMULATIVE_TRANSACTION_AMOUNT_DAY - Maximum Cumulative Transaction Amount Day
  • MAX_CUMULATIVE_TRANSACTION_AMOUNT_WEEK - Maximum Cumulative Transaction Amount Week
  • MAX_CUMULATIVE_TRANSACTION_AMOUNT_MONTH - Maximum Cumulative Transaction Amount Month
  • MAX_TRANSACTION_AMOUNT - Maximum Transaction Amount
  • MAX_TRANSACTION_RISK - Maximum Transaction Risk
  • TOKEN_USAGE_COUNT - Token Usage Count
  • MAX_TOKEN_USAGE_COUNT - Maximum Token Usage Count

Update configurable attributes

PAT_TR_API_Update_Configurable_Attribute

Token Requestor API Response Codes

Response Codes

This section includes detailed information about the API response fields statusCode and statusMessage.

Example HTTP 200 Response

{
    "messageId": "6fdf4f09-7fbb-48ae-be1e-ac412a2949a7",
    "statusCode": "00000",
    "statusMessage": "Success."
}

Example HTTP 200 Response with encTokens

    {
    "messageId": "6fdf4f09-7fbb-48ae-be1e-ac412a2949a7",
    "statusCode": "00000",
    "statusMessage": "Success.", 
    "encTokens": "..."
}

Response Message: HTTP Code, statusCode and statusMessage

HTTP Code statusCode statusMessage Applicable Message
200 0000 Success -
400 9001 INVALID_FORMAT; 1. Mandatory data fields are missing 2. The value of fields are not in the required format (length, data type) 3. When the field has a limited list of pre-defined allowed values (ENUM) and the submitted value is not one of them. -
400 9002 INVALID_VALUE; 1. The request contains a value for a field is used to locate an entity in the server, and the server cannot find the entity (note that other more specific errors might be returned rather than this error code to provide additional information) 2. The web service client making the request is not authorized to make the request. -
400 9104 TOKEN_INVALID_STATE; The token is not currently in a valid state for this request. -
400 9006 TOKEN_NOT_FOUND; Every command with tokenReferenceId in its request while token cannot be found in the token vault. -
500 9003 SERVER_NOT_AVAILABLE; The server is currently under heavy load and cannot handle the request at this time. -
500 9005 GENERIC_ERROR; An unknown error has occurred. This error is used if the occurred error does not match the defined errors, or when the cause of the error is unknown. -
403 9121 REQUEST_NOT_ALLOWED; The request was valid, but it is refused action. -
400 9124 ACCOUNT_TOKENIZATION_NOT_ALLOWED; The provided account is not eligible for tokenization. -
400 9125 TOKEN_ACCOUNT_ISSUER_MISMATCH; The account belongs to a different financial institution. -
400 9128 TOKEN_ACCOUNT_REQUESTER_NOT_ALLOWED; Financial Institution token requestors can only manage their own accounts. -
401 9022 AUTHORIZATION_FAILED; The request has not been applied because it lacks valid authentication credentials for the target resource. -
400 9109 CRYPTOGRAM_INVALID; The cryptogram was not verified successfully. -
400 9110 CRYPTOGRAM_EXPIRED; The cryptogram has expired. -
400 9116 KEYS_NOT_FOUND; Keys cannot be found in KMS. -
400 9117 CRYPTOGRAPHY_ERROR; Failed to encrypt/decrypt data with keys. -
400 9123 COUNTERPARTYDATA_NOT_FOUND; The counterpartydata received is unknown. -
400 9127 FEATURE_NOT_SUPPORTED; The feature is not supported. -
400 9136 TOKEN_REQUESTOR_INVALID_STATE; The token requestor is currently in a state that does not allow the requested action. -
400 9137 TRANSACTION_MAX_AMOUNT_LIMIT_INVALID; The system is configured to reject transactionMaxAmountLimit value included in the request. -
400 9138 COUNTER_PARTY_DATA_REQUIRED; The system is configured to require counterPartyData to be included in the request. -
400 9139 CURRENCY_INVALID; The system is configured to reject transactionCurrencyCode included in the request. -
400 9141 FINANCIAL_INSTITUTION_INVALID_STATE; The request cannot be processed because the financial institution state does not allow for it. -
400 9145 TR_DYNAMIC_TOKEN_ATTRIBUTES_INVALID; Dynamic token attributes are invalid. -
500 9146 NO_MORE_TOKENS_AVAILABLE; No tokens are available for provisioning. -