User Starts from PayPal Integration

DOCS

Last updated: Sept 23rd, 8:20pm

This flow enables users to start on the PayPal website or app and then link partner cards, bank accounts, and rewards accounts to their PayPal wallet.

The initial integration includes adding one card or payment instrument to the account. To add additional cards, see Add more cards.

PayPal-initiated flow sequence diagram

The following diagram illustrates the end-to-end PayPal-initiated flow sequence.

PayPal-Initiated,Pull

Redirect user back to partner

Here's how the partner gets an exchange token:

  1. After login to PayPal, the user identifies a card associated with a partner to add.
  2. User is asked to consent to the partner sharing the card data with PayPal.
  3. After the user consents, the user is redirected to the partner site using an authorization code.
  4. The partner exchanges this authorization code for an access and refresh token.

Endpoints

  • Live: https://api-m.paypal.com/v1/oauth2/token
  • Sandbox: https://api-m.sandbox.paypal.com/v1/oauth2/token

Sample request

    1curl -v https://api-m.paypal.com/v1/oauth2/token \
    2 -u "<CLIENT-ID>:<SECRET>" \
    3 -d "grant_type=authorization_code&code=<Authorization-Code>&code_verifier=<Code verifier value>&redirect_uri=http://www.partner-website.com/myapp/return.php"

    Sample response

      1{
      2 "token_type": "Bearer",
      3 "expires_in": "28000",
      4 "refresh_token": "<Refresh-Token>",
      5 "access_token": "<Access-Token>",
      6 "id_token": "<Identity-Token>"
      7}

      Once the user logs in and consents, the partner presents the list of eligible cards, ACH accounts, and other data to the user. The Linked Instruments resource of the Payment Network Transactions API enables partners to add cards, card art, ACH accounts, or rewards in a linked PayPal wallet.

      Endpoints

      • Live: https://api-m.paypal.com/v1/payment-networks/linked-instruments
      • Sandbox: https://api-m.sandbox.paypal.com/v1/payment-networks/linked-instruments

      Refer to the API Reference for a list of all available fields.

      Sample json request

      Link a card account and optionally designate card art for the card account.

        1curl -v -X POST https://api-m.sandbox.paypal.com/v1/payment-networks/linked-instruments \
        2 -H "PayPal-Request-Id: 12345" \
        3 -H "Content-Type: application/json" \
        4 -H "Authorization: Bearer A21AAFcup1Yr9E-3GEqiGZHNZIVoBnlAekv_3MQhF6Hb4bM-TPtdp2RxrouHu274F_F97GACA3BBFJrXRNO6CLVv7g-oMz4qg" \
        5 -d '{
        6 "card_accounts": [
        7 {
        8 "identifier": "4185560131914493",
        9 "reference_financial_instrument_id": "B2121XYZ",
        10 "expiry_date": "2020-12",
        11 "billing_address": {
        12 "address_line_1": "2211 N 1st Street",
        13 "admin_area_1": "CA",
        14 "admin_area_2": "San Jose",
        15 "country_code": "US",
        16 "postal_code": "95035"
        17 },
        18 "account_holder_name": {
        19 "given_name": "John",
        20 "surname": "Smith"
        21 },
        22 "card_art": {
        23 "reference_id": "GAT13576232",
        24 "product": {
        25 "id": "AEG123ba08y08y3"
        26 },
        27 "primary_content": {
        28 "id": "AG12G1I1H112"
        29 },
        30 "thumbnail_content": {
        31 "id": "G1AHSKSA1DSA"
        32 },
        33 "metadata": {
        34 "id": "AEG123ba08y08y3"
        35 }
        36 }
        37 }
        38 ]
        39}'

        Sample multipart request

        Use a multipart request to link a card, reward account, and add card art to the cardholder's account.

          1curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v1/payment-networks/linked-instruments' \
          2 -H 'Authorization: Bearer A21AAHnicuqnZrlX4qzrm2stVYC2eYnJFhnO_ZfEAs3-kTYUU9gRHSo_WLRipfArOuoUz0DETX-J-A0hgb5eO0k75vjuCKsiw' \
          3 -H 'PayPal-Request-Id: 1234567890123456' \
          4 -H 'Accept: application/json' \
          5 -H 'Content-Type: multipart/form-data' -F 'request={"card_accounts":[{"identifier":"4185560131914493","reference_financial_instrument_id":"B2121XYZ","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"},"card_art":{"reference_id":"GAT13576232","product":{"id":"AEG123ba08y08y3","customer_support":{"email":"help@example.com","phone_number":{"country_code":"1","national_number":"4089671000"}},"product_description":"Discover Rewards"},"primary_content":{"id":"UNIQUE_ID_SAMPLE_1A","format":"image/png","width":500,"height":500},"thumbnail_content":{"id":"UNIQUE_ID_SAMPLE_1B","format":"image/png","width":50,"height":50},"metadata":{"id":"AEG123ba08y08y3","background_color":"0xe6e6e6","foreground_color":"0xddeeff","label_color":"0x214121"}}}]};type=application/json' \
          6 -F 'UNIQUE_ID_SAMPLE_1A=@./discover.png' \
          7 -F 'UNIQUE_ID_SAMPLE_1B=@./discover_thumb.png'

          Redirect user back to PayPal

          After linking accounts, redirect users back to PayPal using one of the following URLs:

          • Live: https://www.paypal.com/myaccount/money/accounts/link
          • Sandbox: https://www.sandbox.paypal.com/myaccount/money/accounts/link

          In case of failure, append an error code to the URL:

          • Live: https://www.paypal.com/myaccount/money/cards/new?error=<error_code>
          • Sandbox: https://www.sandbox.paypal.com/myaccount/money/cards/new?error=<error_code>

          Use one of the following error codes:

          • USER_CANCELLED - User cancelled on your end.
          • INTERNAL_SERVER_ERROR - Partner might be experiencing site issues. Retry the request.
          • UNPROCESSABLE_ENTITY - The request failed due to some business rules and can't be retried.

          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