Orders API
Orders API integration note: The PayPal Commerce Platform is a limited-release solution aimed at partners, crowd funding, and multi-party commerce platforms. To use Orders API for Partners, see PayPal Commerce Platform for Platforms. v1 of the API will be deprecated soon. A new version is available at Orders API v2.
Orders (resource group)
Use the /checkout/orders
resource to create, cancel, and show details for orders.
Create order
Header parameters
PayPal-Partner-Attribution-Id
string
Request body
id
string
The ID of the order.
intent
enum
The intent.
The possible values are:
SALE
. A sale.AUTHORIZE
. An authorization.
An array of purchase units. Each purchase unit establishes a contract between a customer and merchant.
payment_details
The payment details for the order.
gross_total_amount
The currency and amount of the PayPal-computed total of amounts in all purchase units.
application_context
Customizes the payer experience during the approval process for the payment with PayPal.
Note: The PayPal Commerce Platform might configure
brand_name
andshipping_preference
during partner account setup, which overrides the request values.metadata
The name-and-value pairs that contain external data, such as user, user feedback, score, and so on.
status
enum
The status of the order. After the customer approves the order, the status is
APPROVED
. After the payment is made for the order and the order completes, the status isCOMPLETED
.The possible values are:
CREATED
. ThePOST /v1/checkout/orders
call succeeded and the order was created.APPROVED
. The customer approved the order.COMPLETED
. ThePOST /v1/checkout/orders/{order_id}/pay
call succeeded and the order was paid and is complete.FAILED
. The order failed.
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 theGET
method and do not use the link that shows theREDIRECT
method.
Sample Request
curl -v -X POST https://api-m.sandbox.paypal.com/v1/checkout/orders \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-H "PayPal-Partner-Attribution-Id: EXAMPLE_MP" \
-d '{
"purchase_units": [
{
"reference_id": "store_mobile_world_order_1234",
"description": "Mobile World Store order-1234",
"amount": {
"currency": "USD",
"details": {
"subtotal": "1.09",
"shipping": "0.02",
"tax": "0.33"
},
"total": "1.44"
},
"payee": {
"email": "seller@example.com"
},
"items": [
{
"name": "NeoPhone",
"sku": "sku03",
"price": "0.54",
"currency": "USD",
"quantity": "1"
},
{
"name": "Fitness Watch",
"sku": "sku04",
"price": "0.55",
"currency": "USD",
"quantity": "1"
}
],
"shipping_address": {
"line1": "2211 N First Street",
"line2": "Building 17",
"city": "San Jose",
"country_code": "US",
"postal_code": "95131",
"state": "CA",
"phone": "(123) 456-7890"
},
"shipping_method": "United Postal Service",
"partner_fee_details": {
"receiver": {
"email": "partner@example.com"
},
"amount": {
"value": "0.01",
"currency": "USD"
}
},
"payment_linked_group": 1,
"custom": "custom_value_2388",
"invoice_number": "invoice_number_2388",
"payment_descriptor": "Payment Mobile World"
}
],
"redirect_urls": {
"return_url": "https://example.com/return",
"cancel_url": "https://example.com/cancel"
}
}'
Response
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.
The possible values are:
SALE
. A sale.AUTHORIZE
. An authorization.
purchase_units
array (contains the purchase_unit object)
An array of purchase units. Each purchase unit establishes a contract between a customer and merchant.
payment_details
The payment details for the order.
gross_total_amount
The currency and amount of the PayPal-computed total of amounts in all purchase units.
application_context
Customizes the payer experience during the approval process for the payment with PayPal.
Note: The PayPal Commerce Platform might configure
brand_name
andshipping_preference
during partner account setup, which overrides the request values.metadata
The name-and-value pairs that contain external data, such as user, user feedback, score, and so on.
status
enum
The status of the order. After the customer approves the order, the status is
APPROVED
. After the payment is made for the order and the order completes, the status isCOMPLETED
.The possible values are:
CREATED
. ThePOST /v1/checkout/orders
call succeeded and the order was created.APPROVED
. The customer approved the order.COMPLETED
. ThePOST /v1/checkout/orders/{order_id}/pay
call succeeded and the order was paid and is complete.FAILED
. The order failed.
redirect_urls
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 theGET
method and do not use the link that shows theREDIRECT
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"
},
{
"name": "Fitness Watch",
"sku": "sku04",
"price": "0.55",
"currency": "USD",
"quantity": "1"
}
],
"shipping_address": {
"recipient_name": "John Doe",
"default_address": false,
"preferred_address": false,
"primary_address": false,
"disable_for_transaction": false,
"line1": "2211 N First Street",
"line2": "Building 17",
"city": "San Jose",
"country_code": "US",
"postal_code": "95131",
"state": "CA",
"phone": "(123) 456-7890"
},
"shipping_method": "United Postal Service",
"partner_fee_details": {
"receiver": {
"email": "partner@example.com"
},
"amount": {
"value": "0.01",
"currency": "USD"
}
},
"payment_linked_group": 1,
"custom": "custom_value_2388",
"invoice_number": "invoice_number_2388",
"payment_descriptor": "Payment Mobile World",
"status": "CAPTURED"
}
],
"redirect_urls": {
"return_url": "https://example.com/return",
"cancel_url": "https://example.com/cancel"
},
"create_time": "2017-04-26T21:18:49Z",
"links": [
{
"href": "https://api-m.paypal.com/v1/checkout/orders/8RU61172JS455403V",
"rel": "self",
"method": "GET"
},
{
"href": "https://api-m.paypal.com/webapps/hermes?token=8RU61172JS455403V",
"rel": "approval_url",
"method": "GET"
},
{
"href": "https://api-m.paypal.com/v1/checkout/orders/8RU61172JS455403V",
"rel": "cancel",
"method": "DELETE"
}
],
"status": "CREATED"
}
Cancel order
CREATED
or APPROVED
.Path parameters
order_id
string
required
The ID of the order to cancel.
Sample Request
curl -v -X DELETE https://api-m.sandbox.paypal.com/v1/checkout/orders/8SC68793353299025 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
Response
204 No Content
status code with no JSON response body. If the order is already paid, the order cannot be canceled and the request returns the HTTP 422 Unprocessable Entity
status code with the message, This order is in progress
.Sample Response
204 No Content
Show order details
Path parameters
order_id
string
required
The ID of the order for which to show details.
Sample Request
curl -v -X GET https://api-m.sandbox.paypal.com/v1/checkout/orders/8SC68793353299025 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
Response
200 OK
status code and a JSON response body that shows order details.id
string
The ID of the order.
intent
enum
The intent.
The possible values are:
SALE
. A sale.AUTHORIZE
. An authorization.
purchase_units
array (contains the purchase_unit object)
An array of purchase units. Each purchase unit establishes a contract between a customer and merchant.
payment_details
The payment details for the order.
gross_total_amount
The currency and amount of the PayPal-computed total of amounts in all purchase units.
application_context
Customizes the payer experience during the approval process for the payment with PayPal.
Note: The PayPal Commerce Platform might configure
brand_name
andshipping_preference
during partner account setup, which overrides the request values.metadata
The name-and-value pairs that contain external data, such as user, user feedback, score, and so on.
status
enum
The status of the order. After the customer approves the order, the status is
APPROVED
. After the payment is made for the order and the order completes, the status isCOMPLETED
.The possible values are:
CREATED
. ThePOST /v1/checkout/orders
call succeeded and the order was created.APPROVED
. The customer approved the order.COMPLETED
. ThePOST /v1/checkout/orders/{order_id}/pay
call succeeded and the order was paid and is complete.FAILED
. The order failed.
redirect_urls
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 theGET
method and do not use the link that shows theREDIRECT
method.
Sample Response
{
"id": "8SC68793353299025",
"status": "CREATED",
"gross_total_amount": {
"value": "1.44",
"currency": "USD"
},
"application_context": {},
"purchase_units": [
{
"reference_id": "store_mobile_world_order_1234",
"description": "Mobile World Store order-1234",
"amount": {
"currency": "USD",
"details": {
"subtotal": "1.09",
"shipping": "0.02",
"tax": "0.33"
},
"total": "1.44"
},
"payee": {
"email": "seller@example.com"
},
"items": [
{
"name": "NeoPhone",
"sku": "sku03",
"price": "0.54",
"currency": "USD",
"quantity": 1
},
{
"name": "Fitness Watch",
"sku": "sku04",
"price": "0.55",
"currency": "USD",
"quantity": 1
}
],
"shipping_address": {
"line1": "2211 N First Street",
"line2": "Building 17",
"city": "San Jose",
"country_code": "US",
"postal_code": "95131",
"state": "CA",
"phone": "(123) 456-7890"
},
"shipping_method": "United Postal Service",
"partner_fee_details": {
"receiver": {
"email": "partner@example.com"
},
"amount": {
"value": "0.01",
"currency": "USD"
}
},
"payment_linked_group": 1,
"custom": "custom_value_2388",
"invoice_number": "invoice_number_2388",
"payment_descriptor": "Payment Mobile World",
"status": "NOT_PROCESSED"
}
],
"redirect_urls": {
"return_url": "https://example.com/return",
"cancel_url": "https://example.com/cancel"
},
"links": [
{
"href": "https://api-m.paypal.com/v1/checkout/orders/8SC68793353299025",
"rel": "self",
"method": "GET"
},
{
"href": "https://www.paypal.com/checkoutnow?token=8SC68793353299025",
"rel": "approval_url",
"method": "REDIRECT"
}
],
"create_time": "2018-09-21T17:22:45Z"
}
Orders payment actions (resource group)
Use the /checkout/orders
resource with the /pay
action to pay for an order. When you create an order, the response includes an approval URL. Redirect the customer to this approval URL.
Pay for order
Note: For Partner use cases, use the disbursement_mode
to indicate whether to disburse funds to the seller and partner accounts immediately or later. If you delay disbursement, you must call disburse funds to disburse funds to the merchant and partner.
Header parameters
PayPal-Partner-Attribution-Id
string
PayPal-Request-Id
string
The server stores keys forever.
Path parameters
order_id
string
required
The ID of the order for which to execute a payment.
Request body
disbursement_mode
enum
required
Indicates whether to disburse money instantly or later.
The possible values are:
INSTANT
. Money is disbursed instantly.DELAYED
. Money will be disbursed later.
payer
The source of the funds for this payment. Either a PayPal account or a credit card.
Sample Request
curl -v -X POST https://api-m.sandbox.paypal.com/v1/checkout/orders/8SC68793353299025/pay \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
Response
202 Accepted
status code and a JSON response body that shows order and payment details.Note: Applies to existing asynchronous payment processing integrations.
order_id
string
The ID of the order.
status
enum
The status of the order.
The possible values are:
APPROVED
. The order is approved.CANCELED
. The order is canceled.COMPLETED
. The order is completed.CREATED
. The order is created.EXPIRED
. The order is expired.FAILED
. The order FAILED.IN_PROGRESS
. The order is in progress.PARTIALLY_COMPLETED
. The order is partially completed.SUBMITTED
. The order was submitted.
intent
enum
The intent.
The possible values are:
SALE
. A sale.AUTHORIZE
. An authorization.
payer_info
The payer information.
purchase_units
array (contains the purchase_unit object)
An array of purchase units. Each purchase unit establishes a contract between a customer and merchant.
create_time
string
The date and time when the resource was created, in Internet date and time format.
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": "76T08342AW176740Y",
"status": "APPROVED",
"payer_info": {
"email": "buyer@example.com",
"first_name": "Robert",
"last_name": "Lesley",
"payer_id": "HPQAUP5WC3J8U",
"phone": "7028530329",
"country_code": "US",
"shipping_address": {
"recipient_name": "Robert Lesley",
"line1": "2211 N First Street",
"line2": "Building 17",
"city": "San Jose",
"country_code": "US",
"postal_code": "95131",
"state": "CA"
}
},
"create_time": "2018-09-21T17:33:18Z",
"update_time": "2018-09-21T17:33:18Z",
"links": [
{
"href": "https://api-m.paypal.com/v1/checkout/orders/76T08342AW176740Y",
"rel": "self",
"method": "GET"
}
]
}
Common object definitions
address
line1
string
required
The first line of the address. For example, number, street, and so on.
line2
string
The second line of the address. For example, suite or apartment number.
city
string
The city name.
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is
GB
and notUK
as used in the top-level domain names for that country. Use theC2
country code for China worldwide for comparable uncontrolled price (CUP) method, 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
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.
type
string
The type of address. For example,
HOME_OR_WORK
,GIFT
, and so on.
amount
currency
string
required
The three-character ISO-4217 currency code. PayPal does not support all currencies.
total
string
required
The total amount charged to the payee by the payer. For refunds, represents the amount that the payee refunds to the original payer. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
details
The additional details about the payment amount.
application_context
brand_name
string
The label that overrides the business name in the PayPal account on the PayPal pages.
locale
The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code.
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 toLogin
.shipping_preference
enum
The shipping preferences.
The possible values are:
NO_SHIPPING
. Redact shipping address fields from the PayPal pages. Recommended for digital goods.GET_FROM_FILE
. Use the buyer-selected shipping address.SET_PROVIDED_ADDRESS
. Use the merchant-provided address. Buyer cannot change the address on the PayPal pages. If the merchant does not pass an address, the buyer can choose the address on PayPal pages.
user_action
string
Defines whether to present the customer with a Continue or Pay Now checkout flow. To present buyers with the Pay Now checkout flow, set
useraction=commit
. Default is the Continue checkout flow.Checkout flow Choose when Description Continue You do not know the final payment amount when you initiate the checkout flow. The default flow. Redirects the customer to the PayPal payment page, which shows the Continue button. When the customer clicks Continue, the customer can change the payment amount. Pay Now You know the final payment amount when you initiate the checkout flow. Set user_action=commit
. Redirects the customer to the PayPal payment page, which shows the Pay Now button. When the customer clicks Pay Now, the payment is processed immediately.supplementary_data
array (contains the name_value_pair object)
An array of name-and-value pairs that contain supplementary data required by PayPal for transaction processing.
capture
id
string
The ID of the capture transaction.
amount
The amount to capture. Default is the authorization amount. If that amount is the same as the authorized amount, the authorization state changes to
CAPTURED
. Otherwise, the authorization state changes toPARTIALLY_CAPTURED
. To indicate that this capture is the final capture, setis_final_capture
totrue
.status
enum
The status of the capture transaction.
The possible values are:
PENDING
. The purchase unit status isCAPTURED
and the capture status is pending.COMPLETED
. The purchase unit status isCAPTURED
and the payment was captured successfully.REFUNDED
. The purchase unit status isCAPTURED
and the dispute decision was in the customer's favor. A full refund for the captured payment was made successfully to the customer.PARTIALLY_REFUNDED
. The purchase unit status isCAPTURED
and the dispute decision was in the customer's favor. A partial refund for the captured payment was made successfully to the customer.DENIED
. The purchase unit status isCAPTURED
and the capture was denied.
reason_code
enum
A reason code that indicates the reason for the transaction state of
PENDING
orREVERSED
.The possible values are:
CHARGEBACK
. The transaction state isPENDING
orREVERSED
due to a chargeback.GUARANTEE
. The transaction state isPENDING
orREVERSED
due to a guarantee.BUYER_COMPLAINT
. The transaction state isPENDING
orREVERSED
due to a buyer complaint.REFUND
. The transaction state isPENDING
orREVERSED
due to a refund.UNCONFIRMED_SHIPPING_ADDRESS
. The transaction state isPENDING
orREVERSED
due to an unconfirmed shipping address.ECHECK
. The transaction state isPENDING
orREVERSED
due to an e-check.INTERNATIONAL_WITHDRAWAL
. The transaction state isPENDING
orREVERSED
due to an international withdrawal.RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION
. The transaction state isPENDING
orREVERSED
due to a receiving preference that mandates manual action.PAYMENT_REVIEW
. The transaction state isPENDING
orREVERSED
due to a payment review.REGULATORY_REVIEW
. The transaction state isPENDING
orREVERSED
due to a regulatory review.UNILATERAL
. The transaction state isPENDING
orREVERSED
due to a unilateral reason.VERIFICATION_REQUIRED
. The transaction state isPENDING
orREVERSED
because verification is required.DELAYED_DISBURSEMENT
. The transaction state isPENDING
orREVERSED
due to a delayed disbursement.
transaction_fee
The currency and amount of the transaction fee.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
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 notUK
as used in the top-level domain names for that country. Use theC2
country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
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
, oramex
. Do not use these lowercase values for display.expire_month
integer
required
The expiration month with no leading zero. Value is from
1
to12
.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
The billing address for 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 and can be any value, such as a UUID, user name, or email address. Required when you use a vaulted credit card and if a
payer_id
was originally provided when you vaulted the credit card.last4
string
The last four digits of the stored credit card number.
type
string
The credit card type. Value is
visa
,mastercard
,discover
, oramex
. Do not use these lowercase values for display.expire_month
integer
The expiration month with no leading zero. Value is from
1
to12
.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. Includes the specified number of digits after decimal separator for the ISO-4217 currency code.
currency_code
currency_code
string
The three-character ISO-4217 currency code that identifies the currency.
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.
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.
conversion_type
enum
The conversion type to apply.
conversion_type_changeable
boolean
Indicates whether the payer can 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.
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, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
shipping
string
The shipping fee. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
tax
string
The tax. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
handling_fee
string
The handling fee. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
shipping_discount
string
The shipping fee discount. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
insurance
string
The insurance fee. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
gift_wrap
string
The gift wrap fee. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
display_phone
country_code
string
The two-character IS0-3166-1 country code of the payee's country.
number
string
The in-country phone number, in E.164 numbering plan format.
error
name
string
required
The human-readable, unique name of the error.
message
string
required
The message that describes the error.
debug_id
string
required
The PayPal internal ID that is used for correlation purposes.
information_link
string
The information link, or URI, that shows detailed information about this error for the developer.
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. Value is
body
,path
, orquery
.issue
string
required
The unique and fine-grained application-level error code.
description
string
The human-readable description for an issue. The description MAY change over the lifetime of an API, so clients MUST NOT depend on this value.
funding_detail
clearing_time
string
The date and time when the funds are expected to clear, in Internet date and time format.
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.
funding_source
credit_card
Deprecated. The credit card details. You can use this instrument to fund a payment. Use a payment card instead.
credit_card_token
The tokenized credit card details. You can use this instrument to fund a payment.
funding_mode
string
required
The funding mode of the funding source.
funding_instrument_type
string
required
The instrument type for this funding source.
soft_descriptor
string
The soft descriptor for charging this funding source.
The amount and currency of the total to pull from the funding source.
negative_balance_amount
The additional amount to pull from the source to recover a negative balance on the buyer's account that is owed to PayPal.
legal_text
string
The localized legal text for the funding source.
terms
string
The URL to legal terms for the funding source.
funding_detail
The additional details for the funding source.
funding_selection_preference
string
The preferred way to select this funding source.
additional_text
string
Additional text for the funding source.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
installment_info
installment_id
string
The installment ID.
network
enum
The credit card network.
issuer
string
The credit card issuer.
An array of installment options and the cost associated with each one.
installment_option
instrument_attribute
type
enum
The type of metadata to be return for Funding instrument.
The possible values are:
PAYER_DISCLAIMER
. payer disclaimer regarding sharing instrument detail to merchant.COBRAND_CARD_LABEL
. Brand Label Info for instrument.
value
string
Value of metadata for given type.
item
sku
string
The stock keeping unit (SKU) for the item.
name
string
required
The item name. Maximum length is 127 characters.
description
string
The item description. Supported only for the PayPal payment method.
quantity
string
required
The item quantity. Must be a whole number.
price
string
required
The item cost. Supports two decimal places.
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
language
string
The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code.
link_description
href
string
required
The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the
$
,(
, and)
characters. Thehref
is the key HATEOAS component that links a completed call with a subsequent call.rel
string
required
The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
method
enum
The HTTP method required to make the related call.
metadata
supplementary_data
array (contains the name_value_pair object)
An array of name-and-value pairs that contain data required by PayPal for transaction processing.
money
The three-character ISO-4217 currency code that identifies the currency.
value
string
required
The value, which might be:
- An integer for currencies like
JPY
that are not typically fractional. - A decimal fraction for currencies like
TND
that are subdivided into thousandths.
- An integer for currencies like
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.
The possible values are:
SALE
. A sale.AUTHORIZE
. An authorization.
An array of purchase units. Each purchase unit establishes a contract between a customer and merchant.
payment_details
The payment details for the order.
gross_total_amount
The currency and amount of the PayPal-computed total of amounts in all purchase units.
application_context
Customizes the payer experience during the approval process for the payment with PayPal.
Note: The PayPal Commerce Platform might configure
brand_name
andshipping_preference
during partner account setup, which overrides the request values.metadata
The name-and-value pairs that contain external data, such as user, user feedback, score, and so on.
status
enum
The status of the order. After the customer approves the order, the status is
APPROVED
. After the payment is made for the order and the order completes, the status isCOMPLETED
.The possible values are:
CREATED
. ThePOST /v1/checkout/orders
call succeeded and the order was created.APPROVED
. The customer approved the order.COMPLETED
. ThePOST /v1/checkout/orders/{order_id}/pay
call succeeded and the order was paid and is complete.FAILED
. The order failed.
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 theGET
method and do not use the link that shows theREDIRECT
method.
pay_order_request
disbursement_mode
enum
required
Indicates whether to disburse money instantly or later.
The possible values are:
INSTANT
. Money is disbursed instantly.DELAYED
. Money will be disbursed later.
payer
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.
The possible values are:
APPROVED
. The order is approved.CANCELED
. The order is canceled.COMPLETED
. The order is completed.CREATED
. The order is created.EXPIRED
. The order is expired.FAILED
. The order FAILED.IN_PROGRESS
. The order is in progress.PARTIALLY_COMPLETED
. The order is partially completed.SUBMITTED
. The order was submitted.
intent
enum
The intent.
The possible values are:
SALE
. A sale.AUTHORIZE
. An authorization.
payer_info
The payer information.
purchase_units
array (contains the purchase_unit object)
An array of purchase units. Each purchase unit establishes a contract between a customer and merchant.
create_time
string
The date and time when the resource was created, in Internet date and time format.
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. For an intent of authorize or order, the email address must be associated with a confirmed PayPal business account. For an intent of sale, the email can either:
- Be associated with a confirmed PayPal personal or business account.
- Not be associated with a PayPal account.
merchant_id
string
The encrypted PayPal account ID for the payee.
payee_display_metadata
The display-only metadata for the payee.
payee_display_metadata
email
string
The email address for the payer. Maximum length is 127 characters.
display_phone
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.
status
enum
The status of payer's PayPal account.
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
orcredit_card_token
object. If the array contains more than one instrument, the payment is declined.payer_info
The payer information.
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.
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.
tax_id_type
enum
The payer’s tax ID type. Supported for the PayPal payment method only.
country_code
string
The payer's two-character IS0-3166-1 country code.
billing_address
The payer's billing address.
shipping_address
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 the payment instantly or delay the payment.
The possible values are:
INSTANT
. The payment is disbursed instantly.DELAYED
. The payment is 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
The percentage as a fixed-point, signed decimal value. Use for all interest rates. For example, specify an interest rate of 19.99% as
19.99
. The allowed number formats are plain decimal numbers and whole numbers.
purchase_unit
reference_id
string
required
The merchant ID for the purchase unit.
The amount to collect.
payee
The recipient of the funds for this transaction.
description
string
The purchase description.
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.
invoice_number
string
The API caller-provided external invoice ID for this order.. Only supported for the PayPal payment method.
payment_descriptor
string
The payment descriptor on the buyer credit card statement of account activity.
items
array (contains the item object)
An array of items that the customer is purchasing from the merchant.
notify_url
string
The payment notifications URL.
The shipping address details.
shipping_method
string
The shipping method. For example,
USPSParcel
.partner_fee_details
The partner fee that is collected for the original transaction.
payment_linked_group
integer
An ID that groups multiple linked purchase units. The purchase transactions are linked only for the payment and not for refund. A refund is processed only for the specific transaction within the same linked group.
metadata
The name-and-value pairs that contain external data, such as user, user feedback, score, and so on.
payment_summary
The payment summary.
status
enum
The transaction state.
The possible values are:
NOT_PROCESSED
. The transaction was not processed.PENDING
. The transaction is pending.VOIDED
. The transaction was declined and voided.AUTHORIZED
. Payment for the transaction was not authorized.CAPTURED
. Payment for the transaction was captured or is pending capture.
reason_code
enum
The reason code for a transaction status of
PENDING
orREVERSED
. Eventually, this field will replacepending_reason
. Supported only for the PayPal payment method.The possible values are:
PAYER_SHIPPING_UNCONFIRMED
. The transaction state isPENDING
orREVERSED
due to an unconfirmed payer shipping address.MULTI_CURRENCY
. The transaction state isPENDING
orREVERSED
because it is a multi-currency transaction.RISK_REVIEW
. The transaction state isPENDING
orREVERSED
due to a risk review.REGULATORY_REVIEW
. The transaction state isPENDING
orREVERSED
due to a regulatory review.VERIFICATION_REQUIRED
. The transaction state isPENDING
orREVERSED
because verification is required.ORDER
. The transaction state isPENDING
orREVERSED
because the transaction is an order.OTHER
. The transaction state isPENDING
orREVERSED
due to another reason.DECLINED_BY_POLICY
. The transaction state isPENDING
orREVERSED
because it was declined by a policy.
redirect_urls
return_url
string
The URL where the payer is redirected after the payer approves the payment.
cancel_url
string
The URL where the payer is redirected after the payer cancels the payment.
refund
id
string
The ID of the refund transaction. Maximum length is 17 characters.
amount
The amount that is refunded to the payer and the amount that is refunded to the payee. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
capture_id
string
The ID of the sale transaction to refund.
sale_id
string
The ID of the sale transaction to refund.
status
enum
The status of the refund.
The possible values are:
PENDING
. The refund is pending.COMPLETED
. The refund completed.FAILED
. The refund 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
The amount to collect. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
transaction_fee
The currency and amount of the transaction fee. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.
status
enum
The status of the sale transaction.
The possible values are:
COMPLETED
. The sale completed.PARTIALLY_REFUNDED
. The sale was partially refunded.PENDING
. The sale is pending.REFUNDED
. The sale was refunded.DENIED
. The sale was denied.
reason_code
enum
A reason code that indicates the reason for the transaction state of
PENDING
orREVERSED
.The possible values are:
CHARGEBACK
. The transaction state isREVERSED
due to a chargeback.GUARANTEE
. The transaction state isREVERSED
due to a guarantee.BUYER_COMPLAINT
. The transaction state isREVERSED
due to a buyer complaint.REFUND
. The transaction state isREVERSED
due to a refund.UNCONFIRMED_SHIPPING_ADDRESS
. The transaction state isPENDING
orREVERSED
due to an unconfirmed shipping address.ECHECK
. The transaction state isPENDING
due to an e-check.INTERNATIONAL_WITHDRAWAL
. The transaction state isPENDING
due to an international withdrawal.RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION
. The transaction state isPENDING
due to a receiving preference that mandates manual action.PAYMENT_REVIEW
. The transaction state isPENDING
due to a payment review.REGULATORY_REVIEW
. The transaction state isPENDING
due to a regulatory review.UNILATERAL
. The transaction state isPENDING
due to a unilateral reason.VERIFICATION_REQUIRED
. The transaction state isPENDING
because verification is required.DELAYED_DISBURSEMENT
. The transaction state isPENDING
due to a delayed disbursement.
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
The second line of the address. For example, suite or apartment number.
city
string
The city name.
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is
GB
and notUK
as used in the top-level domain names for that country. Use theC2
country code for China worldwide for comparable uncontrolled price (CUP) method, 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
phone
string
The phone number, in E.123 format. Maximum length is 50 characters.
normalization_status
string
The address normalization status. Returned only for payers from Brazil.
type
string
The type of address. For example,
HOME_OR_WORK
,GIFT
, and so on.
recipient_name
string
The name of the recipient at this address.
Additional API information
Error messages
In addition to the common HTTP status codes that the REST APIs return, the Orders API can return the following errors.