Orders

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

To create and process an order:

1. Required Meet the prerequisites.
2. Required Create an order.
3. Required Get customer approval.
4. Required Execute the order.
5. Optional Authorize an order.
6. Optional Capture an order.

Prerequisites

  1. Get an access token.

    To get an access token, you must create a PayPal app. When you create an app, PayPal generates a set of OAuth client_id and secret keys for your app for both the sandbox and live environments. Then, to get an access token, you pass the client_id:secret credentials in the Authorization header in a get access token request. The authorization server issues an access token in exchange for your client ID and secret credentials. You use the access token for authentication when you make REST API requests.

    For more information, see make your first call. If you are a non-US developer, see International Developer Questions. You can use your sandbox access token to try any of the code in the REST API reference.

    Each API response includes HATEOAS links that enable you to construct a payment flow.

  2. To receive payments in a currency that you do not hold, first configure your Payment Receiving Preferences in your PayPal account. Otherwise, your payment status might be pending until you manually approve the payment in your PayPal account.

  3. To receive guest checkout payments, which allow credit cards, enable the PayPal Account Optional option in your account settings. The path to this option for US accounts is:

    Profile > My selling tools > Website preferences > PayPal Account Optional

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 order.
  • 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.
curl -v https://api.sandbox.paypal.com/v1/payments/payment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token" \
  -d '{
  "intent": "order",
  "payer": {
    "payment_method": "paypal"
  },
  "transactions": [{
    "amount": {
      "total": "30.11",
      "currency": "USD",
      "details": {
        "subtotal": "30.00",
        "tax": "0.07",
        "shipping": "0.03",
        "handling_fee": "1.00",
        "shipping_discount": "-1.00",
        "insurance": "0.01"
      }
    },
    "description": "This is the payment transaction description.",
    "custom": "EBAY_EMS_90048630024435",
    "invoice_number": "48787589673",
    "payment_options": {
      "allowed_payment_method": "INSTANT_FUNDING_SOURCE"
    },
    "soft_descriptor": "ECHI5786786",
    "item_list": {
      "items": [{
        "name": "hat",
        "description": "Brown color hat",
        "quantity": "5",
        "price": "3",
        "tax": "0.01",
        "sku": "1",
        "currency": "USD"
      }, {
        "name": "handbag",
        "description": "Black color hand bag",
        "quantity": "1",
        "price": "15",
        "tax": "0.02",
        "sku": "product34",
        "currency": "USD"
      }],
      "shipping_address": {
        "recipient_name": "Betsy Buyer",
        "line1": "4th Floor",
        "line2": "unit#34",
        "city": "San Jose",
        "country_code": "US",
        "postal_code": "95131",
        "phone": "011862212345678",
        "state": "CA"
      }
    }
  }],
  "note_to_payer": "Contact us for any questions on your order.",
  "redirect_urls": {
    "return_url": "http://www.amazon.com",
    "cancel_url": "http://www.hawaii.com"
  }
}'

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

{
  "id": "PAY-6BG64912FX380861UK6SK7OI",
  "intent": "order",
  "state": "created",
  "payer": {
    "payment_method": "paypal"
  },
  "transactions": [{
    "amount": {
      "total": "30.11",
      "currency": "USD",
      "details": {
        "subtotal": "30.00",
        "tax": "0.07",
        "shipping": "0.03",
        "insurance": "0.01",
        "handling_fee": "1.00",
        "shipping_discount": "-1.00"
      }
    },
    "description": "This is the payment transaction description.",
    "custom": "EBAY_EMS_90048630024435",
    "invoice_number": "48787589673",
    "soft_descriptor": "ECHI5786786",
    "payment_options": {
      "allowed_payment_method": "INSTANT_FUNDING_SOURCE",
      "recurring_flag": false,
      "skip_fmf": false
    },
    "item_list": {
      "items": [{
        "name": "hat",
        "sku": "1",
        "description": "Brown color hat",
        "price": "3.00",
        "currency": "USD",
        "tax": "0.01",
        "quantity": 5
      }, {
        "name": "handbag",
        "sku": "product34",
        "description": "Black color hand bag",
        "price": "15.00",
        "currency": "USD",
        "tax": "0.02",
        "quantity": 1
      }],
      "shipping_address": {
        "recipient_name": "Betsy Buyer",
        "line1": "4th Floor",
        "line2": "unit#34",
        "city": "San Jose",
        "state": "CA",
        "postal_code": "95131",
        "country_code": "US",
        "phone": "011862212345678"
      }
    },
    "related_resources": []
  }],
  "note_to_payer": "Contact us for any questions on your order.",
  "create_time": "2017-08-05T15:24:41Z",
  "links": [{
    "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-6BG64912FX380861UK6SK7OI",
    "rel": "self",
    "method": "GET"
  }, {
    "href": "https://www.msmaster.qa.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-3GY98266HG611903V",
    "rel": "approval_url",
    "method": "REDIRECT"
  }, {
    "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-6BG64912FX380861UK6SK7OI/execute",
    "rel": "execute",
    "method": "POST"
  }]
}

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.

For details, see Set up your client.

Note: For legacy full-page-redirect integrations, redirect the customer to the approval_url from the previous response so that he or she can approve the payment.

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:

curl -v -k -X POST https://api.sandbox.paypal.com/v1/payments/payment/PAY-9N9834337A9191208KOZOQWI/execute \
 -H 'Content-Type: application/json' \
 -d '{
  "payer_id": "CR87QHB7JTRSC"
}'

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:

{
  "id": "PAY-9N9834337A9191208KOZOQWI",
  "create_time": "2017-07-01T16:56:57Z",
  "update_time": "2017-07-01T17:05:41Z",
  "state": "approved",
  "intent": "order",
  "payer": {
    "payment_method": "paypal",
    "payer_info": {
      "email": "qa152-biz@paypal.com",
      "first_name": "Thomas",
      "last_name": "Miller",
      "payer_id": "PUP87RBJV8HPU",
      "shipping_address": {
        "line1": "4th Floor, One Lagoon Drive",
        "line2": "Unit #34",
        "city": "Redwood City",
        "state": "CA",
        "postal_code": "94065",
        "country_code": "US",
        "phone": "011862212345678",
        "recipient_name": "Thomas Miller"
      }
    }
  },
  "transactions": [
    {
      "amount": {
        "total": "41.15",
        "currency": "USD",
        "details": {
          "subtotal": "30.00",
          "tax": "0.15",
          "shipping": "11.00"
        }
      },
      "description": "The payment transaction description.",
      "item_list": {
        "items": [
          {
            "name": "hat",
            "sku": "1",
            "price": "3.00",
            "currency": "USD",
            "quantity": "5"
          },
          {
            "name": "handbag",
            "sku": "product34",
            "price": "15.00",
            "currency": "USD",
            "quantity": "1"
          }
        ],
        "shipping_address": {
          "recipient_name": "Thomas Miller",
          "line1": "4th Floor, One Lagoon Drive",
          "line2": "Unit #34",
          "city": "Redwood City",
          "state": "CA",
          "phone": "011862212345678",
          "postal_code": "94065",
          "country_code": "US"
        }
      },
      "related_resources": [
        {
          "order": {
            "id": "O-3SP845109F051535C",
            "create_time": "2017-07-01T16:56:58Z",
            "update_time": "2017-07-01T17:05:41Z",
            "state": "pending",
            "amount": {
              "total": "41.15",
              "currency": "USD"
            },
            "parent_payment": "PAY-9N9834337A9191208KOZOQWI",
            "links": [
              {
                "href": "https://api.sandbox.paypal.com/v1/payments/orders/O-3SP845109F051535C",
                "rel": "self",
                "method": "GET"
              },
              {
                "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-9N9834337A9191208KOZOQWI",
                "rel": "parent_payment",
                "method": "GET"
              },
              {
                "href": "https://api.sandbox.paypal.com/v1/payments/orders/O-3SP845109F051535C/void",
                "rel": "void",
                "method": "POST"
              },
              {
                "href": "https://api.sandbox.paypal.com/v1/payments/orders/O-3SP845109F051535C/authorize",
                "rel": "authorization",
                "method": "POST"
              },
              {
                "href": "https://api.sandbox.paypal.com/v1/payments/orders/O-3SP845109F051535C/capture",
                "rel": "capture",
                "method": "POST"
              }
            ]
          }
        }
      ]
    }
  ],
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-9N9834337A9191208KOZOQWI",
      "rel": "self",
      "method": "GET"
    }
  ]
}

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

Authorize 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 an order payment, 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.

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/orders/O-0NR488530V5211123/authorize \
  -H 'Content-Type:application/json' \
  -H 'Authorization: Bearer Access-Token' \
  -d '{
  "amount":
  {
    "total": "7.00",
    "currency": "USD"
  }
}'

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

{
  "status": "OK",
  "result":
  {
    "id": "0PG032325D352531H",
    "create_time": "2017-06-28T07:38:10Z",
    "update_time": "2017-06-28T07:38:12Z",
    "state": "Pending",
    "amount":
    {
      "total": "41.15",
      "currency": "USD"
    },
    "parent_payment": "O-0NR488530V5211123",
    "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/orders/O-0NR488530V5211123",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/authorization/0PG032325D352531H",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/authorization/0PG032325D352531H/capture",
      "rel": "capture",
      "method": "POST"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-0AY778532K612520BKOXHAKY",
      "rel": "parent_payment",
      "method": "GET"
    }]
  }
}

Next, capture funds for an authorized order payment.

Capture order

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

Note: For a partial capture, you can provide a lower amount than the total payment. Additionally, set is_final_capture to true to explicitly indicate that the capture is the final capture, which completes the transaction and prevents future captures.

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/orders/O-3SP845109F051535C/capture \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "amount": {
  "currency": "USD",
  "total": "4.54"
  },
  "is_final_capture": true
}'

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

{
  "id": "51366113MA710110S",
  "create_time": "2017-07-01T17:13:45Z",
  "update_time": "2017-07-01T17:13:47Z",
  "amount": {
    "total": "4.54",
    "currency": "USD"
  },
  "is_final_capture": true,
  "state": "completed",
  "parent_payment": "PAY-9N9834337A9191208KOZOQWI",
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/capture/51366113MA710110S",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/capture/51366113MA710110S/refund",
      "rel": "refund",
      "method": "POST"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/orders/O-3SP845109F051535C",
      "rel": "order",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-9N9834337A9191208KOZOQWI",
      "rel": "parent_payment",
      "method": "GET"
    }
  ]
}

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.

Additional information