Orders API
Orders (resource group)
/orders
resource to create, update, show details for, and authorize and capture payments for orders.
Create order
Header parameters
-
PayPal-Partner-Attribution-Id
string
For more information about PayPal-Partner-Attribution-Id, see PayPal-Partner-Attribution-Id. -
Prefer
string
The preferred server response upon successful completion of the request. Value is:return=minimal
. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes theid
,status
and HATEOAS links.return=representation
. The server returns a complete resource representation, including the current state of the resource.
-
Authorization
string
required
To make REST API calls, include the bearer token in this header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id;secret>
. -
Content-Type
string
required
Required for operations with a request body. The value is application/. Where the 'format' is 'json'.
Request body
-
intent
enum
required
The intent to either capture payment immediately or authorize a payment for an order after order creation. The allowed values are:CAPTURE
. The merchant intends to capture payment immediately after the customer makes a payment.AUTHORIZE
. The merchant intends to authorize a payment and place funds on hold after the customer makes a payment. Authorized payments are guaranteed for up to three days but are available to capture for up to 29 days. After the three-day honor period, the original authorized payment expires and you must re-authorize the payment. You must make a separate request to capture payments on demand.
-
payer
The customer who approves and pays for the order. The customer is also known as the payer. -
An array of purchase units. At present only 1 purchase_unit is supported. Each purchase unit establishes a contract between a payer and the payee. Each purchase unit represents either a full or partial order that the payer intends to purchase from the payee.
-
application_context
Customize the payer experience during the approval process for the payment with PayPal.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v2/checkout/orders \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"intent": "CAPTURE",
"purchase_units": [
{
"amount": {
"currency_code": "USD",
"value": "100.00"
}
}
]
}'
Response
201 Created
status code and a JSON response body that includes by default a minimal response with the ID, status, and HATEOAS links. If you require the complete order resource representation, you must pass the Prefer: return=representation
request header. This header value is not the default.-
create_time
The date and time when the transaction occurred, in Internet date and time format. -
update_time
The date and time when the transaction was last updated, in Internet date and time format. -
id
string
The ID of the order. -
intent
enum
The intent to either capture payment immediately or authorize a payment for an order after order creation. The possible values are:CAPTURE
. The merchant intends to capture payment immediately after the customer makes a payment.AUTHORIZE
. The merchant intends to authorize a payment and place funds on hold after the customer makes a payment. Authorized payments are guaranteed for up to three days but are available to capture for up to 29 days. After the three-day honor period, the original authorized payment expires and you must re-authorize the payment. You must make a separate request to capture payments on demand.
-
payer
The customer who approves and pays for the order. The customer is also known as the payer. -
purchase_units
array (contains the purchase_unit object)
An array of purchase units. Each purchase unit establishes a contract between a customer and merchant. Each purchase unit represents either a full or partial order that the customer intends to purchase from the merchant. -
status
enum
The order status. The possible values are:CREATED
. The order was created with the specified context.SAVED
. The order was saved and persisted. The order status continues to be in progress until a capture is made withfinal_capture = true
for all purchase units within the order.APPROVED
. The customer approved the payment through the PayPal wallet or another form of guest or unbranded payment. For example, a card, bank account, or so on.VOIDED
. All purchase units in the order are voided.COMPLETED
. The payment was authorized or the authorized payment was captured for the order.
-
links
array (contains the link_description object)
An array of request-related HATEOAS links. To complete payer approval, use theapprove
link with theGET
method.
Sample Response
{
"id": "5O190127TN364715T",
"status": "CREATED",
"links": [
{
"href": "https://api.paypal.com/v2/checkout/orders/5O190127TN364715T",
"rel": "self",
"method": "GET"
},
{
"href": "https://api.sandbox.paypal.com/checkoutnow?token=5O190127TN364715T",
"rel": "approve",
"method": "GET"
},
{
"href": "https://api.paypal.com/v2/checkout/orders/5O190127TN364715T/capture",
"rel": "capture",
"method": "POST"
}
]
}
Update order
CREATED
or APPROVED
status.You cannot update an order with the
COMPLETED
status.To make an update, you must provide a
reference_id
.If you omit a
reference_id
for an order with one purchase unit, PayPal sets the reference_id
to default
, which enables you to use a path:"path": "/purchase_units/@reference_id=='default'/{attribute-or-object}".
You can patch these attributes and objects to complete these operations:
intent
— replace.purchase_units
— replace, add.purchase_units[].custom_id
— replace, add, remove.purchase_units[].description
— replace, add, remove.purchase_units[].payee.email
— replace, add.purchase_units[].shipping
— replace, add, remove.purchase_units[].soft_descriptor
— replace, add, remove.purchase_units[].amount
— replace.purchase_units[].invoice_id
— replace, add, remove.purchase_units[].payment_instruction
— replace.Note: You cannot patch this field when you
replace
apurchase_unit
.purchase_units[].payment_instruction.disbursement_mode
— replace.Note: By default,
disbursement_mode
isINSTANT
.purchase_units[].payment_instruction.platform_fees
— replace, add, remove.
Header parameters
-
Authorization
string
required
To make REST API calls, include the bearer token in this header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id;secret>
. -
Content-Type
string
required
Required for operations with a request body. The value is application/. Where the 'format' is 'json'.
Path parameters
-
order_id
string
required
The ID of the order to update.
Request body
-
patch_request
array (contains the patch object)
An array of JSON patch objects to apply partial updates to resources.
Sample Request
curl -v -X PATCH https://api.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '[
{
"op": "add",
"path": "/purchase_units/@reference_id=='PUHF'/invoice_id",
"value": "INV-HighFashions"
}
]'
Response
204 No Content
status code with an empty object in the JSON response body.Sample Response
204 No Content
Show order details
Header parameters
-
Authorization
string
required
To make REST API calls, include the bearer token in this header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id;secret>
. -
Content-Type
string
required
Required for operations with a request body. The value is application/. Where the 'format' is 'json'.
Path parameters
-
order_id
string
required
The ID of the order for which to show details.
Sample Request
curl -v -X GET https://api.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
Response
200 OK
status code and a JSON response body that shows order details.-
create_time
The date and time when the transaction occurred, in Internet date and time format. -
update_time
The date and time when the transaction was last updated, in Internet date and time format. -
id
string
The ID of the order. -
intent
enum
The intent to either capture payment immediately or authorize a payment for an order after order creation. The possible values are:CAPTURE
. The merchant intends to capture payment immediately after the customer makes a payment.AUTHORIZE
. The merchant intends to authorize a payment and place funds on hold after the customer makes a payment. Authorized payments are guaranteed for up to three days but are available to capture for up to 29 days. After the three-day honor period, the original authorized payment expires and you must re-authorize the payment. You must make a separate request to capture payments on demand.
-
payer
The customer who approves and pays for the order. The customer is also known as the payer. -
purchase_units
array (contains the purchase_unit object)
An array of purchase units. Each purchase unit establishes a contract between a customer and merchant. Each purchase unit represents either a full or partial order that the customer intends to purchase from the merchant. -
status
enum
The order status. The possible values are:CREATED
. The order was created with the specified context.SAVED
. The order was saved and persisted. The order status continues to be in progress until a capture is made withfinal_capture = true
for all purchase units within the order.APPROVED
. The customer approved the payment through the PayPal wallet or another form of guest or unbranded payment. For example, a card, bank account, or so on.VOIDED
. All purchase units in the order are voided.COMPLETED
. The payment was authorized or the authorized payment was captured for the order.
-
links
array (contains the link_description object)
An array of request-related HATEOAS links. To complete payer approval, use theapprove
link with theGET
method.
Sample Response
{
"id": "5O190127TN364715T",
"status": "COMPLETED",
"intent": "CAPTURE",
"payer": {
"name": {
"given_name": "John",
"surname": "Doe"
},
"email_address": "customer@example.com",
"payer_id": "QYR5Z8XDVJNXQ"
},
"purchase_units": [
{
"reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
"amount": {
"currency_code": "USD",
"value": "100.00"
},
"payee": {
"email_address": "merchant@example.com"
},
"payments": {
"captures": [
{
"id": "3C679366HH908993F",
"status": "COMPLETED",
"amount": {
"currency_code": "USD",
"value": "100.00"
},
"seller_protection": {
"status": "ELIGIBLE",
"dispute_categories": [
"ITEM_NOT_RECEIVED",
"UNAUTHORIZED_TRANSACTION"
]
},
"final_capture": true,
"disbursement_mode": "INSTANT",
"application_context": {
"supplementary_data": [
{
"industry_type": "AIRLINE",
"data": {
"airline_itineraries": [
{
"ticket": {
"number": "045-2135145561",
"issue_date": "2018-01-19",
"issuing_carrier_code": "AI",
"travel_agency_name": "World Tours",
"travel_agency_code": "01"
},
"passenger": {
"name": {
"full_name": "Trini George"
},
"date_of_birth": "1981-05-31",
"country_code": "US"
},
"flight_leg_details": [
{
"flight_number": 101,
"carrier_code": "AI",
"service_class": "J",
"departure_date": "2018-02-15",
"departure_time": "15:30",
"departure_airport": "SFO",
"arrival_airport": "DBX",
"stopover_code": "X",
"fare_basis_code": "SPRSVR"
},
{
"flight_number": 102,
"carrier_code": "AI",
"service_class": "J",
"departure_date": "2018-02-15",
"departure_time": "19:05",
"departure_airport": "DBX",
"arrival_airport": "MAA",
"stopover_code": "O",
"fare_basis_code": "SPRSVR"
}
]
}
]
}
}
]
},
"seller_receivable_breakdown": {
"gross_amount": {
"currency_code": "USD",
"value": "100.00"
},
"paypal_fee": {
"currency_code": "USD",
"value": "3.00"
},
"net_amount": {
"currency_code": "USD",
"value": "97.00"
}
},
"create_time": "2018-04-01T21:20:49Z",
"update_time": "2018-04-01T21:20:49Z",
"links": [
{
"href": "https://api.paypal.com/v2/payments/captures/3C679366HH908993F",
"rel": "self",
"method": "GET"
},
{
"href": "https://api.paypal.com/v2/payments/captures/3C679366HH908993F/refund",
"rel": "refund",
"method": "POST"
}
]
}
]
}
}
],
"create_time": "2018-04-01T21:18:49Z",
"update_time": "2018-04-01T21:20:49Z",
"links": [
{
"href": "https://api.paypal.com/v2/checkout/orders/5O190127TN364715T",
"rel": "self",
"method": "GET"
}
]
}
Authorize payment for order
intent=AUTHORIZE
in the create order call.
Header parameters
-
PayPal-Request-Id
string
The server stores keys for 45 days. For more information about PayPal-Request-Id, see PayPal-Request-Id. -
Prefer
string
The preferred server response upon successful completion of the request. Value is:return=minimal
. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes theid
,status
and HATEOAS links.return=representation
. The server returns a complete resource representation, including the current state of the resource.
-
PayPal-Client-Metadata-Id
string
For more information about PayPal-Client-Metadata-Id, see PayPal-Client-Metadata-Id. -
Authorization
string
required
To make REST API calls, include the bearer token in this header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id;secret>
. -
PayPal-Auth-Assertion
string
An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see PayPal-Auth-Assertion. -
Content-Type
string
required
Required for operations with a request body. The value is application/. Where the 'format' is 'json'.
Path parameters
-
order_id
string
required
The ID of the order for which to authorize.
Request body
-
payment_source
The source of payment for the order, which can be a token or a card. Use this object only if you have not redirected the user after order creation to approve the payment. In such cases, the user-selected payment method in the PayPal flow is implicitly used.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/authorize \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-H "PayPal-Request-Id: 7b92603e-77ed-4896-8e78-5dea2050476a"
Response
201 Created
status code with a JSON response body that shows authorized payment details. If a duplicate response is retried, returns the HTTP 200 OK
status code. By default, the response is minimal. If you need the complete resource representation, you must pass the Prefer: return=representation
request header.-
create_time
The date and time when the transaction occurred, in Internet date and time format. -
update_time
The date and time when the transaction was last updated, in Internet date and time format. -
id
string
The ID of the order. -
intent
enum
The intent to either capture payment immediately or authorize a payment for an order after order creation. The possible values are:CAPTURE
. The merchant intends to capture payment immediately after the customer makes a payment.AUTHORIZE
. The merchant intends to authorize a payment and place funds on hold after the customer makes a payment. Authorized payments are guaranteed for up to three days but are available to capture for up to 29 days. After the three-day honor period, the original authorized payment expires and you must re-authorize the payment. You must make a separate request to capture payments on demand.
-
payer
The customer who approves and pays for the order. The customer is also known as the payer. -
purchase_units
array (contains the purchase_unit object)
An array of purchase units. Each purchase unit establishes a contract between a customer and merchant. Each purchase unit represents either a full or partial order that the customer intends to purchase from the merchant. -
status
enum
The order status. The possible values are:CREATED
. The order was created with the specified context.SAVED
. The order was saved and persisted. The order status continues to be in progress until a capture is made withfinal_capture = true
for all purchase units within the order.APPROVED
. The customer approved the payment through the PayPal wallet or another form of guest or unbranded payment. For example, a card, bank account, or so on.VOIDED
. All purchase units in the order are voided.COMPLETED
. The payment was authorized or the authorized payment was captured for the order.
-
links
array (contains the link_description object)
An array of request-related HATEOAS links. To complete payer approval, use theapprove
link with theGET
method.
Sample Response
{
"id": "5O190127TN364715T",
"status": "COMPLETED",
"payer": {
"name": {
"given_name": "John",
"surname": "Doe"
},
"email_address": "customer@example.com",
"payer_id": "QYR5Z8XDVJNXQ"
},
"purchase_units": [
{
"reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
"shipping": {
"address": {
"address_line_1": "2211 N First Street",
"address_line_2": "Building 17",
"admin_area_2": "San Jose",
"admin_area_1": "CA",
"postal_code": "95131",
"country_code": "US"
}
},
"payments": {
"authorizations": [
{
"id": "0AW2184448108334S",
"status": "CREATED",
"amount": {
"currency_code": "USD",
"value": "100.00"
},
"seller_protection": {
"status": "ELIGIBLE",
"dispute_categories": [
"ITEM_NOT_RECEIVED",
"UNAUTHORIZED_TRANSACTION"
]
},
"expiration_time": "2018-05-01T21:20:49Z",
"create_time": "2018-04-01T21:20:49Z",
"update_time": "2018-04-01T21:20:49Z",
"links": [
{
"href": "https://api.paypal.com/v2/payments/authorizations/0AW2184448108334S",
"rel": "self",
"method": "GET"
},
{
"href": "https://api.paypal.com/v2/payments/authorizations/0AW2184448108334S/capture",
"rel": "capture",
"method": "POST"
},
{
"href": "https://api.paypal.com/v2/payments/authorizations/0AW2184448108334S/void",
"rel": "void",
"method": "POST"
},
{
"href": "https://api.paypal.com/v2/payments/authorizations/0AW2184448108334S/reauthorize",
"rel": "reauthorize",
"method": "POST"
}
]
}
]
}
}
],
"links": [
{
"href": "https://api.paypal.com/v2/checkout/orders/5O190127TN364715T",
"rel": "self",
"method": "GET"
}
]
}
Capture payment for order
Header parameters
-
PayPal-Request-Id
string
The server stores keys for 45 days. For more information about PayPal-Request-Id, see PayPal-Request-Id. -
Prefer
string
The preferred server response upon successful completion of the request. Value is:return=minimal
. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes theid
,status
and HATEOAS links.return=representation
. The server returns a complete resource representation, including the current state of the resource.
-
PayPal-Client-Metadata-Id
string
For more information about PayPal-Client-Metadata-Id, see PayPal-Client-Metadata-Id. -
Authorization
string
required
To make REST API calls, include the bearer token in this header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id;secret>
. -
PayPal-Auth-Assertion
string
An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see PayPal-Auth-Assertion. -
Content-Type
string
required
Required for operations with a request body. The value is application/. Where the 'format' is 'json'.
Path parameters
-
order_id
string
required
The ID of the order for which to capture a payment.
Request body
-
payment_source
The payment source definition.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/capture \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-H "PayPal-Request-Id: 7b92603e-77ed-4896-8e78-5dea2050476a"
Response
201 Created
status code with a JSON response body that shows captured payment details. If a duplicate response is retried, returns the HTTP 200 OK
status code. By default, the response is minimal. If you need the complete resource representation, pass the Prefer: return=representation
request header.-
create_time
The date and time when the transaction occurred, in Internet date and time format. -
update_time
The date and time when the transaction was last updated, in Internet date and time format. -
id
string
The ID of the order. -
intent
enum
The intent to either capture payment immediately or authorize a payment for an order after order creation. The possible values are:CAPTURE
. The merchant intends to capture payment immediately after the customer makes a payment.AUTHORIZE
. The merchant intends to authorize a payment and place funds on hold after the customer makes a payment. Authorized payments are guaranteed for up to three days but are available to capture for up to 29 days. After the three-day honor period, the original authorized payment expires and you must re-authorize the payment. You must make a separate request to capture payments on demand.
-
payer
The customer who approves and pays for the order. The customer is also known as the payer. -
purchase_units
array (contains the purchase_unit object)
An array of purchase units. Each purchase unit establishes a contract between a customer and merchant. Each purchase unit represents either a full or partial order that the customer intends to purchase from the merchant. -
status
enum
The order status. The possible values are:CREATED
. The order was created with the specified context.SAVED
. The order was saved and persisted. The order status continues to be in progress until a capture is made withfinal_capture = true
for all purchase units within the order.APPROVED
. The customer approved the payment through the PayPal wallet or another form of guest or unbranded payment. For example, a card, bank account, or so on.VOIDED
. All purchase units in the order are voided.COMPLETED
. The payment was authorized or the authorized payment was captured for the order.
-
links
array (contains the link_description object)
An array of request-related HATEOAS links. To complete payer approval, use theapprove
link with theGET
method.
Sample Response
{
"id": "5O190127TN364715T",
"status": "COMPLETED",
"payer": {
"name": {
"given_name": "John",
"surname": "Doe"
},
"email_address": "customer@example.com",
"payer_id": "QYR5Z8XDVJNXQ"
},
"purchase_units": [
{
"reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
"shipping": {
"address": {
"address_line_1": "2211 N First Street",
"address_line_2": "Building 17",
"admin_area_2": "San Jose",
"admin_area_1": "CA",
"postal_code": "95131",
"country_code": "US"
}
},
"payments": {
"captures": [
{
"id": "3C679366HH908993F",
"status": "COMPLETED",
"amount": {
"currency_code": "USD",
"value": "100.00"
},
"seller_protection": {
"status": "ELIGIBLE",
"dispute_categories": [
"ITEM_NOT_RECEIVED",
"UNAUTHORIZED_TRANSACTION"
]
},
"final_capture": true,
"disbursement_mode": "INSTANT",
"seller_receivable_breakdown": {
"gross_amount": {
"currency_code": "USD",
"value": "100.00"
},
"paypal_fee": {
"currency_code": "USD",
"value": "3.00"
},
"net_amount": {
"currency_code": "USD",
"value": "97.00"
}
},
"create_time": "2018-04-01T21:20:49Z",
"update_time": "2018-04-01T21:20:49Z",
"links": [
{
"href": "https://api.paypal.com/v2/payments/captures/3C679366HH908993F",
"rel": "self",
"method": "GET"
},
{
"href": "https://api.paypal.com/v2/payments/captures/3C679366HH908993F/refund",
"rel": "refund",
"method": "POST"
}
]
}
]
}
}
],
"links": [
{
"href": "https://api.paypal.com/v2/checkout/orders/5O190127TN364715T",
"rel": "self",
"method": "GET"
}
]
}
Common object definitions
activity_timestamps
-
create_time
The date and time when the transaction occurred, in Internet date and time format. -
update_time
The date and time when the transaction was last updated, in Internet date and time format.
address_details
-
street_number
string
The street number. -
street_name
string
The street name. JustDrury
inDrury Lane
. -
street_type
string
The street type. For example, avenue, boulevard, road, or expressway. -
delivery_service
string
The delivery service. Post office box, bag number, or post office name. -
building_name
string
A named locations that represents the premise. Usually a building name or number or collection of buildings with a common name or number. For example,Craven House
. -
sub_building
string
The first-order entity below a named building or location that represents the sub-premise. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment.
address_portable
-
address_line_1
string
The first line of the address. For example, number or street. For example,173 Drury Lane
. Required for data entry and compliance and risk checks. Must contain the full address. -
address_line_2
string
The second line of the address. For example, suite or apartment number. -
admin_area_2
string
A city, town, or village. Smaller thanadmin_area_level_1
. -
admin_area_1
string
The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example,CA
and notCalifornia
. Value, by country, is:- UK. A county.
- US. A state.
- Canada. A province.
- Japan. A prefecture.
- Switzerland. A kanton.
-
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. -
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.
address_portable
-
address_line_1
string
The first line of the address. For example, number or street. For example,173 Drury Lane
. Required for data entry and compliance and risk checks. Must contain the full address. -
address_line_2
string
The second line of the address. For example, suite or apartment number. -
admin_area_2
string
A city, town, or village. Smaller thanadmin_area_level_1
. -
admin_area_1
string
The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example,CA
and notCalifornia
. Value, by country, is:- UK. A county.
- US. A state.
- Canada. A province.
- Japan. A prefecture.
- Switzerland. A kanton.
-
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. -
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.
address_portable
-
address_line_1
string
The first line of the address. For example, number or street. For example,173 Drury Lane
. Required for data entry and compliance and risk checks. Must contain the full address. -
address_line_2
string
The second line of the address. For example, suite or apartment number. -
admin_area_2
string
A city, town, or village. Smaller thanadmin_area_level_1
. -
admin_area_1
string
The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example,CA
and notCalifornia
. Value, by country, is:- UK. A county.
- US. A state.
- Canada. A province.
- Japan. A prefecture.
- Switzerland. A kanton.
-
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. -
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.
address_portable
-
address_line_1
string
The first line of the address. For example, number or street. For example,173 Drury Lane
. Required for data entry and compliance and risk checks. Must contain the full address. -
address_line_2
string
The second line of the address. For example, suite or apartment number. -
address_line_3
string
The third line of the address, if needed. For example, a street complement for Brazil, direction text, such asnext to Walmart
, or a landmark in an Indian address. -
admin_area_4
string
The neighborhood, ward, or district. Smaller thanadmin_area_level_3
orsub_locality
. Value is:- The postal sorting code for Guernsey and many French territories, such as French Guiana.
- The fine-grained administrative levels in China.
-
admin_area_3
string
A sub-locality, suburb, neighborhood, or district. Smaller thanadmin_area_level_2
. Value is:- Brazil. Suburb, bairro, or neighborhood.
- India. Sub-locality or district. Street name information is not always available but a sub-locality or district can be a very small area.
-
admin_area_2
string
A city, town, or village. Smaller thanadmin_area_level_1
. -
admin_area_1
string
The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example,CA
and notCalifornia
. Value, by country, is:- UK. A county.
- US. A state.
- Canada. A province.
- Japan. A prefecture.
- Switzerland. A kanton.
-
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. -
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. -
address_details
The non-portable additional address details that are sometimes needed for compliance, risk, or other scenarios where fine-grain address information might be needed. Not portable with common third party and open source. Redundant with core fields.
For example,address_portable.address_line_1
is usually a combination ofaddress_details.street_number
,street_name
, andstreet_type
.
address_portable_postal_code_validation
-
address_portable_postal_code_validation
amount_breakdown
-
item_total
The subtotal for all items. Required if the request includespurchase_units[].items[].unit_amount
. Must equal the sum of(items[].unit_amount * items[].quantity)
for all items. -
shipping
The shipping fee for all items within a givenpurchase_unit
. -
handling
The handling fee for all items within a givenpurchase_unit
. -
tax_total
The total tax for all items. Required if the request includespurchase_units.items.tax
. Must equal the sum of(items[].tax * items[].quantity)
for all items. -
insurance
The insurance fee for all items within a givenpurchase_unit
. -
shipping_discount
The shipping discount for all items within a givenpurchase_unit
.
amount_with_breakdown
-
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
-
breakdown
The breakdown of the amount. Breakdown provides details such as total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.
application_context
-
brand_name
string
The label that overrides the business name in the PayPal account on the PayPal site. -
locale
The BCP 47-formatted locale of pages that the PayPal payment experience shows. PayPal supports a five-character code. For example,da-DK
,he-IL
,id-ID
,ja-JP
,no-NO
,pt-BR
,ru-RU
,sv-SE
,th-TH
,zh-CN
,zh-HK
, orzh-TW
. -
landing_page
enum
The type of landing page to show on the PayPal site for customer checkout. The possible values are:LOGIN
. When the customer clicks PayPal Checkout, the customer is redirected to a page to log in to PayPal and approve the payment.BILLING
. When the customer clicks PayPal Checkout, the customer is redirected to a page to enter credit or debit card and other relevant billing information required to complete the purchase.
-
shipping_preference
enum
The shipping preference:- Displays the shipping address to the customer.
- Enables the customer to choose an address on the PayPal site.
- Restricts the customer from changing the address during the payment-approval process.
GET_FROM_FILE
. Use the customer-provided shipping address on the PayPal site.NO_SHIPPING
. Redact the shipping address from the PayPal site. Recommended for digital goods.SET_PROVIDED_ADDRESS
. Use the merchant-provided address. The customer cannot change this address on the PayPal site.
-
user_action
enum
Configures a Continue or Pay Now checkout flow. The possible values are:CONTINUE
. After you redirect the customer to the PayPal payment page, a Continue button appears. Use this option when the final amount is not known when the checkout flow is initiated and you want to redirect the customer to the merchant page without processing the payment.PAY_NOW
. After you redirect the customer to the PayPal payment page, a Pay Now button appears. Use this option when the final amount is known when the checkout is initiated and you want to process the payment immediately when the customer clicks Pay Now.
-
payment_method
The customer and merchant payment preferences. -
return_url
string
The URL where the customer is redirected after the customer approves the payment. -
cancel_url
string
The URL where the customer is redirected after the customer cancels the payment.
authorization
-
status
enum
The status for the authorized payment. The possible values are:CREATED
. The authorized payment is created. No captured payments have been made for this authorized payment.CAPTURED
. The authorized payment has one or more captures against it. The sum of these captured payments is greater than the amount of the original authorized payment.DENIED
. PayPal cannot authorize funds for this authorized payment.EXPIRED
. The authorized payment has expired.PARTIALLY_CAPTURED
. A captured payment was made for the authorized payment for an amount that is less than the amount of the original authorized payment.VOIDED
. The authorized payment was voided. No more captured payments can be made against this authorized payment.
-
id
string
The PayPal-generated ID for the authorized payment. -
amount
The amount for this authorized payment. -
invoice_id
string
The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives. -
seller_protection
The level of protection offered as defined by PayPal Seller Protection for Merchants. -
expiration_time
The date and time when the authorized payment expires, in Internet date and time format. -
links
array (contains the link_description object)
An array of related HATEOAS links.
-
create_time
The date and time when the transaction occurred, in Internet date and time format. -
update_time
The date and time when the transaction was last updated, in Internet date and time format.
authorization_status
-
status
enum
The status for the authorized payment. The possible values are:CREATED
. The authorized payment is created. No captured payments have been made for this authorized payment.CAPTURED
. The authorized payment has one or more captures against it. The sum of these captured payments is greater than the amount of the original authorized payment.DENIED
. PayPal cannot authorize funds for this authorized payment.EXPIRED
. The authorized payment has expired.PARTIALLY_CAPTURED
. A captured payment was made for the authorized payment for an amount that is less than the amount of the original authorized payment.VOIDED
. The authorized payment was voided. No more captured payments can be made against this authorized payment.
authorize_request
-
payment_source
The source of payment for the order, which can be a token or a card. Use this object only if you have not redirected the user after order creation to approve the payment. In such cases, the user-selected payment method in the PayPal flow is implicitly used.
capture
-
status
enum
The status of the captured payment. The possible values are:COMPLETED
. The funds for this captured payment were credited to the payee's PayPal account.DECLINED
. The funds could not be captured.PARTIALLY_REFUNDED
. An amount less than this captured payment's amount was partially refunded to the payer.PENDING
. The funds for this captured payment was not yet credited to the payee's PayPal account. For more information, seestatus.details
REFUNDED
. An amount greater than or equal to this captured payment's amount was refunded to the payer.
-
status_details
The details of the captured payment status.
-
id
string
The PayPal-generated ID for the captured payment. -
amount
The amount for this captured payment. -
invoice_id
string
The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives. -
seller_protection
The level of protection offered as defined by PayPal Seller Protection for Merchants. -
final_capture
boolean
Indicates whether you can make additional captures against the authorized payment. Set totrue
if you do not intend to capture additional payments against the authorization. Set tofalse
if you intend to capture additional payments against the authorization. -
seller_receivable_breakdown
The detailed breakdown of the captured payment. -
disbursement_mode
enum
The funds that are held on behalf of the merchant. The possible values are:INSTANT
. The funds are released to the merchant immediately.DELAYED
. The funds are held for a finite number of days. The actual duration depends on the region and type of integration. You can release the funds through a referenced payout. Otherwise, the funds disbursed automatically after the specified duration.
-
links
array (contains the link_description object)
An array of related HATEOAS links.
-
create_time
The date and time when the transaction occurred, in Internet date and time format. -
update_time
The date and time when the transaction was last updated, in Internet date and time format.
capture_status
-
status
enum
The status of the captured payment. The possible values are:COMPLETED
. The funds for this captured payment were credited to the payee's PayPal account.DECLINED
. The funds could not be captured.PARTIALLY_REFUNDED
. An amount less than this captured payment's amount was partially refunded to the payer.PENDING
. The funds for this captured payment was not yet credited to the payee's PayPal account. For more information, seestatus.details
REFUNDED
. An amount greater than or equal to this captured payment's amount was refunded to the payer.
-
status_details
The details of the captured payment status.
capture_status_details
-
reason
enum
The reason why the captured payment status isPENDING
orDENIED
. The possible values are:BUYER_COMPLAINT
. The payer initiated a dispute for this captured payment with PayPal.CHARGEBACK
. The captured funds were reversed in response to the payer disputing this captured payment with the issuer of the financial instrument used to pay for this captured payment.ECHECK
. The payer paid by an eCheck that has not yet cleared.INTERNATIONAL_WITHDRAWAL
. Visit your online account. In your **Account Overview**, accept and deny this payment.OTHER
. No additional specific reason can be provided. For more information about this captured payment, visit your account online or contact PayPal.PENDING_REVIEW
. The captured payment is pending manual review.RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION
. The payee has not yet set up appropriate receiving preferences for their account. For more information about how to accept or deny this payment, visit your account online. This reason is typically offered in scenarios such as when the currency of the captured payment is different from the primary holding currency of the payee.REFUNDED
. The captured funds were refunded.TRANSACTION_APPROVED_AWAITING_FUNDING
. The payer must send the funds for this captured payment. This code generally appears for manual EFTs.UNILATERAL
. The payee does not have a PayPal account.VERIFICATION_REQUIRED
. The payee's PayPal account is not verified.
card
-
id
string
The PayPal-generated ID for the card. -
name
string
The card holder's name as it appears on the card. -
number
string
required
The primary account number (PAN) for the payment card. -
The card expiration year and month, in Internet date format.
-
security_code
string
The three- or four-digit security code of the card. Also known as the CVV, CVC, CVN, CVE, or CID. -
last_digits
string
The last digits of the payment card. -
card_type
enum
The card brand or network. Typically used in the response. The possible values are:VISA
. Visa card.MASTERCARD
. MasterCard card.DISCOVER
. Discover card.AMEX
. American Express card.SOLO
. Solo debit card.JCB
. Japan Credit Bureau card.STAR
. Military Star card.DELTA
. Delta Airlines card.SWITCH
. Switch credit card.MAESTRO
. Maestro credit card.CB_NATIONALE
. Carte Bancaire (CB) credit card.CONFIGOGA
. Configoga credit card.CONFIDIS
. Confidis credit card.ELECTRON
. Visa Electron credit card.CETELEM
. Cetelem credit card.CHINA_UNION_PAY
. China union pay credit card.
-
billing_address
The billing address for this card. Supports only theaddress_line_1
,address_line_2
,admin_area_1
,admin_area_2
,postal_code
, andcountry_code
properties.
card_type
-
card_type
enum
The card network or brand. Applies to credit, debit, gift, and payment cards. The possible values are:VISA
. Visa card.MASTERCARD
. MasterCard card.DISCOVER
. Discover card.AMEX
. American Express card.SOLO
. Solo debit card.JCB
. Japan Credit Bureau card.STAR
. Military Star card.DELTA
. Delta Airlines card.SWITCH
. Switch credit card.MAESTRO
. Maestro credit card.CB_NATIONALE
. Carte Bancaire (CB) credit card.CONFIGOGA
. Configoga credit card.CONFIDIS
. Confidis credit card.ELECTRON
. Visa Electron credit card.CETELEM
. Cetelem credit card.CHINA_UNION_PAY
. China union pay credit card.
checkout_payment_intent
-
checkout_payment_intent
enum
The intent to either capture payment immediately or authorize a payment for an order after order creation. The possible values are:CAPTURE
. The merchant intends to capture payment immediately after the customer makes a payment.AUTHORIZE
. The merchant intends to authorize a payment and place funds on hold after the customer makes a payment. Authorized payments are guaranteed for up to three days but are available to capture for up to 29 days. After the three-day honor period, the original authorized payment expires and you must re-authorize the payment. You must make a separate request to capture payments on demand.
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.
currency_code
-
currency_code
string
The three-character ISO-4217 currency code that identifies the currency.
date_no_time
-
date_no_time
string
The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standarddate_time
type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.
date_time
-
date_time
string
The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.Note: The regular expression provides guidance but does not reject all invalid dates.
date_year_month
-
date_year_month
string
The year and month, in ISO-8601YYYY-MM
date format. See Internet date and time format.
disbursement_mode
-
disbursement_mode
enum
The funds that are held on behalf of the merchant. The possible values are:INSTANT
. The funds are released to the merchant immediately.DELAYED
. The funds are held for a finite number of days. The actual duration depends on the region and type of integration. You can release the funds through a referenced payout. Otherwise, the funds disbursed automatically after the specified duration.
dispute_category
-
dispute_category
enum
The condition that is covered for the transaction. The possible values are:ITEM_NOT_RECEIVED
. The payer paid for an item that he or she did not receive.UNAUTHORIZED_TRANSACTION
. The payer did not authorize the payment.
-
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 accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@
sign exists.
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. 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 this field is in the body, set this value to the field's JSON pointer value. 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 isbody
,path
, orquery
. -
issue
string
required
The unique, fine-grained application-level error code. -
description
string
The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value.
exchange_rate
-
source_currency
The source currency from which to convert an amount. -
target_currency
The target currency into which to convert an amount. -
value
string
The target currency amount. Equivalent to one unit of the source currency. Formatted as integer or decimal value with one to 15 digits to the right of the decimal point.
item
-
name
string
required
The item name or title. -
The item price or rate per unit. If you specify
unit_amount
,purchase_units[].amount.breakdown.item_total
is required. Must equalunit_amount * quantity
for all items. -
tax
The item tax for each unit. Iftax
is specified,purchase_units[].amount.breakdown.tax_total
is required. Must equaltax * quantity
for all items. -
quantity
string
required
The item quantity. Must be a whole number. -
description
string
The detailed item description. -
sku
string
The stock keeping unit (SKU) for the item. -
category
enum
The item category type. The possible values are:DIGITAL_GOODS
. Goods that are stored, delivered, and used in their electronic format.PHYSICAL_GOODS
. A tangible item that can be shipped with proof of delivery.
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.
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
-
prefix
string
The prefix, or title, to the party's name. -
given_name
string
When the party is a person, the party's given, or first, name. -
surname
string
When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname. -
middle_name
string
When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name. -
suffix
string
The suffix for the party's name. -
alternate_full_name
string
DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business. -
full_name
string
When the party is a person, the party's full name.
name
-
full_name
string
When the party is a person, the party's full name.
name
-
given_name
string
When the party is a person, the party's given, or first, name. -
surname
string
When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.
name_validation
-
name_validation
order
-
create_time
The date and time when the transaction occurred, in Internet date and time format. -
update_time
The date and time when the transaction was last updated, in Internet date and time format.
-
id
string
The ID of the order. -
intent
enum
The intent to either capture payment immediately or authorize a payment for an order after order creation. The possible values are:CAPTURE
. The merchant intends to capture payment immediately after the customer makes a payment.AUTHORIZE
. The merchant intends to authorize a payment and place funds on hold after the customer makes a payment. Authorized payments are guaranteed for up to three days but are available to capture for up to 29 days. After the three-day honor period, the original authorized payment expires and you must re-authorize the payment. You must make a separate request to capture payments on demand.
-
payer
The customer who approves and pays for the order. The customer is also known as the payer. -
purchase_units
array (contains the purchase_unit object)
An array of purchase units. Each purchase unit establishes a contract between a customer and merchant. Each purchase unit represents either a full or partial order that the customer intends to purchase from the merchant. -
status
enum
The order status. The possible values are:CREATED
. The order was created with the specified context.SAVED
. The order was saved and persisted. The order status continues to be in progress until a capture is made withfinal_capture = true
for all purchase units within the order.APPROVED
. The customer approved the payment through the PayPal wallet or another form of guest or unbranded payment. For example, a card, bank account, or so on.VOIDED
. All purchase units in the order are voided.COMPLETED
. The payment was authorized or the authorized payment was captured for the order.
-
links
array (contains the link_description object)
An array of request-related HATEOAS links. To complete payer approval, use theapprove
link with theGET
method.
order_action_request
-
payment_source
The source of payment for the order, which can be a token or a card. Use this object only if you have not redirected the user after order creation to approve the payment. In such cases, the user-selected payment method in the PayPal flow is implicitly used.
order_capture_request
-
payment_source
The payment source definition.
order_request
-
intent
enum
required
The intent to either capture payment immediately or authorize a payment for an order after order creation. The possible values are:CAPTURE
. The merchant intends to capture payment immediately after the customer makes a payment.AUTHORIZE
. The merchant intends to authorize a payment and place funds on hold after the customer makes a payment. Authorized payments are guaranteed for up to three days but are available to capture for up to 29 days. After the three-day honor period, the original authorized payment expires and you must re-authorize the payment. You must make a separate request to capture payments on demand.
-
payer
The customer who approves and pays for the order. The customer is also known as the payer. -
An array of purchase units. At present only 1 purchase_unit is supported. Each purchase unit establishes a contract between a payer and the payee. Each purchase unit represents either a full or partial order that the payer intends to purchase from the payee.
-
application_context
Customize the payer experience during the approval process for the payment with PayPal.
order_status
-
order_status
enum
The order status. The possible values are:CREATED
. The order was created with the specified context.SAVED
. The order was saved and persisted. The order status continues to be in progress until a capture is made withfinal_capture = true
for all purchase units within the order.APPROVED
. The customer approved the payment through the PayPal wallet or another form of guest or unbranded payment. For example, a card, bank account, or so on.VOIDED
. All purchase units in the order are voided.COMPLETED
. The payment was authorized or the authorized payment was captured for the order.
patch
-
op
enum
required
The operation. The possible values are:add
. Depending on the target location reference, completes one of these functions:- The target location is an array index. Inserts a new value into the array at the specified index.
- The target location is an object parameter that does not already exist. Adds a new parameter to the object.
- The target location is an object parameter that does exist. Replaces that parameter's value.
value
parameter defines the value to add. For more information, see 4.1. add.remove
. Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.replace
. Replaces the value at the target location with a new value. The operation object must contain avalue
parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.move
. Removes the value at a specified location and adds it to the target location. The operation object must contain afrom
parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, thefrom
location must exist. For more information, see 4.4. move.copy
. Copies the value at a specified location to the target location. The operation object must contain afrom
parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, thefrom
location must exist. For more information, see 4.5. copy.test
. Tests that a value at the target location is equal to a specified value. The operation object must contain avalue
parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to thevalue
value. For test,equal
indicates that the value at the target location and the value thatvalue
defines are of the same JSON type. The data type of the value determines how equality is defined:
For more information, see 4.6. test.Type Considered equal if both values strings Contain the same number of Unicode characters and their code points are byte-by-byte equal. numbers Are numerically equal. arrays Contain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules. objects Contain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules). literals ( false
,true
, andnull
)Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.
-
path
string
The JSON Pointer to the target document location at which to complete the operation. -
value
number,integer,string,boolean,null,array,object
The value to apply. Theremove
operation does not require a value. -
from
string
The JSON Pointer to the target document location from which to move the value. Required for themove
operation.
patch_request
-
patch_request
array (contains the patch object)
An array of JSON patch objects to apply partial updates to resources.
payer
-
name
The name of the payer. Supports only thegiven_name
andsurname
properties. -
email_address
The email address of the payer. -
payer_id
The PayPal assigned ID for the payer. -
phone
The phone number of the customer. Available only when you enable the Contact Telephone Number option in the Profile & Settings for the merchant's PayPal account. Thephone.phone_number
supports onlynational_number
. -
birth_date
The birth date of the payer inYYYY-MM-DD
format. -
tax_info
The tax information of the payer. Required only for Brazilian payer's. Bothtax_id
andtax_id_type
are required. -
address
The address of the payer. Supports only theaddress_line_1
,address_line_2
,admin_area_1
,admin_area_2
,postal_code
, andcountry_code
properties. Also referred to as the billing address of the customer.
payer_id
-
payer_id
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 a proprietary variant of Base32 is used to encode the result.
payment_collection
-
authorizations
array (contains the authorization object)
An array of authorized payments for a purchase unit. A purchase unit can have zero or more authorized payments. -
captures
array (contains the capture object)
An array of captured payments for a purchase unit. A purchase unit can have zero or more captured payments. -
refunds
array (contains the refund object)
An array of refunds for a purchase unit. A purchase unit can have zero or more refunds.
payment_instruction
-
platform_fees
array (contains the platform_fee object)
An array of various fees, commissions, tips, or donations. -
disbursement_mode
enum
The funds that are held on behalf of the merchant. The possible values are:INSTANT
. The funds are released to the merchant immediately.DELAYED
. The funds are held for a finite number of days. The actual duration depends on the region and type of integration. You can release the funds through a referenced payout. Otherwise, the funds disbursed automatically after the specified duration.
payment_method
-
payer_selected
enum
The customer-selected payment method on the merchant site. The possible values are:PAYPAL_CREDIT
. When payer chooses PayPal Credit as the payment method.PAYPAL
. When payer chooses PayPal as the payment method
-
payee_preferred
enum
The merchant-preferred payment sources. The possible values are:UNRESTRICTED
. Accepts any type of payment from the customer.IMMEDIATE_PAYMENT_REQUIRED
. Accepts only immediate payment from the customer. For example, credit card, PayPal balance, or instant ACH. Ensures that at the time of capture, the payment does not have the `pending` status.
phone
-
national_number
string
required
The national number, in its canonical international E.164 numbering plan format. The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).
phone
-
country_code
string
required
The country calling code (CC), in its canonical international E.164 numbering plan format. The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN). -
national_number
string
required
The national number, in its canonical international E.164 numbering plan format. The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN). -
extension_number
string
The extension number.
phone_type
-
phone_type
enum
The phone type.
phone_with_type
-
phone_type
enum
The phone type. -
The phone number, in its canonical international E.164 numbering plan format. Supports only the
national_number
property.
purchase_unit
-
reference_id
string
The API caller-provided external ID for the purchase unit. Required for multiple purchase units when you must update the order throughPATCH
. If not provided and there is only 1purchase_unit
as part of the order, value is automatically set by PayPal todefault
. -
amount
The total order amount with an optional breakdown that provides details, such as the total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.
If you specifyamount.breakdown
, the amount equalsitem_total
plustax_total
plusshipping
plushandling
plusinsurance
minusshipping_discount
.
The amount must be a positive number. For listed of supported currencies and decimal precision, see the PayPal REST APIs Currency Codes. -
payee
The merchant who receives payment for this transaction. -
payment_instruction
Any additional payment instructions for PayPal for Partner customers. Enables features for partners and marketplaces, such as delayed disbursement and collection of a platform fee. Applies during order creation for captured payments or during capture of authorized payments. -
description
string
The purchase description. -
custom_id
string
The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports. -
invoice_id
string
The API caller-provided external invoice ID for this order. -
id
string
The PayPal-generated ID for the purchase unit. This ID appears in both the payer's transaction history and the emails that the payer receives. In addition, this ID is available in transaction and settlement reports that merchants and API callers can use to reconcile transactions. This ID is only available when an order is saved by callingv2/checkout/orders/id/save
. -
soft_descriptor
string
The payment descriptor on the customer's credit card statement of account transactions. -
items
array (contains the item object)
An array of items that the customer purchases from the merchant. -
shipping
The shipping address and method. -
payments
The comprehensive history of payments for the purchase unit.
purchase_unit_request
-
reference_id
string
The ID for the purchase unit. Required for multiplepurchase_units
or if an order must be updated by usingPATCH
. If you omit thereference_id
for an order with one purchase unit, PayPal sets thereference_id
todefault
. -
The total order amount with an optional breakdown that provides details, such as the total item amount, total tax amount, shipping, handling, insurance, and discounts, if any.
If you specifyamount.breakdown
, the amount equalsitem_total
plustax_total
plusshipping
plushandling
plusinsurance
minusshipping_discount
.
The amount must be a positive number. For listed of supported currencies and decimal precision, see the PayPal REST APIs Currency Codes. -
payee
The merchant who receives payment for this transaction. -
payment_instruction
Any additional payment instructions for PayPal for Partner customers. Enables features for partners and marketplaces, such as delayed disbursement and collection of a platform fee. Applies during order creation for captured payments or during capture of authorized payments. -
description
string
The purchase description. -
custom_id
string
The API caller-provided external ID. Used to reconcile client transactions with PayPal transactions. Appears in transaction and settlement reports but is not visible to the payer. -
invoice_id
string
The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives. -
soft_descriptor
string
The payment descriptor on the payer's credit card statement. -
items
array (contains the item object)
An array of items that the customer is purchasing from the merchant. -
shipping
The name and address of the person to whom to ship the items.
refund
-
status
enum
The status of the capture. The possible values are:CANCELLED
. The refund was cancelled.PENDING
. The refund is pending. For more information, seestatus_details.reason
.COMPLETED
. The funds for this transaction were debited to the customer's account.
-
status_details
The details of the refund status.
-
id
string
The PayPal-generated ID for the refund. -
amount
The amount that the payee refunded to the payer. -
invoice_id
string
The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives. -
note_to_payer
string
The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives. -
seller_payable_breakdown
The breakdown of the refund. -
links
array (contains the link_description object)
An array of related HATEOAS links.
-
create_time
The date and time when the transaction occurred, in Internet date and time format. -
update_time
The date and time when the transaction was last updated, in Internet date and time format.
refund_status
-
status
enum
The status of the capture. The possible values are:CANCELLED
. The refund was cancelled.PENDING
. The refund is pending. For more information, seestatus_details.reason
.COMPLETED
. The funds for this transaction were debited to the customer's account.
-
status_details
The details of the refund status.
refund_status_details
-
reason
enum
The reason why the refund has thePENDING
orFAILED
status. The possible values are:ECHECK
. The customer's account is funded through an eCheck, which has not yet cleared.
seller_payable_breakdown
-
gross_amount
The amount that the payee refunded to the payer. -
paypal_fee
The PayPal fee that was refunded to the payer. This fee might not match the PayPal fee that the payee paid when the payment was captured. -
net_amount
The net amount that the payee's account is debited, if the payee holds funds in the currency for this refund. The net amount is calculated asgross_amount
minuspaypal_fee
minusplatform_fees
. -
platform_fees
array (contains the platform_fee object)
An array of platform or partner fees, commissions, or brokerage fees for the refund. -
net_amount_breakdown
array (contains the net_amount_breakdown_item object)
An array of breakdown values for the net amount. Returned when the currency of the refund is different from the currency of the PayPal account where the payee holds their funds. -
total_refunded_amount
The total amount refunded from the original capture to date. For example, if a payer makes a $100 purchase and was refunded $20 a week ago and was refunded $30 in this refund, thegross_amount
is $30 for this refund and thetotal_refunded_amount
is $50.
seller_protection
-
status
enum
Indicates whether the transaction is eligible for seller protection. For information, see PayPal Seller Protection for Merchants. The possible values are:ELIGIBLE
. Your PayPal balance remains intact if the customer claims that he or she did not receive an item or the account holder claims that he or she did not authorize the payment.PARTIALLY_ELIGIBLE
. Your PayPal balance remains intact if the customer claims that he or she did not receive an item.NOT_ELIGIBLE
. This transaction is not eligible for seller protection.
-
dispute_categories
array (contains the dispute_category object)
An array of conditions that are covered for the transaction.
seller_receivable_breakdown
-
gross_amount
The amount for this captured payment. -
paypal_fee
The applicable fee for this captured payment. -
net_amount
The net amount that the payee receives for this captured payment in their PayPal account. The net amount is computed asgross_amount
minus thepaypal_fee
minus theplatform_fees
. -
receivable_amount
The net amount that is credited to the payee's PayPal account. Returned only when the currency of the captured payment is different from the currency of the PayPal account where the payee wants to credit the funds. The amount is computed asnet_amount
timesexchange_rate
. -
exchange_rate
The exchange rate that determines the amount that is credited to the payee's PayPal account. Returned when the currency of the captured payment is different from the currency of the PayPal account where the payee wants to credit the funds. -
platform_fees
array (contains the platform_fee object)
An array of platform or partner fees, commissions, or brokerage fees that associated with the captured payment.
shipping_detail
tax_info
-
tax_id
string
required
The customer's tax ID. Supported for the PayPal payment method only. Typically, the tax ID is 11 characters long for individuals and 14 characters long for businesses. -
tax_id_type
enum
required
The customer's tax ID type. Supported for the PayPal payment method only. The possible values are:BR_CPF
. The individual tax ID type.BR_CNPJ
. The business tax ID type.
token
-
id
string
required
The PayPal-generated ID for the token. -
type
enum
required
The tokenization method that was used to generate the ID. The possible values are:NONCE
. A secure, one-time-use reference to a payment source, such as payment card, PayPal account, and so on.PAYMENT_METHOD_TOKEN
. The payment method token, which is a reference to a transactional payment source. Typically stored on the merchant's server.BILLING_AGREEMENT
. The PayPal billing agreement ID. References an approved recurring payment for goods or services.
Additional API information
Error messages
In addition to common HTTP status codes that the REST APIs return, the Orders API can return the following errors.