Add More Cards

DOCS

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.

add,more,cards,flow

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 encoded client id:secret string

1POST /v1/oauth2/token HTTP/1.1
2Authorization: Basic
3QWF0bmFXZ3d5d0p0VkdManlQdU1yLUpiOUxvdWIxbUJEaV9nUDBSRlR5eUN2MFVva3dxZllYWmp5YjRrNUpZTDJxbVg2emYxRkxiUFZMYmU6RUtoUHI1YlozbnJJVU1sU2lFN1dteHV1am9FS1g4RlcyaHBJS3NJak1HSkhoM3YtcVZESXY2ay14ZzFLMmxTVERuYWEzTGx6dnJJR3d2Yi0=
4Host: api-m.sandbox.paypal.com
5Accept: application/json
6Accept-Language: en_US
7Content-Type: application/x-www-form-urlencoded

Sample request body

R23AAGPIvifgk...VAEwB7pXu0NqLNyg = the stored refresh token from the onboarding flow
https%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 5
PayPal-Request-Id: 12345 = Unique ID for idempotency

1POST /v1/payment-networks/linked-instruments HTTP/1.1
2Host: api-m.sandbox.paypal.com
3Content-Type: application/json
4Authorization: Bearer
5A23AAHMu8Hqsu95UP_bs6-eq3hWlyxEC3ex1mU2dulvZKGXdiUZlw90glroda49YTUEJ6hoiPuCGvqDyHD5vfe55ktZVp6kQ",
6"token_type":"Bearer","app_id":"APP-80W284485P519543T
7PayPal-Request-Id: 12345
8Accept: application/json
9Accept-Language: en_US
10Content-Type: application/x-www-form-urlencoded

Sample request body

GPPSTXo6oYXfH1OxQSTVKw = The JWE-encrypted PAN number.
B2121XYZA = Partner-provided financial_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 Accepted
2Date: Thu, 05 Mar 2020 21:01:41 GMT Server: Apache
3paypal-debug-id: 30ffdc04e3ce
4PayPal-Request-Id: 12345
5{"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 calls
6PN79VDMX6566 = 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}

Encryption

Add More Cards

Add more cards flow sequence diagram

Step 5: oAuth call to get access token using stored refresh token

Sample request body

Step 5: sample response

Step 6: Linked Instrument call with card data and reference_financial_instrument_id

Sample request body

Step 7: Sample response

Step 9: Webhook payload sent to partner

Next