On this page
No Headings
Add More Cards
Last updated: May 21, 2026
DOCS
Important: PayPal Provisioning Platform is a limited-release solution available only to select partners at this time. For more information, reach out to your PayPal Account Manager.
Once a user has linked their accounts to the PayPal app with all the required consents, the partner can add additional cards without logging into the PayPal experience using a server-to-server Linked Instruments API call.
Add more cards flow sequence diagram
The following diagram outlines the end-to-end API sequence to add more cards.
The following samples show the call request and response used to get the access token and replace it with the stored access token. The bulleted items highlight significant details about the identified step in the diagram.
Step 5: oAuth call to get access token using stored refresh token
QWF0bmFXZ3d5d0p0VkdManlQdU1yLUpiOUxvdWIxbUJ...TVERuYWEzTGx6dnJJR3d2Yi0is the Base64 encodedclient id:secretstring
POST /v1/oauth2/token HTTP/1.1
Authorization: Basic
QWF0bmFXZ3d5d0p0VkdManlQdU1yLUpiOUxvdWIxbUJEaV9nUDBSRlR5eUN2MFVva3dxZllYWmp5YjRrNUpZTDJxbVg2emYxRkxiUFZMYmU6RUtoUHI1YlozbnJJVU1sU2lFN1dteHV1am9FS1g4RlcyaHBJS3NJak1HSkhoM3YtcVZESXY2ay14ZzFLMmxTVERuYWEzTGx6dnJJR3d2Yi0=
Host: api-m.sandbox.paypal.com
Accept: application/json
Accept-Language: en_US
Content-Type: application/x-www-form-urlencodedSample request body
R23AAGPIvifgk...VAEwB7pXu0NqLNyg= the stored refresh token from the onboarding flowhttps%3A%2F%2Furi.paypal.com%2Fservices%2Fpayment-networks%2Fcard-accounts%2Freadwrite= the requested scope in the access token
grant_type=refresh_token&refresh_token=R23AAGPIvifgk-ZFFDfuv10JwJwVcQ3mab2NefbOPawZ2rfguplZw3FS9qpTUWmJe88Ty5DuO7zDUIdgpvBAO91VzWF-u9wez1P3TlbrE-5ddd71NXKwaqMgE3CGTN8CrllwcVAEwB7pXu0NqLNyg&scope=
https%3A%2F%2Furi.paypal.com%2Fservices%2Fpayment-networks%2Flinked-instruments%2FreadwriteStep 5: sample response
A23AAHMu8Hqsu95UP_b_s6...4485P519543T= access token used for the next Linked Instrument call
{"scope":"https://uri.paypal.com/services/payment-networks/cardaccounts/readwrite","access_token":
"A23AAHMu8Hqsu95UP_b_s6eq3hWlyxEC3ex1mU2dulvZKGXdiUZlw90glroda49YTUEJ6hoiPuCGvqDyHD5vfe55ktZVp6kQ","token_type":"Bearer","app_id":"APP-80W284485P519543T","expires_in":28800,"nonce":"2020-03--05T22:29:13Z2AiNW78gccQddfGJm9130SuDQT2x1mBPyNFG4LY8Po","visitor_id":"wR90MTP7K1YM9y9DMzkoSBN_pxIvZSwXSHJxYeFZvrQ1KA-SXtplxrYsxftO0RgNKJYdB7pf65ROxBzq"Step 6: Linked Instrument call with card data and reference_financial_instrument_id
A23AAHMu8Hqsu95UP_b_s6...4485P519543T= Access token from Step 5PayPal-Request-Id: 12345= Unique ID for idempotency
POST /v1/payment-networks/linked-instruments HTTP/1.1
Host: api-m.sandbox.paypal.com
Content-Type: application/json
Authorization: Bearer
A23AAHMu8Hqsu95UP_bs6-eq3hWlyxEC3ex1mU2dulvZKGXdiUZlw90glroda49YTUEJ6hoiPuCGvqDyHD5vfe55ktZVp6kQ",
"token_type":"Bearer","app_id":"APP-80W284485P519543T
PayPal-Request-Id: 12345
Accept: application/json
Accept-Language: en_US
Content-Type: application/x-www-form-urlencodedSample request body
GPPSTXo6oYXfH1OxQSTVKw= The JWE-encrypted PAN number.B2121XYZA= Partner-providedfinancial_instrument_idto be echoed back in the webhook payload
{
{
"card_accounts":[
{
"identifier":"eyJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiUlNBLU9BRVAifQ.FNGgAyitajvujmUMOnXQsSrsEv8jUaBTx3gmaCbspSxqKtiu_8NPLIRoEp3sUhM_SoYfmK4GP--iOST215W7XopN_awjnjDYGuMYd31lT1o02xg1wJjibdHtQpcW3RrBFoEyvmrfN44ZSaXhgkhwaZ1cGR_KgbdvtWm2xEaCV_W6HC78gs5A_4REftp40CT9hC-9lq1TQZh5pQxSRnmPihDfBbkXIm5Arciiyu5f7c6GP_TwRFJmA3gsBFVugUvonT_2QCLAgIASFsFUjvfuxGWgI03diGsKAWxvTniwAW05PnSG5ApK0mykuV50GyJBm9GIcWj1kgZuZcLO3FknWQ.maRfYRn9ObALsUzMLC2spQ.k0BiPAMLNwRIPYRsDnhs7ZBKYWDZghKrqPsD5Ukdefg.GPPSTXo6oYXfH1OxQSTVKw",
"reference_financial_instrument_id":"B2121XYZA",
"expiry_date":"2020-12",
"billing_address":{
"address_line_1":"2211 N 1st Street",
"admin_area_1":"CA",
"admin_area_2":"San Jose",
"country_code":"US",
"postal_code":"95035"
},
"account_holder_name":{
"given_name":"John",
"surname":"Smith"
}
}
]
}Step 7: Sample response
30ffdc04e3ce= id logged for use by PayPal support
HTTP/1.1 202 Accepted
Date: Thu, 05 Mar 2020 21:01:41 GMT Server: Apache
paypal-debug-id: 30ffdc04e3ce
PayPal-Request-Id: 12345
{"links":[{"href":"https://www.sandbox.paypal.com/myaccount/money/cards/pull/p3","rel":"redire ct","method":"GET","encType":"application/json"}]}Step 9: Webhook payload sent to partner
reference_financial_instrument_idechoed back by the Partner in the Linked Instruments call- The
partner_financial_instrument-id=reference_financial_instrument_id CC-HFPEET8KTJF8Z= PayPal card identifier needed to make lifecycle API calls6PN79VDMX6566= PayPal encrypted account number needed for PayPal support. This is the same encrypted account number returned in the onboarding flow.
{
"id": "WH-9LG8099179700735B-801161897N370874M",
"event_version": "1.0",
"create_time": "2020-03-05T22:29:38.000Z",
"resource_type": "INSTRUMENT",
"event_type": "PAYMENT_NETWORKS.INSTRUMENT.LINKED-ACCOUNT-UPDATED",
"summary": "An instrument was successfully added.",
"resource": {
"partner_financial_instrument_id":"B2121XYZA"
"financial_instrument_id":"CC-HFPEET8KTJF8Z"
"event": {
"event_type": "INSTRUMENT_ADDED", "event_reason": "USER_INITIATED"
}
,
"customer": {
"paypal_customer_id": "6PN79VDMX6566"
}
}
,
"links": [ {
"href": "https:\/\/api-m.sandbox.paypal.com\/v1\/notifications\/webhooks-events\/WH- 9LG8099179700735B-801161897N370874M", "rel": "self", "method": "GET"
}
,
{
"href": "https:\/\/api-m.sandbox.paypal.com\/v1\/notifications\/webhooks-events\/WH-
9LG8099179700735B-801161897N370874M\/resend", "rel": "resend",
"method": "POST"]
}