Create an Order

Create an order and execute a payment inside your checkout flow.

Integration steps

  1. Get an access token
  2. Create an order
  3. Get order details

Get an access token

To get an access token, pass your OAuth credentials in a get access token call.

Request Sample

curl -v https://api.sandbox.paypal.com/v1/oauth2/token \
  -H "Accept: application/json" \
  -H "Accept-Language: en_US" \
  -u "client_id:secret" \
  -d "grant_type=client_credentials"

Response Sample

In response, the PayPal authorization server issues an access token.

{
  "scope": "https://uri.paypal.com/services/subscriptions https://api.paypal.com/v1/payments/.* https://api.paypal.com/v1/vault/credit-card https://uri.paypal.com/services/applications/webhooks openid https://uri.paypal.com/payments/payouts https://api.paypal.com/v1/vault/credit-card/.*",
  "nonce": "2017-06-08T18:30:28ZCl54Q_OlDqP6-4D03sDT8wRiHjKrYlb5EH7Di0gRrds",
  "access_token": "Access-Token",
  "token_type": "Bearer",
  "app_id": "APP-80W284485P519543T",
  "expires_in": 32398
}

Create an order

In the POST v2/checkout/orders/ call, include the Authorization, Accept, PayPal-Request-Id, and Content-Type headers.

Set these parameters to create an order:

Parameter Type Required Description

intent

string

Required

The intent to either capture payment immediately or authorize a payment for an order after order creation. The allowed values are:

  • CAPTURE. The merchant intends to capture payment immediately after the customer makes a payment.
  • AUTHORIZE. The merchant intends to authorize a payment and place funds on hold after the customer makes a payment. Authorized payments are guaranteed for up to three days but are available to capture for up to 29 days. After the three-day honor period, the original authorized payment expires and you must re-authorize the payment. You must make a separate request to capture payments on demand.

payer

object

Optional

The customer who approves and pays for the order. The customer is also known as the payer.

purchase_units

array (contains the purchase_unit_request object)

Required

An array of purchase units. At present only 1 purchase_unit is supported. Each purchase unit establishes a contract between a payer and the payee. Each purchase unit represents either a full or partial order that the payer intends to purchase from the payee.

application_context

object

Optional

Customize the payer experience during the approval process for the payment with PayPal.

When you create an order, its status is created. You pass the order ID that the create order call returns in subsequent calls.

Request

Example create order request:

curl -v -X POST https://api.sandbox.paypal.com/v2/checkout/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token" \
  -H "PayPal-Partner-Attribution-Id: EXAMPLE_MP" \
  -d '{
  "intent": "CAPTURE",
  "purchase_units": [{
    "amount": {
      "currency_code": "USD",
      "value": "100.00"
    },
    "payee": {
      "email_address": "seller@example.com"
    },
    "payment_instruction": {
      "disbursement_mode": "INSTANT",
      "platform_fees": [{
        "amount": {
          "currency_code": "USD",
          "value": "25.00"
        },
        "payee": {
          "email_address": "seller@example.com"
        }
      }]
    }
  }]
}'

Response

A successful request returns the HTTP 201 Created status code and a JSON response body that includes the PayPal-generated order ID.

{
  "id": "5O190127TN364715T",
  "status": "CREATED",
  "links": [
    {
      "href": "https://api.paypal.com/v2/checkout/orders/5O190127TN364715T",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.paypal.com/checkoutnow?token=5O190127TN364715T",
      "rel": "approve",
      "method": "GET"
    },
    {
      "href": "https://api.paypal.com/v2/checkout/orders/5O190127TN364715T/capture",
      "rel": "capture",
      "method": "POST"
    }
  ]
}

Get order details

To get order details, pass the order ID as a path parameter in a GET /v2/checkout/orders/{order_id} call.

Sample request

curl -v -k -X GET 'https://api.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token"

Sample response

A successful request returns the HTTP 200 OK status code and a JSON response body that shows order details:

{
  "id": "5O190127TN364715T",
  "status": "COMPLETED",
  "intent": "CAPTURE",
  "gross_amount": {
    "currency_code": "USD",
    "value": "100.00"
  },
  "payer": {
    "name": {
      "given_name": "John",
      "surname": "Doe"
    },
    "email_address": "customer@example.com",
    "payer_id": "QYR5Z8XDVJNXQ",
    "phone": {
      "phone_number": {
        "national_number": "8882211161"
      }
    },
    "address": {
      "address_line_1": "2211 N First Street",
      "address_line_2": "Building 17",
      "admin_area_2": "San Jose",
      "admin_area_1": "CA",
      "postal_code": "95131",
      "country_code": "US"
    }
  },
  "purchase_units": [
    {
      "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
      "amount": {
        "currency_code": "USD",
        "value": "100.00"
      },
      "payee": {
        "email_address": "merchant@example.com"
      },
      "payment_instruction": {
        "disbursement_mode": "DELAYED",
        "platform_fees": [
          {
            "amount": {
              "currency_code": "USD",
              "value": "25.00"
            },
            "payee": {
              "email_address": "fee@example.com"
            }
          }
        ]
      },
      "shipping": {
        "method": "United States Postal Service",
        "name": {
          "full_name": "John Williams"
        },
        "address": {
          "address_line_1": "2211 N First Street",
          "address_line_2": "Building 17",
          "admin_area_2": "San Jose",
          "admin_area_1": "CA",
          "postal_code": "95131",
          "country_code": "US"
        }
      },
      "payments": {
        "captures": [
          {
            "id": "3C679366HH908993F",
            "status": "COMPLETED",
            "amount": {
              "currency_code": "USD",
              "value": "100.00"
            },
            "seller_protection": {
              "status": "ELIGIBLE",
              "dispute_categories": [
                "ITEM_NOT_RECEIVED",
                "UNAUTHORIZED_TRANSACTION"
              ]
            },
            "final_capture": true,
            "seller_receivable_breakdown": {
              "gross_amount": {
                "currency_code": "USD",
                "value": "100.00"
              },
              "paypal_fee": {
                "currency_code": "USD",
                "value": "3.00"
              },
              "platform_fees": [
                {
                  "amount": {
                    "currency_code": "USD",
                    "value": "25.00"
                  },
                  "payee": {
                    "email_address": "fee@example.com"
                  }
                }
              ],
              "net_amount": {
                "currency_code": "USD",
                "value": "72.00"
              }
            },
            "create_time": "2018-04-01T21:20:49Z",
            "update_time": "2018-04-01T21:20:49Z",
            "links": [
              {
                "href": "https://api.paypal.com/v2/payments/captures/3C679366HH908993F",
                "rel": "self",
                "method": "GET"
              },
              {
                "href": "https://api.paypal.com/v2/payments/captures/3C679366HH908993F/refund",
                "rel": "refund",
                "method": "POST"
              }
            ]
          }
        ]
      }
    }
  ],
  "create_time": "2018-04-01T21:18:49Z",
  "update_time": "2018-04-01T21:20:49Z",
  "links": [
    {
      "href": "https://api.paypal.com/v2/checkout/orders/5O190127TN364715T",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Next

Payout order

Feedback