Add real-time account updater

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 merchant and have a direct integration with PayPal.

Only cards that the customer has saved on PayPal's Commerce Platform for future payments are eligible for real-time updates. 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, and 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.

Even cards that qualify for real-time updates may not be updated during a transaction. Read PayPal's Online Card Payment Services Agreement for details.

Eligibility

Real-time account updater is a limited early access program for all merchants 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, go to our article about Real-Time Account Updater and integration.

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
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	AT, AU, BE, BG, CH, CY, CZ, DE, DK, EE, ES, FI, FR, GR, HK, HU, IE, IT, LT, LU, LV, MT, NL, NO, PL, PT, RO, SE, SG, 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

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.

A merchant has a card on file that was saved for future payments with the customer's consent.
The buyer makes a purchase using the saved card on file, or the merchant uses the card on file for a recurring payment.
PayPal processes the payment as an advanced credit or debit transaction.
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.
Mastercard notifies PayPal that the issuer declined the card.
PayPal checks to see if the card on file is eligible for real-time account updater.
PayPal sends a request to Mastercard to check whether the card's information is current.
Mastercard confirms that the card has changed, and sends the updated card information.
PayPal resubmits the payment on the merchant's behalf using the updated card information.
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.

Visa

When real-time account updater is enabled, PayPal flags the card for Visa to verify and update card information before the issuer processes the payment.

The buyer makes a purchase using a saved card on file, or the merchant uses the card for a recurring payment.
PayPal processes the payment as an advanced credit or debit card transaction.
PayPal checks if the card is eligible for real-time account updater.
PayPal flags the payment so Visa checks for card updates.
If the card has expired, been cancelled, or is otherwise unavailable, and an update is available, Visa submits the payment to the issuer using the updated card information.
After the issuer approves the payment, Visa returns the updated card information to PayPal.
PayPal returns the updated card information to the merchant. If the card was a vaulted token, PayPal updates the card in the vault.

If no update is available, Visa submits the payment using the original card information. The issuer approves or declines the payment.

API responses for real-time account updater

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

Payments 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:

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.

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

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

{
  "payment_source": {
    "card": {
        "last_digits": "2557",
        "expiry": "2040-12",
        "from_request": {
            "expiry": "2028-01",
            "last_digits": "1234"
        },
        "brand": "MASTER_CARD",
        "type": "CREDIT"
    }
  }
}

Closed card error

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

{
    "name": "UNPROCESSABLE_ENTITY",
    "details": [
            {
                "field": "payment_source/card",
                "location": "body",
                "issue": "CARD_CLOSED",
                "description": "The card is closed."
            }
    ],
    "message": "The requested action could not be performed, semantically incorrect, or failed business validation.",
    "debug_id": "6a20810eaecc5",
    "links": [
            {
                "href": "https://developer.paypal.com/api/orders/v2/error-messages",
                "rel": "information_link",
                "method": "GET"
            }
    ]
}

Test in sandbox

Use sandbox trigger values to simulate real-time account updater scenarios. Pass these values in the card.name field when creating an order with POST /v2/checkout/orders.

Trigger value, Scenario, Behavior
Trigger value	Scenario	Behavior
`CCREJECT-RTAU-EU`	Expired card replaced with updated card	Returns updated card expiration
`CCREJECT-RTAU-PEU`	Lost or stolen card replaced with new card	Returns updated card number and expiration
`CCREJECT-RTAU-AC`	Card closed	Returns `CARD_CLOSED` error and declines the transaction
`CCREJECT-RTAU-NU`	No update available or cardholder opted out	No updates returned; declines if card is expired

The payment token id values in the token scenarios below are placeholders. Generate and use your own payment tokens.

Download the Postman collection to test making updates to cards.

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

A token for an expired card is used for 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.

Endpoint: POST /v2/checkout/orders

{
    "intent": "CAPTURE",
    "payment_source": {
        "token": {
            "id": "0rjdehvx",
            "type": "PAYMENT_METHOD_TOKEN"
        }
    },
    "payer": {
        "name": {
            "given_name": "kakashi Hatakae",
            "surname": "user"
        },
        "address": {
            "address_line_1": "123 Main St.",
            "address_line_2": "Floor 6",
            "admin_area_2": "Anytown",
            "admin_area_1": "CA",
            "postal_code": "12345",
            "country_code": "US"
        }
    },
    "purchase_units": [
        {
            "description": "Item bought at Hemm Store",
            "custom_id": "1111",
            "soft_descriptor": "",
            "amount": {
                "currency_code": "USD",
                "value": "45.00"
            },
            "shipping": {
                "address": {
                    "address_line_1": "123 Main St.",
                    "address_line_2": "Building 17",
                    "admin_area_2": "Anytown",
                    "admin_area_1": "CA",
                    "postal_code": "12345",
                    "country_code": "US"
                }
            }
        }
    ]
}

{
    "id": "7YS401589T475863H",
    "status": "COMPLETED",
    "payment_source": {
        "card": {
            "last_digits": "9855",
            "expiry": "2040-12",
            "brand": "VISA",
            "type": "CREDIT"
        }
    },
    "purchase_units": [
        {
            "reference_id": "default",
            "shipping": {
                "address": {
                    "address_line_1": "123 Main St.",
                    "address_line_2": "Floor 6",
                    "admin_area_2": "Anytown",
                    "admin_area_1": "CA",
                    "postal_code": "12345",
                    "country_code": "US"
                }
            },
            "payments": {
                "captures": [
                    {
                        "id": "1MJ8142177130444J",
                        "status": "COMPLETED",
                        "amount": {
                            "currency_code": "USD",
                            "value": "45.00"
                        },
                        "final_capture": true,
                        "seller_protection": {
                            "status": "NOT_ELIGIBLE"
                        },
                        "seller_receivable_breakdown": {
                            "gross_amount": {
                                "currency_code": "USD",
                                "value": "45.00"
                            },
                            "paypal_fee": {
                                "currency_code": "USD",
                                "value": "1.66"
                            },
                            "net_amount": {
                                "currency_code": "USD",
                                "value": "43.34"
                            }
                        },
                        "custom_id": "1111",
                        "links": [
                            {
                                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/1MJ8142177130444J",
                                "rel": "self",
                                "method": "GET"
                            },
                            {
                                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/1MJ8142177130444J/refund",
                                "rel": "refund",
                                "method": "POST"
                            },
                            {
                                "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/7YS401589T475863H",
                                "rel": "up",
                                "method": "GET"
                            }
                        ],
                        "create_time": "2023-03-12T17:53:18Z",
                        "update_time": "2023-03-12T17:53:18Z",
                        "processor_response": {
                            "avs_code": "A",
                            "cvv_code": "M",
                            "response_code": "0000"
                        }
                    }
                ]
            }
        }
    ],
    "links": [
        {
            "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/7YS401589T475863H",
            "rel": "self",
            "method": "GET"
        }
    ]
}

A token for a card that has been reissued is used for payment. The response returns the new card details.

Endpoint: POST /v2/checkout/orders

{
    "intent": "CAPTURE",
    "payment_source": {
        "token": {
            "id": "nrj02x7a",
            "type": "PAYMENT_METHOD_TOKEN"
        }
    },
    "purchase_units": [
        {
            "reference_id": "123_34897583499",
            "amount": {
                "currency_code": "USD",
                "value": "80.00"
            }
        }
    ]
}

{
    "id": "8U933064PE919040J",
    "status": "COMPLETED",
    "payment_source": {
        "card": {
            "last_digits": "5072",
            "expiry": "2040-12",
            "brand": "VISA",
            "type": "CREDIT"
        }
    },
    "purchase_units": [
        {
            "reference_id": "123_34897583499",
            "payments": {
                "captures": [
                    {
                        "id": "4257163761283522F",
                        "status": "COMPLETED",
                        "amount": {
                            "currency_code": "USD",
                            "value": "80.00"
                        },
                        "final_capture": true,
                        "seller_receivable_breakdown": {
                            "gross_amount": { "currency_code": "USD", "value": "80.00" },
                            "paypal_fee": { "currency_code": "USD", "value": "2.56" },
                            "net_amount": { "currency_code": "USD", "value": "77.44" }
                        },
                        "processor_response": {
                            "response_code": "0000"
                        }
                    }
                ]
            }
        }
    ]
}

A token for a closed card is used for payment. The issuer no longer provides the card, so the updater can't retrieve new information.

Endpoint: POST /v2/checkout/orders

{
    "intent": "CAPTURE",
    "payment_source": {
        "token": {
            "id": "dhq07phc",
            "type": "PAYMENT_METHOD_TOKEN"
        }
    },
    "purchase_units": [
        {
            "reference_id": "123_34897583499",
            "amount": {
                "currency_code": "USD",
                "value": "80.00"
            }
        }
    ]
}

{
    "name": "UNPROCESSABLE_ENTITY",
    "details": [
        {
            "field": "payment_source/card",
            "location": "body",
            "issue": "CARD_CLOSED",
            "description": "The card is closed."
        }
    ],
    "message": "The requested action could not be performed, semantically incorrect, or failed business validation.",
    "debug_id": "",
    "links": [
        {
            "href": "/docs/api/orders/v2/#error-CARD_CLOSED",
            "rel": "information_link",
            "method": "GET"
        }
    ]
}

An expired card is used for payment. The response returns the updated expiration date for the same card.

Endpoint: POST /v2/checkout/orders

{
    "intent": "CAPTURE",
    "payment_source": {
        "card": {
            "number": "4417164131206198",
            "expiry": "2022-01",
            "name": "Firstname Lastname",
            "stored_credential": {
                "payment_initiator": "CUSTOMER",
                "payment_type": "UNSCHEDULED",
                "usage": "SUBSEQUENT"
            }
        }
    },
    "purchase_units": [
        {
            "reference_id": "123_34897583499",
            "amount": {
                "currency_code": "USD",
                "value": "80.00"
            }
        }
    ]
}

{
    "id": "5YF61787W75673346",
    "status": "COMPLETED",
    "payment_source": {
        "card": {
            "last_digits": "6198",
            "expiry": "2040-12",
            "from_request": {
                "last_digits": "6198",
                "expiry": "2022-01"
            },
            "brand": "VISA",
            "type": "CREDIT"
        }
    },
    "purchase_units": [
        {
            "reference_id": "123_34897583499",
            "payments": {
                "captures": [
                    {
                        "id": "9UX37427Y3757812J",
                        "status": "COMPLETED",
                        "amount": {
                            "currency_code": "USD",
                            "value": "80.00"
                        },
                        "final_capture": true,
                        "disbursement_mode": "INSTANT",
                        "seller_protection": {
                            "status": "NOT_ELIGIBLE"
                        },
                        "seller_receivable_breakdown": {
                            "gross_amount": {
                                "currency_code": "USD",
                                "value": "80.00"
                            },
                            "paypal_fee": {
                                "currency_code": "USD",
                                "value": "2.56"
                            },
                            "net_amount": {
                                "currency_code": "USD",
                                "value": "77.44"
                            }
                        },
                        "custom_id": "1111",
                        "links": [
                            {
                                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/9UX37427Y3757812J",
                                "rel": "self",
                                "method": "GET"
                            },
                            {
                                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/9UX37427Y3757812J/refund",
                                "rel": "refund",
                                "method": "POST"
                            },
                            {
                                "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5YF61787W75673346",
                                "rel": "up",
                                "method": "GET"
                            }
                        ],
                        "create_time": "2023-03-12T17:33:41Z",
                        "update_time": "2023-03-12T17:33:41Z",
                        "processor_response": {
                            "avs_code": "A",
                            "cvv_code": "M",
                            "response_code": "0000"
                        }
                    }
                ]
            }
        }
    ],
    "links": [
        {
            "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5YF61787W75673346",
            "rel": "self",
            "method": "GET"
        }
    ]
}

A card on file has been reported lost, stolen, or reissued. The response returns details about the new card.

Endpoint: POST /v2/checkout/orders

{
    "intent": "CAPTURE",
    "payment_source": {
        "card": {
            "number": "4417164138767119",
            "expiry": "2024-09",
            "name": "Firstname Lastname",
            "stored_credential": {
                "payment_initiator": "MERCHANT",
                "payment_type": "RECURRING",
                "usage": "SUBSEQUENT",
                "previous_reference_id": "9UX37427Y3757812J"
            }
        }
    },
    "purchase_units": [
        {
            "reference_id": "123_34897583499",
            "amount": {
                "currency_code": "USD",
                "value": "80.00"
            }
        }
    ]
}

{
    "id": "1C421544FH848363U",
    "status": "COMPLETED",
    "payment_source": {
        "card": {
            "last_digits": "8934",
            "expiry": "2040-12",
            "from_request": {
                "last_digits": "7119",
                "expiry": "2024-09"
            },
            "brand": "VISA",
            "type": "CREDIT"
        }
    },
    "purchase_units": [
        {
            "reference_id": "123_34897583499",
            "payments": {
                "captures": [
                    {
                        "id": "43T026101K926890G",
                        "status": "COMPLETED",
                        "amount": {
                            "currency_code": "USD",
                            "value": "80.00"
                        },
                        "final_capture": true,
                        "seller_receivable_breakdown": {
                            "gross_amount": { "currency_code": "USD", "value": "80.00" },
                            "paypal_fee": { "currency_code": "USD", "value": "2.56" },
                            "net_amount": { "currency_code": "USD", "value": "77.44" }
                        },
                        "processor_response": {
                            "avs_code": "A",
                            "cvv_code": "M",
                            "response_code": "0000"
                        }
                    }
                ]
            }
        }
    ]
}

A closed card is used for payment. The issuer no longer provides the card, so the updater can't retrieve new information.

Endpoint: POST /v2/checkout/orders

{
    "intent": "CAPTURE",
    "payment_source": {
        "card": {
            "number": "5277356243447050",
            "expiry": "2024-09",
            "name": "Firstname Lastname",
            "stored_credential": {
                "payment_initiator": "MERCHANT",
                "payment_type": "RECURRING",
                "usage": "SUBSEQUENT",
                "previous_reference_id": "9UX37427Y3757812J"
            }
        }
    },
    "purchase_units": [
        {
            "reference_id": "123_34897583499",
            "amount": {
                "currency_code": "USD",
                "value": "80.00"
            }
        }
    ]
}

{
    "name": "UNPROCESSABLE_ENTITY",
    "details": [
        {
            "field": "payment_source/card",
            "location": "body",
            "issue": "CARD_CLOSED",
            "description": "The card is closed."
        }
    ],
    "message": "The requested action could not be performed, semantically incorrect, or failed business validation.",
    "debug_id": "4a39c5973dac8",
    "links": [
        {
            "href": "/docs/api/orders/v2/#error-CARD_CLOSED",
            "rel": "information_link",
            "method": "GET"
        }
    ]
}

Use this integration guide if you are a merchant and have a direct integration with PayPal.

Examples of payments using a card on file include recurring payments on a subscription for a service or a product, and 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.

Even cards that qualify for real-time updates may not be updated during a transaction. Read PayPal's Online Card Payment Services Agreement for details.

Eligibility

Real-time account updater is a limited early access program for all merchants 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.

If you're interested in using real-time account updater, go to our article about Real-Time Account Updater and integration.

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
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	AT, AU, BE, BG, CH, CY, CZ, DE, DK, EE, ES, FI, FR, GR, HK, HU, IE, IT, LT, LU, LV, MT, NL, NO, PL, PT, RO, SE, SG, 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

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.

A merchant has a card on file that was saved for future payments with the customer's consent.
The buyer makes a purchase using the saved card on file, or the merchant uses the card on file for a recurring payment.
PayPal processes the payment as an advanced credit or debit transaction.
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.
Mastercard notifies PayPal that the issuer declined the card.
PayPal checks to see if the card on file is eligible for real-time account updater.
PayPal sends a request to Mastercard to check whether the card's information is current.
Mastercard confirms that the card has changed, and sends the updated card information.
PayPal resubmits the payment on the merchant's behalf using the updated card information.
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.

Visa

When real-time account updater is enabled, PayPal flags the card for Visa to verify and update card information before the issuer processes the payment.

The buyer makes a purchase using a saved card on file, or the merchant uses the card for a recurring payment.
PayPal processes the payment as an advanced credit or debit card transaction.
PayPal checks if the card is eligible for real-time account updater.
PayPal flags the payment so Visa checks for card updates.
If the card has expired, been cancelled, or is otherwise unavailable, and an update is available, Visa submits the payment to the issuer using the updated card information.
After the issuer approves the payment, Visa returns the updated card information to PayPal.
PayPal returns the updated card information to the merchant. If the card was a vaulted token, PayPal updates the card in the vault.

If no update is available, Visa submits the payment using the original card information. The issuer approves or declines the payment.

API responses for real-time account updater

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

Payments 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:

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.

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

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

{
  "payment_source": {
    "card": {
        "last_digits": "2557",
        "expiry": "2040-12",
        "from_request": {
            "expiry": "2028-01",
            "last_digits": "1234"
        },
        "brand": "MASTER_CARD",
        "type": "CREDIT"
    }
  }
}

Closed card error

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

{
    "name": "UNPROCESSABLE_ENTITY",
    "details": [
            {
                "field": "payment_source/card",
                "location": "body",
                "issue": "CARD_CLOSED",
                "description": "The card is closed."
            }
    ],
    "message": "The requested action could not be performed, semantically incorrect, or failed business validation.",
    "debug_id": "6a20810eaecc5",
    "links": [
            {
                "href": "https://developer.paypal.com/api/orders/v2/error-messages",
                "rel": "information_link",
                "method": "GET"
            }
    ]
}

Test in sandbox

Use sandbox trigger values to simulate real-time account updater scenarios. Pass these values in the card.name field when creating an order with POST /v2/checkout/orders.

Trigger value, Scenario, Behavior
Trigger value	Scenario	Behavior
`CCREJECT-RTAU-EU`	Expired card replaced with updated card	Returns updated card expiration
`CCREJECT-RTAU-PEU`	Lost or stolen card replaced with new card	Returns updated card number and expiration
`CCREJECT-RTAU-AC`	Card closed	Returns `CARD_CLOSED` error and declines the transaction
`CCREJECT-RTAU-NU`	No update available or cardholder opted out	No updates returned; declines if card is expired

The payment token id values in the token scenarios below are placeholders. Generate and use your own payment tokens.

Download the Postman collection to test making updates to cards.

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

A token for an expired card is used for payment. The response returns the updated expiration date for the same card.

Endpoint: POST /v2/checkout/orders

{
    "intent": "CAPTURE",
    "payment_source": {
        "token": {
            "id": "0rjdehvx",
            "type": "PAYMENT_METHOD_TOKEN"
        }
    },
    "payer": {
        "name": {
            "given_name": "kakashi Hatakae",
            "surname": "user"
        },
        "address": {
            "address_line_1": "123 Main St.",
            "address_line_2": "Floor 6",
            "admin_area_2": "Anytown",
            "admin_area_1": "CA",
            "postal_code": "12345",
            "country_code": "US"
        }
    },
    "purchase_units": [
        {
            "description": "Item bought at Hemm Store",
            "custom_id": "1111",
            "soft_descriptor": "",
            "amount": {
                "currency_code": "USD",
                "value": "45.00"
            },
            "shipping": {
                "address": {
                    "address_line_1": "123 Main St.",
                    "address_line_2": "Building 17",
                    "admin_area_2": "Anytown",
                    "admin_area_1": "CA",
                    "postal_code": "12345",
                    "country_code": "US"
                }
            }
        }
    ]
}

{
    "id": "7YS401589T475863H",
    "status": "COMPLETED",
    "payment_source": {
        "card": {
            "last_digits": "9855",
            "expiry": "2040-12",
            "brand": "VISA",
            "type": "CREDIT"
        }
    },
    "purchase_units": [
        {
            "reference_id": "default",
            "shipping": {
                "address": {
                    "address_line_1": "123 Main St.",
                    "address_line_2": "Floor 6",
                    "admin_area_2": "Anytown",
                    "admin_area_1": "CA",
                    "postal_code": "12345",
                    "country_code": "US"
                }
            },
            "payments": {
                "captures": [
                    {
                        "id": "1MJ8142177130444J",
                        "status": "COMPLETED",
                        "amount": {
                            "currency_code": "USD",
                            "value": "45.00"
                        },
                        "final_capture": true,
                        "seller_protection": {
                            "status": "NOT_ELIGIBLE"
                        },
                        "seller_receivable_breakdown": {
                            "gross_amount": {
                                "currency_code": "USD",
                                "value": "45.00"
                            },
                            "paypal_fee": {
                                "currency_code": "USD",
                                "value": "1.66"
                            },
                            "net_amount": {
                                "currency_code": "USD",
                                "value": "43.34"
                            }
                        },
                        "custom_id": "1111",
                        "links": [
                            {
                                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/1MJ8142177130444J",
                                "rel": "self",
                                "method": "GET"
                            },
                            {
                                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/1MJ8142177130444J/refund",
                                "rel": "refund",
                                "method": "POST"
                            },
                            {
                                "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/7YS401589T475863H",
                                "rel": "up",
                                "method": "GET"
                            }
                        ],
                        "create_time": "2023-03-12T17:53:18Z",
                        "update_time": "2023-03-12T17:53:18Z",
                        "processor_response": {
                            "avs_code": "A",
                            "cvv_code": "M",
                            "response_code": "0000"
                        }
                    }
                ]
            }
        }
    ],
    "links": [
        {
            "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/7YS401589T475863H",
            "rel": "self",
            "method": "GET"
        }
    ]
}

A token for a card that has been reissued is used for payment. The response returns the new card details.

Endpoint: POST /v2/checkout/orders

{
    "intent": "CAPTURE",
    "payment_source": {
        "token": {
            "id": "nrj02x7a",
            "type": "PAYMENT_METHOD_TOKEN"
        }
    },
    "purchase_units": [
        {
            "reference_id": "123_34897583499",
            "amount": {
                "currency_code": "USD",
                "value": "80.00"
            }
        }
    ]
}

{
    "id": "8U933064PE919040J",
    "status": "COMPLETED",
    "payment_source": {
        "card": {
            "last_digits": "5072",
            "expiry": "2040-12",
            "brand": "VISA",
            "type": "CREDIT"
        }
    },
    "purchase_units": [
        {
            "reference_id": "123_34897583499",
            "payments": {
                "captures": [
                    {
                        "id": "4257163761283522F",
                        "status": "COMPLETED",
                        "amount": {
                            "currency_code": "USD",
                            "value": "80.00"
                        },
                        "final_capture": true,
                        "seller_receivable_breakdown": {
                            "gross_amount": { "currency_code": "USD", "value": "80.00" },
                            "paypal_fee": { "currency_code": "USD", "value": "2.56" },
                            "net_amount": { "currency_code": "USD", "value": "77.44" }
                        },
                        "processor_response": {
                            "response_code": "0000"
                        }
                    }
                ]
            }
        }
    ]
}

A token for a closed card is used for payment. The issuer no longer provides the card, so the updater can't retrieve new information.

Endpoint: POST /v2/checkout/orders

{
    "intent": "CAPTURE",
    "payment_source": {
        "token": {
            "id": "dhq07phc",
            "type": "PAYMENT_METHOD_TOKEN"
        }
    },
    "purchase_units": [
        {
            "reference_id": "123_34897583499",
            "amount": {
                "currency_code": "USD",
                "value": "80.00"
            }
        }
    ]
}

{
    "name": "UNPROCESSABLE_ENTITY",
    "details": [
        {
            "field": "payment_source/card",
            "location": "body",
            "issue": "CARD_CLOSED",
            "description": "The card is closed."
        }
    ],
    "message": "The requested action could not be performed, semantically incorrect, or failed business validation.",
    "debug_id": "",
    "links": [
        {
            "href": "/docs/api/orders/v2/#error-CARD_CLOSED",
            "rel": "information_link",
            "method": "GET"
        }
    ]
}

An expired card is used for payment. The response returns the updated expiration date for the same card.

Endpoint: POST /v2/checkout/orders

{
    "intent": "CAPTURE",
    "payment_source": {
        "card": {
            "number": "4417164131206198",
            "expiry": "2022-01",
            "name": "Firstname Lastname",
            "stored_credential": {
                "payment_initiator": "CUSTOMER",
                "payment_type": "UNSCHEDULED",
                "usage": "SUBSEQUENT"
            }
        }
    },
    "purchase_units": [
        {
            "reference_id": "123_34897583499",
            "amount": {
                "currency_code": "USD",
                "value": "80.00"
            }
        }
    ]
}

{
    "id": "5YF61787W75673346",
    "status": "COMPLETED",
    "payment_source": {
        "card": {
            "last_digits": "6198",
            "expiry": "2040-12",
            "from_request": {
                "last_digits": "6198",
                "expiry": "2022-01"
            },
            "brand": "VISA",
            "type": "CREDIT"
        }
    },
    "purchase_units": [
        {
            "reference_id": "123_34897583499",
            "payments": {
                "captures": [
                    {
                        "id": "9UX37427Y3757812J",
                        "status": "COMPLETED",
                        "amount": {
                            "currency_code": "USD",
                            "value": "80.00"
                        },
                        "final_capture": true,
                        "disbursement_mode": "INSTANT",
                        "seller_protection": {
                            "status": "NOT_ELIGIBLE"
                        },
                        "seller_receivable_breakdown": {
                            "gross_amount": {
                                "currency_code": "USD",
                                "value": "80.00"
                            },
                            "paypal_fee": {
                                "currency_code": "USD",
                                "value": "2.56"
                            },
                            "net_amount": {
                                "currency_code": "USD",
                                "value": "77.44"
                            }
                        },
                        "custom_id": "1111",
                        "links": [
                            {
                                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/9UX37427Y3757812J",
                                "rel": "self",
                                "method": "GET"
                            },
                            {
                                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/9UX37427Y3757812J/refund",
                                "rel": "refund",
                                "method": "POST"
                            },
                            {
                                "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5YF61787W75673346",
                                "rel": "up",
                                "method": "GET"
                            }
                        ],
                        "create_time": "2023-03-12T17:33:41Z",
                        "update_time": "2023-03-12T17:33:41Z",
                        "processor_response": {
                            "avs_code": "A",
                            "cvv_code": "M",
                            "response_code": "0000"
                        }
                    }
                ]
            }
        }
    ],
    "links": [
        {
            "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5YF61787W75673346",
            "rel": "self",
            "method": "GET"
        }
    ]
}

A card on file has been reported lost, stolen, or reissued. The response returns details about the new card.

Endpoint: POST /v2/checkout/orders

{
    "intent": "CAPTURE",
    "payment_source": {
        "card": {
            "number": "4417164138767119",
            "expiry": "2024-09",
            "name": "Firstname Lastname",
            "stored_credential": {
                "payment_initiator": "MERCHANT",
                "payment_type": "RECURRING",
                "usage": "SUBSEQUENT",
                "previous_reference_id": "9UX37427Y3757812J"
            }
        }
    },
    "purchase_units": [
        {
            "reference_id": "123_34897583499",
            "amount": {
                "currency_code": "USD",
                "value": "80.00"
            }
        }
    ]
}

{
    "id": "1C421544FH848363U",
    "status": "COMPLETED",
    "payment_source": {
        "card": {
            "last_digits": "8934",
            "expiry": "2040-12",
            "from_request": {
                "last_digits": "7119",
                "expiry": "2024-09"
            },
            "brand": "VISA",
            "type": "CREDIT"
        }
    },
    "purchase_units": [
        {
            "reference_id": "123_34897583499",
            "payments": {
                "captures": [
                    {
                        "id": "43T026101K926890G",
                        "status": "COMPLETED",
                        "amount": {
                            "currency_code": "USD",
                            "value": "80.00"
                        },
                        "final_capture": true,
                        "seller_receivable_breakdown": {
                            "gross_amount": { "currency_code": "USD", "value": "80.00" },
                            "paypal_fee": { "currency_code": "USD", "value": "2.56" },
                            "net_amount": { "currency_code": "USD", "value": "77.44" }
                        },
                        "processor_response": {
                            "avs_code": "A",
                            "cvv_code": "M",
                            "response_code": "0000"
                        }
                    }
                ]
            }
        }
    ]
}

A closed card is used for payment. The issuer no longer provides the card, so the updater can't retrieve new information.

Endpoint: POST /v2/checkout/orders

{
    "intent": "CAPTURE",
    "payment_source": {
        "card": {
            "number": "5277356243447050",
            "expiry": "2024-09",
            "name": "Firstname Lastname",
            "stored_credential": {
                "payment_initiator": "MERCHANT",
                "payment_type": "RECURRING",
                "usage": "SUBSEQUENT",
                "previous_reference_id": "9UX37427Y3757812J"
            }
        }
    },
    "purchase_units": [
        {
            "reference_id": "123_34897583499",
            "amount": {
                "currency_code": "USD",
                "value": "80.00"
            }
        }
    ]
}

{
    "name": "UNPROCESSABLE_ENTITY",
    "details": [
        {
            "field": "payment_source/card",
            "location": "body",
            "issue": "CARD_CLOSED",
            "description": "The card is closed."
        }
    ],
    "message": "The requested action could not be performed, semantically incorrect, or failed business validation.",
    "debug_id": "4a39c5973dac8",
    "links": [
        {
            "href": "/docs/api/orders/v2/#error-CARD_CLOSED",
            "rel": "information_link",
            "method": "GET"
        }
    ]
}

Add real-time account updater

Eligibility

Supported countries

How it works

Mastercard

Visa

API responses for real-time account updater

Payments with a token

Closed card error

Test in sandbox

On this page

On this page

On this page

Add real-time account updater

Eligibility

Supported countries

How it works

Mastercard

Visa

API responses for real-time account updater

Payments with a token

Closed card error

Test in sandbox

On this page

On this page

Add real-time account updater

On this page

On this page

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

Add real-time account updater

On this page

On this page