partners

Create an Order

Important: PayPal for Partners is a limited-release solution at this time. It is available to select partners for approved use cases. For more information, reach out to your PayPal account manager.

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

Integration steps

  1. Get an access token
  2. Create an order

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

To create an order, include the Authorization, PayPal-Request-Id, and Content-Type headers in your request.

This sample shows a multi-seller cart with a partner fee.

curl -v -X POST https://api.sandbox.paypal.com/v1/checkout/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <var>Access-Token</var>" \
  -H "PayPal-Partner-Attribution-Id: EXAMPLE_MP" \
  -d '{
  "purchase_units": [
  {
    "reference_id": "store_mobile_world_order_1234",
    "description": "Mobile World Store order-1234",
    "amount": {
      "currency": "USD",
      "details": {
        "subtotal": "1.09",
        "shipping": "0.02",
        "tax": "0.33"
      },
      "total": "1.44"
    },
    "payee": {
      "email": "seller@example.com"
    },
    "items": [
    {
      "name": "NeoPhone",
      "sku": "sku03",
      "price": "0.54",
      "currency": "USD",
      "quantity": "1"
    },
    {
      "name": "Fitness Watch",
      "sku": "sku04",
      "price": "0.55",
      "currency": "USD",
      "quantity": "1"
    }],
    "shipping_address": {
      "line1": "2211 N First Street",
      "line2": "Building 17",
      "city": "San Jose",
      "country_code": "US",
      "postal_code": "95131",
      "state": "CA",
      "phone": "(123) 456-7890"
    },
    "shipping_method": "United Postal Service",
    "partner_fee_details": {
      "receiver": {
        "email": "partner@example.com"
      },
      "amount": {
        "value": "0.01",
        "currency": "USD"
      }
    },
    "payment_linked_group": 1,
    "custom": "custom_value_2388",
    "invoice_number": "invoice_number_2388",
    "payment_descriptor": "Payment Mobile World"
  }],
  "redirect_urls": {
    "return_url": "https://example.com/return",
    "cancel_url": "https://example.com/cancel"
  }
}'

Response sample

A successful create order request returns an HTTP 201 status code with a response body that includes the PayPal-generated order ID to pass in subsequent calls.

{
  "id": "5O190127TN364715T",
  "gross_total_amount": {
    "value": "1.44",
    "currency": "USD"
  },
  "purchase_units": [
  {
    "reference_id": "store_mobile_world_order_1234",
    "description": "Mobile World Store order-1234",
    "amount": {
      "currency": "USD",
      "details": {
        "subtotal": "1.09",
        "shipping": "0.02",
        "tax": "0.33"
      },
      "total": "1.44"
    },
    "payee": {
      "email": "seller@example.com"
    },
    "items": [
      {
        "name": "NeoPhone",
        "sku": "sku03",
        "price": "0.54",
        "currency": "USD",
        "quantity": "1"
      },
      {
        "name": "Fitness Watch",
        "sku": "sku04",
        "price": "0.55",
        "currency": "USD",
        "quantity": "1"
      }
    ],
    "shipping_address": {
      "recipient_name": "John Doe",
      "default_address": false,
      "preferred_address": false,
      "primary_address": false,
      "disable_for_transaction": false,
      "line1": "2211 N First Street",
      "line2": "Building 17",
      "city": "San Jose",
      "country_code": "US",
      "postal_code": "95131",
      "state": "CA",
      "phone": "(123) 456-7890"
    },
    "shipping_method": "United Postal Service",
    "partner_fee_details": {
      "receiver": {
        "email": "partner@example.com"
      },
      "amount": {
        "value": "0.01",
        "currency": "USD"
      }
    },
    "payment_linked_group": 1,
    "custom": "custom_value_2388",
    "invoice_number": "invoice_number_2388",
    "payment_descriptor": "Payment Mobile World",
    "status": "CAPTURED"
  }],
  "redirect_urls": {
    "return_url": "https://example.com/return",
    "cancel_url": "https://example.com/cancel"
  },
  "create_time": "2017-04-26T21:18:49Z",
  "links": [
  {
    "href": "https://api.paypal.com/v1/checkout/orders/8RU61172JS455403V",
    "rel": "self",
    "method": "GET"
  },
  {
    "href": "https://www.paypal.com/webapps/hermes?token=8RU61172JS455403V",
    "rel": "approval_url",
    "method": "GET"
  },
  {
    "href": "https://api.paypal.com/v1/checkout/orders/8RU61172JS455403V",
    "rel": "cancel",
    "method": "DELETE"
  }],
  "status": "CREATED"
}

Next

Payout order

Feedback