User Starts from PayPal Integration
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.
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.
Next
- 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.