Add More Cards

DOCS

Last updated: Aug 15th, 7:05am

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}

                Next

                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