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:
  1. Request access.
  2. Register your business with the card brands.
  3. Authenticate and Encrypt.
  4. Submit a Card Inquiry in real-time upon a transaction decline or a vault update.
  5. Check response of the inquiry, if new data is available update vault or retry transaction.

​
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 and Encrypting

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. For message body encryption, review the encryption guides.

​
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 FieldVariable TypeDescriptionExample
requestId (Required)stringUUID5f954e17-27c2-46d5-b0ed-f28149267500
network (Required)stringThe card brandThis field can only have one of the following values: visa or mastercard
accountEncrypted (Required)blobContains the account (URL-safe base64 encoded). Format: JSON Web Encrypted string using the RequestEncryptionKey. Validation: The accountNumber in this list must be unique.
subMerchantId (Nullable)stringFor Visa, American Express, and Discover, a sub-merchant ID between 1 to 12 characters. For Mastercard, a 15 character sub_merchant_id issued by Mastercard

​
Account Object (before encryption)

The account object includes the following JSON fields:
Data FieldVariable TypeDescriptionExample
accountNumber (Required)stringValue of length between 13 to 19 characters1111111111111111
expiryYear (Required)stringValue based on YYYY format2024
expiryMonth (Required)stringValue based on MM format09
metadata (Nullable)stringValue of length between 1 to 50 characters51032475-bc83-46d8-8768-15e129f3c6e0

​
Example Request

// The account object in plain-text (before encryption)
{
    "network": "visa",
    "requestId": "d61c0dd7-7bd8-48d7-9bb2-6c46681fea09",
    "account": {
        "accountNumber": "4111111111111111",
        "expiryYear": "2023",
        "expiryMonth": "12",
        "metadata": "51032475-bc83-46d8-8768-15e129f3c6e0"
    },
    "subMerchantId": null
}

// The full request after encryption including headers
{
    "X-Date": "2024-12-24T04:47:52.421Z",
    "X-Client-Key": "C732E1FD95D919F3CBAD56C0382E0D0E",
    "Authorization": "V1-HMAC-SHA256, Signature: uDf66s9aDVIEjbMNYeo+6pcZVlBVfeb1/3ieXUPv5qc=",
    "X-Merchant-Id": "47cb8551-9977-4ea9-bf4d-c12082af233b",
    "Content-Type": "application/json"
}
// The request object (using JWE Token)
{
    "network": "visa",
    "requestId": "d61c0dd7-7bd8-48d7-9bb2-6c46681fea09",
    "subMerchantId": null,
    "accountEncrypted": "eyJ...-Q"
}

​
Check the Inquiry Response

After you submit a successful inquiry to Pagos, you’ll receive an encrypted response. You can decrypt the response using your ResponseDecryptionKey. See our encryption guide for a full example.

​
Response JSON Fields

​
Inquiry Response

The inquiry Response includes the following JSON fields:
Data FieldVariable TypeDescriptionExample
code (Required)numericHTTP response code200
requestId (Required)stringUUID5f954e17-27c2-46d5-b0ed-f28149267500
accountEncrypted (Required)blobContains the account (URL-safe base64 encoded)

​
Account Object (after decryption)

The account object includes the following JSON fields:
Data FieldVariable TypeDescriptionExample
accountNumber (Required)stringValue (13-19 characters)1111111111111111
expiryYear (Required)stringValue based on YYYY format2024
expiryMonth (Required)stringValue based on MM format09
newAccountNumber (Nullable)stringValue (13-19 characters)2222222222222222
newExpiryYear (Nullable)stringValue based on YYYY format2023
newExpiryMonth (Nullable)stringValue based on MM format10
responseCode (Required)stringA code from the Response Codes tableLCA
errorCode (Nullable)stringA code from the Error Codes tableLE01
metadata (Nullable)stringValue (1-50 characters)51032475-bc83-46d8-8768-15e129f3c6e0

​
Example Response

// The encrypted response object
{
    "accountEncrypted": "eyJ...qg",
    "requestId": "d61c0dd7-7bd8-48d7-9bb2-6c46681fea09"
}

// The response object in plain-text (after decryption)
{
    "requestId": "d61c0dd7-7bd8-48d7-9bb2-6c46681fea09",
    "account": {
        "accountNumber": "4111111111111111",
        "expiryYear": "2023",
        "expiryMonth": "12",
        "newAccountNumber": "4166676667666746",
        "newExpiryYear": null,
        "newExpiryMonth": null,
        "responseCode": "LAE",
        "errorCode": null,
        "metadata": "51032475-bc83-46d8-8768-15e129f3c6e0"
    }
}