PayPal Orders API
Use the `/orders` resource to create, update, retrieve, authorize, capture and track orders.
PayPal Orders API is one of 37 APIs that PayPal publishes on the APIs.io network, described by a machine-readable OpenAPI specification and an AsyncAPI event-driven specification.
Tagged areas include Order. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, and an AsyncAPI specification.
This API exposes 7 operations across 6 paths, and defines 206 schemas. It is described by OpenAPI 3.0.3, at version 1.6.
Requests are made against 2 base URLs: https://api-m.sandbox.paypal.com, https://api-m.paypal.com.
7 operations
6 paths
206 schemas
1 GET1 PATCH5 POST
Metadata
The identity and technical contract details declared by the specification.
Authentication & Security 1
PayPal Orders API declares
1 security scheme
for authenticating requests.
It supports OAuth 2.0 (Oauth2) using the clientCredentials flow, exposing 1 scope.
Oauth2— Oauth 2.0 authentication
Paths & Operations 7
Across 6 paths, the API surfaces 7 operations — 1 GET, 1 PATCH, 5 POST. Each is listed below with its method, path, parameters, and response codes.
Orders 7
Use the /orders resource to create, update, retrieve, authorize, capture and track orders.
POST
/v2/checkout/orders
Paypal Create order
GET
/v2/checkout/orders/{id}
Paypal Show order details
PATCH
/v2/checkout/orders/{id}
Paypal Update order
POST
/v2/checkout/orders/{id}/confirm-payment-source
Paypal Confirm the Order
POST
/v2/checkout/orders/{id}/authorize
Paypal Authorize payment for order
POST
/v2/checkout/orders/{id}/capture
Paypal Capture payment for order
POST
/v2/checkout/orders/{id}/track
Paypal Add tracking information for an Order.
Schemas 206
The contract defines 206 schemas that model the data the API accepts and returns. The most detailed are payment_source (15 properties), shipment_tracker (14 properties), purchase_unit (13 properties), payment_source_response (12 properties). Each schema is shown below with its type and property counts.
processing_instruction
string
The instruction to process an order.
tracker
object
The tracking response on creation of tracker.
shipping_detail
object
The shipping details.
4 properties
venmo_wallet_request
object
Information needed to pay using Venmo.
4 properties
authorization_status_details
object
The details of the authorized payment status.
1 property
supplementary_data
object
Supplementary data about a payment. This object passes information that can be used to improve risk assessments and processing costs, for example, by providing…
1 property
paypal_wallet_attributes
object
Additional attributes associated with the use of this PayPal Wallet.
2 properties
net_amount_breakdown_item
object
The net amount. Returned when the currency of the refund is different from the currency of the PayPal account where the merchant holds their funds.
3 properties
link_description
object
The request-related [HATEOAS link](/api/rest/responses/hateoas-links) information.
3 properties
2 required
orders.capture-400
object
1 property
capture
object
A captured payment.
error_422
object
The requested action cannot be performed and may require interaction with APIs or processes outside of the current request. This is distinct from a 500 respons…
5 properties
store_in_vault_instruction
string
Defines how and when the payment source gets vaulted.
card_request
object
The payment card to use to fund a payment. Can be a credit or debit card. Note: Passing card number, cvv and expiry directly via the API requires PCI SAQ D com…
ip_address
string
An Internet Protocol address (IP address). This address assigns a numerical label to each device that is connected to a computer network through the Internet P…
orders.confirm-422
object
1 property
orders.confirm-400
object
1 property
merchant_partner_customer_id
string
The unique ID for a customer generated by PayPal.
amount_breakdown
object
The breakdown of the amount. Breakdown provides details such as total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.
7 properties
checkout_payment_intent
string
The intent to either capture payment immediately or authorize a payment for an order after order creation.
bic
string
The business identification code (BIC). In payments systems, a BIC is used to identify a specific business, most commonly a bank.
error_link_description
object
The request-related [HATEOAS link](/api/rest/responses/hateoas-links) information.
3 properties
2 required
token
object
The tokenized payment source to fund a payment.
2 properties
2 required
payment_source_response
object
The payment source used to fund the payment.
12 properties
orders.track.create-403
object
1 property
phone
object
The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en).
3 properties
2 required
vault_paypal_wallet_base
object
Resource consolidating common request and response attributes for vaulting PayPal Wallet.
1 required
error_default
The default error response.
money-2
object
The currency and amount for a financial transaction, such as a balance or payment due.
2 properties
2 required
vault_id
string
The PayPal-generated ID for the vaulted payment source. This ID should be stored on the merchant's server so the saved payment source can be used for future tr…
bin_details
object
Bank Identification Number (BIN) details used to fund a payment.
4 properties
apple_pay_request
object
Information needed to pay using ApplePay.
8 properties
401
object
1 property
full_name
string
The full name representation like Mr J Smith.
payee_base
object
The details for the merchant who receives the funds and fulfills the order. The merchant is also known as the payee.
2 properties
paypal_wallet_vault_response
object
The details about a saved PayPal Wallet payment source.
orders.authorize-422
object
1 property
iban_last_chars
string
The last characters of the IBAN used to pay.
seller_receivable_breakdown
object
The detailed breakdown of the capture activity. This is not available for transactions that are in pending state.
7 properties
1 required
sofort
object
Information used to pay using Sofort.
4 properties
card
object
The payment card to use to fund a payment. Can be a credit or debit card.
11 properties
venmo_wallet_attributes_response
object
Additional attributes associated with the use of a Venmo Wallet.
1 property
order_authorize_request
object
The authorization of an order request.
1 property
authentication_response
object
Results of Authentication such as 3D Secure.
4 properties
paypal_wallet_attributes_response
object
Additional attributes associated with the use of a PayPal Wallet.
2 properties
error_401
object
Authentication failed due to missing Authorization header, or invalid authentication credentials.
5 properties
refund_status_details
object
The details of the refund status.
1 property
card_stored_credential
object
Provides additional details to process a payment using a card that has been stored or is intended to be stored (also referred to as storedcredential or card-on…
4 properties
2 required
refund_status
object
The refund status.
2 properties
google_pay_request
email_address
string
The internationalized email address. Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accep…
date_time
string
The date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339section-5.6). Seconds are required while fractional seconds are option…
tax_info
object
The tax ID of the customer. The customer is also known as the payer. Both taxid and taxidtype are required.
2 properties
2 required
cobranded_card
object
Details about the merchant cobranded card used for order purchase.
3 properties
paypal_wallet_experience_context
object
Customizes the payer experience during the approval process for payment with PayPal. Note: Partners and Marketplaces might configure brandname and shippingpref…
8 properties
order_confirm_application_context
object
Customizes the payer confirmation experience.
5 properties
capture_status
object
The status of a captured payment.
2 properties
disbursement_mode
string
The funds that are held on behalf of the merchant.
language
string
The [language tag](https://tools.ietf.org/html/bcp47section-2) for the language in which to localize the error-related strings, such as messages, issues, and s…
venmo_wallet_experience_context
object
Customizes the buyer experience during the approval process for payment with Venmo. Note: Partners and Marketplaces might configure shippingpreference during p…
2 properties
payment_source
object
The payment source definition.
15 properties
currency_code-2
string
The [3-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency.
account_id
string
The account identifier for a PayPal account.
authorization_status
object
The status fields for an authorized payment.
2 properties
error_403
object
The client is not authorized to access this resource, although it may have valid credentials.
5 properties
authorization
object
The authorized payment transaction.
liability_shift
string
Liability shift indicator. The outcome of the issuer's authentication.
orders.patch-400
object
1 property
shipment_carrier
string
The carrier for the shipment. Some carriers have a global version as well as local subsidiaries. The subsidiaries are repeated over many countries and might al…
exchange_rate
object
The exchange rate that determines the amount to convert from one currency to another currency.
3 properties
instrument_id
string
The identifier of the instrument.
name
object
The name of the party.
7 properties
p24
object
Information used to pay using P24(Przelewy24).
6 properties
refund
object
The refund information.
three_d_secure_authentication_response
object
Results of 3D Secure Authentication.
2 properties
vault_instruction_base
object
Basic vault instruction specification that can be extended by specific payment sources that supports vaulting.
1 property
v3_vault_instruction_base
object
Base vaulting specification. The object can be extended for specific use cases within each paymentsource that supports vaulting.
1 property
1 required
order_request
object
The order request details.
5 properties
2 required
date_year_month
string
The year and month, in ISO-8601 YYYY-MM date format. See [Internet date and time format](https://tools.ietf.org/html/rfc3339section-5.6).
network_token_request
object
The Third Party Network token used to fund a payment.
5 properties
2 required
blik_experience_context
object
Customizes the payer experience during the approval process for the BLIK payment.
orders.authorize-400
object
1 property
bancontact_request
object
Information needed to pay using Bancontact.
4 properties
2 required
venmo_wallet_attributes
object
Additional attributes associated with the use of this Venmo Wallet.
2 properties
payment_method
object
The customer and merchant payment preferences.
2 properties
blik_seamless
object
Information used to pay using BLIK level0 flow.
1 property
1 required
account_id-2
string
The PayPal payer ID, which is a masked version of the PayPal account number intended for use with third parties. The account number is reversibly encrypted and…
payer_base
object
The customer who approves and pays for the order. The customer is also known as the payer.
2 properties
country_code
string
The [two-character ISO 3166-1 code](/api/rest/reference/country-codes/) that identifies the country or region. Note: The country code for Great Britain is GB a…
platform_fee
object
The platform or partner fee, commission, or brokerage fee that is associated with the transaction. Not a separate or isolated transaction leg from the external…
2 properties
1 required
orders.authorize-403
object
1 property
phone-2
object
The phone number in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en).
1 property
1 required
order_tracker_request
object
The tracking details of an order.
card_type
string
Type of card. i.e Credit, Debit and so on.
orders.capture-403
object
1 property
address_portable-2
object
The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) an…
10 properties
1 required
eci_flag
string
Electronic Commerce Indicator (ECI). The ECI value is part of the 2 data elements that indicate the transaction was processed electronically. This should be pa…
altpay_recurring_attributes
stored_payment_source_usage_type
string
Indicates if this is a first or subsequent payment using a stored payment source (also referred to as stored credential or card on file).
422
object
1 property
activity_timestamps
object
The date and time stamps that are common to authorized payment, captured payment, and refund transactions.
2 properties
mybank
object
Information used to pay using MyBank.
4 properties
name-2
object
The name of the party.
6 properties
universal_product_code
mybank_request
object
Information needed to pay using MyBank.
3 properties
2 required
error_404
object
The server has not found anything matching the request URI. This either means that the URI is incorrect or the resource is not available.
5 properties
phone_type
string
The phone type.
shipping_option
object
The options that the payee or merchant offers to the payer to ship or pick up their items.
5 properties
3 required
payment_collection
object
The collection of payments, or transactions, for a purchase unit in an order. For example, authorized payments, captured payments, and refunds.
3 properties
order_status
string
The order status.
vault_owner_id
blik_one_click_response
object
Information used to pay using BLIK one-click flow.
1 property
order
object
The order details.
authorization_with_additional_data
object
The authorization with additional payment details, such as risk assessment and processor response. These details are populated only for certain payment methods.
exemption_details
card_from_request
object
Representation of card details as received in the request.
2 properties
orders.capture-422
object
1 property
error_details
object
The error details. Required for client-side 4XX errors.
5 properties
1 required
stored_payment_source_payment_type
string
Indicates the type of the stored paymentsource payment.
processor_response
object
The processor response information for payment requests, such as direct credit card transactions.
4 properties
tracker_item
object
The details of the items in the shipment.
6 properties
payee
object
The merchant who receives the funds and fulfills the order. The merchant is also known as the payee.
card_supplementary_data
object
Merchants and partners can add Level 2 and 3 data to payments to reduce risk and payment processing costs. For more information about processing payments, see…
2 properties
purchase_unit_request
object
The purchase unit request. Includes required information for the payment contract.
11 properties
1 required
apple_pay_decrypted_token_data
object
Information about the Payment data obtained by decrypting Apple Pay token.
5 properties
1 required
phone_with_type
object
The phone information.
2 properties
1 required
amount_with_breakdown
object
The total order amount with an optional breakdown that provides details, such as the total item amount, total tax amount, shipping, handling, insurance, and di…
blik_request
object
Information needed to pay using BLIK.
6 properties
2 required
trustly
object
Information needed to pay using Trustly.
4 properties
error_503
object
The server is temporarily unable to handle the request, for example, because of planned maintenance or downtime.
4 properties
pares_status
string
Transactions status result identifier. The outcome of the issuer's authentication.
currency_code
string
The [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency.
orders.patch-422
object
1 property
card_experience_context
object
Customizes the payer experience during the 3DS Approval for payment.
2 properties
level_3_card_processing_data
object
The level 3 card processing data collections, If your merchant account has been configured for Level 3 processing this field will be passed to the processor on…
6 properties
order_authorize_response
object
The order authorize response.
payee_payment_method_preference
string
The merchant-preferred payment methods.
p24_request
object
Information needed to pay using P24 (Przelewy24).
4 properties
3 required
404
object
1 property
payment_initiator
string
The person or party who initiated or triggered the payment.
purchase_unit
object
The purchase unit details. Used to capture required information for the payment contract.
13 properties
email
string
The internationalized email address. Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accep…
vault_venmo_wallet_base
object
Resource consolidating common request and response attirbutes for vaulting Venmo Wallet.
1 required
error_500
object
This is either a system or application error, and generally indicates that although the client appeared to provide a correct request, something unexpected has…
4 properties
tracker_status
payer
object
The customer who approves and pays for the order. The customer is also known as the payer.
error_409
object
The server has detected a conflict while processing this request.
5 properties
403
object
1 property
blik
object
Information used to pay using BLIK.
4 properties
item
object
The details for the items to be purchased.
7 properties
3 required
shipment_tracker
object
The tracking information for a shipment.
14 properties
2 required
date_no_time
string
The stand-alone date, in [Internet date and time format](https://tools.ietf.org/html/rfc3339section-5.6). To represent special legal values, such as a date of…
eps_request
object
Information needed to pay using eps.
3 properties
2 required
payment_instruction
object
Any additional payment instructions to be consider during payment processing. This processing instruction is applicable for Capturing an order or Authorizing a…
4 properties
eps
object
Information used to pay using eps.
3 properties
customer
object
The details about a customer in PayPal's system of record.
3 properties
card_brand
string
The card network or brand. Applies to credit, debit, gift, and payment cards.
patch
object
The JSON patch object to apply partial updates to resources.
4 properties
1 required
card_attributes
object
Additional attributes associated with the use of this card.
2 properties
vault_response
object
The details about a saved payment source.
4 properties
stored_payment_source
object
Provides additional details to process a payment using a paymentsource that has been stored or is intended to be stored (also referred to as storedcredential o…
4 properties
2 required
enrolled
string
Status of Authentication eligibility.
shipment_tracking_status
string
The status of the item shipment. For allowed values, see Shipping Statuses .
url
string
Describes the URL.
giropay
object
Information needed to pay using giropay.
3 properties
level_2_card_processing_data
object
The level 2 card processing data collections. If your merchant account has been configured for Level 2 processing this field will be passed to the processor on…
2 properties
paypal_wallet
object
A resource that identifies a PayPal Wallet is used for payment.
10 properties
apple_pay_payment_data
object
Information about the decrypted apple pay payment data for the token like cryptogram, eci indicator.
4 properties
confirm_order_request
object
Payer confirms the intent to pay for the Order using the provided payment source.
3 properties
1 required
paypal_wallet_customer
object
The details about a customer in PayPal's system of record.
shipment_tracking_number_type
string
The tracking number type.
ideal_request
object
Information needed to pay using iDEAL.
5 properties
2 required
orders.track.create-422
object
1 property
400
object
1 property
giropay_request
object
Information needed to pay using giropay.
3 properties
2 required
error_location
string
The location of the field that caused the error. Value is body, path, or query.
blik_one_click
object
Information used to pay using BLIK one-click flow.
4 properties
1 required
patch_request
array
An array of JSON patch objects to apply partial updates to resources.
trustly_request
object
Information needed to pay using Trustly.
3 properties
2 required
money
object
The currency and amount for a financial transaction, such as a balance or payment due.
2 properties
2 required
capture_status_details
object
The details of the captured payment status.
1 property
billing_agreement_id
string
The PayPal billing agreement ID. References an approved recurring payment for goods or services.
card_response
object
The payment card to use to fund a payment. Card can be a credit or debit card.
10 properties
ideal
object
Information used to pay using iDEAL.
5 properties
address_portable
object
The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) an…
10 properties
1 required
paypal_wallet_response
object
The PayPal Wallet response.
10 properties
venmo_wallet_response
object
Venmo wallet response.
7 properties
card_attributes_response
object
Additional attributes associated with the use of this card.
1 property
shipping_type
string
A classification for the method of purchase fulfillment.
error_400
object
Request is not well-formed, syntactically incorrect, or violates schema.
5 properties
order_capture_request
object
Completes an capture payment for an order.
1 property
experience_context_base
object
Customizes the payer experience during the approval process for the payment.
5 properties
altpay_recurring_attributes_request
network_transaction_reference
object
Reference values used by the card network to identify a transaction.
4 properties
1 required
country_code-2
string
The [2-character ISO 3166-1 code](/api/rest/reference/country-codes/) that identifies the country or region. Note: The country code for Great Britain is GB and…
apple_pay_attributes
orders.track.create-400
object
1 property
seller_protection
object
The level of protection offered as defined by [PayPal Seller Protection for Merchants](https://www.paypal.com/us/webapps/mpp/security/seller-protection).
2 properties
shipping_with_tracking_details
object
The order shipping details.
line_item
object
The line items for this purchase. If your merchant account has been configured for Level 3 processing this field will be passed to the processor on your behalf.
error_415
object
The server does not support the request payload's media type.
5 properties
bancontact
object
Information used to pay Bancontact.
6 properties
phone_type-2
string
The phone type.
order_application_context
object
Customizes the payer experience during the approval process for the payment with PayPal. Note: Partners and Marketplaces might configure brandname and shipping…
9 properties
sofort_request
object
Information needed to pay using Sofort.
3 properties
2 required
authentication_flow
Specification
The full machine-readable OpenAPI contract behind this narrative.
Source
More from PayPal 12
Other APIs PayPal publishes across the network.
PayPal Activate API
PayPal Authorizations API
PayPal Balances API
PayPal Billing API
PayPal Cancel API
PayPal Capture API
PayPal Captures API
PayPal Deactivate API
PayPal Disputes-Actions API
PayPal Disputes API
PayPal Invoices API
PayPal Partner-Referrals API
#Order
Where this information came from
This is an independent, third-party profile of PayPal Orders API, published by API Evangelist. We do not operate, host, resell, or support these APIs, and we are not affiliated with or endorsed by the company unless stated above. Everything here is built from publicly available information — the company's own site, developer portal, documentation, public repositories, and the specifications it publishes for public use. Nothing is obtained by breaching a system, defeating an access control, or using credentials.
The Kin Score and Agent Readiness rating are independently calculated assessments of a company's public API artifacts, scored against a published rubric. They are not certifications, endorsements, security assessments, or audits.
Corrections, re-scores, and removal are free — no partnership or purchase required, and you do not need to justify the request. A removed company is recorded as unrated, never scored zero for having asked. Acknowledgement within one business day; removal within two.
info@apievangelist.com
·
Read the full data-sourcing policy →
On a security or compliance team? Put security in the subject line and
you will get a person, not a form — we will tell you exactly which public URLs this profile was built from.