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, crowdfunding, and multi-party commerce platforms. To use Orders API for Marketplace, see the Orders Integration Guide for Marketplaces.
  • You can use the Orders API with Express Checkout to give your buyers a simplified checkout experience.

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. First, to set the transaction context and enable the server to complete risk and compliance analysis of the transaction, call /v1/risk/transaction-contexts to generate a tracking ID. Save and include this ID in the Paypal-Client-Metadata-Id request header in your call to /v1/checkout/orders.

Parameters

  • order

    body object

    required

    Order.

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/checkout/orders \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-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",
      "category": "PHYSICAL"
    },
    {
      "name": "Fitness Watch",
      "sku": "sku04",
      "price": "0.55",
      "currency": "USD",
      "quantity": "1",
      "category": "PHYSICAL"
    }
    ],
    "shipping_address": {
    "recipient_name": "John Doe",
    "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.
  • intent

    enum

    The intent.

    Possible values: SALE, AUTHORIZE.

  • purchase_units

    array (contains the purchase_unit object)

    required

    An array of purchase units. Each purchase unit establishes a contract between the payer and payee.
  • payment_details

    object

    The payment details for the order.
  • application_context

    object

    The application context experience information.
  • payer_info

    object

    The payer information.
  • metadata

    object

    Creates an order. First, to set the transaction context and enable the server to complete risk and compliance analysis of the transaction, call /v1/risk/transaction-contexts to generate a tracking ID. Save and include this ID in the Paypal-Client-Metadata-Id request header in your call to /v1/checkout/orders.
  • 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.

    Possible values: CREATED, APPROVED, COMPLETED, 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 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",
          "category": "PHYSICAL"
        },
        {
          "name": "Fitness Watch",
          "sku": "sku04",
          "price": "0.55",
          "currency": "USD",
          "quantity": "1",
          "category": "PHYSICAL"
        }
      ],
      "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 resource. To call this method, the order status must be CREATED or APPROVED.

Parameters

  • order_id

    path string

    required

    The ID of the order to cancel.

Sample Request

curl -v -X DELETE https://api.sandbox.paypal.com/v1/checkout/orders/RT52181732T9513405D \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{}'

Response

A successful request returns the HTTP 204 No Content status code with no JSON response body.

Sample Response

{}

Show order details

GET /v1/checkout/orders/{order_id}
Shows details for an order, by ID.

Parameters

  • order_id

    path 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/8RU61172JS455403V \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{}'

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

    enum

    The intent.

    Possible values: SALE, AUTHORIZE.

  • purchase_units

    array (contains the purchase_unit object)

    required

    An array of purchase units. Each purchase unit establishes a contract between the payer and payee.
  • payment_details

    object

    The payment details for the order.
  • application_context

    object

    The application context experience information.
  • payer_info

    object

    The payer information.
  • metadata

    object

    Shows details for an order, by ID.
  • 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.

    Possible values: CREATED, APPROVED, COMPLETED, 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 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",
          "category": "PHYSICAL"
        },
        {
          "name": "Fitness Watch",
          "sku": "sku04",
          "price": "0.55",
          "currency": "USD",
          "quantity": "1",
          "category": "PHYSICAL"
        }
      ],
      "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",
        "type": "GIFT"
      },
      "shipping_method": "United Postal Service",
      "partner_fee_details": {
        "receiver": {
          "email": "partner@example.com"
        },
        "amount": {
          "value": "0.01",
          "currency": "USD"
        }
      },
      "payment_linked_group": 1,
      "payment_summary": {
        "captures": [
          {
            "id": "14U02018GD754745H",
            "amount": {
              "currency": "USD",
              "details": {},
              "total": "1.44"
            },
            "status": "COMPLETED",
            "transaction_fee": {
              "value": "0.36",
              "currency": "USD"
            },
            "links": [
              {
                "href": "https://api.paypal.com/v1/payments/capture/14U02018GD754745H",
                "rel": "self",
                "method": "GET"
              },
              {
                "href": "https://api.paypal.com/v1/payments/capture/14U02018GD754745H/refund",
                "rel": "refund",
                "method": "POST"
              }
            ]
          }
        ]
      },
      "custom": "custom_value_2388",
      "invoice_number": "invoice_number_2388",
      "payment_descriptor": "Payment Mobile World",
      "status": "CAPTURED"
    }
  ],
  "payment_details": {
    "payment_id": "PAYID-LEAQ63Q3HV803789J6535430"
  },
  "payer_info": {
    "email": "test-payer@paypal.com",
    "first_name": "Jake",
    "last_name": "Doe",
    "payer_id": "9WVBNYPKKNBJS",
    "country_code": "US",
    "billing_address": {
      "line1": "1 Main St",
      "line2": "",
      "city": "San Jose",
      "country_code": "US",
      "postal_code": "95131",
      "state": "CA"
    },
    "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",
      "type": "GIFT"
    }
  },
  "metadata": {
    "supplementary_data": [
      {
        "name": "risk_correlation_id",
        "value": "8RU61172JS455403V"
      },
      {
        "name": "buyer_ipaddress",
        "value": "10.225.82.18"
      },
      {
        "name": "external_channel",
        "value": "WEB"
      }
    ]
  },
  "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"
    }
  ],
  "status": "COMPLETED"
}

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 /payments/referenced-payouts-items/pay to disburse funds to the merchant and marketplace.

Parameters

  • order_id

    path string

    required

    The ID of the order for which to execute a payment.
  • pay_order_request

    body object

    required

    Execute order request object.

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/checkout/orders/8RU61172JS455403V/pay \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "disbursement_mode": "DELAYED"
}'

Response

A successful request returns the HTTP 202 Accepted status code and a JSON response body that shows order and payment details. ** Applicable for existing Asynchronous payment processing integrations **
  • order_id

    string

    The ID of the order.
  • status

    enum

    The status of the order.

    Possible values: APPROVED, CANCELED, COMPLETED, CREATED, EXPIRED, FAILED, IN_PROGRESS, PARTIALLY_COMPLETED, SUBMITTED.

  • intent

    enum

    The intent.

    Possible values: SALE, AUTHORIZE.

  • payer_info

    object

    The payer information.
  • purchase_units

    array (contains the purchase_unit object)

    An array of purchase units. Each unit establishes a contract between a payer and payee.
  • 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.

Sample Response

{
  "order_id": "8RU61172JS455403V",
  "status": "APPROVED",
  "payer_info": {
    "email": "test-payer@paypal.com",
    "first_name": "Jake",
    "last_name": "Doe",
    "payer_id": "9WVBNYPKKNBJS",
    "phone": "4087811648",
    "country_code": "US",
    "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"
    }
  },
  "create_time": "2017-04-26T21:21:50Z",
  "update_time": "2017-04-26T21:21:50Z",
  "links": [
    {
      "href": "https://api.paypal.com/v1/checkout/orders/8RU61172JS455403V",
      "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

    Optional. The second line of the address. For example, suite, apartment number, and so on.
  • 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 is used in that country's top-level domain names. Use the C2 country code for CHINA WORLDWIDE for CUP, bank card, and cross-border transactions.
  • 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.

    Possible values: UNKNOWN, UNNORMALIZED_USER_PREFERRED, NORMALIZED, UNNORMALIZED.

  • status

    enum

    The address status.

    Possible values: CONFIRMED, UNCONFIRMED.

  • 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. Supports two decimal places.
  • 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 is 127 single-byte alphanumeric characters.
  • locale

    string

    The BCP-47 formatted locale of pages that the PayPal payment experience displays. A valid value is AU, AT, BE, BR, CA, CH, CN, DE, ES, GB, FR, IT, NL, PL, PT, RU, or US. A 5-character code is also valid for languages in these countries: DA-DK, HE-IL, ID-ID, JA-JP, NO-NO, PT-BR, RU-RU, SV-SE, TH-TH, ZH-CN, ZH-HK, or ZH-TW.
  • 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

    Specify Shipping Preferences:
    • 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 doesn't pass an address buyer has the option to choose the address on PayPal pages.
    .

    Possible values: NO_SHIPPING, GET_FROM_FILE, SET_PROVIDED_ADDRESS.

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

bank_account

  • account_number

    string

    required

    The account number in either:

    Maximum length: 34.

  • account_number_type

    enum

    required

    The type of the bank account number, which is an International Bank Account Number (IBAN) or Basic Bank Account Number (BBAN).

    Possible values: BBAN, IBAN.

  • routing_number

    string

    The routing transit number, or bank code, of the bank. Typically used for domestic accounts only. For international accounts, the IBAN includes the bank code. For more information, see Bank code.

    Maximum length: 34.

  • account_type

    enum

    The bank account type.

    Possible values: CHECKING, SAVINGS.

  • account_name

    string

    The customer-designated account name.

    Maximum length: 64.

  • check_type

    enum

    The check type. Valid when the facilitator or merchant obtained this information from a check.

    Possible values: PERSONAL, COMPANY.

  • auth_type

    enum

    The method by which the check was obtained from the customer, if a check was the source of the information.

    Possible values: CCD, PPD, TEL, POP, ARC, RCK, WEB.

  • auth_capture_timestamp

    string

    The date and time when the authorization was captured, in Internet date and time format. Use this field if the user authorization must be captured due to any privacy requirements.
  • bank_name

    string

    The bank name.

    Maximum length: 64.

  • country_code

    string

    The two-character ISO 3166-1 code that identifies the country or region of the account holder.
  • first_name

    string

    The account holder's first name.

    Maximum length: 64.

  • last_name

    string

    The account holder's last name.

    Maximum length: 64.

  • birth_date

    string

    The account holder's birth date, in Internet date format.
  • billing_address

    object

    The billing address.
  • state

    enum

    The funding instrument's state.

    Possible values: ACTIVE, INACTIVE, DELETED.

  • confirmation_status

    enum

    The bank account's confirmation status.

    Possible values: UNCONFIRMED, CONFIRMED.

  • payer_id

    string

    [DEPRECATED] The payer ID. Use external_customer_id instead.
  • external_customer_id

    string

    The facilitor-provided ID of the customer to whom this bank account belongs. Required when you create or use a funding instrument that is stored in the vault.

    Maximum length: 256.

  • merchant_id

    string

    The facilitator-provided ID of the merchant for which this bank account has been stored. Usage of the bank account is restricted to the specific merchant.

    Maximum length: 256.

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

    string

    The date and time when the resource can no longer be used to fund a payment, in Internet date and time format.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

capture

  • id

    string

    The ID of the capture transaction.
  • amount

    object

    The amount to capture. If you omit this amount, default is the amount from the authorization. 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 state of the capture transaction.

    Possible values: PENDING, COMPLETED, REFUNDED, PARTIALLY_REFUNDED.

  • reason_code

    enum

    A reason code. Indicates the reason for the transaction state of pending or reversed.

    Possible values: CHARGEBACK, GUARANTEE, BUYER_COMPLAINT, REFUND, UNCONFIRMED_SHIPPING_ADDRESS, ECHECK, INTERNATIONAL_WITHDRAWAL, RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION, PAYMENT_REVIEW, REGULATORY_REVIEW, UNILATERAL, VERIFICATION_REQUIRED, DELAYED_DISBURSEMENT.

  • transaction_fee

    object

    The transaction fee.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

country-code

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 CUP, 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.
  • 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 associated with this card.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

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. This ID can be any value you would like to associate with the saved card, such as a UUID, user name, or email address. Required when you use a vaulted credit card 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.
  • type

    string

    The credit card type. Value is visa, mastercard, discover, or amex. Values are in lowercase; do not use these values for display.
  • expire_month

    integer

    The expiration month with no leading zero. Value is from 1 to 12.
  • expire_year

    integer

    The four-digit expiration year.

currency

  • currency

    string

    required

    The three-character ISO-4217 currency code. PayPal does not support all currencies.
  • value

    string

    required

    The amount, up to N digits after the decimal separator, as defined in ISO-4217 for the appropriate 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.
  • from_currency

    string

    required

    The three-character ISO-4217 currency code of the currency from which to convert the from amount.
  • from_amount

    string

    required

    The from amount, which is the pre-currency conversion value. Default is 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.
  • to_amount

    string

    required

    The to amount, which is the post-currency conversion value.

    Minimum value: 0.

  • conversion_type

    enum

    The conversion type to apply.

    Possible values: PAYPAL, VENDOR.

    Default: PAYPAL.

  • conversion_type_changeable

    boolean

    Indicates whether the payer can or cannot change the conversion type.
  • spread

    string

    The rate, as a percentage, that PayPal charges above the foreign exchange rate provided by PayPal’s financial partners.

    Minimum value: 0.

    Maximum value: 100.

  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

details

  • subtotal

    string

    The subtotal amount for the items. If the request includes line items, this property is required. Maximum length is 10 characters. Supports two decimal places.
  • shipping

    string

    The shipping fee. Maximum length is 10 characters. Supports two decimal places.
  • tax

    string

    The tax. Maximum length is 10 characters. Supports two decimal places.
  • handling_fee

    string

    The handling fee. Supported for the PayPal payment method only.
  • shipping_discount

    string

    The shipping fee discount. Supported for the PayPal payment method only.
  • insurance

    string

    The insurance fee. Supported only for the PayPal payment method.
  • gift_wrap

    string

    The gift wrap fee.

display_phone

error

  • name

    string

    required

    A human-readable, unique name of the error.
  • message

    string

    required

    A message that describes the error.
  • debug_id

    string

    required

    PayPal internal ID that is used for correlation purposes.
  • information_link

    string

    An information link, or URI, that shows detailed information about this error for the developer.
  • 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.

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. A valid value is body, path, or query. Default is body.
  • issue

    string

    required

    The reason for the error.

funding_detail

  • clearing_time

    string

    The date and time when the funds are expected to clear, in Internet date and time format.
  • 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.
  • 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.
  • processing_type

    enum

    The processing type of the payment card.

    Possible values: CUP_SECURE, PINLESS_DEBIT.

funding_instrument

  • credit_card

    object

    The credit card instrument.
  • credit_card_token

    object

    The PayPal vaulted credit card instrument.

funding_source

  • credit_card

    object

    The credit card instrument.
  • credit_card_token

    object

    The PayPal vaulted credit card instrument.
  • funding_mode

    enum

    required

    The funding mode of the funding source.

    Possible values: INSTANT_TRANSFER, MANUAL_BANK_TRANSFER, DELAYED_TRANSFER, ECHECK, PAY_UPON_INVOICE.

  • funding_instrument_type

    enum

    required

    The instrument type for this funding source.

    Possible values: BALANCE, PAYMENT_CARD, BANK_ACCOUNT, CREDIT, INCENTIVE, EXTERNAL_FUNDING, TAB.

  • soft_descriptor

    string

    The soft descriptor for charging this funding source.

    Maximum length: 22.

  • amount

    object

    required

    The total amount to pull from the funding source.
  • negative_balance_amount

    array

    An array of additional amounts 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

    enum

    The preferred way to select this funding source.

    Possible values: NONE, WALLET_PREFERRED, PAYMENT_PREFERRED, SYSTEM_DEFAULTED.

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

    enum

    The credit card network.

    Possible values: VISA, MASTERCARD.

  • issuer

    string

    The credit card issuer.
  • 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 monthly payment.
  • discount_amount

    object

    The discount amount applied to the payment, if any.
  • discount_percentage

    string

    The discount percentage applied to the payment, if any.

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. Maximum length is 10 characters.
  • price

    string

    required

    The item cost. Maximum length is 10 characters.
  • currency

    string

    required

  • 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

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

    enum

    The intent.

    Possible values: SALE, AUTHORIZE.

  • purchase_units

    array (contains the purchase_unit object)

    required

    An array of purchase units. Each purchase unit establishes a contract between the payer and payee.
  • payment_details

    object

    The payment details for the order.
  • application_context

    object

    The application context experience information.
  • payer_info

    object

    The payer information.
  • metadata

    object

    Order.
  • status

    enum

    The status of the order. After the customer approves the order, the status is APPROVED. After the payment is made for the order and the order completes, the status is COMPLETED.

    Possible values: CREATED, APPROVED, COMPLETED, 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.

partner_fee_details

  • receiver

    object

    required

    The partner who receives the partner fee.
  • amount

    object

    required

    The partner fee amount.

pay_order_request

  • disbursement_mode

    enum

    required

    Indicates whether to disburse money instantly or later.

    Possible values: INSTANT, DELAYED.

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

    enum

    The status of the order.

    Possible values: APPROVED, CANCELED, COMPLETED, CREATED, EXPIRED, FAILED, IN_PROGRESS, PARTIALLY_COMPLETED, SUBMITTED.

  • intent

    enum

    The intent.

    Possible values: SALE, AUTHORIZE.

  • payer_info

    object

    The payer information.
  • purchase_units

    array (contains the purchase_unit object)

    An array of purchase units. Each unit establishes a contract between a payer and payee.
  • 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.

payee

  • email

    string

    The email address associated with the payee's PayPal account. If the provided email address is not associated with any PayPal account, the payee can only receive PayPal Wallet payments. Direct credit card payments are denied due to card compliance requirements.
  • merchant_id

    string

    The encrypted PayPal account ID for the payee.
  • payee_display_metadata

    object

    Payee metadata references 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.

    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-related information. If the payment_method is paypal, you must set the email address of the PayPal account that funds the transaction in the payer_info.

payer_info

  • email

    string

    The payer's email address. Maximum length is 127 characters.
  • salutation

    string

    The payer's salutation.
  • first_name

    string

    The payer's first name.
  • middle_name

    string

    The payer's middle name.
  • last_name

    string

    The payer's last name.
  • suffix

    string

    The payer's suffix.
  • payer_id

    string

    The PayPal-assigned encrypted payer ID.
  • phone

    string

    The payer's phone number. Maximum length is 20 characters.
  • phone_type

    enum

    The phone type.

    Possible values: HOME, WORK, MOBILE, OTHER.

  • 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

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

payment_details

  • payment_id

    string

    The payment ID for the order.
  • disbursement_mode

    enum

    Indicates whether to disburse money instantly or later.

    Possible values: INSTANT, DELAYED.

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

    A percentage as a fixed-point, signed decimal value. Use for all interest rates. For example, represent an interest rate of 19.99% as 19.99. The allowed number formats are plain decimal numbers and whole numbers. Unlike a JSON number or JSON Schema number type, this value MUST NOT be deserialized in JavaScript into a JavaScript Number object, which is 64-bit floating-point and cannot accurately represent all values transmitted by this type. Likewise, in Java, this type MUST be deserialized into a BigDecimal or other fixed-point numeric type.

    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 partner-provided external invoice number 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.
  • notify_url

    string

    The payment notifications URL.

    Maximum length: 2048.

  • shipping_address

    object

    The shipping address.
  • shipping_method

    string

    The shipping method. For example, USPSParcel.
  • partner_fee_details

    object

    The partner fee.
  • 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

    A purchase unit. Use to capture required information for the payment contract.
  • payment_summary

    object

    A payment summary for the purchase unit.
  • status

    enum

    The transaction state.

    Possible values: NOT_PROCESSED, PENDING, VOIDED, AUTHORIZED, CAPTURED.

  • reason_code

    enum

    The reason code for a transaction state of pending or reversed. Eventually, this field will replace pending_reason. Only supported for the PayPal payment method.

    Possible values: PAYER_SHIPPING_UNCONFIRMED, MULTI_CURRENCY, RISK_REVIEW, REGULATORY_REVIEW, VERIFICATION_REQUIRED, ORDER, OTHER, DECLINED_BY_POLICY.

redirect_urls

  • return_url

    string

    The URL where the payer is redirected after he or she approves the payment.
  • cancel_url

    string

    The URL where the payer is redirected after he or she cancels the payment.

refund

  • id

    string

    The ID of the refund transaction. Maximum length is 17 characters.
  • amount

    object

    Details including both the amount refunded to the payer and the amount refunded to the payee. Maximum length is ten characters.
  • capture_id

    string

    The ID of the sale transaction to refund.
  • sale_id

    string

    The ID of the sale transaction to refund.
  • status

    enum

    The status of the refund.

    Possible values: PENDING, COMPLETED, FAILED.

  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

sale

  • id

    string

    The ID of the sale transaction.
  • amount

    object

    The amount to collect.
  • transaction_fee

    object

    The transaction fee.
  • status

    enum

    The status of the sale transaction.

    Possible values: COMPLETED, PARTIALLY_REFUNDED, PENDING, REFUNDED, DENIED.

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

shipping_address

  • line1

    string

    required

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

    string

    Optional. The second line of the address. For example, suite, apartment number, and so on.
  • 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 is used in that country's top-level domain names. Use the C2 country code for CHINA WORLDWIDE for CUP, bank card, and cross-border transactions.
  • 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.

    Possible values: UNKNOWN, UNNORMALIZED_USER_PREFERRED, NORMALIZED, UNNORMALIZED.

  • status

    enum

    The address status.

    Possible values: CONFIRMED, UNCONFIRMED.

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

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

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