Add More Cards
Last updated: Aug 15th, 7:05am
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
...TVERuYWEzTGx6dnJJR3d2Yi0
is the Base64 encodedclient id:secret
string
1POST /v1/oauth2/token HTTP/1.12Authorization: Basic3QWF0bmFXZ3d5d0p0VkdManlQdU1yLUpiOUxvdWIxbUJEaV9nUDBSRlR5eUN2MFVva3dxZllYWmp5YjRrNUpZTDJxbVg2emYxRkxiUFZMYmU6RUtoUHI1YlozbnJJVU1sU2lFN1dteHV1am9FS1g4RlcyaHBJS3NJak1HSkhoM3YtcVZESXY2ay14ZzFLMmxTVERuYWEzTGx6dnJJR3d2Yi0=4Host: api-m.sandbox.paypal.com5Accept: application/json6Accept-Language: en_US7Content-Type: application/x-www-form-urlencoded
Sample 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
1grant_type=refresh_token&refresh_token=R23AAGPIvifgk-ZFFDfuv10JwJwVcQ3mab2NefbOPawZ2rfguplZw3FS9qpTUWmJe88Ty5DuO7zDUIdgpvBAO91VzWF-u9wez1P3TlbrE-5ddd71NXKwaqMgE3CGTN8CrllwcVAEwB7pXu0NqLNyg&scope=2https%3A%2F%2Furi.paypal.com%2Fservices%2Fpayment-networks%2Flinked-instruments%2Freadwrite
Step 5: sample response
A23AAHMu8Hqsu95UP_b_s6
...4485P519543T
= access token used for the next Linked Instrument call
1{"scope":"https://uri.paypal.com/services/payment-networks/cardaccounts/readwrite","access_token":2"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
1POST /v1/payment-networks/linked-instruments HTTP/1.12Host: api-m.sandbox.paypal.com3Content-Type: application/json4Authorization: Bearer5A23AAHMu8Hqsu95UP_bs6-eq3hWlyxEC3ex1mU2dulvZKGXdiUZlw90glroda49YTUEJ6hoiPuCGvqDyHD5vfe55ktZVp6kQ",6"token_type":"Bearer","app_id":"APP-80W284485P519543T7PayPal-Request-Id: 123458Accept: application/json9Accept-Language: en_US10Content-Type: application/x-www-form-urlencoded
Sample request body
GPPSTXo6oYXfH1OxQSTVKw
= The JWE-encrypted PAN number.B2121XYZA
= Partner-providedfinancial_instrument_id
to be echoed back in the webhook payload
1{2 {3 "card_accounts":[4 {5 "identifier":"eyJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiUlNBLU9BRVAifQ.FNGgAyitajvujmUMOnXQsSrsEv8jUaBTx3gmaCbspSxqKtiu_8NPLIRoEp3sUhM_SoYfmK4GP--iOST215W7XopN_awjnjDYGuMYd31lT1o02xg1wJjibdHtQpcW3RrBFoEyvmrfN44ZSaXhgkhwaZ1cGR_KgbdvtWm2xEaCV_W6HC78gs5A_4REftp40CT9hC-9lq1TQZh5pQxSRnmPihDfBbkXIm5Arciiyu5f7c6GP_TwRFJmA3gsBFVugUvonT_2QCLAgIASFsFUjvfuxGWgI03diGsKAWxvTniwAW05PnSG5ApK0mykuV50GyJBm9GIcWj1kgZuZcLO3FknWQ.maRfYRn9ObALsUzMLC2spQ.k0BiPAMLNwRIPYRsDnhs7ZBKYWDZghKrqPsD5Ukdefg.GPPSTXo6oYXfH1OxQSTVKw",6 "reference_financial_instrument_id":"B2121XYZA",7 "expiry_date":"2020-12",8 "billing_address":{9 "address_line_1":"2211 N 1st Street",10 "admin_area_1":"CA",11 "admin_area_2":"San Jose",12 "country_code":"US",13 "postal_code":"95035"14 },15 "account_holder_name":{16 "given_name":"John",17 "surname":"Smith"18 }19 }20 ]21 }
Step 7: Sample response
30ffdc04e3ce
= id logged for use by PayPal support
1HTTP/1.1 202 Accepted2Date: Thu, 05 Mar 2020 21:01:41 GMT Server: Apache3paypal-debug-id: 30ffdc04e3ce4PayPal-Request-Id: 123455{"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_id
echoed 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.
1{2"id": "WH-9LG8099179700735B-801161897N370874M",3"event_version": "1.0",4"create_time": "2020-03-05T22:29:38.000Z",5"resource_type": "INSTRUMENT",6"event_type": "PAYMENT_NETWORKS.INSTRUMENT.LINKED-ACCOUNT-UPDATED",7"summary": "An instrument was successfully added.",8"resource": {9 "partner_financial_instrument_id":"B2121XYZA"10 "financial_instrument_id":"CC-HFPEET8KTJF8Z"11 "event": {12 "event_type": "INSTRUMENT_ADDED", "event_reason": "USER_INITIATED"13 }14 ,15 "customer": {16 "paypal_customer_id": "6PN79VDMX6566"17 }18}19,20"links": [ {21 "href": "https:\/\/api-m.sandbox.paypal.com\/v1\/notifications\/webhooks-events\/WH- 9LG8099179700735B-801161897N370874M", "rel": "self", "method": "GET"22}23,24{25 "href": "https:\/\/api-m.sandbox.paypal.com\/v1\/notifications\/webhooks-events\/WH-269LG8099179700735B-801161897N370874M\/resend", "rel": "resend",27"method": "POST"]28}