PayPal Payments

API

Last updated: Aug 15th, 5:50am

Use the Payments API to easily and securely accept online and mobile PayPal payments. You can enable customers to make PayPal payments with only a few clicks, depending on the country. A completed payment is known as a sale.

Integration steps
1. Required Set up your development environment.
2. Required Create PayPal payment.
3. Required Get payment approval.
4. Required Execute payment.
5. Optional Search payment details.

Set up your development environment

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

Create PayPal payment

After you collect the payment details from the customer, specify the payment details in a /payment call.

In the request URI, set the <Access-Token>.

In the JSON request body, set the intent to sale, the redirect URLs, the payment_method to paypal, and the transaction information in the transactions array, which contains one or more transaction objects:

    1curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/payment \
    2  -H "Content-Type: application/json" \
    3  -H "Authorization: Bearer <Access-Token>" \
    4  -d '{
    5  "intent": "sale",
    6  "payer": {
    7    "payment_method": "paypal"
    8  },
    9  "transactions": [{
    10    "amount": {
    11      "total": "30.11",
    12      "currency": "USD",
    13      "details": {
    14        "subtotal": "30.00",
    15        "tax": "0.07",
    16        "shipping": "0.03",
    17        "handling_fee": "1.00",
    18        "shipping_discount": "-1.00",
    19        "insurance": "0.01"
    20      }
    21    },
    22    "description": "This is the payment transaction description.",
    23    "custom": "EBAY_EMS_90048630024435",
    24    "invoice_number": "48787589673",
    25    "payment_options": {
    26      "allowed_payment_method": "INSTANT_FUNDING_SOURCE"
    27    },
    28    "soft_descriptor": "ECHI5786786",
    29    "item_list": {
    30      "items": [{
    31        "name": "hat",
    32        "description": "Brown color hat",
    33        "quantity": "5",
    34        "price": "3",
    35        "tax": "0.01",
    36        "sku": "1",
    37        "currency": "USD"
    38      }, {
    39        "name": "handbag",
    40        "description": "Black color hand bag",
    41        "quantity": "1",
    42        "price": "15",
    43        "tax": "0.02",
    44        "sku": "product34",
    45        "currency": "USD"
    46      }],
    47      "shipping_address": {
    48        "recipient_name": "Hello World",
    49        "line1": "4thFloor",
    50        "line2": "unit#34",
    51        "city": "SAn Jose",
    52        "country_code": "US",
    53        "postal_code": "95131",
    54        "phone": "011862212345678",
    55        "state": "CA"
    56      }
    57    }
    58  }],
    59  "note_to_payer": "Contact us for any questions on your order.",
    60  "redirect_urls": {
    61    "return_url": "https://example.com",
    62    "cancel_url": "https://example.com"
    63  }
    64}'

    A successful call returns confirmation of the transaction, with the created state and a payment ID that you can use in subsequent calls:

      1{
      2  "id": "PAY-1B56960729604235TKQQIYVY",
      3  "create_time": "2014-09-22T20:53:43Z",
      4  "update_time": "2014-09-22T20:53:44Z",
      5  "state": "created",
      6  "intent": "sale",
      7  "payer": {
      8    "payment_method": "paypal"
      9  },
      10  "transactions": [
      11    {
      12      "amount": {
      13        "total": "30.11",
      14        "currency": "USD",
      15        "details": {
      16          "subtotal": "30.00",
      17          "tax": "0.07",
      18          "shipping": "0.03",
      19          "handling_fee": "1.00",
      20          "insurance": "0.01",
      21          "shipping_discount": "-1.00"
      22        }
      23      },
      24      "description": "This is the payment transaction description.",
      25      "custom": "EBAY_EMS_90048630024435",
      26      "invoice_number": "48787589673",
      27      "item_list": {
      28        "items": [
      29          {
      30            "name": "hat",
      31            "sku": "1",
      32            "price": "3.00",
      33            "currency": "USD",
      34            "quantity": "5",
      35            "description": "Brown color hat",
      36            "tax": "0.01"
      37          },
      38          {
      39            "name": "handbag",
      40            "sku": "product34",
      41            "price": "15.00",
      42            "currency": "USD",
      43            "quantity": "1",
      44            "description": "Black color handbag",
      45            "tax": "0.02"
      46          }
      47        ],
      48        "shipping_address": {
      49          "recipient_name": "HelloWorld",
      50          "line1": "4thFloor",
      51          "line2": "unit#34",
      52          "city": "SAn Jose",
      53          "state": "CA",
      54          "phone": "011862212345678",
      55          "postal_code": "95131",
      56          "country_code": "US"
      57        }
      58      }
      59    }
      60  ],
      61  "links": [
      62    {
      63      "href": "https://api-m.paypal.com/v1/payments/payment/PAY-1B56960729604235TKQQIYVY",
      64      "rel": "self",
      65      "method": "GET"
      66    },
      67    {
      68      "href": "https://api-m.paypal.com/v1/payments//cgi-bin/webscr?cmd=_express-checkout&token=EC-60385559L1062554J",
      69      "rel": "approval_url",
      70      "method": "REDIRECT"
      71    },
      72    {
      73      "href": "https://api-m.paypal.com/v1/payments/payment/PAY-1B56960729604235TKQQIYVY/execute",
      74      "rel": "execute",
      75      "method": "POST"
      76    }
      77  ]
      78}

      Next, get approval from the customer for the payment.

      Get payment approval

      When you create a payment for a PayPal payment, the customer must approve the payment before you can execute the sale. To enable the customer to approve the payment, pass the id field to the payment function on your client. When the customer approves the payment, PayPal calls your client-side onAuthorize callback. PayPal passes the data.paymentID and data.payerID to your call back.

      For details, see Set up your client.

      Next, execute the payment.

      Execute payment

      To execute the payment after the customer's approval, make a /payment/execute/ call. In the JSON request body, use the payerID value that was passed to your site. In the header, use the access token that you used when you created the payment.

        1curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-34629814WL663112AKEE3AWQ/execute \
        2  -H "Content-Type: application/json" \
        3  -H "Authorization: Bearer <Access-Token>" \
        4  -d '{
        5  "payer_id": "RRCYJUTFJGZTA"
        6}'

        The execute payment call returns a payment object with transaction details:

          1{
          2  "id": "PAY-4N746561P0587231SKQQK6MY",
          3  "create_time": "2014-09-22T23:22:27Z",
          4  "update_time": "2014-09-22T23:31:13Z",
          5  "state": "approved",
          6  "intent": "sale",
          7  "payer": {
          8    "payment_method": "paypal",
          9    "payer_info": {
          10      "email": "npurayil-uspr-60@paypal.com",
          11      "first_name": "Brian",
          12      "last_name": "Robinson",
          13      "payer_id": "JMKDKJ4D7DG7G",
          14      "shipping_address": {
          15        "line1": "4thFloor",
          16        "line2": "unit#34",
          17        "city": "SAn Jose",
          18        "state": "CA",
          19        "postal_code": "95131",
          20        "country_code": "US",
          21        "phone": "011862212345678",
          22        "recipient_name": "HelloWorld"
          23      }
          24    }
          25  },
          26  "transactions": [
          27    {
          28      "amount": {
          29        "total": "30.11",
          30        "currency": "USD",
          31        "details": {
          32          "subtotal": "30.00",
          33          "tax": "0.07",
          34          "shipping": "0.03",
          35          "handling_fee": "1.00",
          36          "insurance": "0.01",
          37          "shipping_discount": "-1.00"
          38        }
          39      },
          40      "description": "This is the payment transaction description.",
          41      "item_list": {
          42        "items": [
          43          {
          44            "name": "hat",
          45            "sku": "1",
          46            "price": "3.00",
          47            "currency": "USD",
          48            "quantity": "5",
          49            "description": "Brown color hat",
          50            "tax": "0.01"
          51          },
          52          {
          53            "name": "handbag",
          54            "sku": "product34",
          55            "price": "15.00",
          56            "currency": "USD",
          57            "quantity": "1",
          58            "description": "Black color handbag",
          59            "tax": "0.02"
          60          }
          61        ],
          62        "shipping_address": {
          63          "recipient_name": "HelloWorld",
          64          "line1": "4thFloor",
          65          "line2": "unit#34",
          66          "city": "SAn Jose",
          67          "state": "CA",
          68          "phone": "011862212345678",
          69          "postal_code": "95131",
          70          "country_code": "US"
          71        }
          72      },
          73      "related_resources": [
          74        {
          75          "sale": {
          76            "id": "4XP56210M0797192Y",
          77            "create_time": "2014-09-22T23:22:27Z",
          78            "update_time": "2014-09-22T23:31:13Z",
          79            "amount": {
          80              "total": "30.11",
          81              "currency": "USD"
          82            },
          83            "payment_mode": "INSTANT_TRANSFER",
          84            "state": "completed",
          85            "protection_eligibility": "ELIGIBLE",
          86            "protection_eligibility_type": "ITEM_NOT_RECEIVED_ELIGIBLE",
          87            "transaction_fee": {
          88              "value": "1.75",
          89              "currency": "USD"
          90            },
          91            "parent_payment": "PAY-4N746561P0587231SKQQK6MY",
          92            "links": [
          93              {
          94                "href": "https://api-m.paypal.com/v1/payments/sale/4XP56210M0797192Y",
          95                "rel": "self",
          96                "method": "GET"
          97              },
          98              {
          99                "href": "https://api-m.paypal.com/v1/payments/sale/4XP56210M0797192Y/refund",
          100                "rel": "refund",
          101                "method": "POST"
          102              },
          103              {
          104                "href": "https://api-m.paypal.com/v1/payments/payment/PAY-4N746561P0587231SKQQK6MY",
          105                "rel": "parent_payment",
          106                "method": "GET"
          107              }
          108            ]
          109          }
          110        }
          111      ]
          112    }
          113  ],
          114  "links": [
          115    {
          116      "href": "https://api-m.paypal.com/v1/payments/payment/PAY-4N746561P0587231SKQQK6MY",
          117      "rel": "self",
          118      "method": "GET"
          119    }
          120  ]
          121}

          Search payment details

          You can use the Payments API to list completed payments with transaction details. Then, use the transaction IDs in the response to complete other payment operations. For example, you can issue a refund for a payment, by transaction ID.

          List payments with transaction details

          To list payments with transaction details, enter query parameters to specify the time range of the transaction, how many payments to list, and the sort order of the payments in the response.

          Query parameters Description
          start_time end_time Specify the start and end times Internet date and time format.

          For example: start_time=2017-03-06T11:00:00Z and end_time=2017-03-06T16:00:00Z
          start_id The ID of the starting resource in the response. When results are paged and you're making subsequent payments calls, you can use the next_id value as the start_id to continue with the next set of results.
          count The number of items to list in the response. The default is 10 with a maximum of 20.
          start_index The start index of the payments to list. Typically, you use the start_index to jump to a specific position in the resource history based on its cart. For example, to start at the second item in a list of results, specify ?start_index=2.
          sort_by Sort payments by the payment create_time or update_time.

          Request

          This example request lists ten payments by create time:

            1curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/payment?count=10&start_index=0&sort_by=create_time \
            2-H "Content-Type: application/json" \
            3-H "Authorization: Bearer <Access-Token>"

            Response

            The JSON response body lists payments that match the search criteria. The count field indicates the number of payments in the response. In a subsequent list payments call, set start_id to the next_id value to list the next set of payments.

              1{
              2  "payments": [
              3    {
              4      "id": "PAY-0US81985GW1191216KOY7OXA",
              5      "create_time": "2017-06-30T23:48:44Z",
              6      "update_time": "2017-06-30T23:49:27Z",
              7      "state": "APPROVED",
              8      "intent": "order",
              9      "payer": {
              10        "payment_method": "paypal"
              11      },
              12      "transactions": [
              13        {
              14          "amount": {
              15            "total": "41.15",
              16            "currency": "USD",
              17            "details": {
              18              "subtotal": "30.00",
              19              "tax": "1.15",
              20              "shipping": "10.00"
              21            }
              22          },
              23          "description": "The payment transaction description.",
              24          "item_list": {
              25            "items": [
              26              {
              27                "name": "hat",
              28                "sku": "1",
              29                "price": "3.00",
              30                "currency": "USD",
              31                "quantity": "5"
              32              },
              33              {
              34                "name": "handbag",
              35                "sku": "product34",
              36                "price": "15.00",
              37                "currency": "USD",
              38                "quantity": "1"
              39              }
              40            ],
              41            "shipping_address": {
              42              "recipient_name": "John Doe",
              43              "line1": "4th Floor, One Lagoon Drive",
              44              "line2": "Unit #34",
              45              "city": "Redwood City",
              46              "state": "CA",
              47              "phone": "4084217591",
              48              "postal_code": "94065",
              49              "country_code": "US"
              50            }
              51          },
              52          "related_resources": [
              53            {
              54              "authorization": {
              55                "id": "53P09338XY5426455",
              56                "create_time": "2017-06-30T23:50:01Z",
              57                "update_time": "2017-06-30T23:50:01Z",
              58                "amount": {
              59                  "total": "41.15",
              60                  "currency": "USD"
              61                },
              62                "parent_payment": "PAY-0US81985GW1191216KOY7OXA",
              63                "valid_until": "2017-07-29T23:49:52Z",
              64                "links": [
              65                  {
              66                    "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-0US81985GW1191216KOY7OXA",
              67                    "rel": "parent_payment",
              68                    "method": "GET"
              69                  }
              70                ]
              71              }
              72            }
              73          ]
              74        }
              75      ],
              76      "links": [
              77        {
              78          "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-0US81985GW1191216KOY7OXA",
              79          "rel": "self",
              80          "method": "GET"
              81        }
              82      ]
              83    },
              84    {
              85      "id": "PAY-53485002LD6169910KOZQ25I",
              86      "create_time": "2017-07-01T19:35:17Z",
              87      "update_time": "2017-07-01T19:36:05Z",
              88      "state": "APPROVED",
              89      "intent": "order",
              90      "payer": {
              91        "payment_method": "paypal"
              92      },
              93      "transactions": [
              94        {
              95          "amount": {
              96            "total": "33.00",
              97            "currency": "USD",
              98            "details": {
              99              "subtotal": "21.00",
              100              "tax": "2.00",
              101              "shipping": "10.00"
              102            }
              103          },
              104          "description": "The payment transaction description.",
              105          "item_list": {
              106            "items": [
              107              {
              108                "name": "hat",
              109                "sku": "1",
              110                "price": "3.00",
              111                "currency": "USD",
              112                "quantity": "2"
              113              },
              114              {
              115                "name": "handbag",
              116                "sku": "product34",
              117                "price": "15.00",
              118                "currency": "USD",
              119                "quantity": "1"
              120              }
              121            ],
              122            "shipping_address": {
              123              "recipient_name": "Hannah Lu",
              124              "line1": "1602 Crane ct",
              125              "line2": "",
              126              "city": "San Jose",
              127              "state": "CA",
              128              "phone": "4084217591",
              129              "postal_code": "95052",
              130              "country_code": "US"
              131            }
              132          },
              133          "related_resources": [
              134            {
              135              "authorization": {
              136                "id": "91527087GH224122L",
              137                "create_time": "2017-07-01T19:36:22Z",
              138                "update_time": "2017-07-01T19:36:22Z",
              139                "amount": {
              140                  "total": "33.00",
              141                  "currency": "USD"
              142                },
              143                "parent_payment": "PAY-53485002LD6169910KOZQ25I",
              144                "valid_until": "2017-07-30T19:36:22Z",
              145                "links": [
              146                  {
              147                    "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-53485002LD6169910KOZQ25I",
              148                    "rel": "parent_payment",
              149                    "method": "GET"
              150                  }
              151                ]
              152              }
              153            }
              154          ]
              155        }
              156      ],
              157      "links": [
              158        {
              159          "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-53485002LD6169910KOZQ25I",
              160          "rel": "self",
              161          "method": "GET"
              162        }
              163      ]
              164    },
              165    {
              166      "id": "PAY-7F5790198P134484LKOZSG7Q",
              167      "create_time": "2017-07-01T21:09:18Z",
              168      "update_time": "2017-07-01T22:31:56Z",
              169      "state": "APPROVED",
              170      "intent": "order",
              171      "payer": {
              172        "payment_method": "paypal"
              173      },
              174      "transactions": [
              175        {
              176          "amount": {
              177            "total": "42.00",
              178            "currency": "USD",
              179            "details": {
              180              "subtotal": "36.00",
              181              "tax": "1.00",
              182              "shipping": "5.00"
              183            }
              184          },
              185          "description": "The payment transaction description.",
              186          "item_list": {
              187            "items": [
              188              {
              189                "name": "handbag",
              190                "sku": "product34",
              191                "price": "36.00",
              192                "currency": "USD",
              193                "quantity": "1"
              194              }
              195            ],
              196            "shipping_address": {
              197              "recipient_name": "Anna Joseph",
              198              "line1": "2525 North 1st street",
              199              "line2": "unit 4",
              200              "city": "San Jose",
              201              "state": "CA",
              202              "phone": "011862212345678",
              203              "postal_code": "95031",
              204              "country_code": "US"
              205            }
              206          },
              207          "related_resources": [
              208            {
              209              "capture": {
              210                "id": "26062838D7499294V",
              211                "create_time": "2017-07-01T21:16:22Z",
              212                "update_time": "2017-07-01T21:16:24Z",
              213                "amount": {
              214                  "total": "7.00",
              215                  "currency": "USD"
              216                },
              217                "state": "COMPLETED",
              218                "parent_payment": "PAY-7F5790198P134484LKOZSG7Q",
              219                "links": [
              220                  {
              221                    "href": "https://api-m.sandbox.paypal.com/v1/payments/capture/26062838D7499294V",
              222                    "rel": "self",
              223                    "method": "GET"
              224                  },
              225                  {
              226                    "href": "https://api-m.sandbox.paypal.com/v1/payments/capture/26062838D7499294V/refund",
              227                    "rel": "refund",
              228                    "method": "POST"
              229                  },
              230                  {
              231                    "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-7F5790198P134484LKOZSG7Q",
              232                    "rel": "parent_payment",
              233                    "method": "GET"
              234                  }
              235                ]
              236              }
              237            },
              238            {
              239              "capture": {
              240                "id": "0YU20012P1477553M",
              241                "create_time": "2017-07-01T22:31:54Z",
              242                "update_time": "2017-07-01T22:31:56Z",
              243                "amount": {
              244                  "total": "35.00",
              245                  "currency": "USD"
              246                },
              247                "state": "COMPLETED",
              248                "parent_payment": "PAY-7F5790198P134484LKOZSG7Q",
              249                "links": [
              250                  {
              251                    "href": "https://api-m.sandbox.paypal.com/v1/payments/capture/0YU20012P1477553M",
              252                    "rel": "self",
              253                    "method": "GET"
              254                  },
              255                  {
              256                    "href": "https://api-m.sandbox.paypal.com/v1/payments/capture/0YU20012P1477553M/refund",
              257                    "rel": "refund",
              258                    "method": "POST"
              259                  },
              260                  {
              261                    "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-7F5790198P134484LKOZSG7Q",
              262                    "rel": "parent_payment",
              263                    "method": "GET"
              264                  }
              265                ]
              266              }
              267            }
              268          ]
              269        }
              270      ],
              271      "links": [
              272        {
              273          "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-7F5790198P134484LKOZSG7Q",
              274          "rel": "self",
              275          "method": "GET"
              276        }
              277      ]
              278    }
              279  ],
              280  "count": 3,
              281  "next_id": "PAY-9X4935091L753623RKOZTRHI"
              282}

              Show payment with transaction details

              The show payment details, show sale details, and show captured payment details calls return an array of transactions that include transaction IDs. To show transaction details, call show payment details with a transaction ID.

              For example, a payment request returns the following ID:

                1"id": "PAY-1B56960729604235TKQQIYVY"

                Request

                To show transaction details, specify the id in the following call:

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

                  Response

                  The response lists transactions:

                    1{
                    2  "id": "PAY-5YK922393D847794YKER7MUI",
                    3  "create_time": "2017-02-19T22:01:53Z",
                    4  "update_time": "2017-02-19T22:01:55Z",
                    5  "state": "approved",
                    6  "intent": "sale",
                    7  "payer": {
                    8    "payment_method": "credit_card",
                    9    "funding_instruments": []
                    10  },
                    11  "transactions": [{
                    12    "amount": {},
                    13    "description": "The payment transaction description.",
                    14    "note_to_payer": "Contact us for any questions on your order.",
                    15    "related_resources": [{
                    16      "sale": {
                    17        "id": "36C38912MN9658832",
                    18        "create_time": "2017-02-19T22:01:53Z",
                    19        "update_time": "2017-02-19T22:01:55Z",
                    20        "state": "completed",
                    21        "amount": {},
                    22        "protection_eligibility": "ELIGIBLE",
                    23        "protection_eligibility_type": "ITEM_NOT_RECEIVED_ELIGIBLE",
                    24        "transaction_fee": {},
                    25        "parent_payment": "PAY-5YK922393D847794YKER7MUI",
                    26        "links": [{},
                    27          {},
                    28          {}
                    29        ]
                    30      }
                    31    }]
                    32  }],
                    33  "links": []
                    34}

                    Next

                    A sale is a completed payment. You can use the payment ID to show sale details and refund a sale.

                    Then, learn how to authorize and capture payments.

                    Additional information

                    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