API Version

Orders API

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. 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

id
string
The ID of the order.
intent
enum
The intent.
The possible values are:
- SALE. A sale.
- AUTHORIZE. An authorization.
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.
payment_details
object
The payment details for the order.
gross_total_amount
object
The currency and amount of the PayPal-computed total of amounts in all purchase units.
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.
metadata
object
The name-and-value pairs that contain external data, such as user, user feedback, score, and so on.
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.
redirect_urls
object
required
The redirect URLs. Required only for the PayPal payment method. The supported settings are return and cancel URLs.
create_time
string
The date and time when the resource was created, in Internet date and time format.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
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.

Sample Request

curl -v -X POST https://api.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.

id
string
The ID of the order.
Read only.
intent
enum
The intent.
The possible values are:
- SALE. A sale.
- AUTHORIZE. An authorization.
purchase_units
array (contains the purchase_unit object)
An array of purchase units. Each purchase unit establishes a contract between a customer and merchant.
payment_details
object
The payment details for the order.
gross_total_amount
object
The currency and amount of the PayPal-computed total of amounts in all purchase units.
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.
metadata
object
The name-and-value pairs that contain external data, such as user, user feedback, score, and so on.
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.
redirect_urls
object
The redirect URLs. Required only for the PayPal payment method. The supported settings are return and cancel URLs.
create_time
string
The date and time when the resource was created, in Internet date and time format.
Read only.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
Read only.
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.

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.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.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.

id
string
The ID of the order.
Read only.
intent
enum
The intent.
The possible values are:
- SALE. A sale.
- AUTHORIZE. An authorization.
purchase_units
array (contains the purchase_unit object)
An array of purchase units. Each purchase unit establishes a contract between a customer and merchant.
payment_details
object
The payment details for the order.
gross_total_amount
object
The currency and amount of the PayPal-computed total of amounts in all purchase units.
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.
metadata
object
The name-and-value pairs that contain external data, such as user, user feedback, score, and so on.
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.
redirect_urls
object
The redirect URLs. Required only for the PayPal payment method. The supported settings are return and cancel URLs.
create_time
string
The date and time when the resource was created, in Internet date and time format.
Read only.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
Read only.
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.

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.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.

order_id
string
The ID of the order.
Read only.
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.
intent
enum
The intent.
The possible values are:
- SALE. A sale.
- AUTHORIZE. An authorization.
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.
create_time
string
The date and time when the resource was created, in Internet date and time format.
Read only.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
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

line1
string
required
The first line of the address. For example, number, street, and so on.
line2
string
The second line of the address. For example, suite or apartment number.
city
string
The city name.
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)$.
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.
phone
string
The phone number, in E.123 format. Maximum length is 50 characters.
normalization_status
enum
The address normalization status. Returned only for payers from Brazil.
Read only.
Possible values: UNKNOWN,UNNORMALIZED_USER_PREFERRED,NORMALIZED,UNNORMALIZED.
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.
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}))?$.
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.
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.

`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.

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.

capture

id
string
The ID of the capture transaction.
Read only.
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.
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.
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.
transaction_fee
object
The currency and amount of the transaction fee.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

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

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.
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.
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.
billing_address
object
The billing address for this card.
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.
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.
last4
string
The last four digits of the stored credit card number.
Read only.
type
string
The credit card type. Value is visa, mastercard, discover, or amex. Do not use these lowercase values for display.
Read only.
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.

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

conversion_date
string
The date and time when the conversion rate becomes no longer valid, in Internet date and time format.
Read only.
from_currency
string
required
The three-character ISO-4217 currency code of the currency from which to convert the from amount.
Read only.
from_amount
string
required
The from amount, which is the pre-currency conversion value.
Read only.
Minimum value: 1.
to_currency
string
required
The three-character ISO-4217 currency code of the currency into which to convert the from amount.
Read only.
to_amount
string
required
The to amount, which is the post-currency conversion value.
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.
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.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

details

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.
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.
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.
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.
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.
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.
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.

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

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

error_details

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.
value
string
The value of the field that caused the error.
location
string
The location of the field that caused the error. Value is body, path, or query.
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.

funding_detail

clearing_time
string
The date and time when the funds are expected to clear, 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.
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.
processing_type
enum
The processing type of the payment card.
Read only.
Possible values: CUP_SECURE,PINLESS_DEBIT.

funding_instrument

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

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_mode
string
required
The funding mode of the funding source.
funding_instrument_type
string
required
The instrument type for this funding source.
soft_descriptor
string
The soft descriptor for charging this funding source.
Maximum length: 22.
amount
object
required
The amount and currency of the total to pull from the funding source.
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.
legal_text
string
The localized legal text for the funding source.
terms
string
The URL to legal terms 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.
additional_text
string
Additional text for the funding source.
links
array (contains the link_description object)
An array of request-related HATEOAS links.

installment_info

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

installment_option

term
integer
required
The number of installments.
monthly_payment
object
required
The amount and currency of the monthly payment.
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

sku
string
The stock keeping unit (SKU) for the item.
Maximum length: 127.
name
string
required
The item name. Maximum length is 127 characters.
description
string
The item description. Supported only for the PayPal payment method.
Maximum length: 127.
quantity
string
required
The item quantity. Must be a whole number.
Maximum length: 10.
Pattern: ^[0-9]{0,10}$.
price
string
required
The item cost. Supports two decimal places.
Maximum length: 10.
Pattern: ^[0-9]{0,10}(\.[0-9]{0,2})?$.
currency
string
required
The three-character ISO-4217 currency code.
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

id
string
The ID of the order.
Read only.
intent
enum
The intent.
The possible values are:
- SALE. A sale.
- AUTHORIZE. An authorization.
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.
payment_details
object
The payment details for the order.
gross_total_amount
object
The currency and amount of the PayPal-computed total of amounts in all purchase units.
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.
metadata
object
The name-and-value pairs that contain external data, such as user, user feedback, score, and so on.
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.
redirect_urls
object
required
The redirect URLs. Required only for the PayPal payment method. The supported settings are return and cancel URLs.
create_time
string
The date and time when the resource was created, in Internet date and time format.
Read only.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
Read only.
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.

partner_fee_details

receiver
object
required
The partner who receives the partner fee.
amount
object
required
The amount and currency of 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

order_id
string
The ID of the order.
Read only.
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.
intent
enum
The intent.
The possible values are:
- SALE. A sale.
- AUTHORIZE. An authorization.
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.
create_time
string
The date and time when the resource was created, in Internet date and time format.
Read only.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
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

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

payer

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.
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.

payer_info

email
string
The payer's email address. Maximum length is 127 characters.
salutation
string
The payer's salutation.
Read only.
first_name
string
The payer's first name.
Read only.
middle_name
string
The payer's middle name.
Read only.
last_name
string
The payer's last name.
Read only.
suffix
string
The payer's suffix.
Read only.
payer_id
string
The PayPal-assigned encrypted payer ID.
Read only.
birth_date
string
The birth date of the payer, in Internet date format. For example, 1990-04-12.
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.
country_code
string
The payer's two-character IS0-3166-1 country code.
billing_address
object
The payer's billing address.
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.

payment_details

payment_id
string
The payment ID for the order.
Read only.
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_summary

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.
authorizations
array (contains the sale object)
An array of authorizations for a purchase unit. A purchase unit can have zero or more authorizations.

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

reference_id
string
required
The merchant ID for the purchase unit.
Maximum length: 256.
amount
object
required
The amount to collect.
payee
object
The recipient of the funds for this transaction.
description
string
The purchase description.
Maximum length: 127.
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.
invoice_number
string
The API caller-provided external invoice ID for this order.. Only supported for the PayPal payment method.
Maximum length: 256.
payment_descriptor
string
The payment descriptor on the buyer credit card statement of account activity.
Maximum length: 22.
items
array (contains the item object)
An array of items that the customer is purchasing from the merchant.
notify_url
string
The payment notifications URL.
Maximum length: 2048.
shipping_address
The shipping address details.
shipping_method
string
The shipping method. For example, USPSParcel.
partner_fee_details
object
The partner fee that is collected for the original transaction.
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.
metadata
object
The name-and-value pairs that contain external data, such as user, user feedback, score, and so on.
payment_summary
object
The payment summary.
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.
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.

redirect_urls

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

refund

id
string
The ID of the refund transaction. Maximum length is 17 characters.
Read only.
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.
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.
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.
Read only.
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.
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.
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.
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.
create_time
string
The date and time when the resource was created, in Internet date and time format.
Read only.
update_time
string
The date and time when the resource was last updated, in Internet date and time format.
Read only.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

shipping_address

line1
string
required
The first line of the address. For example, number, street, and so on.
line2
string
The second line of the address. For example, suite or apartment number.
city
string
The city name.
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)$.
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.
phone
string
The phone number, in E.123 format. Maximum length is 50 characters.
normalization_status
string
The address normalization status. Returned only for payers from Brazil.
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.
INTERNAL_SERVER_ERROR
An internal server error occurred.
INVALID_REQUEST
The request is not well-formed, is syntactically incorrect, or violates schema.
NOT_AUTHORIZED
Authorization failed due to insufficient permissions.
PAYMENT_NOT_APPROVED_FOR_EXECUTION
Payer has not approved payment.
RESOURCE_NOT_FOUND
The specified resource does not exist.
UNAUTHORIZED
Authentication failed due to invalid authentication credentials.
VALIDATION_ERROR
Required field is missing.

PayPal Commerce Platform for Business

PayPal Commerce Platform for Marketplaces and Platforms

PayPal Commerce Platform for Enterprise

Docs Catalog

Reference

Developer Tools

Regional Codes

PayPal-Partner-Attribution-Id

id

intent

purchase_units

payment_details

gross_total_amount

application_context

metadata

status

redirect_urls

create_time

update_time

links

Sample Request

id

intent

purchase_units

payment_details

gross_total_amount

application_context

metadata

status

redirect_urls

create_time

update_time

links

Sample Response

order_id

Sample Request

Sample Response

order_id

Sample Request

id

intent

purchase_units

payment_details

gross_total_amount

application_context

metadata

status

redirect_urls

create_time

update_time

links

Sample Response

PayPal-Partner-Attribution-Id

PayPal-Request-Id

order_id

disbursement_mode

payer

Sample Request

order_id

status

intent

payer_info

purchase_units

create_time

update_time

links

Sample Response

line1

line2

city

country_code

postal_code

state

phone

normalization_status

type

currency

total

details

brand_name

`PayPal-Partner-Attribution-Id`

`id`

`intent`

`purchase_units`

`payment_details`

`gross_total_amount`

`application_context`

`metadata`

`status`

`redirect_urls`

`create_time`

`update_time`

`links`

`id`

`intent`

`purchase_units`

`payment_details`

`gross_total_amount`

`application_context`

`metadata`

`status`

`redirect_urls`

`create_time`

`update_time`

`links`

`order_id`

`order_id`

`id`

`intent`

`purchase_units`

`payment_details`

`gross_total_amount`

`application_context`

`metadata`

`status`

`redirect_urls`

`create_time`

`update_time`

`links`

`PayPal-Partner-Attribution-Id`

`PayPal-Request-Id`

`order_id`

`disbursement_mode`

`payer`

`order_id`

`status`

`intent`

`payer_info`

`purchase_units`

`create_time`

`update_time`

`links`

`line1`

`line2`

`city`

`country_code`

`postal_code`

`state`

`phone`

`normalization_status`

`type`

`currency`

`total`

`details`

`brand_name`

`locale`

`landing_page`

`shipping_preference`

`user_action`

`supplementary_data`

`id`

`amount`

`status`

`reason_code`

`transaction_fee`

`links`

`country_code`

`number`

`type`

`expire_month`