Real-Time Account Updater API Overview

With Real-Time Account Updater, you can securely update your customers’ account information at the time of a transaction and avoid (or recover) declines caused by account lifecycle events (e.g. expirations, reissuances, etc.). A Real-Time Account Updater request is for a single card per request. At this time, Real-Time Account Updater provides account updater support for Visa and Mastercard only. This guide outlines the following Real-Time Account Updater processes, from registration to receiving your first update:

Request access.
Register your business with the card brands.
Authenticate.
Submit a Card Inquiry in real-time upon a transaction decline or a vault update.
Check response of the inquiry, if new data is available update vault or retry transaction.

Review our Testing guide for full instructions on how to test the Real-Time Account Updater API in the sandbox.

Request Access

Contact us if you’re interested in Real-Time Account Updater. Once onboarded, you’ll have access to the Account Updater page in your Pagos Service Panel.

Register With Card Brands

Before you can start requesting and receiving updated card details from the card brands, Pagos must first register your business with Visa and Mastercard. Pagos will work with you directly to collect the necessary business details and complete this registration process. This process is mandatory and required by each card brand. You can check the status of your enrollment on the Networks tab of the Account Updater page.

Authenticating

The Pagos platform uses API keys to authenticate requests to all our services. See our API Authentication guide for full instructions on generating API keys and authenticating with the Pagos APIs.

Submit a Card Inquiry

You can submit card inquiries on POST: /inquiry

There is only one account per request

Request JSON Fields

Inquiry Request

The inquiry request includes the following JSON fields:

Data Field	Variable Type	Description	Example
`requestId` (Required)	string	UUID	`5f954e17-27c2-46d5-b0ed-f28149267500`
`network` (Required)	string	The card brand	This field can only have one of the following values: `visa` or `mastercard`
`account` (Required)	account object	Contains the `account` object listed below.
`subMerchantId` (Nullable)	string	For Visa, a sub-merchant ID between 1 to 12 characters. For Mastercard, a 15 character sub_merchant_id issued by Mastercard

Account Object

The account object includes the following JSON fields:

Data Field	Variable Type	Description	Example
`accountNumber` (Required)	string	Value of length between 13 to 19 characters	`1111111111111111`
`expiryYear` (Required)	string	Value based on YYYY format	`2024`
`expiryMonth` (Required)	string	Value based on MM format	`09`
`metadata` (Nullable)	string	Value of length between 1 to 50 characters	`51032475-bc83-46d8-8768-15e129f3c6e0`

Example Request

{
    "network": "mastercard",
    "requestId": "5f954e17-27c2-46d5-b0ed-f28149267500",
    "account": {
        "accountNumber": "5105105105105100",
        "expiryMonth": "12",
        "expiryYear": "2023",
        "metadata": "51032475-bc83-46d8-8768-15e129f3c6e0"
    }

}

Response JSON Fields

Inquiry Response

The inquiry Response includes the following JSON fields:

Data Field	Variable Type	Description	Example
`code` (Required)	numeric	HTTP response code	`200`
`requestId` (Required)	string	UUID	`5f954e17-27c2-46d5-b0ed-f28149267500`
`account` (Required)	account object	Contains the json account

Account Object

The account object includes the following JSON fields:

Data Field	Variable Type	Description	Example
`accountNumber` (Required)	string	Value (13-19 characters)	`1111111111111111`
`expiryYear` (Required)	string	Value based on YYYY format	`2024`
`expiryMonth` (Required)	string	Value based on MM format	`09`
`newAccountNumber` (Nullable)	string	Value (13-19 characters)	`2222222222222222`
`newExpiryYear` (Nullable)	string	Value based on YYYY format	`2023`
`newExpiryMonth` (Nullable)	string	Value based on MM format	`10`
`responseCode` (Required)	string	A code from the Response Codes table	`LCA`
`errorCode` (Nullable)	string	A code from the Error Codes table	`LE01`
`metadata` (Nullable)	string	Value (1-50 characters)	`51032475-bc83-46d8-8768-15e129f3c6e0`

Example Response

{
    "account": {
        "accountNumber": "5105105105105100",
        "expiryYear": "2023",
        "expiryMonth": "12",
        "newAccountNumber": "5233580618829955",
        "newExpiryYear": "2026",
        "newExpiryMonth": "12",
        "responseCode": "LAE",
        "errorCode": null,
        "metadata": "51032475-bc83-46d8-8768-15e129f3c6e0"
    },
    "requestId": "5f954e17-27c2-46d5-b0ed-f28149267500"
}

Authentication

Data & Response Codes

Data Ingestion

Pagos MCP Server

BIN Database

Account Updater

Network Tokenization

Real-Time Account Updater API Overview

Request Access

Register With Card Brands

Authenticating

Submit a Card Inquiry

Request JSON Fields

Inquiry Request

Account Object

Example Request

Response JSON Fields

Inquiry Response

Account Object

Example Response

​Request Access

​Register With Card Brands

​Authenticating

​Submit a Card Inquiry

​Request JSON Fields

​Inquiry Request

​Account Object

​Example Request

​Response JSON Fields

​Inquiry Response

​Account Object

​Example Response

Request Access

Register With Card Brands

Authenticating

Submit a Card Inquiry

Request JSON Fields

Inquiry Request

Account Object

Example Request

Response JSON Fields

Inquiry Response

Account Object

Example Response