PayPal Orders API
Use the `/orders` resource to create, update, retrieve, authorize, capture and track orders.
PayPal Orders API is one of 27 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.2.0, at version 2.13.
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 4 scopes.
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.
trustly_request
object
Information needed to pay using Trustly.
3 properties
2 required
order_status
string
The order status.
phone_type-2
string
The phone type.
apple_pay_request
object
Information needed to pay using ApplePay.
8 properties
orders.capture-403
object
1 property
shipping_detail
object
The shipping details.
4 properties
enrolled
string
Status of Authentication eligibility.
google_pay_request
401
object
1 property
apple_pay_payment_data
object
Information about the decrypted apple pay payment data for the token like cryptogram, eci indicator.
4 properties
payment_initiator
string
The person or party who initiated or triggered the payment.
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
url
string
Describes the URL.
error_default
The default error response.
address_portable-2
object
The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) an…
10 properties
1 required
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
shipment_tracker
object
The tracking information for a shipment.
14 properties
2 required
orders.track.create-403
object
1 property
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…
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
purchase_unit
object
The purchase unit details. Used to capture required information for the payment contract.
13 properties
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.
payment_source_response
object
The payment source used to fund the payment.
12 properties
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
disbursement_mode
string
The funds that are held on behalf of the merchant.
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
full_name
string
The full name representation like Mr J Smith.
altpay_recurring_attributes
trustly
object
Information needed to pay using Trustly.
4 properties
blik_experience_context
object
Customizes the payer experience during the approval process for the BLIK payment.
bancontact_request
object
Information needed to pay using Bancontact.
4 properties
2 required
ideal
object
Information used to pay using iDEAL.
5 properties
token
object
The tokenized payment source to fund a payment.
2 properties
2 required
iban_last_chars
string
The last characters of the IBAN used to pay.
liability_shift
string
Liability shift indicator. The outcome of the issuer's authentication.
error_400
object
Request is not well-formed, syntactically incorrect, or violates schema.
5 properties
checkout_payment_intent
string
The intent to either capture payment immediately or authorize a payment for an order after order creation.
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
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).
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…
paypal_wallet_vault_response
object
The details about a saved PayPal Wallet payment source.
three_d_secure_authentication_response
object
Results of 3D Secure Authentication.
2 properties
orders.confirm-422
object
1 property
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
order
object
The order details.
vault_response
object
The details about a saved payment source.
4 properties
paypal_wallet_response
object
The PayPal Wallet response.
10 properties
p24_request
object
Information needed to pay using P24 (Przelewy24).
4 properties
3 required
orders.capture-422
object
1 property
vault_venmo_wallet_base
object
Resource consolidating common request and response attirbutes for vaulting Venmo Wallet.
1 required
pares_status
string
Transactions status result identifier. The outcome of the issuer's authentication.
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
shipping_type
string
A classification for the method of purchase fulfillment.
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
400
object
1 property
payee_payment_method_preference
string
The merchant-preferred payment methods.
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
phone_type
string
The phone type.
order_tracker_request
object
The tracking details of an order.
network_transaction_reference
object
Reference values used by the card network to identify a transaction.
4 properties
1 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…
mybank_request
object
Information needed to pay using MyBank.
3 properties
2 required
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…
processing_instruction
string
The instruction to process an order.
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…
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…
vault_paypal_wallet_base
object
Resource consolidating common request and response attributes for vaulting PayPal Wallet.
1 required
instrument_id
string
The identifier of the instrument.
phone_with_type
object
The phone information.
2 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…
purchase_unit_request
object
The purchase unit request. Includes required information for the payment contract.
11 properties
1 required
order_authorize_request
object
The authorization of an order request.
1 property
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…
card_type
string
Type of card. i.e Credit, Debit and so on.
payer_base
object
The customer who approves and pays for the order. The customer is also known as the payer.
2 properties
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…
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
card_brand
string
The card network or brand. Applies to credit, debit, gift, and payment cards.
address_portable
object
The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) an…
10 properties
1 required
apple_pay_decrypted_token_data
object
Information about the Payment data obtained by decrypting Apple Pay token.
5 properties
1 required
venmo_wallet_attributes_response
object
Additional attributes associated with the use of a Venmo Wallet.
1 property
paypal_wallet_attributes_response
object
Additional attributes associated with the use of a PayPal Wallet.
2 properties
universal_product_code
403
object
1 property
order_authorize_response
object
The order authorize response.
patch
object
The JSON patch object to apply partial updates to resources.
4 properties
1 required
capture_status_details
object
The details of the captured payment status.
1 property
apple_pay_attributes
patch_request
array
An array of JSON patch objects to apply partial updates to resources.
giropay
object
Information needed to pay using giropay.
3 properties
cobranded_card
object
Details about the merchant cobranded card used for order purchase.
3 properties
sofort
object
Information used to pay using Sofort.
4 properties
experience_context_base
object
Customizes the payer experience during the approval process for the payment.
5 properties
ideal_request
object
Information needed to pay using iDEAL.
5 properties
2 required
giropay_request
object
Information needed to pay using giropay.
3 properties
2 required
authentication_response
object
Results of Authentication such as 3D Secure.
4 properties
error_503
object
The server is temporarily unable to handle the request, for example, because of planned maintenance or downtime.
4 properties
mybank
object
Information used to pay using MyBank.
4 properties
currency_code-2
string
The [3-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency.
bic
string
The business identification code (BIC). In payments systems, a BIC is used to identify a specific business, most commonly a bank.
blik
object
Information used to pay using BLIK.
4 properties
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
tracker_item
object
The details of the items in the shipment.
6 properties
card_from_request
object
Representation of card details as received in the request.
2 properties
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
error_401
object
Authentication failed due to missing Authorization header, or invalid authentication credentials.
5 properties
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
eps
object
Information used to pay using eps.
3 properties
paypal_wallet
object
A resource that identifies a PayPal Wallet is used for payment.
10 properties
authentication_flow
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
error_415
object
The server does not support the request payload's media type.
5 properties
orders.authorize-400
object
1 property
card_attributes_response
object
Additional attributes associated with the use of this card.
1 property
link_description
object
The request-related [HATEOAS link](/api/rest/responses/hateoas-links) information.
3 properties
2 required
capture
object
A captured payment.
exchange_rate
object
The exchange rate that determines the amount to convert from one currency to another currency.
3 properties
currency_code
string
The [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency.
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.
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…
order_confirm_application_context
object
Customizes the payer confirmation experience.
5 properties
merchant_partner_customer_id
string
The unique ID for a customer generated by PayPal.
refund_status
object
The refund status.
2 properties
refund_status_details
object
The details of the refund status.
1 property
p24
object
Information used to pay using P24(Przelewy24).
6 properties
account_id
string
The account identifier for a PayPal account.
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…
order_request
object
The order request details.
5 properties
2 required
error_403
object
The client is not authorized to access this resource, although it may have valid credentials.
5 properties
bin_details
object
Bank Identification Number (BIN) details used to fund a payment.
4 properties
store_in_vault_instruction
string
Defines how and when the payment source gets vaulted.
blik_seamless
object
Information used to pay using BLIK level0 flow.
1 property
1 required
blik_one_click_response
object
Information used to pay using BLIK one-click flow.
1 property
shipment_tracking_number_type
string
The tracking number type.
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
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
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
payment_method
object
The customer and merchant payment preferences.
2 properties
processor_response
object
The processor response information for payment requests, such as direct credit card transactions.
4 properties
error_details
object
The error details. Required for client-side 4XX errors.
5 properties
1 required
payee
object
The merchant who receives the funds and fulfills the order. The merchant is also known as the payee.
paypal_wallet_attributes
object
Additional attributes associated with the use of this PayPal Wallet.
2 properties
venmo_wallet_response
object
Venmo wallet response.
7 properties
card_response
object
The payment card to use to fund a payment. Card can be a credit or debit card.
10 properties
error_location
string
The location of the field that caused the error. Value is body, path, or query.
authorization_status_details
object
The details of the authorized payment status.
1 property
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
payment_source
object
The payment source definition.
15 properties
orders.track.create-422
object
1 property
orders.patch-400
object
1 property
shipment_tracking_status
string
The status of the item shipment. For allowed values, see Shipping Statuses .
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
authorization_status
object
The status fields for an authorized payment.
2 properties
stored_payment_source_payment_type
string
Indicates the type of the stored paymentsource payment.
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).
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
confirm_order_request
object
Payer confirms the intent to pay for the Order using the provided payment source.
3 properties
1 required
network_token_request
object
The Third Party Network token used to fund a payment.
5 properties
2 required
venmo_wallet_request
object
Information needed to pay using Venmo.
4 properties
customer
object
The details about a customer in PayPal's system of record.
3 properties
error_409
object
The server has detected a conflict while processing this request.
5 properties
authorization
object
The authorized payment transaction.
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…
order_capture_request
object
Completes an capture payment for an order.
1 property
vault_instruction_base
object
Basic vault instruction specification that can be extended by specific payment sources that supports vaulting.
1 property
altpay_recurring_attributes_request
money
object
The currency and amount for a financial transaction, such as a balance or payment due.
2 properties
2 required
card_attributes
object
Additional attributes associated with the use of this card.
2 properties
card
object
The payment card to use to fund a payment. Can be a credit or debit card.
11 properties
shipping_with_tracking_details
object
The order shipping details.
blik_request
object
Information needed to pay using BLIK.
6 properties
2 required
orders.confirm-400
object
1 property
sofort_request
object
Information needed to pay using Sofort.
3 properties
2 required
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…
422
object
1 property
error_link_description
object
The request-related [HATEOAS link](/api/rest/responses/hateoas-links) information.
3 properties
2 required
blik_one_click
object
Information used to pay using BLIK one-click flow.
4 properties
1 required
refund
object
The refund information.
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…
orders.authorize-422
object
1 property
money-2
object
The currency and amount for a financial transaction, such as a balance or payment due.
2 properties
2 required
orders.authorize-403
object
1 property
activity_timestamps
object
The date and time stamps that are common to authorized payment, captured payment, and refund transactions.
2 properties
billing_agreement_id
string
The PayPal billing agreement ID. References an approved recurring payment for goods or services.
venmo_wallet_attributes
object
Additional attributes associated with the use of this Venmo Wallet.
2 properties
name
object
The name of the party.
7 properties
orders.track.create-400
object
1 property
name-2
object
The name of the party.
6 properties
orders.patch-422
object
1 property
payer
object
The customer who approves and pays for the order. The customer is also known as the payer.
exemption_details
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
tracker_status
item
object
The details for the items to be purchased.
7 properties
3 required
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
capture_status
object
The status of a captured payment.
2 properties
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
paypal_wallet_customer
object
The details about a customer in PayPal's system of record.
eps_request
object
Information needed to pay using eps.
3 properties
2 required
tracker
object
The tracking response on creation of tracker.
404
object
1 property
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
vault_owner_id
bancontact
object
Information used to pay Bancontact.
6 properties
card_experience_context
object
Customizes the payer experience during the 3DS Approval for payment.
2 properties
orders.capture-400
object
1 property
Specification
The full machine-readable OpenAPI contract behind this narrative.
Source
More from PayPal 12
Other APIs PayPal publishes across the network.
PayPal Authorizations API
PayPal Balances API
PayPal Billing API
PayPal Captures API
PayPal Disputes-Actions API
PayPal Disputes API
PayPal Invoices API
PayPal Partner-Referrals API
PayPal Payment-Tokens API
PayPal Payouts API
PayPal Payouts-Item API
PayPal Products 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.