Use real-time account updater

DocsCurrentADVANCED

Last updated: Oct 30th, 10:46am

Use real-time account updates to reduce declined card payments. Real-time account updater increases payment success by asking the card issuer for updates about the buyer's card, and applying any changes to the current card.

Use this integration guide if you are a developer from a third-party platform or marketplace that offers PayPal as a payment processing gateway to your sellers.

If you are new to PayPal, visit this page to learn more about the third-party platforms available for your integration.

If you are a merchant and already have a shop set up with any of PayPal's third-party partners, ask your provider if they already support this feature. If the partner can offer you this feature, you don't need to follow the instructions in this guide.

What is real-time account updater?

A buyer's credit or debit card can be declined for many reasons. When a card on file expires, is lost or stolen, or changes for any other reason, payments using that saved card are declined. A declined card can interrupt or prevent a transaction and impact your relationship with that customer.

Only cards that the customer has saved for future payments are eligible for real-time updates. The card can be saved from a previous successful transaction in the partner's vault, or a third-party PCI-compliant vaulting solution provider. When triggered, real-time account updater obtains the updated card information to use for the payment. The API response includes data about the card used to complete the payment. For details on how to save a card for future payments, visit Save payment methods.

Examples of payments using a card on file include:

  • Recurring payments on a subscription for a service or a product.
  • Online or mobile checkout using a previously saved credit or debit card.

Real-time account updater doesn't apply to mobile payments from a digital wallet, such as Apple Pay, Google Pay, and Samsung Pay.

Eligibility

Real-time account updater is a limited early access program for all partners with the following integrations enabled:

Real-time account updates only occur on subsequent card payments using a card on file. For examples of subsequent payment scenarios, see the Strong Customer Authentication payment indicators page.

Real-time account updater works when issuers agree to share card updates via card networks. PayPal can’t provide a card update when the card issuer or cardholder opts out of automatic updates. When a card account doesn’t support real-time account updates, request a card update directly from the cardholder.

If you're interested in using real-time account updater and are already a partner affiliated with PayPal, contact your PayPal sales representative. To apply to become a PayPal partner, go to the PayPal Partners page and select Contact us.

Supported countries

The following table shows the card types and countries that real-time account updater supports.

  • Issuing country: The country of the bank that issues the card.
  • Merchant country: The country where the merchant receives the payment.
Card network Card type Issuing country Merchant country
Mastercard Credit and debit cards AT, AU, BE, BG, CA, CY, CZ, DE, DK, EE, ES, FI, FR, GR, HU, IE, IT, LI, LT, LU, LV, MT, NL, NO, PL, PT, RO, SE, SI, SK, UK, US AT, AU, BE, BG, CA, CN, CY, CZ, DE, DK, EE, ES, FI, FR, GR, HU, IE, IT, LI, LT, LU, LV, MT, NL, NO, PL, PT, RO, SE, SI, SK, UK, US
Visa Credit and debit cards US AT, AU, BE, BG, CA, CN, CY, CZ, DE, DK, EE, ES, FI, FR, GR, HU, IE, IT, LI, LT, LU, LV, MT, NL, NO, PL, PT, RO, SE, SI, SK, UK, US

How it works

PayPal works with Mastercard and Visa to reduce declined payments using real-time account updates.

Mastercard

When a partner or direct merchant has real-time account updater enabled for their account, PayPal checks if the card information is current and eligible for updates.

  1. A merchant has a card on file that was saved for future payments with the customer's consent.
  2. The buyer makes a purchase using the saved card on file, or the merchant uses the card on file for a recurring payment.
  3. PayPal processes the payment as an advanced credit or debit transaction.
  4. Mastercard sends the payment to the card issuer, but the card on file has expired, has been cancelled, or is otherwise not available for payment.
  5. Mastercard notifies PayPal that the issuer declined the card.
  6. PayPal checks to see if the card on file is eligible for real-time account updater.
  7. PayPal sends a request to Mastercard to check whether the card's information is current.
  8. Mastercard confirms that the card has changed, and sends the updated card information.
  9. PayPal resubmits the payment on the merchant's behalf using the updated card information.
  10. PayPal returns the updated card information to the merchant. If the card on file was a vaulted token, PayPal updates the card on file in the PayPal Complete Payments Platform vault.


image

Visa

When a partner or direct merchant has real-time account updater enabled for their account, PayPal flags the card for Visa to verify and update card information.

  1. A merchant has a card on file that was saved for future payments with the customer's consent.
  2. The buyer makes a purchase using the saved card on file, or the merchant uses the card on file for a recurring payment.
  3. PayPal processes the payment as an advanced credit or debit card transaction.
  4. PayPal checks to see if the card on file is eligible for real-time account updater.
  5. PayPal flags the payment so that Visa checks for card updates.
  6. The card on file has expired, has been cancelled, or is otherwise not available for payment.
  7. If an update is available, Visa submits the payment to the issuer using the updated card information.
  8. After the issuer approves the payment, Visa returns the updated card information to PayPal.
  9. PayPal returns the updated card information to the merchant. If the card on file was a vaulted token, PayPal updates the card on file in the PayPal Complete Payments Platform vault.


image

API responses

Real-time account updates use specific fields and error codes that could impact your existing integration.

Real-time account updater supports multiparty payments for cards and tokens.

Payment requests with a card

Payment requests that use a card return 2 additional parameters: expiry and from_request.

expiry response

The expiry response field is included in the card object and returns the expiration date of the card used for payment.

from_request response

The from_request response field shows the last 4 digits and expiration date of the card submitted for the payment.

Sample payment response

    1{
    2  "payment_source": {
    3    "card": {
    4        "last_digits": "2557",
    5        "expiry": "2040-12",
    6        "from_request": {
    7            "expiry": "2023-01",
    8            "last_digits": "4792"
    9        },
    10        "brand": "MASTER_CARD",
    11        "type": "CREDIT"
    12    }
    13  }
    14}

    Sample payment response for closed card error

    The HTTP 422 error response is returned when a card on file when a card on file that is marked as closed is used for payment.

      1{
      2    "name": "UNPROCESSABLE_ENTITY",
      3    "details": [
      4            {
      5                "field": "payment_source/card",
      6                "location": "body",
      7                "issue": "CARD_CLOSED",
      8                "description": "The card is closed."
      9            }
      10    ],
      11    "message": "The requested action could not be performed, semantically incorrect, or failed business validation.",
      12    "debug_id": "6a20810eaecc5",
      13    "links": [
      14            {
      15                "href": "/docs/api/orders/v2/#error-CARD_CLOSED",
      16                "rel": "information_link",
      17                "method": "GET"
      18            }
      19    ]
      20  }

      Payment requests with a token

      Payment requests that use a payment token return 2 additional parameters: expiry and last_digits.

      When PayPal completes a payment using an updated expiration or primary account number (PAN):

      • The response fields pass the new values instead of the old values stored in the payment method in PayPal's vault.
      • PayPal updates the vaulted payment method with the new values.

      expiry response

      The expiry response field is included in the card object and returns the expiration date of the card used for payment.

      last_digits response

      The last_digits response field is included in the card object and returns the last 4 digits of the card number used for payment.

      Sample payment response

        1{
        2  "payment_source": {
        3    "card": {
        4        "last_digits": "2557",
        5        "expiry": "2040-12",
        6        "brand": "MASTER_CARD",
        7        "type": "CREDIT"
        8    }
        9  }

        Sample payment response for closed card error

        The HTTP 422 error response is returned when a card on file that is marked as closed is used for payment.

          1{
          2    "name": "UNPROCESSABLE_ENTITY",
          3    "details": [
          4            {
          5                "field": "payment_source/card",
          6                "location": "body",
          7                "issue": "CARD_CLOSED",
          8                "description": "The card is closed."
          9            }
          10    ],
          11    "message": "The requested action could not be performed, semantically incorrect, or failed business validation.",
          12    "debug_id": "6a20810eaecc5",
          13    "links": [
          14            {
          15                "href": "/docs/api/orders/v2/#error-CARD_CLOSED",
          16                "rel": "information_link",
          17                "method": "GET"
          18            }
          19    ]
          20  }

          Postman collection

          Download the Postman collection for real-time account updater to test making updates to cards.

          Sample card change scenarios

          This section shows how real-time account updater responds to 6 different card changes.

          • Expired card
          • Updated card
          • Closed card
          • Expired token
          • Updated token
          • Closed token

          Expired card

          This sample shows what happens when an expired card is used for a payment. The response returns the updated expiration date for the same card.

          API endpoint: /v2/checkout/orders

          1. Request
          2. Response
          1{
          2    "intent": "CAPTURE",
          3    "payment_source": {
          4        "card": {
          5            "number": "4417164131206198",
          6            "expiry": "2022-01",
          7            "name": "Firstname Lastname",
          8            "stored_credential": {
          9                "payment_initiator": "CUSTOMER",
          10                "payment_type": "UNSCHEDULED",
          11                "usage": "SUBSEQUENT"
          12            }
          13        }
          14    },
          15    "payer": {
          16        "name": {
          17            "given_name": "Firstname Lastname",
          18            "surname": "user"
          19        },
          20        "address": {
          21            "address_line_1": "123 Main St.",
          22            "address_line_2": "",
          23            "admin_area_2": "Anytown",
          24            "admin_area_1": "CA",
          25            "postal_code": "12345",
          26            "country_code": "US"
          27        }
          28    },
          29    "purchase_units": [
          30        {
          31            "reference_id": "123_34897583499",
          32            "description": "Item bought at Hemm Store",
          33            "custom_id": "1111",
          34            "soft_descriptor": "",
          35            "amount": {
          36                "currency_code": "USD",
          37                "value": "80.00"
          38            },
          39            "shipping": {
          40                "address": {
          41                    "address_line_1": "123 Main St.",
          42                    "address_line_2": "",
          43                    "admin_area_2": "Anytown",
          44                    "admin_area_1": "CA",
          45                    "postal_code": "12345",
          46                    "country_code": "US"
          47                }
          48            },
          49            "payee": {
          50                "email_address": "payer@example.com"
          51            }
          52        }
          53    ]
          54}

          Updated card

          This sample shows what happens when an unexpired card is used for payment, but the details of the card don't match the card on file. For example, the card could be reported as lost or stolen, or otherwise reissued. The response returns details about the new card issued.

          API endpoint: /v2/checkout/orders

          1. Request
          2. Response
          1{
          2    "intent": "CAPTURE",
          3    "payment_source": {
          4        "card": {
          5            "number": "4417164138767119",
          6            "expiry": "2024-09",
          7            "name": "Firstname Lastname",
          8            "stored_credential": {
          9                "payment_initiator": "MERCHANT",
          10                "payment_type": "RECURRING",
          11                "usage": "SUBSEQUENT",
          12                "previous_reference_id": "9UX37427Y3757812J"
          13            }
          14        }
          15    },
          16    "payer": {
          17        "name": {
          18            "given_name": "Firstname Lastname",
          19            "surname": "user"
          20        },
          21        "address": {
          22            "address_line_1": "123 Main St.",
          23            "address_line_2": "",
          24            "admin_area_2": "Anytown",
          25            "admin_area_1": "CA",
          26            "postal_code": "12345",
          27            "country_code": "US"
          28        }
          29    },
          30    "purchase_units": [
          31        {
          32            "reference_id": "123_34897583499",
          33            "description": "Item bought at Hemm Store",
          34            "custom_id": "1111",
          35            "soft_descriptor": "",
          36            "amount": {
          37                "currency_code": "USD",
          38                "value": "80.00"
          39            },
          40            "shipping": {
          41                "address": {
          42                    "address_line_1": "123 Main St.",
          43                    "address_line_2": "",
          44                    "admin_area_2": "Anytown",
          45                    "admin_area_1": "CA",
          46                    "postal_code": "12345",
          47                    "country_code": "US"
          48                }
          49            },
          50            "payee": {
          51                "email_address": "payer@example.com"
          52            }
          53        }
          54    ]
          55}

          Closed card

          This sample shows what happens when a closed card is used for a payment. The cardholder no longer has the card with the issuer, so the updater can't get new card information. The response shows that the card is closed.

          API endpoint: /v2/checkout/orders

          1. Request
          2. Response
          1{
          2    "intent": "CAPTURE",
          3    "payment_source": {
          4        "card": {
          5            "number": "5277356243447050",
          6            "expiry": "2024-09",
          7            "name": "Firstname Lastname",
          8            "stored_credential": {
          9                "payment_initiator": "MERCHANT",
          10                "payment_type": "RECURRING",
          11                "usage": "SUBSEQUENT",
          12                "previous_reference_id": "9UX37427Y3757812J"
          13            }
          14        }
          15    },
          16    "payer": {
          17        "name": {
          18            "given_name": "Firstname Lastname",
          19            "surname": "user"
          20        },
          21        "address": {
          22            "address_line_1": "123 Main St.",
          23            "address_line_2": "",
          24            "admin_area_2": "Anytown",
          25            "admin_area_1": "CA",
          26            "postal_code": "12345",
          27            "country_code": "US"
          28        }
          29    },
          30    "purchase_units": [
          31        {
          32            "reference_id": "123_34897583499",
          33            "description": "Item bought at Hemm Store",
          34            "custom_id": "1111",
          35            "soft_descriptor": "",
          36            "amount": {
          37                "currency_code": "USD",
          38                "value": "80.00"
          39            },
          40            "shipping": {
          41                "address": {
          42                    "address_line_1": "123 Main St.",
          43                    "address_line_2": "",
          44                    "admin_area_2": "Anytown",
          45                    "admin_area_1": "CA",
          46                    "postal_code": "12345",
          47                    "country_code": "US"
          48                }
          49            },
          50            "payee": {
          51                "email_address": "payer@example.com"
          52            }
          53        }
          54    ]
          55}

          Expired token

          This sample shows what happens when a token for an expired card is used for a payment. The response returns the updated expiration date for the same card.

          If you call GET /v3/vault/payment-tokens/{id} using the token before you submit the order using POST /v2/checkout/orders, the POST response includes the updated values that PayPal used to complete the payment. Compare the expiry returned by the GET call to the expiry returned by the POST call.

          API endpoint: /v2/checkout/orders

          1. Request
          2. Response
          1{
          2    "intent": "CAPTURE",
          3    "payment_source": {
          4        "token": {
          5            "id": "2hkeag02",
          6            "type": "PAYMENT_METHOD_TOKEN"
          7        }
          8    },
          9    "payer": {
          10        "name": {
          11            "given_name": "Firstname Lastname",
          12            "surname": "user"
          13        },
          14        "address": {
          15            "address_line_1": "123 Main St.",
          16            "address_line_2": "",
          17            "admin_area_2": "Anytown",
          18            "admin_area_1": "CA",
          19            "postal_code": "12345",
          20            "country_code": "US"
          21        }
          22    },
          23    "purchase_units": [
          24        {
          25            "reference_id": "123_34897583499",
          26            "description": "Item bought at Hemm Store",
          27            "custom_id": "1111",
          28            "soft_descriptor": "",
          29            "amount": {
          30                "currency_code": "USD",
          31                "value": "80.00"
          32            },
          33            "shipping": {
          34                "address": {
          35                    "address_line_1": "123 Main St.",
          36                    "address_line_2": "",
          37                    "admin_area_2": "Anytown",
          38                    "admin_area_1": "CA",
          39                    "postal_code": "12345",
          40                    "country_code": "US"
          41                }
          42            },
          43            "payee": {
          44                "email_address": "payer@example.com"
          45            }
          46        }
          47    ]
          48}

          Updated token

          This sample shows what happens when a token for an unexpired card is used for a payment. The response returns details about the new card issued.

          If you call GET /v3/vault/payment-tokens/{id} using the token before you submit the order using POST /v2/checkout/orders, the POST response includes the updated values that PayPal used to complete the payment. Compare the expiry and last_digits returned by the GET call to the values returned by the POST call.

          API endpoint: /v2/checkout/orders

          1. Request
          2. Response
          1{
          2    "intent": "CAPTURE",
          3    "payment_source": {
          4        "token": {
          5            "id": "nrj02x7a",
          6            "type": "PAYMENT_METHOD_TOKEN"
          7        }
          8    },
          9    "payer": {
          10        "name": {
          11            "given_name": "Firstname Lastname",
          12            "surname": "user"
          13        },
          14        "address": {
          15            "address_line_1": "123 Main St.",
          16            "address_line_2": "",
          17            "admin_area_2": "Anytown",
          18            "admin_area_1": "CA",
          19            "postal_code": "12345",
          20            "country_code": "US"
          21        }
          22    },
          23    "purchase_units": [
          24        {
          25            "reference_id": "123_34897583499",
          26            "description": "Item bought at Hemm Store",
          27            "custom_id": "1111",
          28            "soft_descriptor": "",
          29            "amount": {
          30                "currency_code": "USD",
          31                "value": "80.00"
          32            },
          33            "shipping": {
          34                "address": {
          35                    "address_line_1": "123 Main St.",
          36                    "address_line_2": "",
          37                    "admin_area_2": "Anytown",
          38                    "admin_area_1": "CA",
          39                    "postal_code": "12345",
          40                    "country_code": "US"
          41                }
          42            },
          43            "payee": {
          44                "email_address": "payer@example.com"
          45            }
          46        }
          47    ]
          48}

          Closed token

          This sample shows what happens when a token for a closed card is used for a payment. The issuer no longer provides the linked card to the cardholder, so the updater can't get new token information. The response shows that the card is closed.

          API endpoint: /v2/checkout/orders

          1. Request
          2. Response
          1{
          2    "intent": "CAPTURE",
          3    "payment_source": {
          4        "token": {
          5            "id": "dhq07phc",
          6            "type": "PAYMENT_METHOD_TOKEN"
          7        }
          8    },
          9    "payer": {
          10        "name": {
          11            "given_name": "Firstname Lastname",
          12            "surname": "user"
          13        },
          14        "address": {
          15            "address_line_1": "123 Main St.",
          16            "address_line_2": "",
          17            "admin_area_2": "Anytown",
          18            "admin_area_1": "CA",
          19            "postal_code": "12345",
          20            "country_code": "US"
          21        }
          22    },
          23    "purchase_units": [
          24        {
          25            "reference_id": "123_34897583499",
          26            "description": "Item bought at Hemm Store",
          27            "custom_id": "1111",
          28            "soft_descriptor": "",
          29            "amount": {
          30                "currency_code": "USD",
          31                "value": "80.00"
          32            },
          33            "shipping": {
          34                "address": {
          35                    "address_line_1": "123 Main St.",
          36                    "address_line_2": "",
          37                    "admin_area_2": "Anytown",
          38                    "admin_area_1": "CA",
          39                    "postal_code": "12345",
          40                    "country_code": "US"
          41                }
          42            },
          43            "payee": {
          44                "email_address": "payer@example.com"
          45            }
          46        }
          47    ]
          48}
          ReferencePayPal.comPrivacyCookiesSupportLegalContact

          We use cookies to improve your experience on our site. May we use marketing cookies to show you personalized ads? Manage all cookies