Partners can use the Orders API to create, show details for, authorize, and capture payment for orders.
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 Multiparty Payments. v1 of the API will be deprecated soon. A new version is available at Orders API v2.
Creates an order.
A successful request returns the HTTP 200 OK
status code and a JSON response body that includes the PayPal-generated order ID, an array of purchase unit objects, payment details, customer information, metadata, and order status.
curl -v -X POST https://api-m.sandbox.paypal.com/v1/checkout/orders \ \ -d '{ "application_context": { "locale": "en-US", "brand_name": "walmart", "landing_page": "billing", "user_action": "continue", "supplementary_data": [ { "name": "risk_correlation_id", "value": "9N8554567F903282T" }, { "name": "buyer_ipaddress", "value": "109.20.212.116" }, { "name": "external_channel", "value": "WEB" } ] }, "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" } }'
{- "id": "8RU61172JS455403V",
- "gross_total_amount": {
- "value": "1.44",
- "currency": "USD"
}, - "application_context": {
- "locale": "en-US",
- "brand_name": "walmart",
- "landing_page": "billing",
- "user_action": "continue",
- "supplementary_data": [
- {
- "name": "risk_correlation_id",
- "value": "9N8554567F903282T"
}, - {
- "name": "buyer_ipaddress",
- "value": "109.20.212.116"
}, - {
- "name": "external_channel",
- "value": "WEB"
}
]
}, - "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": {
}, - "create_time": "2017-04-26T21:18:49Z",
- "links": [
- {
- "rel": "self",
- "method": "GET"
}, - {
- "rel": "approval_url",
- "method": "GET"
}, - {
- "rel": "cancel",
- "method": "DELETE"
}
], - "status": "CREATED"
}
Shows details for an order, by ID.
A successful request returns the HTTP 200 OK
status code and a JSON response body that shows order details.
curl -v -X GET https://api-m.sandbox.paypal.com/v1/checkout/orders/8SC68793353299025 \ -H 'Authorization: Bearer access_token6V7rbVwmlM1gFZKW_8QtzWXqpcwQ6T5vhEGYNJDAAdn3paCgRpdeMdVYmWzgbKSsECednupJ3Zx5Xd-g'
{- "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": {
}, - "links": [
- {
- "rel": "self",
- "method": "GET"
}, - {
- "rel": "approval_url",
- "method": "POST"
}
], - "create_time": "2018-09-21T17:22:45Z"
}
Cancels an order, by ID, and deletes the order. To call this method, the order status must be CREATED
or APPROVED
.
A successful request returns the HTTP 204 No Content
status code with no JSON response body. If the order is already paid, the order cannot be canceled and the request returns the HTTP 422 Unprocessable Entity
status code with the message, This order is in progress
.
curl -v -X DELETE https://api-m.sandbox.paypal.com/v1/checkout/orders/8SC68793353299025 \ -H 'Authorization: Bearer access_token6V7rbVwmlM1gFZKW_8QtzWXqpcwQ6T5vhEGYNJDAAdn3paCgRpdeMdVYmWzgbKSsECednupJ3Zx5Xd-g'
Initiates a PayPal payment that a buyer has approved.
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.
A successful request returns the HTTP 200 OK
status code and a JSON response body that shows order and payment details.
curl -v -X POST https://api-m.sandbox.paypal.com/v1/checkout/orders/8SC68793353299025/pay \ -H 'Authorization: Bearer access_token6V7rbVwmlM1gFZKW_8QtzWXqpcwQ6T5vhEGYNJDAAdn3paCgRpdeMdVYmWzgbKSsECednupJ3Zx5Xd-g' \ -d '{}'
{- "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": [
- {
- "rel": "self",
- "method": "GET"
}
]
}
Message:
Account cannot be fetched.
Description:
The server cannot get the partner or seller account information. The account is either not available or incorrect. The API returns this error for seller accounts when you do not enable onboarding after buyers make purchases for the associated partner.
Message:
An internal server error occurred.
Description:
A system or application error occurred. Although the client appears to provide a correct request, something unexpected occurred on the server. A 500
response indicates a server-side software defect or site outage.
Message:
The request is not well-formed, is syntactically incorrect, or violates schema.
Description:
The server did not understand the request because the API could not convert the payload data to the underlying data type, the data was not in the expected data format, the required field was not available, or a simple data validation error occurred. See Validation errors.
Message:
Authorization failed due to insufficient permissions.
Description:
The client is not authorized to access this resource although it might have valid credentials. For example, the client does not have the correct OAuth2 scope. Additionally, a business-level authorization error might have occurred. For example, the account holder does not have sufficient funds.
Message:
Payer has not approved payment.
Description:
The API created the order. However, the customer has not approved the payment.
Message:
The specified resource does not exist.
Description:
The server did not find anything that matches the request URI. Either the URI is incorrect or the resource is not available. For example, no data exists in the database at that key.
Message:
Authentication failed due to invalid authentication credentials.
Description:
The request requires authentication and the caller did not provide valid authentication credentials. Note the difference between this error and the NOT_AUTHORIZED
error. See Authentication errors.
Message:
Required field is missing.
Description:
The server did not understand the request because the API could not convert the payload data to the underlying data type, the data was not in the expected data format, the required field was not available, or a simple data validation error occurred. See Validation errors.
The billing address or shipping address for a payment.
line1 required | string 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. |
country_code required | string <ppaas_common_country_code_v2> (country_code) = 2 characters ^([A-Z]{2}|C2)$ The two-character ISO 3166-1 code that identifies the country or region. Note: The country code for Great Britain is |
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 | |
phone | string <phone> 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, |
{- "line1": "string",
- "line2": "string",
- "city": "string",
- "country_code": "st",
- "postal_code": "string",
- "state": "string",
- "phone": "string",
- "normalization_status": "UNKNOWN",
- "type": "string"
}
The payment amount, with details.
currency required | string The three-character ISO-4217 currency code. PayPal does not support all currencies. |
total required | string 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:
|
object (Payment Amount Details) The additional details about the payment amount. |
{- "currency": "string",
- "total": "string",
- "details": {
- "subtotal": "string",
- "shipping": "string",
- "tax": "string",
- "handling_fee": "string",
- "shipping_discount": "string",
- "insurance": "string",
- "gift_wrap": "string"
}
}
Customizes the payer experience during the approval process for the payment with PayPal.
Note: The PayPal Commerce Platform might configurebrand_name
andshipping_preference
during partner account setup, which overrides the request values.
brand_name | string <= 127 characters The label that overrides the business name in the PayPal account on the PayPal pages. | |||||||||
locale | string <ppaas_common_language_v3> (language) [ 2 .. 10 ] characters ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))... 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. | |||||||||
shipping_preference | string The shipping preferences.
| |||||||||
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
| |||||||||
Array of objects (Name and Value Pair) An array of name-and-value pairs that contain supplementary data required by PayPal for transaction processing. |
{- "brand_name": "string",
- "locale": "string",
- "shipping_preference": "NO_SHIPPING",
- "user_action": "string",
- "supplementary_data": [
- {
- "name": "string",
- "value": "string"
}
]
}
A capture transaction.
id | string The ID of the capture transaction. | ||||||||||||||||||||||||||||
status | string The status of the capture transaction.
| ||||||||||||||||||||||||||||
reason_code | string A reason code that indicates the reason for the transaction state of
| ||||||||||||||||||||||||||||
Array of objects (Link Description) An array of request-related HATEOAS links. | |||||||||||||||||||||||||||||
object (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 | |||||||||||||||||||||||||||||
object (Currency) The currency and amount of the transaction fee. |
{- "id": "string",
- "status": "PENDING",
- "reason_code": "CHARGEBACK",
- "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
], - "amount": {
- "currency": "string",
- "total": "string",
- "details": {
- "subtotal": "string",
- "shipping": "string",
- "tax": "string",
- "handling_fee": "string",
- "shipping_discount": "string",
- "insurance": "string",
- "gift_wrap": "string"
}
}, - "transaction_fee": {
- "currency": "string",
- "value": "string"
}
}
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain isGB
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.
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain isGB
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.
"st"
Deprecated. The credit card details. You can use this instrument to fund a payment. Use a payment card instead.
number required | string 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 required | string The credit card type. Value is |
expire_month required | integer The expiration month with no leading zero. Value is from |
expire_year required | integer 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. |
Array of objects (Link Description) An array of request-related HATEOAS links. | |
object (Address) The billing address or shipping address for a payment. |
{- "number": "string",
- "type": "string",
- "expire_month": 0,
- "expire_year": 0,
- "cvv2": "string",
- "first_name": "string",
- "last_name": "string",
- "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
], - "billing_address": {
- "line1": "string",
- "line2": "string",
- "city": "string",
- "country_code": "st",
- "postal_code": "string",
- "state": "string",
- "phone": "string",
- "normalization_status": "UNKNOWN",
- "type": "string"
}
}
The tokenized credit card details. You can use this instrument to fund a payment.
credit_card_id required | string 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 |
last4 | string The last four digits of the stored credit card number. |
type | string The credit card type. Value is |
expire_month | integer The expiration month with no leading zero. Value is from |
expire_year | integer The four-digit expiration year. |
{- "credit_card_id": "string",
- "payer_id": "string",
- "last4": "string",
- "type": "string",
- "expire_month": 0,
- "expire_year": 0
}
The currency and amount for a transaction.
currency required | string The three-character ISO-4217 currency code. PayPal does not support all currencies. |
value required | string The amount. Includes the specified number of digits after decimal separator for the ISO-4217 currency code. |
{- "currency": "string",
- "value": "string"
}
The three-character ISO-4217 currency code that identifies the currency.
The three-character ISO-4217 currency code that identifies the currency.
"str"
The error details.
name required | string The human-readable, unique name of the error. |
message required | string The message that describes the error. |
debug_id required | string 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. |
Array of objects (Error Details) An array of additional details about the error. | |
Array of objects (Link Description) An array of request-related HATEOAS links. |
{- "name": "string",
- "message": "string",
- "debug_id": "string",
- "information_link": "string",
- "details": [
- {
- "field": "string",
- "value": "string",
- "location": "body",
- "issue": "string",
- "description": "string"
}
], - "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
]
}
The error details. Required for client-side 4XX
errors.
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 Default: "body" The location of the field that caused the error. Value is |
issue required | string 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. |
{- "field": "string",
- "value": "string",
- "location": "body",
- "issue": "string",
- "description": "string"
}
An execute order request.
disbursement_mode required | string Indicates whether to disburse money instantly or later.
| ||||||
object (Payer) The source of the funds for this payment. Either a PayPal account or a credit card. |
{- "disbursement_mode": "INSTANT",
- "payer": {
- "payment_method": "credit_card",
- "status": "VERIFIED",
- "funding_instruments": [
- {
- "credit_card": {
- "number": "string",
- "type": "string",
- "expire_month": 0,
- "expire_year": 0,
- "cvv2": "string",
- "first_name": "string",
- "last_name": "string",
- "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
], - "billing_address": {
- "line1": "string",
- "line2": "string",
- "city": "string",
- "country_code": "st",
- "postal_code": "string",
- "state": "string",
- "phone": "string",
- "normalization_status": "UNKNOWN",
- "type": "string"
}
}, - "credit_card_token": {
- "credit_card_id": "string",
- "payer_id": "string",
- "last4": "string",
- "type": "string",
- "expire_month": 0,
- "expire_year": 0
}
}
], - "payer_info": {
- "email": "user@example.com",
- "salutation": "string",
- "first_name": "string",
- "middle_name": "string",
- "last_name": "string",
- "suffix": "string",
- "payer_id": "string",
- "birth_date": "2019-08-24T14:15:22Z",
- "tax_id": "string",
- "tax_id_type": "BR_CPF",
- "country_code": "string",
- "billing_address": {
- "line1": "string",
- "line2": "string",
- "city": "string",
- "country_code": "st",
- "postal_code": "string",
- "state": "string",
- "phone": "string",
- "normalization_status": "UNKNOWN",
- "type": "string"
}, - "shipping_address": {
- "line1": "string",
- "line2": "string",
- "city": "string",
- "country_code": "st",
- "postal_code": "string",
- "state": "string",
- "phone": "string",
- "normalization_status": "UNKNOWN",
- "type": "string",
- "recipient_name": "string"
}
}
}
}
The funding instrument details. An instance of this schema is valid if and only if it validates against exactly one of these supported properties.
object (Credit Card) Deprecated. The credit card details. You can use this instrument to fund a payment. Use a payment card instead. | |
object (Credit Card Token) The tokenized credit card details. You can use this instrument to fund a payment. |
{- "credit_card": {
- "number": "string",
- "type": "string",
- "expire_month": 0,
- "expire_year": 0,
- "cvv2": "string",
- "first_name": "string",
- "last_name": "string",
- "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
], - "billing_address": {
- "line1": "string",
- "line2": "string",
- "city": "string",
- "country_code": "st",
- "postal_code": "string",
- "state": "string",
- "phone": "string",
- "normalization_status": "UNKNOWN",
- "type": "string"
}
}, - "credit_card_token": {
- "credit_card_id": "string",
- "payer_id": "string",
- "last4": "string",
- "type": "string",
- "expire_month": 0,
- "expire_year": 0
}
}
The installment option details.
term required | integer The number of installments. |
required | object (Currency) The currency and amount for a transaction. |
object (Currency) The currency and amount for a transaction. | |
discount_percentage | string <ppaas_common_percentage_v1> (Percentage) ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$ The percentage as a fixed-point, signed decimal value. Use for all interest rates. For example, specify an interest rate of 19.99% as |
{- "term": 0,
- "monthly_payment": {
- "currency": "string",
- "value": "string"
}, - "discount_amount": {
- "currency": "string",
- "value": "string"
}, - "discount_percentage": "string"
}
The item details.
sku | string <= 127 characters The stock keeping unit (SKU) for the item. |
name required | string The item name. Maximum length is 127 characters. |
description | string <= 127 characters The item description. Supported only for the PayPal payment method. |
quantity required | string <= 10 characters ^[0-9]{0,10}$ The item quantity. Must be a whole number. |
price required | string <= 10 characters ^[0-9]{0,10}(\.[0-9]{0,2})?$ The item cost. Supports two decimal places. |
currency required | string |
tax | string The item tax. Supported only for the PayPal payment method. |
url | string <uri> The URL to item information. Available to the payer in the transaction history. |
{- "sku": "string",
- "name": "string",
- "description": "string",
- "quantity": "string",
- "price": "string",
- "currency": "string",
- "tax": "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.
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.
"string"
The request-related HATEOAS link information.
href required | string The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the |
rel required | string The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations. |
method | string The HTTP method required to make the related call. |
{- "href": "string",
- "rel": "string",
- "method": "GET"
}
The name-and-value pairs that contain external data, such as user, user feedback, score, and so on.
Array of objects (Name and Value Pair) An array of name-and-value pairs that contain data required by PayPal for transaction processing. |
{- "supplementary_data": [
- {
- "name": "string",
- "value": "string"
}
]
}
The name-and-value pair details.
name required | string The key for the name-and-value pair. You must correlate the value and name types. |
value required | string The value for the name-and-value pair. |
{- "name": "string",
- "value": "string"
}
An order.
id | string The ID of the order. | ||||||||||
intent | string The intent.
| ||||||||||
required | Array of objects (Purchase Unit) non-empty An array of purchase units. Each purchase unit establishes a contract between a customer and merchant. | ||||||||||
object (Payment Details) The payment details for the order. | |||||||||||
object (Application Context) Customizes the payer experience during the approval process for the payment with PayPal. Note: The PayPal Commerce Platform might configure | |||||||||||
status | string The status of the order. After the customer approves the order, the status is
| ||||||||||
required | object (Redirect URLs) The redirect URLs. Required only for the PayPal payment method. The supported settings are return and cancel URLs. | ||||||||||
create_time | string <date-time> The date and time when the resource was created, in Internet date and time format. | ||||||||||
update_time | string <date-time> The date and time when the resource was last updated, in Internet date and time format. | ||||||||||
Array of objects (Link Description) An array of request-related HATEOAS links. To complete the buyer approval, use the | |||||||||||
object (Currency) The currency and amount of the PayPal-computed total of amounts in all purchase units. | |||||||||||
object (Metadata) The name-and-value pairs that contain external data, such as user, user feedback, score, and so on. |
{- "id": "string",
- "intent": "SALE",
- "purchase_units": [
- {
- "reference_id": "string",
- "description": "string",
- "custom": "string",
- "invoice_number": "string",
- "payment_descriptor": "string",
- "items": [
- {
- "sku": "string",
- "name": "string",
- "description": "string",
- "quantity": "string",
- "price": "string",
- "currency": "string",
- "tax": "string",
}
], - "shipping_address": {
- "line1": "string",
- "line2": "string",
- "city": "string",
- "country_code": "st",
- "postal_code": "string",
- "state": "string",
- "phone": "string",
- "normalization_status": "UNKNOWN",
- "type": "string",
- "recipient_name": "string"
}, - "shipping_method": "string",
- "partner_fee_details": {
- "receiver": {
- "email": "user@example.com",
- "merchant_id": "string",
- "payee_display_metadata": {
- "email": "user@example.com",
- "display_phone": {
- "country_code": "string",
- "number": "string"
}, - "brand_name": "string"
}
}, - "amount": {
- "currency": "string",
- "value": "string"
}
}, - "payment_linked_group": 1,
- "metadata": {
- "supplementary_data": [
- {
- "name": "string",
- "value": "string"
}
]
}, - "payment_summary": {
- "captures": [
- {
- "id": "string",
- "status": "PENDING",
- "reason_code": "CHARGEBACK",
- "links": [
- {
- "href": null,
- "rel": null,
- "method": null
}
], - "amount": {
- "currency": "string",
- "total": "string",
- "details": {
- "subtotal": null,
- "shipping": null,
- "tax": null,
- "handling_fee": null,
- "shipping_discount": null,
- "insurance": null,
- "gift_wrap": null
}
}, - "transaction_fee": {
- "currency": "string",
- "value": "string"
}
}
], - "refunds": [
- {
- "id": "string",
- "capture_id": "string",
- "sale_id": "string",
- "status": "PENDING",
- "links": [
- {
- "href": null,
- "rel": null,
- "method": null
}
], - "amount": {
- "currency": "string",
- "total": "string",
- "details": {
- "subtotal": null,
- "shipping": null,
- "tax": null,
- "handling_fee": null,
- "shipping_discount": null,
- "insurance": null,
- "gift_wrap": null
}
}
}
], - "sales": [
- {
- "id": "string",
- "status": "COMPLETED",
- "reason_code": "CHARGEBACK",
- "create_time": "2019-08-24T14:15:22Z",
- "update_time": "2019-08-24T14:15:22Z",
- "links": [
- {
- "href": null,
- "rel": null,
- "method": null
}
], - "amount": {
- "currency": "string",
- "total": "string",
- "details": {
- "subtotal": null,
- "shipping": null,
- "tax": null,
- "handling_fee": null,
- "shipping_discount": null,
- "insurance": null,
- "gift_wrap": null
}
}, - "transaction_fee": {
- "currency": "string",
- "value": "string"
}
}
], - "authorizations": [
- {
- "id": "string",
- "status": "COMPLETED",
- "reason_code": "CHARGEBACK",
- "create_time": "2019-08-24T14:15:22Z",
- "update_time": "2019-08-24T14:15:22Z",
- "links": [
- {
- "href": null,
- "rel": null,
- "method": null
}
], - "amount": {
- "currency": "string",
- "total": "string",
- "details": {
- "subtotal": null,
- "shipping": null,
- "tax": null,
- "handling_fee": null,
- "shipping_discount": null,
- "insurance": null,
- "gift_wrap": null
}
}, - "transaction_fee": {
- "currency": "string",
- "value": "string"
}
}
]
}, - "status": "NOT_PROCESSED",
- "reason_code": "PAYER_SHIPPING_UNCONFIRMED",
- "amount": {
- "currency": "string",
- "total": "string",
- "details": {
- "subtotal": "string",
- "shipping": "string",
- "tax": "string",
- "handling_fee": "string",
- "shipping_discount": "string",
- "insurance": "string",
- "gift_wrap": "string"
}
}, - "payee": {
- "email": "user@example.com",
- "merchant_id": "string",
- "payee_display_metadata": {
- "email": "user@example.com",
- "display_phone": {
- "country_code": "string",
- "number": "string"
}, - "brand_name": "string"
}
}
}
], - "payment_details": {
- "payment_id": "string",
- "disbursement_mode": "INSTANT"
}, - "application_context": {
- "brand_name": "string",
- "locale": "string",
- "shipping_preference": "NO_SHIPPING",
- "user_action": "string",
- "supplementary_data": [
- {
- "name": "string",
- "value": "string"
}
]
}, - "status": "CREATED",
- "create_time": "2019-08-24T14:15:22Z",
- "update_time": "2019-08-24T14:15:22Z",
- "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
], - "gross_total_amount": {
- "currency": "string",
- "value": "string"
}, - "metadata": {
- "supplementary_data": [
- {
- "name": "string",
- "value": "string"
}
]
}
}
The partner fee that is collected for the original transaction.
required | object (Payee) The partner who receives the partner fee. |
required | object (Currency) The amount and currency of the partner fee. |
{- "receiver": {
- "email": "user@example.com",
- "merchant_id": "string",
- "payee_display_metadata": {
- "email": "user@example.com",
- "display_phone": {
- "country_code": "string",
- "number": "string"
}, - "brand_name": "string"
}
}, - "amount": {
- "currency": "string",
- "value": "string"
}
}
A pay order response.
order_id | string The ID of the order. | ||||||||||||||||||||
status | string The status of the order.
| ||||||||||||||||||||
intent | string The intent.
| ||||||||||||||||||||
Array of objects (Purchase Unit) non-empty An array of purchase units. Each purchase unit establishes a contract between a customer and merchant. | |||||||||||||||||||||
create_time | string <date-time> The date and time when the resource was created, in Internet date and time format. | ||||||||||||||||||||
update_time | string <date-time> The date and time when the resource was last updated, in Internet date and time format. | ||||||||||||||||||||
Array of objects (Link Description) An array of request-related HATEOAS links. | |||||||||||||||||||||
object (Payer Information) The payer information. |
{- "order_id": "string",
- "status": "APPROVED",
- "intent": "SALE",
- "purchase_units": [
- {
- "reference_id": "string",
- "description": "string",
- "custom": "string",
- "invoice_number": "string",
- "payment_descriptor": "string",
- "items": [
- {
- "sku": "string",
- "name": "string",
- "description": "string",
- "quantity": "string",
- "price": "string",
- "currency": "string",
- "tax": "string",
}
], - "shipping_address": {
- "line1": "string",
- "line2": "string",
- "city": "string",
- "country_code": "st",
- "postal_code": "string",
- "state": "string",
- "phone": "string",
- "normalization_status": "UNKNOWN",
- "type": "string",
- "recipient_name": "string"
}, - "shipping_method": "string",
- "partner_fee_details": {
- "receiver": {
- "email": "user@example.com",
- "merchant_id": "string",
- "payee_display_metadata": {
- "email": "user@example.com",
- "display_phone": {
- "country_code": "string",
- "number": "string"
}, - "brand_name": "string"
}
}, - "amount": {
- "currency": "string",
- "value": "string"
}
}, - "payment_linked_group": 1,
- "metadata": {
- "supplementary_data": [
- {
- "name": "string",
- "value": "string"
}
]
}, - "payment_summary": {
- "captures": [
- {
- "id": "string",
- "status": "PENDING",
- "reason_code": "CHARGEBACK",
- "links": [
- {
- "href": null,
- "rel": null,
- "method": null
}
], - "amount": {
- "currency": "string",
- "total": "string",
- "details": {
- "subtotal": null,
- "shipping": null,
- "tax": null,
- "handling_fee": null,
- "shipping_discount": null,
- "insurance": null,
- "gift_wrap": null
}
}, - "transaction_fee": {
- "currency": "string",
- "value": "string"
}
}
], - "refunds": [
- {
- "id": "string",
- "capture_id": "string",
- "sale_id": "string",
- "status": "PENDING",
- "links": [
- {
- "href": null,
- "rel": null,
- "method": null
}
], - "amount": {
- "currency": "string",
- "total": "string",
- "details": {
- "subtotal": null,
- "shipping": null,
- "tax": null,
- "handling_fee": null,
- "shipping_discount": null,
- "insurance": null,
- "gift_wrap": null
}
}
}
], - "sales": [
- {
- "id": "string",
- "status": "COMPLETED",
- "reason_code": "CHARGEBACK",
- "create_time": "2019-08-24T14:15:22Z",
- "update_time": "2019-08-24T14:15:22Z",
- "links": [
- {
- "href": null,
- "rel": null,
- "method": null
}
], - "amount": {
- "currency": "string",
- "total": "string",
- "details": {
- "subtotal": null,
- "shipping": null,
- "tax": null,
- "handling_fee": null,
- "shipping_discount": null,
- "insurance": null,
- "gift_wrap": null
}
}, - "transaction_fee": {
- "currency": "string",
- "value": "string"
}
}
], - "authorizations": [
- {
- "id": "string",
- "status": "COMPLETED",
- "reason_code": "CHARGEBACK",
- "create_time": "2019-08-24T14:15:22Z",
- "update_time": "2019-08-24T14:15:22Z",
- "links": [
- {
- "href": null,
- "rel": null,
- "method": null
}
], - "amount": {
- "currency": "string",
- "total": "string",
- "details": {
- "subtotal": null,
- "shipping": null,
- "tax": null,
- "handling_fee": null,
- "shipping_discount": null,
- "insurance": null,
- "gift_wrap": null
}
}, - "transaction_fee": {
- "currency": "string",
- "value": "string"
}
}
]
}, - "status": "NOT_PROCESSED",
- "reason_code": "PAYER_SHIPPING_UNCONFIRMED",
- "amount": {
- "currency": "string",
- "total": "string",
- "details": {
- "subtotal": "string",
- "shipping": "string",
- "tax": "string",
- "handling_fee": "string",
- "shipping_discount": "string",
- "insurance": "string",
- "gift_wrap": "string"
}
}, - "payee": {
- "email": "user@example.com",
- "merchant_id": "string",
- "payee_display_metadata": {
- "email": "user@example.com",
- "display_phone": {
- "country_code": "string",
- "number": "string"
}, - "brand_name": "string"
}
}
}
], - "create_time": "2019-08-24T14:15:22Z",
- "update_time": "2019-08-24T14:15:22Z",
- "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
], - "payer_info": {
- "email": "user@example.com",
- "salutation": "string",
- "first_name": "string",
- "middle_name": "string",
- "last_name": "string",
- "suffix": "string",
- "payer_id": "string",
- "birth_date": "2019-08-24T14:15:22Z",
- "tax_id": "string",
- "tax_id_type": "BR_CPF",
- "country_code": "string",
- "billing_address": {
- "line1": "string",
- "line2": "string",
- "city": "string",
- "country_code": "st",
- "postal_code": "string",
- "state": "string",
- "phone": "string",
- "normalization_status": "UNKNOWN",
- "type": "string"
}, - "shipping_address": {
- "line1": "string",
- "line2": "string",
- "city": "string",
- "country_code": "st",
- "postal_code": "string",
- "state": "string",
- "phone": "string",
- "normalization_status": "UNKNOWN",
- "type": "string",
- "recipient_name": "string"
}
}
}
The payee who receives the funds and fulfills the order.
string <email> 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:
| |
merchant_id | string The encrypted PayPal account ID for the payee. |
object (Payee Display Metadata) The display-only metadata for the payee. |
{- "email": "user@example.com",
- "merchant_id": "string",
- "payee_display_metadata": {
- "email": "user@example.com",
- "display_phone": {
- "country_code": "string",
- "number": "string"
}, - "brand_name": "string"
}
}
The display-only metadata for the payee.
string <email> The email address for the payer. Maximum length is 127 characters. | |
object (Display Phone) The payee's phone number. | |
brand_name | string The payer's business name. |
{- "email": "user@example.com",
- "display_phone": {
- "country_code": "string",
- "number": "string"
}, - "brand_name": "string"
}
The payer. The payer funds the payment.
payment_method | string The payment method. Value is PayPal Wallet payment, bank direct debit, or direct credit card. |
status | string The status of payer's PayPal account. |
Array of objects (Funding Instrument) 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 | |
object (Payer Information) The payer information. |
{- "payment_method": "credit_card",
- "status": "VERIFIED",
- "funding_instruments": [
- {
- "credit_card": {
- "number": "string",
- "type": "string",
- "expire_month": 0,
- "expire_year": 0,
- "cvv2": "string",
- "first_name": "string",
- "last_name": "string",
- "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
], - "billing_address": {
- "line1": "string",
- "line2": "string",
- "city": "string",
- "country_code": "st",
- "postal_code": "string",
- "state": "string",
- "phone": "string",
- "normalization_status": "UNKNOWN",
- "type": "string"
}
}, - "credit_card_token": {
- "credit_card_id": "string",
- "payer_id": "string",
- "last4": "string",
- "type": "string",
- "expire_month": 0,
- "expire_year": 0
}
}
], - "payer_info": {
- "email": "user@example.com",
- "salutation": "string",
- "first_name": "string",
- "middle_name": "string",
- "last_name": "string",
- "suffix": "string",
- "payer_id": "string",
- "birth_date": "2019-08-24T14:15:22Z",
- "tax_id": "string",
- "tax_id_type": "BR_CPF",
- "country_code": "string",
- "billing_address": {
- "line1": "string",
- "line2": "string",
- "city": "string",
- "country_code": "st",
- "postal_code": "string",
- "state": "string",
- "phone": "string",
- "normalization_status": "UNKNOWN",
- "type": "string"
}, - "shipping_address": {
- "line1": "string",
- "line2": "string",
- "city": "string",
- "country_code": "st",
- "postal_code": "string",
- "state": "string",
- "phone": "string",
- "normalization_status": "UNKNOWN",
- "type": "string",
- "recipient_name": "string"
}
}
}
The payer information.
string <email> 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 <date-time> The birth date of the payer, in Internet date format. For example, |
tax_id | string <= 14 characters The payer’s tax ID. Supported for the PayPal payment method only. |
tax_id_type | string 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. |
object (Address) The billing address or shipping address for a payment. | |
object (Shipping Address) The shipping address details. |
{- "email": "user@example.com",
- "salutation": "string",
- "first_name": "string",
- "middle_name": "string",
- "last_name": "string",
- "suffix": "string",
- "payer_id": "string",
- "birth_date": "2019-08-24T14:15:22Z",
- "tax_id": "string",
- "tax_id_type": "BR_CPF",
- "country_code": "string",
- "billing_address": {
- "line1": "string",
- "line2": "string",
- "city": "string",
- "country_code": "st",
- "postal_code": "string",
- "state": "string",
- "phone": "string",
- "normalization_status": "UNKNOWN",
- "type": "string"
}, - "shipping_address": {
- "line1": "string",
- "line2": "string",
- "city": "string",
- "country_code": "st",
- "postal_code": "string",
- "state": "string",
- "phone": "string",
- "normalization_status": "UNKNOWN",
- "type": "string",
- "recipient_name": "string"
}
}
The payment details for the order.
payment_id | string The payment ID for the order. | ||||||
disbursement_mode | string Indicates whether to disburse the payment instantly or delay the payment.
|
{- "payment_id": "string",
- "disbursement_mode": "INSTANT"
}
The payment summary.
Array of objects (Capture) non-empty An array of captures for a purchase unit. A purchase unit can have zero or more captures. | |
Array of objects (Refund) non-empty An array of refunds for a purchase unit. A purchase unit can have zero or more refunds. | |
Array of objects (Sale) non-empty An array of sales for a purchase unit. A purchase unit can have zero or more sales. | |
Array of objects (Sale) non-empty An array of authorizations for a purchase unit. A purchase unit can have zero or more authorizations. |
{- "captures": [
- {
- "id": "string",
- "status": "PENDING",
- "reason_code": "CHARGEBACK",
- "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
], - "amount": {
- "currency": "string",
- "total": "string",
- "details": {
- "subtotal": "string",
- "shipping": "string",
- "tax": "string",
- "handling_fee": "string",
- "shipping_discount": "string",
- "insurance": "string",
- "gift_wrap": "string"
}
}, - "transaction_fee": {
- "currency": "string",
- "value": "string"
}
}
], - "refunds": [
- {
- "id": "string",
- "capture_id": "string",
- "sale_id": "string",
- "status": "PENDING",
- "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
], - "amount": {
- "currency": "string",
- "total": "string",
- "details": {
- "subtotal": "string",
- "shipping": "string",
- "tax": "string",
- "handling_fee": "string",
- "shipping_discount": "string",
- "insurance": "string",
- "gift_wrap": "string"
}
}
}
], - "sales": [
- {
- "id": "string",
- "status": "COMPLETED",
- "reason_code": "CHARGEBACK",
- "create_time": "2019-08-24T14:15:22Z",
- "update_time": "2019-08-24T14:15:22Z",
- "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
], - "amount": {
- "currency": "string",
- "total": "string",
- "details": {
- "subtotal": "string",
- "shipping": "string",
- "tax": "string",
- "handling_fee": "string",
- "shipping_discount": "string",
- "insurance": "string",
- "gift_wrap": "string"
}
}, - "transaction_fee": {
- "currency": "string",
- "value": "string"
}
}
], - "authorizations": [
- {
- "id": "string",
- "status": "COMPLETED",
- "reason_code": "CHARGEBACK",
- "create_time": "2019-08-24T14:15:22Z",
- "update_time": "2019-08-24T14:15:22Z",
- "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
], - "amount": {
- "currency": "string",
- "total": "string",
- "details": {
- "subtotal": "string",
- "shipping": "string",
- "tax": "string",
- "handling_fee": "string",
- "shipping_discount": "string",
- "insurance": "string",
- "gift_wrap": "string"
}
}, - "transaction_fee": {
- "currency": "string",
- "value": "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.
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.
"string"
A purchase unit. Establishes a contract between the payer and payee.
reference_id required | string <= 256 characters The merchant ID for the purchase unit. | ||||||||||||||||||
description | string <= 127 characters The purchase description. | ||||||||||||||||||
custom | string <= 127 characters 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 <= 256 characters The API caller-provided external invoice ID for this order.. Only supported for the PayPal payment method. | ||||||||||||||||||
payment_descriptor | string <= 22 characters The payment descriptor on the buyer credit card statement of account activity. | ||||||||||||||||||
Array of objects (Item) An array of items that the customer is purchasing from the merchant. | |||||||||||||||||||
notify_url | string <uri> <= 2048 characters The payment notifications URL. | ||||||||||||||||||
object (Shipping Address) The shipping address details. | |||||||||||||||||||
shipping_method | string The shipping method. For example, | ||||||||||||||||||
object (Partner Fee Details) The partner fee that is collected for the original transaction. | |||||||||||||||||||
payment_linked_group | integer [ 1 .. 100 ] 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. | ||||||||||||||||||
object (Metadata) The name-and-value pairs that contain external data, such as user, user feedback, score, and so on. | |||||||||||||||||||
object (Payment Summary) The payment summary. | |||||||||||||||||||
status | string The transaction state.
| ||||||||||||||||||
reason_code | string The reason code for a transaction status of
| ||||||||||||||||||