Orders API

Use the Orders API to create, show details for, authorize, and capture payment for orders.
Orders API integration note: PayPal for Marketplaces is a limited-release solution aimed at marketplaces, crowd funding, and multi-party commerce platforms. To use Orders API for Marketplaces, see Make an Orders API call.

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

For more information about HTTP request headers, see HTTP request headers.

Request body

  • intent

    enum

    The intent. The allowed 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.
  • metadata

    object

    The name-and-value pairs that contain external data, such as user, user feedback, score, and so on.
  • redirect_urls

    object

    required

    The redirect URLs. Required only for the PayPal payment method. The supported settings are return and cancel URLs.

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

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/RT52181732T9513405D/cancel \
-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

{
  "name": "ORDER_NOT_FOUND",
  "message": "Order Resource doesn't exist",
  "debug_id": "90957fca61718"
}

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/66181732T9513405D \
-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.
  • 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

{
  "name": "ORDER_NOT_FOUND",
  "message": "Order Resource doesn't exist",
  "debug_id": "90957fca61718"
}

Orders payment actions (resource group)

Use the /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 URL to approve the order.

Pay for order

POST /v1/checkout/orders/{order_id}/pay
Initiates a PayPal payment that a buyer has approved.
Note: For Marketplace use cases, use the disbursement_mode to indicate whether to disburse funds to the merchant and marketplace accounts immediately or later. If you delay disbursement, you must call disburse funds to disburse funds to the merchant and marketplace.

Header parameters

For more information about HTTP request headers, see HTTP request headers.
  • PayPal-Partner-Attribution-Id

    string

    For more information about PayPal-Partner-Attribution-Id, see PayPal-Partner-Attribution-Id.
  • PayPal-Request-Id

    string

    The server stores keys forever. For more information about PayPal-Request-Id, see PayPal-Request-Id.

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 allowed 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/92V50600P8987630S/pay \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "disbursement_mode": "DELAYED",
  "payer": {
    "payment_method": "paypal",
    "funding_instruments": [
      {
        "credit_card": {
          "number": "4417119669820331",
          "type": "visa",
          "expire_month": 11,
          "expire_year": 2018,
          "cvv2": "874",
          "first_name": "Betsy",
          "last_name": "Buyer",
          "billing_address": {
            "line1": "2211 N First Street",
            "line2": "Building 17",
            "city": "San Jose",
            "state": "CA",
            "postal_code": "95131",
            "country_code": "US"
          }
        }
      }
    ]
  }
}'

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

{
  "name": "CONTINGENCY",
  "message": "buyer needs to choose currency conversion choice",
  "debug_id": "90957fca61718",
  "information_link": "https://developer.paypal.com/docs/api/errors/#contingency",
  "links": [
    {
      "href": "https://www.paypal.com/webapps/helios?action=changeCurrencyConv&cart_id=06N23580936872525&payer_id=NMXBYHSEL4FEY&client_id=QXJpZXM%3D&funding_option_id=1&checkout_session_id=0NF484574F9638815&redirect_uri=",
      "rel": "contingency",
      "method": "GET"
    }
  ]
}

Common object definitions

address

  • line1

    string

    required

    The first line of the address. For example, number, street, and so on.

    Maximum length: 100.

  • line2

    string

    The second line of the address. For example, suite or apartment number.

    Maximum length: 100.

  • city

    string

    The city name.

    Maximum length: 64.

  • 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. The possible values are:
    • UNKNOWN. Unknown.
    • UNNORMALIZED_USER_PREFERRED. Unnormalized user preferred.
    • NORMALIZED. Normalized.
    • UNNORMALIZED. Unnormalized.

    Read only.

  • 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

    A 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. Redacts shipping address fields from the PayPal pages. Recommended value to use for digital goods.
    • GET_FROM_FILE. Get the shipping address selected by the buyer on PayPal pages.
    • SET_PROVIDED_ADDRESS. Use the address provided by the merchant. Buyer is not able to change the address on the PayPal pages. If 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 flowChoose whenDescription
    ContinueYou 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 NowYou 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.
  • postback_data

    array (contains the name_value_pair object)

    An array of name-and-value pairs that contain external data, such as user feedback, score, and so on.
  • 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

    Optional. 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.
    Important: The use of the PayPal REST /payments APIs to accept credit card payments is restricted. Instead, you can accept credit card payments with Braintree Direct.
  • 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_code

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.

    Default: 1.

    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.

    Minimum value: 0.

  • conversion_type

    enum

    The conversion type to apply. The possible values are:
    • PAYPAL. PayPal conversion type.
    • VENDOR. Vendor conversion type.

    Default: PAYPAL.

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

    Minimum value: 0.

    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

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.

    Default: body.

  • 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. The possible values are:
    • CUP_SECURE. CUP secure.
    • PINLESS_DEBIT. Pinless debit.

    Read only.

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

    enum

    required

    The funding mode of the funding source. The possible values are:
    • INSTANT_TRANSFER. Instant transfer.
    • MANUAL_BANK_TRANSFER. Manual bank transfer.
    • DELAYED_TRANSFER. Delayed transfer.
    • ECHECK. E-check.
    • PAY_UPON_INVOICE. Pay upon invoice.

    Read only.

  • funding_instrument_type

    enum

    required

    The instrument type for this funding source. The possible values are:
    • BALANCE. Balance.
    • PAYMENT_CARD. Payment card.
    • BANK_ACCOUNT. Bank account.
    • CREDIT. Credit.
    • INCENTIVE. Incentive.
    • EXTERNAL_FUNDING. External funding.
    • TAB. Tab.

    Read only.

  • soft_descriptor

    string

    The soft descriptor for charging this funding source.

    Read only.

    Maximum length: 22.

  • amount

    object

    required

    The amount and currency of the total to pull from the funding source.

    Read only.

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

    Read only.

  • 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

    enum

    The preferred way to select this funding source. The possible values are:
    • NONE. None.
    • WALLET_PREFERRED. Wallet preferred.
    • PAYMENT_PREFERRED. Payment preferred.
    • SYSTEM_DEFAULTED. System defaulted.

    Read only.

  • additional_text

    string

    Additional text for the funding source.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

installment_info

  • installment_id

    string

    The installment ID.

    Read only.

  • network

    enum

    The credit card network. The possible values are:
    • VISA. Visa.
    • MASTERCARD. Mastercard.

    Read only.

  • 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]+))$.

item

  • sku

    string

    The stock keeping unit (SKU) for the item.

    Maximum length: 127.

  • name

    string

    The item name. If this value is greater than the maximum allowed length, the API truncates the string.

    Maximum length: 127.

  • description

    string

    The item description. Supported for only 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 that identifies the currency.

    Minimum length: 3.

    Maximum length: 3.

  • tax

    string

    The item tax. Supported only for the PayPal payment method.

language

metadata

  • postback_data

    array (contains the name_value_pair object)

    An array of name-and-value pairs that contain external data, such as user, user feedback, score, and so on.
  • 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.

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.
  • 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 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.
    Important: The use of the PayPal REST /payments APIs to accept credit card payments is restricted. Instead, you can accept credit card payments with:
    The possible values are:
    • credit_card. Credit card.
    • paypal. A PayPal Wallet payment.
    • pay_upon_invoice. Pay upon invoice.
    • carrier. Carrier.
    • alternate_payment. Alternate payment.
    • bank. Bank.
  • status

    enum

    The status of payer's PayPal account. The possible values are:
    • VERIFIED.
    • UNVERIFIED.

    Read only.

  • 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. The possible values are:
    • BR_CPF. BR CPF tax ID type.
    • BR_CNPJ. BR CNPJ tax ID type.
  • 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

    object

    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.

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

    Maximum length: 100.

  • line2

    string

    The second line of the address. For example, suite or apartment number.

    Maximum length: 100.

  • city

    string

    The city name.

    Maximum length: 64.

  • 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. The possible values are:
    • UNKNOWN. Unknown.
    • UNNORMALIZED_USER_PREFERRED. Unnormalized user preferred.
    • NORMALIZED. Normalized.
    • UNNORMALIZED. Unnormalized.

    Read only.

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

Additional API information

Error messages

In addition to 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 is not able to retrieve the account information based on the partner or seller accounts. The account is either not available or incorrect. This error is returned for seller accounts only when progressive onboarding is not enabled for the associated partner.

  • INTERNAL_SERVER_ERROR

    An internal server error has 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. The 500 status code is not used for client validation or logic error handling.

  • INVALID_REQUEST

    Request is not well-formed, syntactically incorrect, or violates schema. The server did not understand the request because the payload data could not be converted 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 order was created. 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. See Authentication errors. The request requires authentication and none was provided. Note the difference between this error and the NOT_AUTHORIZED error.

  • VALIDATION_ERROR

    Invalid request - see details. The server did not understand the request because the payload data could not be converted 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.

Feedback

Have feedback?

Let us know.