Personal Payments Token/
Integrate

Personal Payments Token Integration Guide

Last updated: Aug 15th, 6:04am

Follow these steps to integrate the Personal Payments Token API:

  1. Set up your development environment.
  2. Create peer-to-peer access token.
  3. Complete the payment.
  4. Show payment details.

Set up your development environment

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

Create peer-to-peer access token

You need these elements to create a peer-to-peer access token:

  1. Amount of money to be paid
  2. Recipient's email address, phone number, or account number
  3. Payment type
  4. Redirect context (the URL where the user lands after completing the payment)

Sample request

    1curl -X POST https://api-m.sandbox.paypal.com/v1/payments/personal-payment-tokens \
    2  -H 'Accept: application/json' \
    3  -H 'Content-Type: application/json' \
    4  -H 'Authorization: Bearer <Access-Token>' \
    5  -d '{
    6  "amount": {
    7    "value": "10.00",
    8    "currency": "USD"
    9  },
    10  "payee": {
    11    "id": "[email protected]",
    12    "type": "EMAIL"
    13  },
    14  "redirect_context": {
    15    "return_url": "https://example.com/return"
    16    "cancel_url": "https://example.com/cancel"
    17  },
    18  "payment_type": "PERSONAL",
    19  "note_to_payee": "Hello World"
    20}'

    Sample response

      1{
      2  "id": "P2P-61F03DC650CD400F",
      3  "amount": {
      4    "currency": "USD",
      5    "value": "10.00"
      6  },
      7  "payee": {
      8    "id": "[email protected]",
      9    "type": "EMAIL"
      10  },
      11  "payment_type": "PERSONAL",
      12  "redirect_context": {
      13    "return_url": "https://example.com/return",
      14    "cancel_url": "https://example.com/cancel"
      15  },
      16  "links": [{
      17    "href": "https://api-m.sandbox.paypal.com/myaccount/transfer/send/external/pisp?token_id=P2P-61F03DC65",
      18    "rel": "initiate_payment",
      19    "method": "GET"
      20  }],
      21  "status": "CREATED",
      22  "note_to_payee": "Hello World"
      23}

      Send payments to a mobile phone number

      This code sample shows the request payload for a recipient paid by phone number:

        1{
        2  "payee": {
        3    "id": "+14088363374",
        4    "type": "PHONE"
        5  }
        6}

        You must provide the phone number in E164 standard format. PayPal recommends using Google's open-source phonelib to validate and convert phone numbers into E164 format.

        The Personal Payment Token API supports payments to recipients with phone numbers from these countries:

        • United States of America (US)
        • Canada (CA)
        • United Kingdom (GB)
        • Australia (AU)
        • France (FR)
        • Italy (IT)
        • Spain (ES)
        • Brazil (BR)
        • Singapore (SG)
        • Mexico (MX)
        • Malaysia (MY)

        Complete the payment

        After you create a token and the user sends money to another user via PayPal, you must redirect the user to your app to complete the payment. After the user completes the payment, you can retrieve the payment details.

        Redirect to PayPal

        Once you create a token, perform a browser redirect. You can optionally append a state query parameter to the redirect URL. The URL is passed back as-is when the redirect completes.

        You can complete the redirect in these environments:

        • iOS. Use SFSafariViewController.
        • Android. Use Chrome Custom Tabs.
        • Desktop or laptops. Use a full-page redirect or a browser mini window. For security reasons, you cannot iFrame this experience into the partner website.

        When the sender lands on the redirect, the sender must log in and complete the payment. Whether the payment completes or fails, the sender is redirected to the partner's app or website, as specified in the return_url when you create the token.

        On success, the partner receives the redirect, along with these query parameters:

          1status=success&transactionId=ABCD12435

          A failed request returns this response:

            1status=failed

            The completed transaction returns the PayPal transaction ID.

            Show payment details

            You can show the token status from valid tokens. By default, tokens remain valid for 24 hours. If a token contains a successful payment, you can show the details of the transaction at any time.

            The following code shows a token without a completed payment:

            Sample request

              1curl -X GET \
              2  https://api-m.sandbox.paypal.com/v1/payments/personal-payment-tokens/P2P-61F03DC650CD400F \
              3  -H 'Accept: application/json' \
              4  -H 'Content-Type: application/json' \
              5  -H 'Authorization: Bearer <Access-Token>'

              Sample response

                1{
                2  "id": "P2P-61F03DC650CD400F",
                3  "amount": {
                4    "currency": "USD",
                5    "value": "10.00"
                6  },
                7  "payee": {
                8    "id": "123456789",
                9    "type": "ACCOUNT"
                10  },
                11  "payment_type": "PERSONAL",
                12  "redirect_context": {
                13    "return_url": "https://example.com/return",
                14    "cancel_url": "https://example.com/cancel"
                15  },
                16  "links": [{
                17    "href": "https://api-m.sandbox.paypal.com/myaccount/transfer/send/external/pisp?token_id=P2P-61F03DC65",
                18    "rel": "initiate_payment",
                19    "method": "GET"
                20  }],
                21  "status": "CREATED",
                22  "note_to_payee": "Hello World"
                23}

                This example response shows a completed payment:

                  1{
                  2  "id": "P2P-61F03DC650CD400F",
                  3  "amount": {
                  4    "currency": "USD",
                  5    "value": "10.00"
                  6  },
                  7  "payee": {
                  8    "id": "123456789",
                  9    "type": "ACCOUNT"
                  10  },
                  11  "payment_type": "PERSONAL",
                  12  "redirect_context": {
                  13    "return_url": "https://example.com/return",
                  14    "cancel_url": "https://example.com/cancel"
                  15  },
                  16  "personal_payment": {
                  17    "payment_id": "19B80652DF518842M",
                  18    "receiver_payment_id": "94F65398TY420544J",
                  19    "status": "COMPLETED",
                  20    "payee": {
                  21      "id": "123456789",
                  22      "type": "ACCOUNT",
                  23      "name": "abc",
                  24      "country_code": "GB",
                  25      "is_paypal_account": true,
                  26      "is_paypal_alias_confirmed": true
                  27    },
                  28    "payment_amount": {
                  29      "currency": "USD",
                  30      "value": "10.00"
                  31    }
                  32  }
                  33}
                  ReferencePayPal.comPrivacyCookiesSupportLegalContact

                  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