Payment Account Tokenization

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

Transaction API

This API is used to detokenize the debtor and creditor tokens and validate the attributes on the tokens against the transaction data.

API Overview

This API is used to detokenize the debtor and creditor tokens and validate the attributes on the tokens against the transaction data.

Available Endpoints

Endpoint Usage
/validatetransaction Used to detokenize and validate token attributes.

API Reference

<Link to APIConnect reference page>

Transaction Message Flows

Message flow patterns for transaction validation and processing.

Transaction Message Flows

The diagram below provides an overview of the TXN API message flow for transaction validation and token processing.

Transaction Validation Process

  1. Transaction request received with token information
  2. Tokens are detokenized to reveal real account information
  3. Token attributes and restrictions are validated
  4. Transaction data is checked against token rules
  5. Validation results are returned with account attributes

Validation Components

  • Token state verification
  • Restriction compliance checking
  • Counterparty validation
  • Amount and currency limits
  • Account category matching

Transaction API Response Codes

Response codes and status messages for Transaction API endpoints.

Response Codes

This section includes detailed information about the API Response fields: statusCode, statusMessage, result, reasonCode and message.

Example HTTP 200 Transaction Response Example

{
"messageId": "b43fe87a-9deb-4086-a03f-ec1f8a603e70", 
"conversationId" : "1b1685b3-0723-4d30-ba6d-b19ea1d35da3", 
"statusMessage": "Success.",
"statusCode": "00000", 
"transactionIndicator": true, 
"originator": { 
"accountRoutingNumber": "013456789",
"accountNumber": "00000000000000447",
"tokenRoutingNumber": "111456789",
"tokenNumber": "99999999929007929"
},
"recipient": {
"accountRoutingNumber": "033456789",
"accountNumber": "00000000000000001",
"tokenRoutingNumber": "333456789",
"tokenNumber": "99999999999122147",
"reasonCodes": [ "001","002"
]
}
}

Response Message: HTTP Code, statusCode and statusMessage

HTTP Code statusCode statusMessage Applicable Message
200 00000 Success. /v1/validatetransaction
400 11100 Invalid request. The data field is not in the correct data type format or length or pre-defined values or the required data field is missing. /v1/validatetransaction
400 11104 Cryptographic error. /v1/validatetransaction
400 11105 Invalid token requestor id. Only token requestors of RTP domain can proceed the transaction. /v1/validatetransaction
500 11800 Unknown internal server error. Try again later. /v1/validatetransaction
500 11801 Unknown error. /v1/validatetransaction

API Reference

<Link to APIConnect reference page>

Example Transaction HTTP 200 Response

Example HTTP 200 response from Transaction API validation.

Example HTTP 200 Transaction Response

{
"messageId": "b43fe87a-9deb-4086-a03f-ec1f8a603e70", 
"conversationId" : "1b1685b3-0723-4d30-ba6d-b19ea1d35da3", 
"statusMessage": "Success.",
"statusCode": "00000", 
"transactionIndicator": true, 
"originator": { 
"accountRoutingNumber": "013456789",
"accountNumber": "00000000000000447",
"tokenRoutingNumber": "111456789",
"tokenNumber": "99999999929007929"
},
"recipient": {
"accountRoutingNumber": "033456789",
"accountNumber": "00000000000000001",
"tokenRoutingNumber": "333456789",
"tokenNumber": "99999999999122147",
"reasonCodes": [ "001","002"
]
}
}

Response Components

  • messageId: Unique message identifier
  • conversationId: Conversation tracking identifier
  • transactionIndicator: Boolean indicating transaction processing status
  • originator: Originating account and token information
  • recipient: Receiving account and token information
  • reasonCodes: Array of reason codes for validation results

Transaction Response Message Codes

Detailed response message codes for Transaction API operations.

Transaction Response Message Codes

This section provides detailed information about response message codes specific to Transaction API operations.

Transaction Validation

Transaction API responses include validation results for:

  • Token state verification
  • Restriction compliance
  • Counterparty validation
  • Amount and currency limits
  • Account category matching

Validation Results

Transaction validation results provide detailed information about why a transaction was approved or rejected, enabling informed decision-making by the requesting system.

Reason Codes and Descriptions

Reason codes and their descriptions for Transaction API responses.

reasonCodes and their description

reasonCode Description
SUCCESS -
INVALID_FIELD_VALUE Requestor is not valid
INVALID_FIELD_VALUE Token Requestor legal name is already used by another TRID
INVALID_VALUE INTERNAL_PROCESSING_FAILURE
INVALID_FIELD_VALUE Token Requestor legal name is empty

Tokenization Flag in Request

How the tokenization flag in transaction requests affects the response content.

tokenization flag in request

The tokenization flag in the /txn-request indicates the presence of Originator/Recipient in response.

Originator/Recipient in Request tokenization Originator/Recipient in Response
tokenRoutingNumber&tokenNumber true/false/null accountRoutingNumber&accountNumber&tokenRoutingNumber&tokenNumber
accountRoutingNumber&accountNumber true accountRoutingNumber&accountNumber&tokenRoutingNumber&tokenNumber
accountRoutingNumber&accountNumber false/null accountRoutingNumber&accountNumber