Payment Account Tokenization

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

Notification API

This API is used to notify Financial Institutions and Token Requestors when tokens are provisioned or when the state of a token change.

API Overview

This API is used to notify Financial Institutions and Token Requestors when tokens are provisioned or when the state of a token change.

Available Endpoints

Endpoint Usage
/token/state/provisioned Notification to inform FI that the token was provisioned to their account.
/token/state/changed Notification to inform FIs and TRs that token state has changed.

API Reference

<Link to APIConnect reference page>

Notification Message Flows

Message flow patterns for PAT notification delivery.

Notification Message Flows

PAT uses standardized message flows to deliver notifications to Financial Institutions and Token Requestors. These flows ensure reliable and consistent notification delivery.

Provisioning Notification

During provisioning of tokens by the Token Requestor, the Financial Institution can receive a notification with the real account number that is tokenized. Token Requestors can use the Token Requestor API or batch tokenization to provision tokens.

Lifecycle Change Notifications

When token states change, notifications are sent to relevant parties:

  • FI receives notifications for TR-initiated changes
  • TR receives notifications for FI-initiated changes
  • Both parties receive system-initiated notifications

Provisioning Notification

Notifications sent during token provisioning operations.

Provisioning Notification

During provisioning of tokens by the Token Requestor, the Financial Institution can receive a notification with the real account number that is tokenized.

Notification Content

Provisioning notifications include:

  • Real account number that was tokenized
  • Token information and identifiers
  • Token Requestor information
  • Provisioning timestamp
  • Any restrictions applied to the token

Provisioning Methods

Token Requestors can use the Token Requestor API or batch tokenization to provision tokens, and notifications will be sent for both methods.

Lifecycle Notifications Overview

Overview of token lifecycle notification processes and flows.

Lifecycle Notifications

PAT provides comprehensive notification capabilities to keep Financial Institutions and Token Requestors informed about token state changes. These notifications ensure all parties are aware of important token lifecycle events.

Notification Types

  • FI-initiated notifications: When Financial Institutions change token states
  • TR-initiated notifications: When Token Requestors change token states
  • System-initiated notifications: When PAT system changes token states

Notification Delivery

Notifications are delivered through the Notification API endpoints and include:

  • Token identification information
  • State change details
  • Reason codes and messages
  • Timestamp information

Lifecycle Management Notification - FI Initiated

Notifications sent when Financial Institutions initiate token lifecycle changes.

LCM Notification FI Initiated

Financial Institutions can change the state of tokens that are linked to their real account numbers. Token state changes can be initiated using the Financial Institution API, Customer Service Portal or batch lifecycle management. The Token Requestor that owns the linked token can receive a notification. If the Token Requestor is part of a requestor chain, then the notification is sent to the root level Token Requestor.

Notification Flow

When a Financial Institution initiates a token state change:

  1. The FI makes the lifecycle management request
  2. PAT processes the state change
  3. A notification is sent to the Token Requestor
  4. The Token Requestor receives the state change notification

Supported State Changes

  • Token activation
  • Token suspension
  • Token deactivation
  • Token deletion

Lifecycle Management Notification - TR Initiated

Notifications sent when Token Requestors initiate token lifecycle changes.

LCM Notification TR Initiated

Token Requestors can change the state of the tokens they own. Token state changes can be initiated using the Token Requestor API or Customer Service Portal. The Financial Institution that owns the linked real account number can receive a notification.

Notification Flow

When a Token Requestor initiates a token state change:

  1. The TR makes the lifecycle management request
  2. PAT processes the state change
  3. A notification is sent to the Financial Institution
  4. The FI receives the state change notification

Use Cases

  • Token suspension due to suspected fraud
  • Token deactivation when no longer needed
  • Token reactivation after issue resolution
  • Bulk token management operations

Notification API Response Codes

Response codes and status messages for Notification API endpoints.

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", 
"conversationId": "aa3a5f54-6eb2-4714-aea3-9f525353cbd7", 
"statusCode": "0000",
"statusMessage": "Success.", 
"stateChangeReasonCode": "INITIATED_BY_REQUESTOR"
}

Response Message: HTTP Code, statusCode and statusMessage

HTTP Code statusCode statusMessage Applicable Message
200 0000 Success. -
400 1301 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. -
500 1300 Unknown internal server error. Try again later. -
500 1399 Unknown error. -

API Reference

<Link to APIConnect reference page>

Example Notification HTTP 200 Response

Example HTTP 200 response from Notification API.

Example HTTP 200 Notification Response

{
"messageId": "6fdf4f09-7fbb-48ae-be1e-ac412a2949a7", 
"conversationId": "aa3a5f54-6eb2-4714-aea3-9f525353cbd7", 
"statusCode": "0000",
"statusMessage": "Success.", 
"stateChangeReasonCode": "INITIATED_BY_REQUESTOR"
}

Response Elements

  • messageId: Unique message identifier
  • conversationId: Conversation tracking identifier
  • statusCode: Response status code
  • statusMessage: Human-readable status message
  • stateChangeReasonCode: Reason for the token state change

Notification Response Message Codes

Detailed response message codes for Notification API operations.

Notification Response Message Codes

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

Notification Delivery Status

Notification API responses indicate the success or failure of notification delivery attempts.

Response Handling

Notification recipients should handle responses appropriately:

  • Acknowledge successful notification receipt
  • Implement retry logic for failed deliveries
  • Log notification events for audit purposes
  • Handle duplicate notifications gracefully