Orders Integration Guide

API

Last updated: Aug 15th, 7:30am

Use the Payments REST API to create a PayPal order, which is a purchase that a customer consents to but for which funds are not placed on hold.

Overview

To complete an order, you can either:

  • Directly capture funds when you create the order. No additional authorization is required.

  • Create an authorization, which authorizes and places funds on hold for the order. Later, you can capture the funds for the order.

    For example, you can use the authorization and capture technique for orders that contain items that are not immediately available for shipment. Then, you can create subsequent basic authorizations as the items become available. These authorizations ensure that the customer still has the funds available to purchase each item.

An order is valid for 29 days. During this period, you can request from one to ten or more authorizations to ensure the availability of funds. By default, you can make up to ten basic authorizations for each order. To configure your account to enable up to 99 basic authorizations for each order, contact PayPal Customer Support.

The sum of the amounts in any open authorizations for an order cannot exceed 115% or $75, whichever is less, of the amount that you requested when you created the order.

Integration steps
1. Required Set up your development environment.
2. Required Create an order.
3. Required Get customer approval.
4. Required Execute the order.
5. Optional Authorize payment for an order.
6. Optional Capture payment for an order.

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 order

When you create an order, you provide payment details just as you do when you create a PayPal payment.

In the JSON request body, set:

  • The intent to sale.
  • The payment_method to paypal. The only supported payment method for an order is a PayPal payment.
  • The redirect URLs, which are used to redirect the customer when he or she approves or cancels the order.
    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    {
    11      "amount": {
    12        "total": "30.11",
    13        "currency": "USD",
    14        "details": {
    15          "subtotal": "30.00",
    16          "tax": "0.07",
    17          "shipping": "0.03",
    18          "handling_fee": "1.00",
    19          "shipping_discount": "-1.00",
    20          "insurance": "0.01"
    21        }
    22      },
    23      "description": "The payment transaction description.",
    24      "custom": "EBAY_EMS_90048630024435",
    25      "invoice_number": "48787589673",
    26      "payment_options": {
    27        "allowed_payment_method": "INSTANT_FUNDING_SOURCE"
    28      },
    29      "soft_descriptor": "ECHI5786786",
    30      "item_list": {
    31        "items": [
    32          {
    33            "name": "hat",
    34            "description": "Brown hat.",
    35            "quantity": "5",
    36            "price": "3",
    37            "tax": "0.01",
    38            "sku": "1",
    39            "currency": "USD"
    40          },
    41          {
    42            "name": "handbag",
    43            "description": "Black handbag.",
    44            "quantity": "1",
    45            "price": "15",
    46            "tax": "0.02",
    47            "sku": "product34",
    48            "currency": "USD"
    49          }
    50        ],
    51        "shipping_address": {
    52          "recipient_name": "Brian Robinson",
    53          "line1": "4th Floor",
    54          "line2": "Unit #34",
    55          "city": "San Jose",
    56          "country_code": "US",
    57          "postal_code": "95131",
    58          "phone": "011862212345678",
    59          "state": "CA"
    60        }
    61      }
    62    }
    63  ],
    64  "note_to_payer": "Contact us for any questions on your order.",
    65  "redirect_urls": {
    66    "return_url": "https://example.com/return",
    67    "cancel_url": "https://example.com/cancel"
    68  }
    69}'

    A successful call returns the order details including a PayPal-generated order ID, the order state, which is created, and the date and time when the order was created.

      1{
      2  "id": "PAY-1B56960729604235TKQQIYVY",
      3  "create_time": "2017-09-22T20:53:43Z",
      4  "update_time": "2017-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": "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 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 handbag.",
      45            "tax": "0.02"
      46          }
      47        ],
      48        "shipping_address": {
      49          "recipient_name": "Brian Robinson",
      50          "line1": "4th Floor",
      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.sandbox.paypal.com/v1/payments/payment/PAY-1B56960729604235TKQQIYVY",
      64      "rel": "self",
      65      "method": "GET"
      66    },
      67    {
      68      "href": "https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-60385559L1062554J",
      69      "rel": "approval_url",
      70      "method": "REDIRECT"
      71    },
      72    {
      73      "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-1B56960729604235TKQQIYVY/execute",
      74      "rel": "execute",
      75      "method": "POST"
      76    }
      77  ]
      78}

      Next, get customer approval for the PayPal payment for the order.

      Get customer approval

      When you create an order, the customer must approve the PayPal payment before you can execute the order. To enable the customer to approve the payment, pass the id value from the create order response 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.

      To test customer approval in sandbox:

      1. Navigate to the approval_url given in the HATEOAS links provided in your create order call.
      2. When the checkout flow popup appears, log in using the buyer account created for you when you created your sandbox account.
      3. Make the payment.
      4. Log into https://www.sandbox.paypal.com/ with your buyer account. You will see the funds transfer from the buyer side.
      5. Log into https://www.sandbox.paypal.com/ with your facilitator account (also automatically created when you created a sandbox account) and you will see the funds transfer to you from the buyer.

      Next, execute the order.

      Execute order

      To execute the order after the customer's approval, make a /payment/payment_id/execute/ call, where payment_id is the ID of the payment to execute. In the JSON request body, the payer_id is the ID of the payer that PayPal passes in the data.payerID to your call back:

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

        The execute payment call returns a payment object with transaction details. The response returns HATEOAS links that you can use to complete further operations on the order:

          1{
          2  "id": "PAY-9N9834337A9191208KOZOQWI",
          3  "create_time": "2017-07-01T16:56:57Z",
          4  "update_time": "2017-07-01T17:05:41Z",
          5  "state": "approved",
          6  "intent": "order",
          7  "payer": {
          8    "payment_method": "paypal",
          9    "payer_info": {
          10      "email": "payer@example.com",
          11      "first_name": "Thomas",
          12      "last_name": "Miller",
          13      "payer_id": "PUP87RBJV8HPU",
          14      "shipping_address": {
          15        "line1": "4th Floor, One Lagoon Drive",
          16        "line2": "Unit #34",
          17        "city": "Redwood City",
          18        "state": "CA",
          19        "postal_code": "94065",
          20        "country_code": "US",
          21        "phone": "011862212345678",
          22        "recipient_name": "Thomas Miller"
          23      }
          24    }
          25  },
          26  "transactions": [
          27  {
          28    "amount": {
          29      "total": "41.15",
          30      "currency": "USD",
          31      "details": {
          32        "subtotal": "30.00",
          33        "tax": "0.15",
          34        "shipping": "11.00"
          35      }
          36    },
          37    "description": "The payment transaction description.",
          38    "item_list": {
          39      "items": [
          40      {
          41        "name": "hat",
          42        "sku": "1",
          43        "price": "3.00",
          44        "currency": "USD",
          45        "quantity": "5"
          46      },
          47      {
          48        "name": "handbag",
          49        "sku": "product34",
          50        "price": "15.00",
          51        "currency": "USD",
          52        "quantity": "1"
          53      }],
          54      "shipping_address": {
          55        "recipient_name": "Thomas Miller",
          56        "line1": "4th Floor, One Lagoon Drive",
          57        "line2": "Unit #34",
          58        "city": "Redwood City",
          59        "state": "CA",
          60        "phone": "011862212345678",
          61        "postal_code": "94065",
          62        "country_code": "US"
          63      }
          64    },
          65    "related_resources": [
          66    {
          67      "order": {
          68        "id": "O-3SP845109F051535C",
          69        "create_time": "2017-07-01T16:56:58Z",
          70        "update_time": "2017-07-01T17:05:41Z",
          71        "state": "pending",
          72        "amount": {
          73          "total": "41.15",
          74          "currency": "USD"
          75        },
          76        "parent_payment": "PAY-9N9834337A9191208KOZOQWI",
          77        "links": [
          78        {
          79          "href": "https://api-m.sandbox.paypal.com/v1/payments/orders/O-3SP845109F051535C",
          80          "rel": "self",
          81          "method": "GET"
          82        },
          83        {
          84          "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-9N9834337A9191208KOZOQWI",
          85          "rel": "parent_payment",
          86          "method": "GET"
          87        },
          88        {
          89          "href": "https://api-m.sandbox.paypal.com/v1/payments/orders/O-3SP845109F051535C/void",
          90          "rel": "void",
          91          "method": "POST"
          92        },
          93        {
          94          "href": "https://api-m.sandbox.paypal.com/v1/payments/orders/O-3SP845109F051535C/authorize",
          95          "rel": "authorization",
          96          "method": "POST"
          97        },
          98        {
          99          "href": "https://api-m.sandbox.paypal.com/v1/payments/orders/O-3SP845109F051535C/capture",
          100          "rel": "capture",
          101          "method": "POST"
          102        }]
          103      }
          104    }]
          105  }],
          106  "links": [
          107  {
          108    "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-9N9834337A9191208KOZOQWI",
          109    "rel": "self",
          110    "method": "GET"
          111  }]
          112}

          Next, for orders for which you do not immediately capture funds, you can authorize funds and capture the funds later.

          Authorize payment for an order

          Authorizing an order confirms the availability of funds but does not place the funds on hold.

          You can make multiple authorizations and captures against a single order.

          To authorize payment for an order, pass the order ID in the URI of a POST call. The authorize order call confirms that funds are available to complete the order payment.

            1curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/orders/O-0NR488530V5211123/authorize \
            2  -H 'Content-Type: application/json' \
            3  -H 'Authorization: Bearer <Access-Token>' \
            4  -d '{
            5  "amount":
            6  {
            7    "total": "7.00",
            8    "currency": "USD"
            9  }
            10}'

            The response includes a capture link that you use to capture the payment.

              1{
              2  "status": "OK",
              3  "result":
              4  {
              5    "id": "0PG032325D352531H",
              6    "create_time": "2017-06-28T07:38:10Z",
              7    "update_time": "2017-06-28T07:38:12Z",
              8    "state": "Pending",
              9    "amount":
              10    {
              11      "total": "41.15",
              12      "currency": "USD"
              13    },
              14    "parent_payment": "O-0NR488530V5211123",
              15    "links": [
              16    {
              17      "href": "https://api-m.sandbox.paypal.com/v1/payments/orders/O-0NR488530V5211123",
              18      "rel": "self",
              19      "method": "GET"
              20    },
              21    {
              22      "href": "https://api-m.sandbox.paypal.com/v1/payments/authorization/0PG032325D352531H",
              23      "rel": "self",
              24      "method": "GET"
              25    },
              26    {
              27      "href": "https://api-m.sandbox.paypal.com/v1/payments/authorization/0PG032325D352531H/capture",
              28      "rel": "capture",
              29      "method": "POST"
              30    },
              31    {
              32      "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-0AY778532K612520BKOXHAKY",
              33      "rel": "parent_payment",
              34      "method": "GET"
              35    }]
              36  }
              37}

              Next, capture funds for an authorized order payment.

              Capture payment for an order

              To capture the payment for an order, use the capture link from the previous response.

                1curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/orders/0PG032325D352531H/capture \
                2  -H "Content-Type: application/json" \
                3  -H "Authorization: Bearer <Access-Token>" \
                4  -d '{
                5  "amount": {
                6    "currency": "USD",
                7    "total": "4.54"
                8  },
                9  "is_final_capture": true
                10}'

                A successful call returns a capture object with details about the captured payment:

                  1{
                  2  "id": "51366113MA710110S",
                  3  "create_time": "2017-07-01T17:13:45Z",
                  4  "update_time": "2017-07-01T17:13:47Z",
                  5  "amount": {
                  6    "total": "4.54",
                  7    "currency": "USD"
                  8  },
                  9  "is_final_capture": true,
                  10  "state": "completed",
                  11  "parent_payment": "PAY-9N9834337A9191208KOZOQWI",
                  12  "links": [
                  13  {
                  14    "href": "https://api-m.sandbox.paypal.com/v1/payments/capture/51366113MA710110S",
                  15    "rel": "self",
                  16    "method": "GET"
                  17  },
                  18  {
                  19    "href": "https://api-m.sandbox.paypal.com/v1/payments/capture/51366113MA710110S/refund",
                  20    "rel": "refund",
                  21    "method": "POST"
                  22  },
                  23  {
                  24    "href": "https://api-m.sandbox.paypal.com/v1/payments/orders/O-3SP845109F051535C",
                  25    "rel": "order",
                  26    "method": "GET"
                  27  },
                  28  {
                  29    "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-9N9834337A9191208KOZOQWI",
                  30    "rel": "parent_payment",
                  31    "method": "GET"
                  32  }]
                  33}

                  Next

                  You can use the order ID to show order details or void an order. You cannot void an order if the payment has already been partially or fully captured.

                  Learn how to capture an authorization or refund payments.

                  Additional information

                  ReferencePayPal.comPrivacyCookiesSupportLegalContact

                  We use cookies to improve your experience on our site. May we use marketing cookies to show you personalized ads? Manage all cookies