User Starts from PayPal Integration

DOCS

Last updated: Sept 23rd, 8:20pm

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.

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:

After login to PayPal, the user identifies a card associated with a partner to add.

User is asked to consent to the partner sharing the card data with PayPal.

After the user consents, the user is redirected to the partner site using an authorization code.

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}

Link data into PayPal

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.

Note: While the following sample code uses a single API call to link multiple accounts to PayPal, you can also use these APIs to link accounts or update card art separately.

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.

See User starts from partner site if you want users to start P3 from the partner site in addition to PayPal.

See Integration Features for optional features you can add to your integrations to enhance the user experience.

User Starts from PayPal Integration

PayPal-initiated flow sequence diagram

Redirect user back to partner

Endpoints

Sample request

Sample response

Link data into PayPal

Endpoints

Sample json request

Sample multipart request

Redirect user back to PayPal

Next