Personal Payments v2 Integration Guide

DOCS

Last updated: Aug 15th, 6:14am

The Personal Payments v2 API provides an easy and secure way to send money. Money can be sent to PayPal members and non-members. Non-members must create a PayPal account to receive payment.

This PayPal experience is for peer-to-peer payments, such as payments between friends and family, or small purchases of goods or services.

Use the API to make these types of transactions:

Transaction type	Examples
Personal	Send money to a family member, split the cost of a dinner, etc.
Purchase	Buy cookies, pay for a hairdresser appointment, etc.

Know before you code

Before you code, make sure you:

Know when not to use this API
Get approval to use the API
Choose an integration pattern

When not to use this API

Do not use this API to transfer money if the sender and receiver are the same entity. No deposits or withdrawals to the same user.

Get approval to use this API

You must be approved to use the Personal Payments v2 API. Send an email to the following address to request approval:

[email protected]

Choose an integration pattern

You can integrate the Personal Payments v2 API in one of two ways:

Use PayPal UI for transactions

Send your users to PayPal to complete a transaction.

This integration pattern uses PayPal's UI to send money between PayPal members. The benefits of this implementation are:

You don't have to make user experience changes when new contingencies roll out due to regulations - PayPal handles this
You can leverage PayPal's tested and refined UI

Use partner UI for transactions

In this integration pattern, you control the user experience and UI for a payment, and use PayPal on the backend.

This pattern is for large enterprises with an in-house compliance team.
This pattern calls APIs with extra authentication, and asks for explicit consent in user interaction.

Set up your development environment

Before you can integrate Personal Payments v2, you must set up your development environment. After you get a token that lets you access protected REST API resources, you create sandbox accounts to test your web and mobile apps. For details, see Get started.

Then, return to this page to integrate Personal Payments v2.

Integrate with PayPal UI

Note: PayPal strongly recommends this option for all partners except large enterprises.

Send your users to PayPal to complete a transaction. PayPal recommends this integration pattern.


1.	Required	Create a personal payment token
2.	Required	Perform a browser redirect
3.	Optional	Get transaction details for a payment

Step 1: Create a personal payment token

To integrate with PayPal's UI, you'll need to create a personal payment token.

Sample request

This sample request creates a personal payment token. In the request body, note_to_receiver is an optional field.

1curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v2/personal-payments/tokens' \
2-H 'Accept: application/json' \
3-H 'Content-Type: application/json' \
4-H 'Authorization: Bearer <Access-Token>' \
5-d '{
6    "receiver": {
7        "id": "[email protected]",
8        "type": "EMAIL"
9    },
10    "amount": {
11        "currency_code": "USD",
12        "value": "10.50"
13    },
14    "payment_type": "PERSONAL",
15    "intent": "CAPTURE",
16    "note_to_receiver": "Thank you!",
17    "external_reference_id": "reference_id_generated_by_third_party"
18}'

Sample response

This is a sample response of the personal payment token API. The response provides the ID of the personal payment token and the redirect URL for the payer to complete the payment.

1{
2    "id": "PP-P7HR12783L46611419",
3    "status": "CREATED",
4    "sender": {
5        "account_id": "<Sender_Account_ID>",
6        "name": {
7            "person_name": {
8                "full_name": "<Full_Name>"
9            }
10        },
11        "country_code": "US",
12        "account_type": "PERSONAL",
13        "registration_type": "FULL"
14    },
15    "receiver": {
16        "id": "[email protected]",
17        "type": "EMAIL",
18        "account_id": "<Receiver_Account_ID>",
19        "name": {
20            "person_name": {
21                "full_name": "<Full_Name>"
22            }
23        },
24        "country_code": "US",
25        "account_type": "PERSONAL",
26        "registration_type": "FULL"
27    },
28    "amount": {
29        "currency_code": "USD",
30        "value": "10.50"
31    },
32    "payment_type": "PERSONAL",
33    "intent": "CAPTURE",
34    "external_reference_id": "reference_id_generated_by_third_party",
35    "note_to_receiver": "Thank you!",
36    "facilitator": {
37        "account_id": "<Third_Party_Account_ID>",
38        "integration_id": "<Third_Party_ID>"
39    },
40    "links": [
41        {
42            "href": "https://api-m.sandbox.paypal.com/v2/personal-payments/tokens/PP-P7HR12783L46611419",
43            "rel": "self",
44            "method": "GET",
45            "encType": "application/json"
46        },
47        {
48            "href": "https://api-m.sandbox.paypal.com/myaccount/transfer/send/external/pisp?token_id=PP-P7HR12783L46611419",
49            "rel": "initiate_payment",
50            "method": "GET",
51            "encType": "application/json"
52        }
53    ]
54}

Step 2: Perform a browser redirect

Append &return_url= then <your_return_URL> to the last URL in the above sample to perform a browser redirect. <your_return_URL> is where you want the user to land after interacting with the PayPal UI.

You can include one pair of parameters in your return URL.

Sample response

The following code is a sample response returned from a browser redirect.

1https://api-m.sandbox.paypal.com/myaccount/transfer/send/external/pisp?token_id=PP-P7HR12783L46611419&return_url=https://www.partner.com/url?param1=value1

On success, the user is redirected to the return_url and you receive the following query parameters:

1status=success
2    transactionId=ABCD12435
3    returnCode='SUCCESS'

Once you've integrated Personal Payments v2 with the PayPal UI, you can get transaction details for a payment.

Integrate with partner UI

Important: Partners must ensure their UI stays compliant with government regulations. If the UI goes out of compliance, the partner may be fined or shut down.

Process a transaction with the UI of your choice, while PayPal handles the transaction on the backend.

You can choose to pass a pre-configured funding option to the customer, or have the customer choose their funding option.

By default, this integration passes a pre-configured funding option to the customer.


1.	Optional	Evaluate funding options
2.	Required	Create and execute payment
3.	Optional	Get transaction details for a payment

Step 1: Evaluate funding options (optional)

If you want the customer to choose their funding option on the partner UI, you'll first need to list the available funding options for a payment.

In the JSON request body, include the amount of the payment, recipient information, an optional shipping address for the payer for purchases, and the payment type, which is personal or purchase.

Sample request

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/personal-payments/evaluate-funding-options \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer <Access-Token>" \
4-d '{
5  "sender": {
6    "account_id": "N9ZXXK2PVTFWN"
7  },
8  "receiver": {
9    "id": "[email protected]",
10    "type": "EMAIL"
11  },
12  "amount": {
13    "currency_code": "USD",
14    "value": "100"
15  },
16  "payment_type": "PERSONAL",
17  "intent": "CAPTURE"
18}'

Sample response

The response lists the available funding options for the specified amount for a personal payment:

1{
2  "sender": {
3    "account_id": "N9ZXXK2PVTFWN"
4  },
5  "receiver": {
6    "id": "[email protected]",
7    "type": "EMAIL"
8  },
9  "payment_type": "PERSONAL",
10  "intent": "CAPTURE",
11  "funding_options": [
12    {
13      "id": "8a7a00078a594ccd8c504aba3bdde676",
14      "funding_sources": [
15        {
16          "instrument_type": "BANK",
17          "bank": {
18            "id": "BA-EVRPX24FW6HRU",
19            "account_type": "CHECKING",
20            "last_n_chars": "1234",
21            "bank_name": "Bank of America"
22          },
23          "amount": {
24            "currency_code": "USD",
25            "value": "100"
26          }
27        }
28      ],
29      "amounts_breakdown": {
30        "sender": {
31          "amount_sent": {
32            "currency_code": "USD",
33            "value": "100"
34          },
35          "total_amount_sent": {
36            "currency_code": "USD",
37            "value": "100"
38          }
39        },
40        "receiver": {
41          "amount_sent": {
42            "currency_code": "USD",
43            "value": "100"
44          },
45          "amount_received": {
46            "currency_code": "USD",
47            "value": "100"
48          }
49        },
50        "funding_mode": "INSTANT"
51      }
52    }
53  ],
54  "backup_funding_sources": [
55    {
56      "instrument_type": "CARD",
57      "card": {
58        "id": "CC-GQJ8BNQ8S7TRU",
59        "last_n_chars": "1234",
60        "type": "CREDIT_CARD",
61        "brand": "VISA"
62      }
63    }
64  ],
65  "contingencies": [
66    {
67      "action": "OBTAIN_REAL_TIME_BALANCE_CONSENT",
68      "real_time_balance_consent": {
69        "links": [
70          {
71            "href": "https://www.paypal.com/myaccount/money/flow/banks/BA-EVRPX24FW6HRU/confirmation?action=complete-instant-confirmation&flow=eyJzdWNjZXNzVXJsIjoic3VjY2VzcyIsImZhaWx1cmVVcmwiOiJmYWlsIn0=",
72            "rel": "consent",
73            "method": "POST"
74          }
75        ]
76      }
77    }
78  ]
79}

Step 2: Create and execute payment

To create and execute a payment, pass the ID of a funding option returned in the evaluate-funding-options request.

Sample request

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/personal-payments/payments \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer <Access-Token>" \
4-H "PayPal-Request-Id: 20c81d45477f499f8a9503e074729607" \
5-d '{
6  "sender": {
7    "account_id": "N9ZXXK2PVTFWN"
8  },
9  "receiver": {
10    "id": "[email protected]",
11    "type": "EMAIL"
12  },
13  "amount": {
14    "currency_code": "USD",
15    "value": "100"
16  },
17  "payment_type": "PERSONAL",
18  "intent": "CAPTURE"
19}'

Sample response

The response returns details about the completed personal payment:

1{
2  "id": "3J343066RE851350G",
3  "create_time": "2020-01-26T15:30:00Z",
4  "status": "COMPLETED",
5  "amounts_breakdown": {
6    "sender": {
7      "amount_sent": {
8        "currency_code": "USD",
9        "value": "100"
10      },
11      "total_amount_sent": {
12        "currency_code": "USD",
13        "value": "100"
14      }
15    },
16    "receiver": {
17      "amount_sent": {
18        "currency_code": "USD",
19        "value": "100"
20      },
21      "amount_received": {
22        "currency_code": "USD",
23        "value": "100"
24      }
25    }
26  },
27  "sender": {
28    "account_id": "N9ZXXK2PVTFWN"
29  },
30  "receiver": {
31    "id": "[email protected]",
32    "type": "EMAIL"
33  },
34  "amount": {
35    "currency_code": "USD",
36    "value": "100"
37  },
38  "payment_type": "PERSONAL",
39  "intent": "CAPTURE"
40}

If the transaction succeeds, PayPal notifies the recipient by email or, for mobile transactions, a text message.

Step 3: Get transaction details for a payment

To get transaction details for a specific payment, specify the payment token ID in the JSON request body.

Sample request

This sample request gets payment details for a given payment token ID.

1curl -v -k -X GET 'https://api-m.sandbox.paypal.com/v2/personal-payments/tokens/PP-P7HR12783L46611419' \
2-H 'Accept: application/json' \
3-H 'Content-Type: application/json' \
4-H 'Authorization: Bearer <Access-Token>' \

Sample response

1{
2  "id": "3J343066RE851350G",
3  "create_time": "2020-01-26T15:30:00Z",
4  "status": "COMPLETED",
5  "amounts_breakdown": {
6    "sender": {
7      "amount_sent": {
8        "currency_code": "USD",
9        "value": "100"
10      },
11      "total_amount_sent": {
12        "currency_code": "USD",
13        "value": "100"
14      }
15    },
16    "receiver": {
17      "amount_sent": {
18        "currency_code": "USD",
19        "value": "100"
20      },
21      "amount_received": {
22        "currency_code": "USD",
23        "value": "100"
24      }
25    }
26  },
27  "sender": {
28    "account_id": "N9ZXXK2PVTFWN"
29  },
30  "receiver": {
31    "id": "[email protected]",
32    "type": "EMAIL"
33  },
34  "amount": {
35    "currency_code": "USD",
36    "value": "100"
37  },
38  "payment_type": "PERSONAL",
39  "intent": "CAPTURE"
40}

Personal Payments v2 Integration Guide

Know before you code

When not to use this API

Get approval to use this API

Choose an integration pattern

Use PayPal UI for transactions

Use partner UI for transactions

Set up your development environment

Integrate with PayPal UI

Step 1: Create a personal payment token

Sample request

Sample response

Step 2: Perform a browser redirect

Sample response

Next

Integrate with partner UI

Step 1: Evaluate funding options (optional)

Sample request

Sample response

Step 2: Create and execute payment

Sample request

Sample response

Step 3: Get transaction details for a payment

Sample request

Sample response

Additional information

Personal Payments v2 Integration Guide

Know before you code

When not to use this API

Get approval to use this API

Choose an integration pattern

Use PayPal UI for transactions

Use partner UI for transactions

Set up your development environment

Integrate with PayPal UI

Step 1: Create a personal payment token

Sample request

Sample response

Step 2: Perform a browser redirect

Sample response

Next

Integrate with partner UI

Step 1: Evaluate funding options (optional)

Sample request

Sample response

Step 2: Create and execute payment

Sample request

Sample response

Step 3: Get transaction details for a payment

Sample request

Sample response

Additional information

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