Orders API

API Version

Partners can use the Orders API to create, show details for, authorize, and capture payment for orders.

Orders API integration note: The PayPal Commerce Platform is a limited-release solution aimed at partners, crowd funding, and multi-party commerce platforms. To use Orders API for Partners, see PayPal Commerce Platform for Platforms. v1 of the API will be deprecated soon. A new version is available at Orders API v2.

Orders (resource group)

Use the /checkout/orders resource to create, cancel, and show details for orders.

Create order

POST/v1/checkout/orders

Creates an order.

Header parameters

PayPal-Partner-Attribution-Id
string

Request body

purchase_units
array (contains the purchase_unit object)
required
An array of purchase units. Each purchase unit establishes a contract between a customer and merchant.
redirect_urls
object
required
The redirect URLs. Required only for the PayPal payment method. The supported settings are return and cancel URLs.
application_context
object
Customizes the payer experience during the approval process for the payment with PayPal.
Note: The PayPal Commerce Platform might configure brand_name and shipping_preference during partner account setup, which overrides the request values.
create_time
string
The date and time when the resource was created, in Internet date and time format.
gross_total_amount
object
The currency and amount of the PayPal-computed total of amounts in all purchase units.
id
string
The ID of the order.
intent
enum
The intent.
The possible values are:
- SALE. A sale.
- AUTHORIZE. An authorization.
links
array (contains the link_description object)
An array of request-related HATEOAS links. To complete the buyer approval, use the approval_url link with the GET method and do not use the link that shows the REDIRECT method.
metadata
object
The name-and-value pairs that contain external data, such as user, user feedback, score, and so on.
payment_details
object
The payment details for the order.
status
enum
The status of the order. After the customer approves the order, the status is APPROVED. After the payment is made for the order and the order completes, the status is COMPLETED.
The possible values are:
- CREATED. The POST /v1/checkout/orders call succeeded and the order was created.
- APPROVED. The customer approved the order.
- COMPLETED. The POST /v1/checkout/orders/{order_id}/pay call succeeded and the order was paid and is complete.
- FAILED. The order failed.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.

Sample Request

curl -v -X POST https://api-m.sandbox.paypal.com/v1/checkout/orders \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-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

A successful request returns the HTTP 200 OK status code and a JSON response body that includes the PayPal-generated order ID, an array of purchase unit objects, payment details, customer information, metadata, and order status.

application_context
object
Customizes the payer experience during the approval process for the payment with PayPal.
Note: The PayPal Commerce Platform might configure brand_name and shipping_preference during partner account setup, which overrides the request values.
create_time
string
The date and time when the resource was created, in Internet date and time format.
Read only.
gross_total_amount
object
The currency and amount of the PayPal-computed total of amounts in all purchase units.
id
string
The ID of the order.
Read only.
intent
enum
The intent.
The possible values are:
- SALE. A sale.
- AUTHORIZE. An authorization.
links
array (contains the link_description object)
An array of request-related HATEOAS links. To complete the buyer approval, use the approval_url link with the GET method and do not use the link that shows the REDIRECT method.
Read only.
metadata
object
The name-and-value pairs that contain external data, such as user, user feedback, score, and so on.
payment_details
object
The payment details for the order.
purchase_units
array (contains the purchase_unit object)
An array of purchase units. Each purchase unit establishes a contract between a customer and merchant.
redirect_urls
object
The redirect URLs. Required only for the PayPal payment method. The supported settings are return and cancel URLs.
status
enum
The status of the order. After the customer approves the order, the status is APPROVED. After the payment is made for the order and the order completes, the status is COMPLETED.
The possible values are:
- CREATED. The POST /v1/checkout/orders call succeeded and the order was created.
- APPROVED. The customer approved the order.
- COMPLETED. The POST /v1/checkout/orders/{order_id}/pay call succeeded and the order was paid and is complete.
- FAILED. The order failed.
Read only.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
Read only.

Sample Response

{
  "id": "8RU61172JS455403V",
  "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-m.paypal.com/v1/checkout/orders/8RU61172JS455403V",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.paypal.com/webapps/hermes?token=8RU61172JS455403V",
      "rel": "approval_url",
      "method": "GET"
    },
    {
      "href": "https://api-m.paypal.com/v1/checkout/orders/8RU61172JS455403V",
      "rel": "cancel",
      "method": "DELETE"
    }
  ],
  "status": "CREATED"
}

Cancel order

DELETE/v1/checkout/orders/{order_id}

Cancels an order, by ID, and deletes the order. To call this method, the order status must be CREATED or APPROVED.

Path parameters

order_id
string
required
The ID of the order to cancel.

Sample Request

curl -v -X DELETE https://api-m.sandbox.paypal.com/v1/checkout/orders/8SC68793353299025 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful request returns the HTTP 204 No Content status code with no JSON response body. If the order is already paid, the order cannot be canceled and the request returns the HTTP 422 Unprocessable Entity status code with the message, This order is in progress.

Sample Response

204 No Content

Show order details

GET/v1/checkout/orders/{order_id}

Shows details for an order, by ID.

Path parameters

order_id
string
required
The ID of the order for which to show details.

Sample Request

curl -v -X GET https://api-m.sandbox.paypal.com/v1/checkout/orders/8SC68793353299025 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

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

application_context
object
Customizes the payer experience during the approval process for the payment with PayPal.
Note: The PayPal Commerce Platform might configure brand_name and shipping_preference during partner account setup, which overrides the request values.
create_time
string
The date and time when the resource was created, in Internet date and time format.
Read only.
gross_total_amount
object
The currency and amount of the PayPal-computed total of amounts in all purchase units.
id
string
The ID of the order.
Read only.
intent
enum
The intent.
The possible values are:
- SALE. A sale.
- AUTHORIZE. An authorization.
links
array (contains the link_description object)
An array of request-related HATEOAS links. To complete the buyer approval, use the approval_url link with the GET method and do not use the link that shows the REDIRECT method.
Read only.
metadata
object
The name-and-value pairs that contain external data, such as user, user feedback, score, and so on.
payment_details
object
The payment details for the order.
purchase_units
array (contains the purchase_unit object)
An array of purchase units. Each purchase unit establishes a contract between a customer and merchant.
redirect_urls
object
The redirect URLs. Required only for the PayPal payment method. The supported settings are return and cancel URLs.
status
enum
The status of the order. After the customer approves the order, the status is APPROVED. After the payment is made for the order and the order completes, the status is COMPLETED.
The possible values are:
- CREATED. The POST /v1/checkout/orders call succeeded and the order was created.
- APPROVED. The customer approved the order.
- COMPLETED. The POST /v1/checkout/orders/{order_id}/pay call succeeded and the order was paid and is complete.
- FAILED. The order failed.
Read only.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
Read only.

Sample Response

{
  "id": "8SC68793353299025",
  "status": "CREATED",
  "gross_total_amount": {
    "value": "1.44",
    "currency": "USD"
  },
  "application_context": {},
  "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",
      "status": "NOT_PROCESSED"
    }
  ],
  "redirect_urls": {
    "return_url": "https://example.com/return",
    "cancel_url": "https://example.com/cancel"
  },
  "links": [
    {
      "href": "https://api-m.paypal.com/v1/checkout/orders/8SC68793353299025",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://www.paypal.com/checkoutnow?token=8SC68793353299025",
      "rel": "approval_url",
      "method": "REDIRECT"
    }
  ],
  "create_time": "2018-09-21T17:22:45Z"
}

Orders payment actions (resource group)

Use the /checkout/orders resource with the /pay action to pay for an order. When you create an order, the response includes an approval URL. Redirect the customer to this approval URL.

Pay for order

POST/v1/checkout/orders/{order_id}/pay

Initiates a PayPal payment that a buyer has approved.

Note: For Partner use cases, use the disbursement_mode to indicate whether to disburse funds to the seller and partner accounts immediately or later. If you delay disbursement, you must call disburse funds to disburse funds to the merchant and partner.

Header parameters

PayPal-Partner-Attribution-Id
string
PayPal-Request-Id
string
The server stores keys forever.

Path parameters

order_id
string
required
The ID of the order for which to execute a payment.

Request body

disbursement_mode
enum
required
Indicates whether to disburse money instantly or later.
The possible values are:
- INSTANT. Money is disbursed instantly.
- DELAYED. Money will be disbursed later.
payer
object
The source of the funds for this payment. Either a PayPal account or a credit card.

Sample Request

curl -v -X POST https://api-m.sandbox.paypal.com/v1/checkout/orders/8SC68793353299025/pay \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

Response

A successful request returns the HTTP 202 Accepted status code and a JSON response body that shows order and payment details.

Note: Applies to existing asynchronous payment processing integrations.

create_time
string
The date and time when the resource was created, in Internet date and time format.
Read only.
intent
enum
The intent.
The possible values are:
- SALE. A sale.
- AUTHORIZE. An authorization.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.
order_id
string
The ID of the order.
Read only.
payer_info
object
The payer information.
purchase_units
array (contains the purchase_unit object)
An array of purchase units. Each purchase unit establishes a contract between a customer and merchant.
status
enum
The status of the order.
The possible values are:
- APPROVED. The order is approved.
- CANCELED. The order is canceled.
- COMPLETED. The order is completed.
- CREATED. The order is created.
- EXPIRED. The order is expired.
- FAILED. The order FAILED.
- IN_PROGRESS. The order is in progress.
- PARTIALLY_COMPLETED. The order is partially completed.
- SUBMITTED. The order was submitted.
Read only.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
Read only.

Sample Response

{
  "order_id": "76T08342AW176740Y",
  "status": "APPROVED",
  "payer_info": {
    "email": "buyer@example.com",
    "first_name": "Robert",
    "last_name": "Lesley",
    "payer_id": "HPQAUP5WC3J8U",
    "phone": "7028530329",
    "country_code": "US",
    "shipping_address": {
      "recipient_name": "Robert Lesley",
      "line1": "2211 N First Street",
      "line2": "Building 17",
      "city": "San Jose",
      "country_code": "US",
      "postal_code": "95131",
      "state": "CA"
    }
  },
  "create_time": "2018-09-21T17:33:18Z",
  "update_time": "2018-09-21T17:33:18Z",
  "links": [
    {
      "href": "https://api-m.paypal.com/v1/checkout/orders/76T08342AW176740Y",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Common object definitions

address

country_code
string
required
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
Minimum length: 2.
Maximum length: 2.
Pattern: ^([A-Z]{2}|C2)$.
line1
string
required
The first line of the address. For example, number, street, and so on.
city
string
The city name.
line2
string
The second line of the address. For example, suite or apartment number.
normalization_status
enum
The address normalization status. Returned only for payers from Brazil.
Read only.
Possible values: UNKNOWN,UNNORMALIZED_USER_PREFERRED,NORMALIZED,UNNORMALIZED.
phone
string
The phone number, in E.123 format. Maximum length is 50 characters.
postal_code
string
The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.
state
string
The code for a US state or the equivalent for other countries. Required for transactions if the address is in one of these countries: Argentina, Brazil, Canada, India, Italy, Japan, Mexico, Thailand, or United States. Maximum length is 40 single-byte characters.
type
string
The type of address. For example, HOME_OR_WORK, GIFT, and so on.

amount

currency
string
required
The three-character ISO-4217 currency code. PayPal does not support all currencies.
total
string
required
The total amount charged to the payee by the payer. For refunds, represents the amount that the payee refunds to the original payer. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
details
object
The additional details about the payment amount.

application_context

brand_name
string
The label that overrides the business name in the PayPal account on the PayPal pages.
Maximum length: 127.
landing_page
string
The type of landing page to display on the PayPal site for user checkout. To use the non-PayPal account landing page, set to Billing. To use the PayPal account login landing page, set to Login.
locale
string
The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code.
Minimum length: 2.
Maximum length: 10.
Pattern: ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))?$.
shipping_preference
enum
The shipping preferences.
The possible values are:
- NO_SHIPPING. Redact shipping address fields from the PayPal pages. Recommended for digital goods.
- GET_FROM_FILE. Use the buyer-selected shipping address.
- SET_PROVIDED_ADDRESS. Use the merchant-provided address. Buyer cannot change the address on the PayPal pages. If the merchant does not pass an address, the buyer can choose the address on PayPal pages.
supplementary_data
array (contains the name_value_pair object)
An array of name-and-value pairs that contain supplementary data required by PayPal for transaction processing.

`user_action`

string

Defines whether to present the customer with a Continue or Pay Now checkout flow. To present buyers with the Pay Now checkout flow, set useraction=commit. Default is the Continue checkout flow.

Checkout flow	Choose when	Description
Continue	You do not know the final payment amount when you initiate the checkout flow.	The default flow. Redirects the customer to the PayPal payment page, which shows the Continue button. When the customer clicks Continue, the customer can change the payment amount.
Pay Now	You know the final payment amount when you initiate the checkout flow.	Set `user_action=commit`. Redirects the customer to the PayPal payment page, which shows the Pay Now button. When the customer clicks Pay Now, the payment is processed immediately.

capture

amount
object
The amount to capture. Default is the authorization amount. If that amount is the same as the authorized amount, the authorization state changes to CAPTURED. Otherwise, the authorization state changes to PARTIALLY_CAPTURED. To indicate that this capture is the final capture, set is_final_capture to true.
id
string
The ID of the capture transaction.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.
reason_code
enum
A reason code that indicates the reason for the transaction state of PENDING or REVERSED.
The possible values are:
- CHARGEBACK. The transaction state is PENDING or REVERSED due to a chargeback.
- GUARANTEE. The transaction state is PENDING or REVERSED due to a guarantee.
- BUYER_COMPLAINT. The transaction state is PENDING or REVERSED due to a buyer complaint.
- REFUND. The transaction state is PENDING or REVERSED due to a refund.
- UNCONFIRMED_SHIPPING_ADDRESS. The transaction state is PENDING or REVERSED due to an unconfirmed shipping address.
- ECHECK. The transaction state is PENDING or REVERSED due to an e-check.
- INTERNATIONAL_WITHDRAWAL. The transaction state is PENDING or REVERSED due to an international withdrawal.
- RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION. The transaction state is PENDING or REVERSED due to a receiving preference that mandates manual action.
- PAYMENT_REVIEW. The transaction state is PENDING or REVERSED due to a payment review.
- REGULATORY_REVIEW. The transaction state is PENDING or REVERSED due to a regulatory review.
- UNILATERAL. The transaction state is PENDING or REVERSED due to a unilateral reason.
- VERIFICATION_REQUIRED. The transaction state is PENDING or REVERSED because verification is required.
- DELAYED_DISBURSEMENT. The transaction state is PENDING or REVERSED due to a delayed disbursement.
Read only.
status
enum
The status of the capture transaction.
The possible values are:
- PENDING. The purchase unit status is CAPTURED and the capture status is pending.
- COMPLETED. The purchase unit status is CAPTURED and the payment was captured successfully.
- REFUNDED. The purchase unit status is CAPTURED and the dispute decision was in the customer's favor. A full refund for the captured payment was made successfully to the customer.
- PARTIALLY_REFUNDED. The purchase unit status is CAPTURED and the dispute decision was in the customer's favor. A partial refund for the captured payment was made successfully to the customer.
- DENIED. The purchase unit status is CAPTURED and the capture was denied.
Read only.
transaction_fee
object
The currency and amount of the transaction fee.

country_code

country_code
string
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
Minimum length: 2.
Maximum length: 2.
Pattern: ^([A-Z]{2}|C2)$.

credit_card

expire_month
integer
required
The expiration month with no leading zero. Value is from 1 to 12.
expire_year
integer
required
The four-digit expiration year.
number
string
required
The credit card number. Value is numeric characters only with no spaces or punctuation. Must conform to the modulo and length required by each credit card type. Redacted in responses.
type
string
required
The credit card type. Value is visa, mastercard, discover, or amex. Do not use these lowercase values for display.
billing_address
object
The billing address for this card.
cvv2
string
The three- to four-digit card validation code.
first_name
string
The card holder's first name.
last_name
string
The card holder's last name.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

credit_card_token

credit_card_id
string
required
The ID of credit card that is stored in the PayPal vault.
expire_month
integer
The expiration month with no leading zero. Value is from 1 to 12.
Read only.
expire_year
integer
The four-digit expiration year.
Read only.
last4
string
The last four digits of the stored credit card number.
Read only.
payer_id
string
A unique ID that you can assign and track when you store a credit card in the vault or use a vaulted credit card. This ID can help to avoid unintentional use or misuse of credit cards and can be any value, such as a UUID, user name, or email address. Required when you use a vaulted credit card and if a payer_id was originally provided when you vaulted the credit card.
type
string
The credit card type. Value is visa, mastercard, discover, or amex. Do not use these lowercase values for display.
Read only.

currency

currency
string
required
The three-character ISO-4217 currency code. PayPal does not support all currencies.
value
string
required
The amount. Includes the specified number of digits after decimal separator for the ISO-4217 currency code.

currency_code

currency_code
string
The three-character ISO-4217 currency code that identifies the currency.
Minimum length: 3.
Maximum length: 3.

currency_conversion

from_amount
string
required
The from amount, which is the pre-currency conversion value.
Read only.
Minimum value: 1.
from_currency
string
required
The three-character ISO-4217 currency code of the currency from which to convert the from amount.
Read only.
to_amount
string
required
The to amount, which is the post-currency conversion value.
Read only.
to_currency
string
required
The three-character ISO-4217 currency code of the currency into which to convert the from amount.
Read only.
conversion_date
string
The date and time when the conversion rate becomes no longer valid, in Internet date and time format.
Read only.
conversion_type
enum
The conversion type to apply.
Possible values: PAYPAL,VENDOR.
conversion_type_changeable
boolean
Indicates whether the payer can change the conversion type.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.
spread
string
The rate, as a percentage, that PayPal charges above the foreign exchange rate provided by PayPal’s financial partners.
Read only.
Maximum value: 100.

details

gift_wrap
string
The gift wrap fee. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
handling_fee
string
The handling fee. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
Supported for the PayPal payment method only.
insurance
string
The insurance fee. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
Supported only for the PayPal payment method.
shipping
string
The shipping fee. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
shipping_discount
string
The shipping fee discount. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
Supported for the PayPal payment method only.
subtotal
string
The subtotal amount for the items. If the request includes line items, this property is required. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
tax
string
The tax. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.

display_phone

country_code
string
The two-character IS0-3166-1 country code of the payee's country.
number
string
The in-country phone number, in E.164 numbering plan format.

error

debug_id
string
required
The PayPal internal ID that is used for correlation purposes.
message
string
required
The message that describes the error.
name
string
required
The human-readable, unique name of the error.
details
array (contains the error_details object)
An array of additional details about the error.
information_link
string
The information link, or URI, that shows detailed information about this error for the developer.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

error_details

issue
string
required
The unique and fine-grained application-level error code.
description
string
The human-readable description for an issue. The description MAY change over the lifetime of an API, so clients MUST NOT depend on this value.
field
string
The field that caused the error. If the field is in the body, set this value to the JSON pointer to that field. Required for client-side errors.
location
string
The location of the field that caused the error. Value is body, path, or query.
value
string
The value of the field that caused the error.

funding_detail

Hide deprecated

clearing_time
string
The date and time when the funds are expected to clear, in Internet date and time format.
Read only.
payment_debit_date
string
The date and time when the funds will be debited from the payer's account, in Internet date and time format.
Read only.
payment_hold_date
string
Deprecated. The date and time when the payment will no longer be held, in Internet date and time format. Instead, use the payment_debit_date.
Read only.
processing_type
enum
The processing type of the payment card.
Read only.
Possible values: CUP_SECURE,PINLESS_DEBIT.

funding_instrument

Hide deprecated

credit_card
object
Deprecated. The credit card details. You can use this instrument to fund a payment. Use a payment card instead.
credit_card_token
object
The tokenized credit card details. You can use this instrument to fund a payment.

funding_source

Hide deprecated

credit_card
object
Deprecated. The credit card details. You can use this instrument to fund a payment. Use a payment card instead.
credit_card_token
object
The tokenized credit card details. You can use this instrument to fund a payment.

amount
object
required
The amount and currency of the total to pull from the funding source.
funding_instrument_type
string
required
The instrument type for this funding source.
funding_mode
string
required
The funding mode of the funding source.
additional_text
string
Additional text for the funding source.
funding_detail
object
The additional details for the funding source.
funding_selection_preference
string
The preferred way to select this funding source.
legal_text
string
The localized legal text for the funding source.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
negative_balance_amount
object
The additional amount to pull from the source to recover a negative balance on the buyer's account that is owed to PayPal.
soft_descriptor
string
The soft descriptor for charging this funding source.
Maximum length: 22.
terms
string
The URL to legal terms for the funding source.

installment_info

installment_options
array (contains the installment_option object)
required
An array of installment options and the cost associated with each one.
installment_id
string
The installment ID.
Read only.
issuer
string
The credit card issuer.
Read only.
network
enum
The credit card network.
Read only.
Possible values: VISA,MASTERCARD.

installment_option

monthly_payment
object
required
The amount and currency of the monthly payment.
term
integer
required
The number of installments.
discount_amount
object
The amount and currency of the discount applied to the payment, if any.
discount_percentage
string
The discount percentage applied to the payment, if any.
Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

instrument_attribute

type
enum
The type of metadata to be return for Funding instrument.
The possible values are:
- PAYER_DISCLAIMER. payer disclaimer regarding sharing instrument detail to merchant.
- COBRAND_CARD_LABEL. Brand Label Info for instrument.
Read only.
value
string
Value of metadata for given type.
Read only.
Minimum length: 1.
Maximum length: 256.

item

currency
string
required
The three-character ISO-4217 currency code.
name
string
required
The item name. Maximum length is 127 characters.
price
string
required
The item cost. Supports two decimal places.
Maximum length: 10.
Pattern: ^[0-9]{0,10}(\.[0-9]{0,2})?$.
quantity
string
required
The item quantity. Must be a whole number.
Maximum length: 10.
Pattern: ^[0-9]{0,10}$.
description
string
The item description. Supported only for the PayPal payment method.
Maximum length: 127.
sku
string
The stock keeping unit (SKU) for the item.
Maximum length: 127.
tax
string
The item tax. Supported only for the PayPal payment method.
url
string
The URL to item information. Available to the payer in the transaction history.

language

language
string
The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code.
Minimum length: 2.
Maximum length: 10.
Pattern: ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))?$.

link_description

href
string
required
The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the $, (, and ) characters. The href is the key HATEOAS component that links a completed call with a subsequent call.
rel
string
required
The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
method
enum
The HTTP method required to make the related call.
Possible values: GET,POST,PUT,DELETE,HEAD,CONNECT,OPTIONS,PATCH.

metadata

supplementary_data
array (contains the name_value_pair object)
An array of name-and-value pairs that contain data required by PayPal for transaction processing.

money

currency_code
string
required
The three-character ISO-4217 currency code that identifies the currency.
Minimum length: 3.
Maximum length: 3.
value
string
required
The value, which might be:
- An integer for currencies like JPY that are not typically fractional.
- A decimal fraction for currencies like TND that are subdivided into thousandths.
For the required number of decimal places for a currency code, see Currency Codes.
Maximum length: 32.
Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

name_value_pair

name
string
required
The key for the name-and-value pair. You must correlate the value and name types.
value
string
required
The value for the name-and-value pair.

order

purchase_units
array (contains the purchase_unit object)
required
An array of purchase units. Each purchase unit establishes a contract between a customer and merchant.
redirect_urls
object
required
The redirect URLs. Required only for the PayPal payment method. The supported settings are return and cancel URLs.
application_context
object
Customizes the payer experience during the approval process for the payment with PayPal.
Note: The PayPal Commerce Platform might configure brand_name and shipping_preference during partner account setup, which overrides the request values.
create_time
string
The date and time when the resource was created, in Internet date and time format.
Read only.
gross_total_amount
object
The currency and amount of the PayPal-computed total of amounts in all purchase units.
id
string
The ID of the order.
Read only.
intent
enum
The intent.
The possible values are:
- SALE. A sale.
- AUTHORIZE. An authorization.
links
array (contains the link_description object)
An array of request-related HATEOAS links. To complete the buyer approval, use the approval_url link with the GET method and do not use the link that shows the REDIRECT method.
Read only.
metadata
object
The name-and-value pairs that contain external data, such as user, user feedback, score, and so on.
payment_details
object
The payment details for the order.
status
enum
The status of the order. After the customer approves the order, the status is APPROVED. After the payment is made for the order and the order completes, the status is COMPLETED.
The possible values are:
- CREATED. The POST /v1/checkout/orders call succeeded and the order was created.
- APPROVED. The customer approved the order.
- COMPLETED. The POST /v1/checkout/orders/{order_id}/pay call succeeded and the order was paid and is complete.
- FAILED. The order failed.
Read only.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
Read only.

partner_fee_details

amount
object
required
The amount and currency of the partner fee.
receiver
object
required
The partner who receives the partner fee.

pay_order_request

disbursement_mode
enum
required
Indicates whether to disburse money instantly or later.
The possible values are:
- INSTANT. Money is disbursed instantly.
- DELAYED. Money will be disbursed later.
payer
object
The source of the funds for this payment. Either a PayPal account or a credit card.

pay_order_response

create_time
string
The date and time when the resource was created, in Internet date and time format.
Read only.
intent
enum
The intent.
The possible values are:
- SALE. A sale.
- AUTHORIZE. An authorization.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.
order_id
string
The ID of the order.
Read only.
payer_info
object
The payer information.
purchase_units
array (contains the purchase_unit object)
An array of purchase units. Each purchase unit establishes a contract between a customer and merchant.
status
enum
The status of the order.
The possible values are:
- APPROVED. The order is approved.
- CANCELED. The order is canceled.
- COMPLETED. The order is completed.
- CREATED. The order is created.
- EXPIRED. The order is expired.
- FAILED. The order FAILED.
- IN_PROGRESS. The order is in progress.
- PARTIALLY_COMPLETED. The order is partially completed.
- SUBMITTED. The order was submitted.
Read only.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
Read only.

payee

email
string
The email address associated with the payee's PayPal account. For an intent of authorize or order, the email address must be associated with a confirmed PayPal business account. For an intent of sale, the email can either:
- Be associated with a confirmed PayPal personal or business account.
- Not be associated with a PayPal account.
merchant_id
string
The encrypted PayPal account ID for the payee.
payee_display_metadata
object
The display-only metadata for the payee.

payee_display_metadata

brand_name
string
The payer's business name.
display_phone
object
The payee's phone number.
email
string
The email address for the payer. Maximum length is 127 characters.

payer

funding_instruments
array (contains the funding_instrument object)
An array of a single funding instrument for the current payment. Valid only and required for the credit card payment method. The array must include either a credit_card or credit_card_token object. If the array contains more than one instrument, the payment is declined.
payer_info
object
The payer information.
payment_method
enum
The payment method. Value is PayPal Wallet payment, bank direct debit, or direct credit card.
Possible values: credit_card,paypal.
status
enum
The status of payer's PayPal account.
Read only.
Possible values: VERIFIED,UNVERIFIED.

payer_info

Hide deprecated

billing_address
object
The payer's billing address.
birth_date
string
The birth date of the payer, in Internet date format. For example, 1990-04-12.
country_code
string
The payer's two-character IS0-3166-1 country code.
email
string
The payer's email address. Maximum length is 127 characters.
first_name
string
The payer's first name.
Read only.
last_name
string
The payer's last name.
Read only.
middle_name
string
The payer's middle name.
Read only.
payer_id
string
The PayPal-assigned encrypted payer ID.
Read only.
salutation
string
The payer's salutation.
Read only.
shipping_address
object
Deprecated. The shipping address. Use the shipping address for the purchase unit or at the root level of the checkout session.
Read only.
suffix
string
The payer's suffix.
Read only.
tax_id
string
The payer’s tax ID. Supported for the PayPal payment method only.
Maximum length: 14.
tax_id_type
enum
The payer’s tax ID type. Supported for the PayPal payment method only.
Possible values: BR_CPF,BR_CNPJ.

payment_details

disbursement_mode
enum
Indicates whether to disburse the payment instantly or delay the payment.
The possible values are:
- INSTANT. The payment is disbursed instantly.
- DELAYED. The payment is delayed.
Read only.
payment_id
string
The payment ID for the order.
Read only.

payment_summary

authorizations
array (contains the sale object)
An array of authorizations for a purchase unit. A purchase unit can have zero or more authorizations.
captures
array (contains the capture object)
An array of captures for a purchase unit. A purchase unit can have zero or more captures.
refunds
array (contains the refund object)
An array of refunds for a purchase unit. A purchase unit can have zero or more refunds.
sales
array (contains the sale object)
An array of sales for a purchase unit. A purchase unit can have zero or more sales.

percentage

percentage
string
The percentage as a fixed-point, signed decimal value. Use for all interest rates. For example, specify an interest rate of 19.99% as 19.99. The allowed number formats are plain decimal numbers and whole numbers.
Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

purchase_unit

amount
object
required
The amount to collect.
reference_id
string
required
The merchant ID for the purchase unit.
Maximum length: 256.
custom
string
The client-provided external ID. Used to reconcile client transactions with PayPal transactions. Returned in transaction and settlement reports. Only supported for the PayPal payment method.
Maximum length: 127.
description
string
The purchase description.
Maximum length: 127.
invoice_number
string
The API caller-provided external invoice ID for this order.. Only supported for the PayPal payment method.
Maximum length: 256.
items
array (contains the item object)
An array of items that the customer is purchasing from the merchant.
metadata
object
The name-and-value pairs that contain external data, such as user, user feedback, score, and so on.
notify_url
string
The payment notifications URL.
Maximum length: 2048.
partner_fee_details
object
The partner fee that is collected for the original transaction.
payee
object
The recipient of the funds for this transaction.
payment_descriptor
string
The payment descriptor on the buyer credit card statement of account activity.
Maximum length: 22.
payment_linked_group
integer
An ID that groups multiple linked purchase units. The purchase transactions are linked only for the payment and not for refund. A refund is processed only for the specific transaction within the same linked group.
Minimum value: 1.
Maximum value: 100.
payment_summary
object
The payment summary.
reason_code
enum
The reason code for a transaction status of PENDING or REVERSED. Eventually, this field will replace pending_reason. Supported only for the PayPal payment method.
The possible values are:
- PAYER_SHIPPING_UNCONFIRMED. The transaction state is PENDING or REVERSED due to an unconfirmed payer shipping address.
- MULTI_CURRENCY. The transaction state is PENDING or REVERSED because it is a multi-currency transaction.
- RISK_REVIEW. The transaction state is PENDING or REVERSED due to a risk review.
- REGULATORY_REVIEW. The transaction state is PENDING or REVERSED due to a regulatory review.
- VERIFICATION_REQUIRED. The transaction state is PENDING or REVERSED because verification is required.
- ORDER. The transaction state is PENDING or REVERSED because the transaction is an order.
- OTHER. The transaction state is PENDING or REVERSED due to another reason.
- DECLINED_BY_POLICY. The transaction state is PENDING or REVERSED because it was declined by a policy.
Read only.
shipping_address
The shipping address details.
shipping_method
string
The shipping method. For example, USPSParcel.
status
enum
The transaction state.
The possible values are:
- NOT_PROCESSED. The transaction was not processed.
- PENDING. The transaction is pending.
- VOIDED. The transaction was declined and voided.
- AUTHORIZED. Payment for the transaction was not authorized.
- CAPTURED. Payment for the transaction was captured or is pending capture.
Read only.

redirect_urls

cancel_url
string
The URL where the payer is redirected after the payer cancels the payment.
return_url
string
The URL where the payer is redirected after the payer approves the payment.

refund

amount
object
The amount that is refunded to the payer and the amount that is refunded to the payee. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
capture_id
string
The ID of the sale transaction to refund.
Read only.
id
string
The ID of the refund transaction. Maximum length is 17 characters.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.
sale_id
string
The ID of the sale transaction to refund.
Read only.
status
enum
The status of the refund.
The possible values are:
- PENDING. The refund is pending.
- COMPLETED. The refund completed.
- FAILED. The refund failed.
Read only.

sale

amount
object
The amount to collect. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
create_time
string
The date and time when the resource was created, in Internet date and time format.
Read only.
id
string
The ID of the sale transaction.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.
reason_code
enum
A reason code that indicates the reason for the transaction state of PENDING or REVERSED.
The possible values are:
- CHARGEBACK. The transaction state is REVERSED due to a chargeback.
- GUARANTEE. The transaction state is REVERSED due to a guarantee.
- BUYER_COMPLAINT. The transaction state is REVERSED due to a buyer complaint.
- REFUND. The transaction state is REVERSED due to a refund.
- UNCONFIRMED_SHIPPING_ADDRESS. The transaction state is PENDING or REVERSED due to an unconfirmed shipping address.
- ECHECK. The transaction state is PENDING due to an e-check.
- INTERNATIONAL_WITHDRAWAL. The transaction state is PENDING due to an international withdrawal.
- RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION. The transaction state is PENDING due to a receiving preference that mandates manual action.
- PAYMENT_REVIEW. The transaction state is PENDING due to a payment review.
- REGULATORY_REVIEW. The transaction state is PENDING due to a regulatory review.
- UNILATERAL. The transaction state is PENDING due to a unilateral reason.
- VERIFICATION_REQUIRED. The transaction state is PENDING because verification is required.
- DELAYED_DISBURSEMENT. The transaction state is PENDING due to a delayed disbursement.
Read only.
status
enum
The status of the sale transaction.
The possible values are:
- COMPLETED. The sale completed.
- PARTIALLY_REFUNDED. The sale was partially refunded.
- PENDING. The sale is pending.
- REFUNDED. The sale was refunded.
- DENIED. The sale was denied.
Read only.
transaction_fee
object
The currency and amount of the transaction fee. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
Read only.

shipping_address

country_code
string
required
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
Minimum length: 2.
Maximum length: 2.
Pattern: ^([A-Z]{2}|C2)$.
line1
string
required
The first line of the address. For example, number, street, and so on.
city
string
The city name.
line2
string
The second line of the address. For example, suite or apartment number.
normalization_status
string
The address normalization status. Returned only for payers from Brazil.
phone
string
The phone number, in E.123 format. Maximum length is 50 characters.
postal_code
string
The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.
state
string
The code for a US state or the equivalent for other countries. Required for transactions if the address is in one of these countries: Argentina, Brazil, Canada, India, Italy, Japan, Mexico, Thailand, or United States. Maximum length is 40 single-byte characters.
type
string
The type of address. For example, HOME_OR_WORK, GIFT, and so on.

recipient_name
string
The name of the recipient at this address.
Maximum length: 127.

Error messages

In addition to the common HTTP status codes that the REST APIs return, the Orders API can return the following errors.

ACCOUNT_CANNOT_BE_FETCHED
Account cannot be fetched.

The server cannot get the partner or seller account information. The account is either not available or incorrect. The API returns this error for seller accounts when you do not enable onboarding after buyers make purchases for the associated partner.
INTERNAL_SERVER_ERROR
An internal server error occurred.

A system or application error occurred. Although the client appears to provide a correct request, something unexpected occurred on the server. A 500 response indicates a server-side software defect or site outage.
INVALID_REQUEST
The request is not well-formed, is syntactically incorrect, or violates schema.

The server did not understand the request because the API could not convert the payload data to the underlying data type, the data was not in the expected data format, the required field was not available, or a simple data validation error occurred. See Validation errors.
NOT_AUTHORIZED
Authorization failed due to insufficient permissions.

The client is not authorized to access this resource although it might have valid credentials. For example, the client does not have the correct OAuth2 scope. Additionally, a business-level authorization error might have occurred. For example, the account holder does not have sufficient funds.
PAYMENT_NOT_APPROVED_FOR_EXECUTION
Payer has not approved payment.

The API created the order. However, the customer has not approved the payment.
RESOURCE_NOT_FOUND
The specified resource does not exist.

The server did not find anything that matches the request URI. Either the URI is incorrect or the resource is not available. For example, no data exists in the database at that key.
UNAUTHORIZED
Authentication failed due to invalid authentication credentials.

The request requires authentication and the caller did not provide valid authentication credentials. Note the difference between this error and the NOT_AUTHORIZED error. See Authentication errors.
VALIDATION_ERROR
Required field is missing.

The server did not understand the request because the API could not convert the payload data to the underlying data type, the data was not in the expected data format, the required field was not available, or a simple data validation error occurred. See Validation errors.

PayPal-Partner-Attribution-Id

purchase_units

redirect_urls

application_context

create_time

gross_total_amount

id

intent

links

metadata

payment_details

status

update_time

Sample Request

application_context

create_time

gross_total_amount

id

intent

links

metadata

payment_details

purchase_units

redirect_urls

status

update_time

Sample Response

order_id

Sample Request

Sample Response

order_id

Sample Request

application_context

create_time

gross_total_amount

id

intent

links

metadata

payment_details

purchase_units

redirect_urls

status

update_time

Sample Response

PayPal-Partner-Attribution-Id

PayPal-Request-Id

order_id

disbursement_mode

payer

Sample Request

create_time

intent

links

order_id

payer_info

purchase_units

status

update_time

Sample Response

country_code

line1

city

line2

normalization_status

phone

postal_code

state

type

currency

total

details

brand_name

landing_page

locale

shipping_preference

supplementary_data

user_action

amount

id

`PayPal-Partner-Attribution-Id`

`purchase_units`

`redirect_urls`

`application_context`

`create_time`

`gross_total_amount`

`id`

`intent`

`links`

`metadata`

`payment_details`

`status`

`update_time`

`application_context`

`create_time`

`gross_total_amount`

`id`

`intent`

`links`

`metadata`

`payment_details`

`purchase_units`

`redirect_urls`

`status`

`update_time`

`order_id`

`order_id`

`application_context`

`create_time`

`gross_total_amount`

`id`

`intent`

`links`

`metadata`

`payment_details`

`purchase_units`

`redirect_urls`

`status`

`update_time`

`PayPal-Partner-Attribution-Id`

`PayPal-Request-Id`

`order_id`

`disbursement_mode`

`payer`

`create_time`

`intent`

`links`

`order_id`

`payer_info`

`purchase_units`

`status`

`update_time`

`country_code`

`line1`

`city`

`line2`

`normalization_status`

`phone`

`postal_code`

`state`

`type`

`currency`

`total`

`details`

`brand_name`

`landing_page`

`locale`

`shipping_preference`

`supplementary_data`

`user_action`

`amount`

`id`

`links`

`reason_code`

`status`

`transaction_fee`

`country_code`

`expire_month`

`expire_year`

`number`