Personal Payments Integration Guide

The Personal Payments API is a PayPal limited release REST API that you can use in conjunction with other publicly available external APIs.

Overview

The API provides an easy and secure way to send money to another PayPal member. This PayPal web experience is intended for peer-to-peer payments, typically transfers between friends and family, and small purchases of a good or service. It is not related to merchant payments.

Use the API to make these types of transactions:

In most countries, sending money between friends and family is free of charge for all but credit and debit card transactions. Payments for goods or services include a fee that one of the involved parties pays.

To complete a payment, you must first generate a list of funding options. Then, when you create and execute the payment, include the ID of a funding option along with either a phone number or account number for the payee.

Integration steps

To use the Personal Payments API to make a personal payments request:

Set up your development environment

Before you can integrate Personal Payments, 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.

List payer eligibility

You can list the payment types that the payer can make and the currencies that he or she can use to complete the payment. The payment type is PERSONAL for friends and family and PURCHASE for goods or services.

This sample request lists the currencies that the payer can use to make personal payments or purchases:

1curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/personal-payments/eligibility \
2  -H "Content-Type: application/json" \
3  -H "Authorization: Bearer <Access-Token>"

The response shows that the payer can make purchases or personal payments in a number of currencies:

1{
2  "payment_types": [
3    "PURCHASE",
4    "PERSONAL"
5  ],
6  "currencies": [
7    "USD",
8    "ARS",
9    "AUD",
10    "BRL",
11    "CAD",
12    "CHF",
13    "CZK",
14    "DKK",
15    "EUR",
16    "GBP",
17    "HKD",
18    "HUF",
19    "ILS",
20    "JPY",
21    "MXN",
22    "NOK",
23    "NZD",
24    "PHP",
25    "PLN",
26    "SEK",
27    "SGD",
28    "THB",
29    "TWD"
30  ]
31}

Next, evaluate and list the eligible payment types and currencies for a payer and payee, based on their respective country codes.

Evaluate payer and payee eligibility

You can evaluate and list the eligible payment types and currencies for a payer and payee, based on their respective country codes. The list shows in which currencies the payer can make payments and in which currencies the payee can receive payments.

In the JSON request body, specify the payer's and payee's country codes.

This sample request evaluates the eligibility of a payer in the United States and a payee in Great Britain:

1curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/personal-payments/evaluate-eligibility \
2  -H "Content-Type: application/json" \
3  -H "Authorization: Bearer <Access-Token>" \
4  -d '{
5  "payer": {
6    "country_code": "US"
7  },
8  "payee": {
9    "country_code": "GB"
10  }
11}'

The response shows that the payer can make purchases and personal payments in a variety of currencies, and the payee can receive such payments in multiple currencies:

1{
2  "payer": {
3    "payment_types": [
4      "PURCHASE",
5      "PERSONAL"
6    ],
7    "currencies": [
8      "USD",
9      "ARS",
10      "AUD",
11      "BRL",
12      "CAD",
13      "CHF",
14      "CZK",
15      "DKK",
16      "EUR",
17      "GBP",
18      "HKD",
19      "HUF",
20      "ILS",
21      "JPY",
22      "MXN",
23      "NOK",
24      "NZD",
25      "PHP",
26      "PLN",
27      "SEK",
28      "SGD",
29      "THB",
30      "TWD"
31    ]
32  },
33  "payee": {
34    "payment_types": [
35      "PURCHASE",
36      "PERSONAL"
37    ],
38    "currencies": [
39      "GBP",
40      "ARS",
41      "AUD",
42      "BRL",
43      "CAD",
44      "CHF",
45      "CZK",
46      "DKK",
47      "EUR",
48      "HKD",
49      "HUF",
50      "ILS",
51      "JPY",
52      "MXN",
53      "NOK",
54      "NZD",
55      "PHP",
56      "PLN",
57      "SEK",
58      "SGD",
59      "THB",
60      "TWD",
61      "USD"
62    ]
63  }
64}

Next, list the available funding options for a personal payment.

List funding options

You can list the available funding options for a personal payment.

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

This sample request lists funding options with the payer as the fee payer:

1curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/personal-payments/funding-options \
2  -H "Content-Type: application/json" \
3  -H "Authorization: Bearer <Access-Token>" \
4  -d '{
5  "amount": {
6    "value": "10",
7    "currency": "USD"
8  },
9  "payee": {
10    "id": "[email protected]",
11    "type": "EMAIL"
12  },
13  "fee": {
14    "payer": "PAYER"
15  },
16  "payment_type": "PERSONAL"
17}'

The response lists the available funding options for the specified amount for a personal payment where the payer pays the fee:

1{
2  "funding_options": {
3    "payee": {
4      "type": "EMAIL",
5      "id": "[email protected]",
6      "name": "Chinta Raja Dayanands US",
7      "country_code": "US",
8      "is_registered": true
9    },
10    "options": [
11      {
12        "id": "R5hTlsACO7EuP1TbngsRhBUGQElnh5sg0FpoUssk5QMqAPLl2gRLPw6EUjd8XGAytOBBvW",
13        "fee": {
14          "payer": "PAYER",
15          "amount": {
16            "value": "0.00",
17            "currency": "USD"
18          }
19        },
20        "sources": [
21          {
22            "instrument_type": "HOLDING",
23            "holding": {
24              "id": "123456",
25              "amount": {
26                "value": "10.00",
27                "currency": "USD"
28              }
29            }
30          }
31        ],
32        "funding_mode": "INSTANT",
33        "estimated_funds_arrival": "2014-07-04T03:14:15Z"
34      }
35    ],
36    "payment_type": "PERSONAL"
37  },
38  "links": [
39    {
40      "href": "https://api-m.paypal.com/v1/payments/personal-payments",
41      "rel": "create-payment",
42      "method": "POST"
43    }
44  ]
45}

Next, create and execute the payment.

Create and execute payment

To create and execute the payment, you pass the ID of a funding option from the list of funding options in the request.

This sample request specifies a funding option ID and a note to the payee:

1curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/personal-payments \
2  -H "Content-Type: application/json" \
3  -H "Authorization: Bearer <Access-Token>" \
4  -d '{
5  "funding_option_id": "R5hTlsACO7EuP1TbngsRhBUGQElnh5sg0FpoUssk5QMqAPLl2gRLPw6EUjd8XGAytOBBvW",
6  "note_to_payee": "Hola! Here is your first payment."
7}'

The response shows details about the completed personal payment:

1{
2  "personal_payment": {
3    "payee": {
4      "type": "EMAIL",
5      "id": "[email protected]",
6      "name": "Chinta Raja Dayanand US",
7      "country_code": "US",
8      "is_paypal_account": true
9    },
10    "amount": {
11      "value": "10.00",
12      "currency": "USD"
13    },
14    "fee": {
15      "payer": "PAYER",
16      "amount": {
17        "value": "0.00",
18        "currency": "USD"
19      }
20    },
21    "payment_id": "12V62082M56974514",
22    "payment_type": "PERSONAL",
23    "create_time": "2014-07-10T14:38:17Z",
24    "note_to_payee": "Hola! Here is your first payment.",
25    "estimated_funds_arrival": "2014-07-04T03:14:15Z"
26  }
27}

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

Third-party provider integrations

To use the Personal Payments API to make a personal payments request on behalf of third-parties:

1. Get an access token.

2. Create a personal payment token.

   In the JSON request body, include the amount and currency of the payment, payee information, and the payment type, which is PERSONAL or PURCHASE.

   This sample request creates a personal payment token:

   1curl -v -k -X POST https://api-m.sandbox.paypal.com/v1/payments/personal-payment-tokens \
   2-H "Authorization: Bearer <Access-Token>" \
   3-H "Content-Type: application/json" \
   4-d '{
   5  "amount": {
   6    "value": "5",
   7    "currency": "USD"
   8  },
   9  "payee": {
   10    "id": "[email protected]",
   11    "type": "EMAIL"
   12  },
   13  "payment_type": "PERSONAL"
   14}'

   The response provides the ID of the personal payment token and the redirect URL for the payer to authorize the personal payment:

   1{
   2  "id": "P2P-603655C67C4F6E82",
   3  "create_time": "2017-12-14T21:42:00Z",
   4  "expiry_time": "2017-12-14T22:13:00Z",
   5  "links": [{
   6    "href": "https://api-m.sandbox.paypal.com/myaccount/transfer/send/external/pisp?token_id=P2P-603655C67C4F6E82",
   7    "rel": "initiate_payment",
   8    "method": "GET"
   9  }]
   10}

   The partner should append the return_url to this and perform a browser redirect. The resulting URL will look like this:

   1https://www.paypal.com/myaccount/transfer/send/external/pisp?token_id=P2P-603655C67C4F6E82&return_url=https://www.partner.com/url

   On success, the partner will receive the redirect, along with the following query parameters:

   • status=success
   • transactionId=ABCD12435

   On failure, the partner will receive the following:

   • status=failed

3. Get transaction details for a given payment (optional).

   In the JSON request body, specify the transaction ID (obtained in step 2 above) for which to show details.

   This sample request retrieves the details of a payment for a given transaction ID:

   1curl -v -k -X GET 'https://api-m.sandbox.paypal.com/v1/payments/personal-payments/6XM224482E4007349' \
   2  -H "Authorization: Bearer <Access-Token>"

   The response provides the transaction details, including payee, amount, fee and payment type details:

   1{
   2  "personal_payment": {
   3    "payee": {
   4      "id": "[email protected]",
   5      "type": "EMAIL",
   6      "name": "Dayanand's US",
   7      "country_code": "US",
   8      "is_paypal_account": true            
   9    },
   10    "payment_amount": {
   11      "currency": "USD",
   12      "value": "5.00"
   13    },
   14    "total_fee": {
   15      "currency": "USD",
   16      "value": "0.00"
   17    },
   18    "total_amount_paid": {
   19     "currency": "USD",
   20     "value": "5.00"
   21    },
   22    "total_amount_received": {
   23     "currency": "USD",
   24     "value": "5.00"
   25    },
   26    "payment_id": "6XM224482E4007349",
   27    "payment_type": "PERSONAL",
   28    "estimated_funds_arrival": "2017-01-25T14:1619Z",
   29    "create_time": "2017-01-25T14:16:19Z"
   30  }
   31}

Additional information

• Personal payment transaction fees
• Regulatory requirements
• Send money to phone or account number
• Personal Payments Limited Release API Reference