Orders API
Orders (resource group)
Use the /orders
resource to create, update, retrieve, authorize, and capture orders.
Create order
Header parameters
PayPal-Request-Id
string
The server stores keys for 3 hours.
PayPal-Partner-Attribution-Id
string
PayPal-Client-Metadata-Id
string
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 the
Bearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id:secret>
.Content-Type
string
required
The media type. Required for operations with a request body. The value is
application/<format>
, whereformat
isjson
.
Request body
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 best captured within three days of authorization 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. This intent is not supported when you have more than one `purchase_unit` within your order.
payer
The customer who approves and pays for the order. The customer is also known as the payer.
An array of purchase units. 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-m.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.
payment_source
The payment source used to fund the 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 best captured within three days of authorization 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. This intent is not supported when you have more than one `purchase_unit` within your order.
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.PAYER_ACTION_REQUIRED
. The order requires an action from the payer (e.g. 3DS authentication). Redirect the payer to the "rel":"payer-action" HATEOAS link returned as part of the response prior to authorizing or capturing the order.
links
array (contains the link_description object)
An array of request-related HATEOAS links. To complete payer approval, use the
approve
link to redirect the payer. The API caller has 3 hours (default setting, this which can be changed by your account manager to 24/48/72 hours to accommodate your use case) from the time the order is created, to redirect your payer. Once redirected, the API caller has 3 hours for the payer to approve the order and either authorize or capture the order. If you are not using the PayPal JavaScript SDK to initiate PayPal Checkout (in context) ensure that you includeapplication_context.return_url
is specified or you will get "We're sorry, Things don't appear to be working at the moment" after the payer approves the payment.
Sample Response
{
"id": "5O190127TN364715T",
"status": "CREATED",
"links": [
{
"href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
"rel": "self",
"method": "GET"
},
{
"href": "https://www.paypal.com/checkoutnow?token=5O190127TN364715T",
"rel": "approve",
"method": "GET"
},
{
"href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
"rel": "update",
"method": "PATCH"
},
{
"href": "https://api-m.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 defaults to a reference_id
of 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.purchase_units[].shipping.name
— replace, add.purchase_units[].shipping.address
— replace, add.purchase_units[].soft_descriptor
— replace, remove.purchase_units[].amount
— replace.purchase_units[].invoice_id
— replace, add, remove.purchase_units[].payment_instruction
— replace.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 the
Bearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id:secret>
.Content-Type
string
required
The media type. Required for operations with a request body. The value is
application/<format>
, whereformat
isjson
.
Path parameters
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-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '[
{
"op": "replace",
"path": "/purchase_units/@reference_id=='PUHF'/shipping/address",
"value": {
"address_line_1": "123 Townsend St",
"address_line_2": "Floor 6",
"admin_area_2": "San Francisco",
"admin_area_1": "CA",
"postal_code": "94107",
"country_code": "US"
}
}
]'
Response
204 No Content
status code with an empty object in the JSON response body.Sample Response
204 No Content
Show order details
Query parameters
fields
string
A comma-separated list of fields that should be returned for the order. Valid filter field is
payment_source
.
Header parameters
Authorization
string
required
To make REST API calls, include the bearer token in this header with the
Bearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id:secret>
.Content-Type
string
required
The media type. Required for operations with a request body. The value is
application/<format>
, whereformat
isjson
.
Path parameters
id
string
required
The ID of the order for which to show details.
Sample Request
curl -v -X GET https://api-m.sandbox.paypal.com/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.
payment_source
The payment source used to fund the 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 best captured within three days of authorization 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. This intent is not supported when you have more than one `purchase_unit` within your order.
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.PAYER_ACTION_REQUIRED
. The order requires an action from the payer (e.g. 3DS authentication). Redirect the payer to the "rel":"payer-action" HATEOAS link returned as part of the response prior to authorizing or capturing the order.
links
array (contains the link_description object)
An array of request-related HATEOAS links. To complete payer approval, use the
approve
link to redirect the payer. The API caller has 3 hours (default setting, this which can be changed by your account manager to 24/48/72 hours to accommodate your use case) from the time the order is created, to redirect your payer. Once redirected, the API caller has 3 hours for the payer to approve the order and either authorize or capture the order. If you are not using the PayPal JavaScript SDK to initiate PayPal Checkout (in context) ensure that you includeapplication_context.return_url
is specified or you will get "We're sorry, Things don't appear to be working at the moment" after the payer approves the payment.
Sample Response
{
"id": "5O190127TN364715T",
"status": "PAYER_ACTION_REQUIRED",
"intent": "CAPTURE",
"payment_source": {
"alipay": {
"name": "John Doe",
"country_code": "C2"
}
},
"purchase_units": [
{
"reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
"amount": {
"currency_code": "USD",
"value": "100.00"
},
"payee": {
"email_address": "payee@example.com"
}
}
],
"create_time": "2018-04-01T21:18:49Z",
"links": [
{
"href": "https://www.paypal.com/payment/alipay?token=5O190127TN364715T",
"rel": "payer-action",
"method": "GET"
},
{
"href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
"rel": "self",
"method": "GET"
}
]
}
Authorize payment for order
Header parameters
PayPal-Request-Id
string
The server stores keys for 45 days.
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
Authorization
string
required
To make REST API calls, include the bearer token in this header with the
Bearer
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
The media type. Required for operations with a request body. The value is
application/<format>
, whereformat
isjson
.
Path parameters
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.
application_context
Customizes the payer experience during the approval process for the payment with PayPal.
Note: Partners and Marketplaces might configure
brand_name
andshipping_preference
during partner account setup, which overrides the request values.
Sample Request
curl -v -X POST https://api-m.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.
payment_source
The payment source used to fund the 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 best captured within three days of authorization 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. This intent is not supported when you have more than one `purchase_unit` within your order.
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.PAYER_ACTION_REQUIRED
. The order requires an action from the payer (e.g. 3DS authentication). Redirect the payer to the "rel":"payer-action" HATEOAS link returned as part of the response prior to authorizing or capturing the order.
links
array (contains the link_description object)
An array of request-related HATEOAS links. To complete payer approval, use the
approve
link to redirect the payer. The API caller has 3 hours (default setting, this which can be changed by your account manager to 24/48/72 hours to accommodate your use case) from the time the order is created, to redirect your payer. Once redirected, the API caller has 3 hours for the payer to approve the order and either authorize or capture the order. If you are not using the PayPal JavaScript SDK to initiate PayPal Checkout (in context) ensure that you includeapplication_context.return_url
is specified or you will get "We're sorry, Things don't appear to be working at the moment" after the payer approves the payment.
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-m.paypal.com/v2/payments/authorizations/0AW2184448108334S",
"rel": "self",
"method": "GET"
},
{
"href": "https://api-m.paypal.com/v2/payments/authorizations/0AW2184448108334S/capture",
"rel": "capture",
"method": "POST"
},
{
"href": "https://api-m.paypal.com/v2/payments/authorizations/0AW2184448108334S/void",
"rel": "void",
"method": "POST"
},
{
"href": "https://api-m.paypal.com/v2/payments/authorizations/0AW2184448108334S/reauthorize",
"rel": "reauthorize",
"method": "POST"
}
]
}
]
}
}
],
"links": [
{
"href": "https://api-m.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.
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
Authorization
string
required
To make REST API calls, include the bearer token in this header with the
Bearer
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
The media type. Required for operations with a request body. The value is
application/<format>
, whereformat
isjson
.
Path parameters
id
string
required
The ID of the order for which to capture a payment.
Request body
payment_source
The payment source definition.
application_context
Customizes the payer experience during the approval process for the payment with PayPal.
Note: Partners and Marketplaces might configure
brand_name
andshipping_preference
during partner account setup, which overrides the request values.
Sample Request
curl -v -X POST https://api-m.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.
payment_source
The payment source used to fund the 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 best captured within three days of authorization 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. This intent is not supported when you have more than one `purchase_unit` within your order.
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.PAYER_ACTION_REQUIRED
. The order requires an action from the payer (e.g. 3DS authentication). Redirect the payer to the "rel":"payer-action" HATEOAS link returned as part of the response prior to authorizing or capturing the order.
links
array (contains the link_description object)
An array of request-related HATEOAS links. To complete payer approval, use the
approve
link to redirect the payer. The API caller has 3 hours (default setting, this which can be changed by your account manager to 24/48/72 hours to accommodate your use case) from the time the order is created, to redirect your payer. Once redirected, the API caller has 3 hours for the payer to approve the order and either authorize or capture the order. If you are not using the PayPal JavaScript SDK to initiate PayPal Checkout (in context) ensure that you includeapplication_context.return_url
is specified or you will get "We're sorry, Things don't appear to be working at the moment" after the payer approves the payment.
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-m.paypal.com/v2/payments/captures/3C679366HH908993F",
"rel": "self",
"method": "GET"
},
{
"href": "https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F/refund",
"rel": "refund",
"method": "POST"
}
]
}
]
}
}
],
"links": [
{
"href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
"rel": "self",
"method": "GET"
}
]
}
Common object definitions
account_id
account_id
string
The account identifier for a PayPal account.
account_id
account_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.
account_tag
account_tag
string
Account tag in User domain by other clients Eg: YOUTH_ACCOUNT, RESTRICTED, WAX_USER, MASSPAY_ENABLED etc.
account_tier
account_tier
enum
Paypal account type.
The possible values are:
BUSINESS
. PayPal Business account.PERSONAL
. PayPal personal account.PREMIER
. PayPal Premier account.
ach_debit
account_number
string
required
The US bank account number from which the payment will be debited.
routing_number
string
required
The 9-digit ABA routing transit number for the bank at which the account is held.
account_type
enum
Represents the type of the bank account. If not provided, default is CHECKING.
The possible values are:
CHECKING
. Bank account of type CHECKING.SAVINGS
. Bank account of type SAVINGS.
account_holder_name
string
required
Name of the person or business that owns the bank account.
ach_debit_response
last_digits
string
The last 4 digits of the bank account number.
routing_number
string
The 9-digit ABA routing transit number for the bank at which the account is held.
account_holder_name
string
Name of the person or business that owns the bank account.
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. Just
Drury
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_name
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 as
next to Walmart
, or a landmark in an Indian address.admin_area_4
string
The neighborhood, ward, or district. Smaller than
admin_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 than
admin_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 than
admin_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
.
addressee
string
The name on the address, for example, Mr J. Smith.
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 as
next to Walmart
, or a landmark in an Indian address.admin_area_4
string
The neighborhood, ward, or district. Smaller than
admin_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 than
admin_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 than
admin_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
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 than
admin_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 as
next to Walmart
, or a landmark in an Indian address.admin_area_4
string
The neighborhood, ward, or district. Smaller than
admin_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 than
admin_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 than
admin_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
address_portable_postal_code_validation
address_portable_postal_code_validation
amount_breakdown
item_total
The subtotal for all items. Required if the request includes
purchase_units[].items[].unit_amount
. Must equal the sum of(items[].unit_amount * items[].quantity)
for all items.item_total.value
can not be a negative number.shipping
The shipping fee for all items within a given
purchase_unit
.shipping.value
can not be a negative number.handling
The handling fee for all items within a given
purchase_unit
.handling.value
can not be a negative number.tax_total
The total tax for all items. Required if the request includes
purchase_units.items.tax
. Must equal the sum of(items[].tax * items[].quantity)
for all items.tax_total.value
can not be a negative number.insurance
The insurance fee for all items within a given
purchase_unit
.insurance.value
can not be a negative number.shipping_discount
The shipping discount for all items within a given
purchase_unit
.shipping_discount.value
can not be a negative number.discount
The discount for all items within a given
purchase_unit
.discount.value
can not be a negative number.
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.
authentication_response
liability_shift
enum
Liability shift indicator. The outcome of the issuer's authentication.
The possible values are:
YES
. Liability has shifted to the card issuer. Available only after order is authorized or captured.NO
. Liability is with the merchant.POSSIBLE
. Liability may shift to the card issuer. Available only before order is authorized or captured.UNKNOWN
. The authentication system is not available.
three_d_secure
Results of 3D Secure Authentication.
authorization
status
string
The status for the authorized payment.
status_details
The details of the authorized order pending status.
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.
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.
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.PARTIALLY_CREATED
. The payment which was authorized for an amount that is less than the originally requested amount.VOIDED
. The authorized payment was voided. No more captured payments can be made against this authorized payment.PENDING
. The created authorization is in pending state. For more information, seestatus.details
.
status_details
The details of the authorized order pending status.
authorization_status_details
reason
enum
The reason why the authorized status is
PENDING
.The possible values are:
PENDING_REVIEW
. Authorization is pending manual review.
authorization_with_additional_data
processor_response
The processor response for card transactions.
bic
bic
string
The business identification code (BIC). In payments systems, a BIC is used to identify a specific business, most commonly a bank.
business_name
business_name
string
Required. The business name of the party.
orthography
enum
The orthography type based on the ISO 15924 names for scripts. Scipts are chosen based on most widely used writing systems.
The possible values are:
Zyyy
. The orthography cannot be determined.Zzzz
. The orthography is unknown.Kana
. An angular form of Japanese writing for words of foreign origin.Cyrl
. The Slavic languages alphabet. Used in eastern Europe.Arab
. The Arabic language alphabet.Armn
. The Armenian alphabet.Beng
. The Bengali alphabet. Used in eastern India.Cans
. The Unified Canadian Aboriginal Syllabics alphabet.Deva
. The Devanagari (Nagari) alphabet.Ethi
. The Ethiopic alphabet.Geor
. The Georgian (Mkhedruli and Mtavruli) alphabet.Grek
. The Greek alphabet.Gujr
. The Gujurati language alphabet. Used in western India.Guru
. The Gurmukhi alphabet. Used in the northern Indian state of Punjab.Hani
. The Han (Hanzi, Kanji, Hanja) alphabet.Hebr
. The Hebrew alphabet.Java
. The Javanese alphabet.Jpan
. The Japanese (alias for Han + Hiragana + Katakana) alphabet.Khmr
. The Khmer alphabet.Knda
. The Kannada alphabet. Used in the southern Indian state of Karnataka.Kore
. Korean (alias for Hangul + Han).Laoo
. The Lao alphabet.Latn
. The Latin alphabet.Mlym
. The Malayalam alphabet. Used in the southern Indian state of Kerala.Mong
. The Mongolian alphabet.Mymr
. The Myanmar (Burmese) alphabet.Orya
. The Oriya (Odia) alphabet. Used in the eastern Indian state of Odisha.Sinh
. The Sinhala alphabet.Sund
. The Sundanese alphabet.Syrc
. The Syriac alphabet.Taml
. The Tamil alphabet. Used in the southern Indian state of Tamilnadu.Telu
. The Telugu language alphabet. Used in the southern Indian state of Andhra pradesh.Thaa
. The Thaana (Maldivian) alphabet.Thai
. The Thai alphabet. Used in Thailand.Tibt
. The Tibetan alphabet.Yiii
. The Yi alphabet.
business_name_validation
business_name_validation
business_type
business_type
enum
The business types classified.
The possible values are:
ANY_OTHER_BUSINESS_ENTITY
. The any other business entity.ASSOCIATION
. The association.CORPORATION
. The corporation.GENERAL_PARTNERSHIP
. The general partnership.GOVERNMENT
. The government.INDIVIDUAL
. The individual.LIMITED_LIABILITY_PARTNERSHIP
. The limited liability partnership.LIMITED_LIABILITY_PROPRIETORS
. The limited liability proprietors.LIMITED_LIABILITY_PRIVATE_CORPORATION
. The limited liability private corporation.LIMITED_PARTNERSHIP
. The limited partnership.LIMITED_PARTNERSHIP_PRIVATE_CORPORATION
. The limited partnership private corporation.NONPROFIT
. The nonprofit.ONLY_BUY_OR_SEND_MONEY
. The only buy and send money.OTHER_CORPORATE_BODY
. The other corporate body.PARTNERSHIP
. The partnership.PRIVATE_PARTNERSHIP
. The private partnership.PROPRIETORSHIP
. The proprietorship.PROPRIETORSHIP_CRAFTSMAN
. The proprietorship craftsman.PROPRIETORY_COMPANY
. The proprietory company.PRIVATE_CORPORATION
. The private corporation.PUBLIC_COMPANY
. The public company.PUBLIC_CORPORATION
. The public corporation.PUBLIC_PARTNERSHIP
. The public partnership.REGISTERED_COOPERATIVE
. A group of private owners who have registered their bsuiness.
capture
status
string
The status of the captured payment.
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.
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.
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 to
true
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 capture activity. This object is not applicable for transactions that are in pending state and hence it is not available.
disbursement_mode
The funds that are held on behalf of the merchant.
links
array (contains the link_description object)
An array of related HATEOAS links.
processor_response
An object that provides additional processor information for a direct credit card transaction.
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 is
PENDING
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_brand
card_brand
enum
The card network or brand. Applies to credit, debit, gift, and payment cards.
The possible values are:
VISA
. Visa card.MASTERCARD
. Mastecard 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.
card_response
last_digits
string
The last digits of the payment card.
brand
enum
The card brand or network. Typically used in the response.
The possible values are:
VISA
. Visa card.MASTERCARD
. Mastecard 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.
type
enum
The payment card type.
The possible values are:
CREDIT
. A credit card.DEBIT
. A debit card.PREPAID
. A Prepaid card.UNKNOWN
. Card type cannot be determined.
authentication_result
Results of Authentication such as 3D Secure.
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 best captured within three days of authorization 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. This intent is not supported when you have more than one `purchase_unit` within your order.
contingency
contingency
enum
An action to be taken on a payment method to validate it.
The possible values are:
3D_SECURE
. When specified, 3D Secure contingency will be triggered on 3DS enabled cards, if required.
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.
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.
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 standard
date_time
type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.
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 standard
date_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_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-8601
YYYY-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 they did not receive.UNAUTHORIZED_TRANSACTION
. The payer did not authorize the payment.
document_issuer
The country code where document was issued.
province_code
string
The state or province code that issued the identity document, as defined by ISO 3166-2:2013.
authority
string
The entity that issued the identity document. For example,
registration authority
.
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.
email_address
email_address
string
The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the
@
sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@
sign exists.
email_address
email_address
string
The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the
@
sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@
sign exists.
enrolled
enrolled
enum
Status of Authentication eligibility.
The possible values are:
Y
. Yes. The bank is participating in 3-D Secure protocol and will return the ACSUrl.N
. No. The bank is not participating in 3-D Secure protocol.U
. Unavailable. The DS or ACS is not available for authentication at the time of the request.B
. Bypass. The merchant authentication rule is triggered to bypass authentication.
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 is
body
,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 to 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.
iban_last_chars
iban_last_chars
string
The last characters of the IBAN used to pay.
identity_document
type
enum
The identity document type.
The possible values are:
SOCIAL_SECURITY_NUMBER
. Social security number.INDIVIDUAL_TAXPAYER_IDENTIFICATION_NUMBER
. Individual tax identification number.NATIONAL_IDENTIFICATION_NUMBER
. National identification number, such as CPF or AADHAR.TAX_IDENTIFICATION_NUMBER
. The tax identification number, such as PAN CARD.PASSPORT_NUMBER
. The passport number.SSN4
. Last 4 digits of the social security number.
issuer
The issuer of the document.
id_number
string
The document number, such as the passport number.
issued_date
The date when the document was issued.
expiration_date
The expiration date of the document.
identity_document_type
identity_document_type
enum
The identity document type.
The possible values are:
SOCIAL_SECURITY_NUMBER
. Social security number.INDIVIDUAL_TAXPAYER_IDENTIFICATION_NUMBER
. Individual tax identification number.NATIONAL_IDENTIFICATION_NUMBER
. National identification number, such as CPF or AADHAR.TAX_IDENTIFICATION_NUMBER
. The tax identification number, such as PAN CARD.PASSPORT_NUMBER
. The passport number.SSN4
. Last 4 digits of the social security number.
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.unit_amount.value
can not be a negative number.tax
The item tax for each unit. If
tax
is specified,purchase_units[].amount.breakdown.tax_total
is required. Must equaltax * quantity
for all items.tax.value
can not be a negative number.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. This value is not currently supported for API callers that leverage the [PayPal for Commerce Platform](https://www.paypal.com/us/webapps/mpp/commerce-platform) product.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.
liability_shift
liability_shift
enum
Liability shift indicator. The outcome of the issuer's authentication.
The possible values are:
YES
. Liability has shifted to the card issuer. Available only after order is authorized or captured.NO
. Liability is with the merchant.POSSIBLE
. Liability may shift to the card issuer. Available only before order is authorized or captured.UNKNOWN
. The authentication system is not available.
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.
merchant_partner_customer_id
merchant_partner_customer_id
string
The unique ID for a customer in merchant's or partner's system of records.
model-account
account_number
string
Unique account number.
account_id
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.
tier
enum
The classification of the PayPal account.
The possible values are:
BUSINESS
. PayPal Business account.PERSONAL
. PayPal personal account.PREMIER
. PayPal Premier account.
registration_type
string
The registration_type fields represents how the account was created. Currently supported values are FULL, GUEST, ANONYMOUS. For more information about the meaning of each registration type, refer to the UserGuide.
legal_country_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.account_tags
array (contains the account_tag object)
Array of tags stored for the account in User domain by other clients Eg: YOUTH_ACCOUNT, RESTRICTED, WAX_USER, MASSPAY_ENABLED etc.
status
string
Status of account like OPEN, or CLOSED. For paypal accounts, the status is defined by User domain.
pricing_category
string
Pricing category for the account as defined by PalPal pricing.
legal_entity
string
The account's legal PayPal entity Eg: INC, EUROPE, CHINA etc. For paypal accounts, it is defined by User domain.
time_created
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.
model-address_with_confirmation
id
string
Unique address identifier.
confirmation_status
string
Address confirmation status like NONE, PENDING, CONFIRMED, FAILED.
confirmation_authority
string
What 3rd party or process has determined the current confirmation_status.
model-auth_tolerance
model-authorization_directives
honor_time_offset
integer
Honor period offset. This is the offset period (in seconds) starting from time of authorization after which held funds (if any) will be released automatically.
expiry_time_offset
integer
Expiry period offset. This is the offset period (in seconds) starting from time of authorization after which authorization is voided automatically.
allow_multiple_captures
boolean
Indicates if multiple captures can be allowed on an Authorization.
tolerance
Auth-Capture Tolerance details.
model-business
id
string
Unique identifier for a party.
external_id
string
External identifier for a party, it could be venmo id, facebook email etc.
primary
boolean
Indicates if the party is primary Party.
primary_email
The primary email address of the party.
emails
array (contains the email_address object)
Email addresses.
phones
array (contains the model-phone_info object)
Details of party's phone numbers.
addresses
array (contains the model-address_with_confirmation object)
Details of party's addresses.
create_time
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.
update_time
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.
names
array (contains the business_name object)
Names of business.
type
Type of business. Eg: INDIVIDUAL, PROPRIETORSHIP, PARTNERSHIP etc.
category
Business category information. Refer: https://developer.paypal.com/docs/commerce-platform/reference/categories-subcategories/.
identifications
array (contains the model-business_identification object)
Identification details for the business.
description
string
Description of business.
owners
array (contains the model-person object)
Beneficial owners of the business.
url
string
Web site url (online presence) for the business.
customer_service_contacts
Contact information for customer service.
model-business_category
category
string
Industry standard category code of business.
sub_category
string
Industry standard sub category of business.
mcc_code
string
Industry standard merchant category code of business.
model-business_identification
type
string
The type of identification number. Eg: TAX_IDENTIFICATION_NUMBER, BUSINESS_REGISTRATION_NUMBER.
identifier
string
The number or value of the identifier.
issuer
The document-issuing authority information.
issued_time
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.
model-customer_service_contact
emails
array (contains the email_address object)
Customer service email addresses.
phones
array (contains the model-phone_info object)
Details of customer service phone numbers.
model-enums-currency_receiving_type
model-enums-currency_receiving_type
enum
Currency receiving type defines the options when receiving payment in a currency not held by the reciver.
The possible values are:
ACCEPT
. Accept payment after auto currency conversion.DENY
. Deny payment.HOLD
. Pend payment for seller's approval.ACCEPT_OPEN
. Accept payment after opening a new currency holding.
model-enums-disbursement_type
model-enums-disbursement_type
enum
Disbursement type.
The possible values are:
INSTANT
. Instant Disbursement Type.DELAYED
. Delayed Disbursement Type.
model-enums-facilitator_type
model-enums-facilitator_type
enum
Facilitator type.
The possible values are:
API_CALLER
. A party who sets up the context and eventually owns or controls the payment.PARTNER
. A checkout participant involved in the transaction who is setup as a partner.INTERNAL
. Internal applications or actors.
model-enums-liability_type
model-enums-liability_type
enum
Liability type defined by PayPal Risk.
The possible values are:
FULL
. Full liability for post payment events. The loss_account will be used for events including refunds, reversals, disputes etc.PARTIAL
. Partial liability for post payment events. The loss_account will be used for limited cases like UNAUTH.
model-enums-participant_type
model-enums-participant_type
enum
Participant type.
The possible values are:
SENDER
. Sender of the payment.RECEIVER
. Receiver of the payment.FACILITATOR
. Facilitator of the payment.
model-enums-pricing_type
model-enums-pricing_type
enum
Type of pricing applied to a payment.
The possible values are:
BLENDED
. Blended Pricing Type.IC_PLUS
. IC+ Pricing Type.
model-odfi_details
standard_entry_class_code
enum
The Standard Entry Class (SEC) code is a three-character code included in the company/batch header record to identify the type of ACH transactions contained in that batch.
The possible values are:
ARC
. Account Receivable Check. Converted checks received via the US mail or at a drop box location for the payment of goods or services.BOC
. Back Office Conversion. Converted checks received by merchant at the point of purchase or at manned bill payment locations, and processed during back office operations.CCD
. Corporate Credit or Debit. Transfer of funds where they are either distributed or consolidated between corporate entities.CTX
. Corporate Trade Exchange. Application that supports the transfer of funds within a trading partner relationship.IAT
. International ACH Transaction. Transaction involving a financial agency's office that is not located in the territorial jurisdiction of the United States.POP
. Point of Purchase Entry. Entry initiated by the consumer via a debit card for payment of goods or services.PPD
. Prearranged Payment and Deposit Entry. Entry initiated by an organization based on a standing or single entry authorization from a receiver to transfer funds to or from a consumer account of the receiver.RCK
. Represented Check Entry. Application used by originators to re-present a check that has been processed through the check collection system and returned because of insufficient or uncollected funds.TEL
. Telephone Authorized Entry. Debit transaction to a consumer's account pursuant to an oral authorization obtained from the consumer via the telephone.WEB
. Internet Authorized Entry. Entry used for the origination of debit entries to a consumer's account pursuant to an authorization that is obtained from the Receiver via the internet.
model-participant
account_number
string
Unique account number.
account_id
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.
tier
The classification of the PayPal account.
registration_type
string
The registration_type fields represents how the account was created. Currently supported values are FULL, GUEST, ANONYMOUS. For more information about the meaning of each registration type, refer to the UserGuide.
legal_country_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.account_tags
array (contains the account_tag object)
Array of tags stored for the account in User domain by other clients Eg: YOUTH_ACCOUNT, RESTRICTED, WAX_USER, MASSPAY_ENABLED etc.
status
string
Status of account like OPEN, or CLOSED. For paypal accounts, the status is defined by User domain.
pricing_category
string
Pricing category for the account as defined by PalPal pricing.
legal_entity
string
The account's legal PayPal entity Eg: INC, EUROPE, CHINA etc. For paypal accounts, it is defined by User domain.
time_created
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.
Person information.
business
Business information.
model-party
id
string
Unique identifier for a party.
external_id
string
External identifier for a party, it could be venmo id, facebook email etc.
primary
boolean
Indicates if the party is primary Party.
primary_email
The primary email address of the party.
emails
array (contains the email_address object)
Email addresses.
phones
array (contains the model-phone_info object)
Details of party's phone numbers.
addresses
array (contains the model-address_with_confirmation object)
Details of party's addresses.
create_time
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.
update_time
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.
model-payment_context_attribute
name
string
Context attribute name.
value
string
Context attribute value.
model-payment_details_request
payment_source
The payment source used for the payment of an order
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.
model-payment_directives
disbursement_type
enum
Disbursement type.
The possible values are:
INSTANT
. Instant Disbursement Type.DELAYED
. Delayed Disbursement Type.
linked_group_id
string
Identifier that links the transactions to be treated as one atomic unit for payment processing. All-or-none policy is enforced by this identifier.
settlement_account_number
string
Settlement account number where the funds finally get settled to.
loss_account_number
string
Loss account number used for recovery of loss.
liability_type
enum
Liability type defined by PayPal Risk.
The possible values are:
FULL
. Full liability for post payment events. The loss_account will be used for events including refunds, reversals, disputes etc.PARTIAL
. Partial liability for post payment events. The loss_account will be used for limited cases like UNAUTH.
special_deny
boolean
Special deny setting to force decline a (compliance) pending transaction.
allow_duplicate_invoice_id
boolean
A directive to allow or deny transactions with duplicate invoice id (for the receiver account).
policy_directives
array (contains the model-policy_directive object)
Policy directives indicating how to process the payment.
payment_method_directives
array (contains the model-payment_method_directive object)
Directives for certain payment methods based on eligibility.
pricing_directives
array (contains the model-pricing_directive object)
Pricing directives for the transaction.
authorization_directives
Auth directives for the transaction.
currency_receiving_directive
enum
Currency receiving type defines the options when receiving payment in a currency not held by the reciver.
The possible values are:
ACCEPT
. Accept payment after auto currency conversion.DENY
. Deny payment.HOLD
. Pend payment for seller's approval.ACCEPT_OPEN
. Accept payment after opening a new currency holding.
immediate_payment_required
boolean
Flag to indicate if immediate payment is required. A directive to fail the transaction if the payment goes to a pending state.
model-payment_method_directive
payment_processing_type
string
Indicates the type of payment processing. Eg: CUSTOM_CARD_PROCESSING, CUSTOM_BANK_PROCESSING.
processing_decision
string
Defines the payment processing decision as ALLOW, DENY, UNKNOWN.
reason
array (contains the reason_code object)
Reasons for the decision. Usually set for a DENY decision.
model-person
id
string
Unique identifier for a party.
external_id
string
External identifier for a party, it could be venmo id, facebook email etc.
primary
boolean
Indicates if the party is primary Party.
primary_email
The primary email address of the party.
emails
array (contains the email_address object)
Email addresses.
phones
array (contains the model-phone_info object)
Details of party's phone numbers.
addresses
array (contains the model-address_with_confirmation object)
Details of party's addresses.
create_time
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.
update_time
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.
names
array (contains the name object)
Names of person.
citizenship
The two character iso country code for where the legal citizenship of party.
birth_date
Person's date of birth.
identifications
array (contains the identity_document object)
Identity documents for the entity like passport number.
model-phone_info
phone_number
The phone number in its canonical international E.164 numbering plan format.
phone_type
enum
The phone type.
The possible values are:
FAX
. A fax machine.HOME
. A home phone.MOBILE
. A mobile phone.OTHER
. Other.PAGER
. A pager.WORK
. A work phone.
model-policy_directive
payment_decision
string
Indicates the payment state decision. Can be ALLOW, DENY or ALLOW_WITH_HOLD.
reason
array (contains the reason_code object)
List of reasons for the payment decision.
model-pricing_directive
participant_type
enum
Participant type.
The possible values are:
SENDER
. Sender of the payment.RECEIVER
. Receiver of the payment.FACILITATOR
. Facilitator of the payment.
account_number
string
Account number of the preference owner.
type
enum
Pricing type.
The possible values are:
BLENDED
. Blended Pricing Type.IC_PLUS
. IC+ Pricing Type.
model-shipping_details
shipping_address
Shipping Address.
options
array (contains the shipping_option object)
An array of shipping options that the payee or merchant offers to the payer to ship or pick up their items.
model-soft_descriptor_details
soft_descriptor
string
Soft Descriptor.
contact_type
string
Contact type allows the merchant to specify the type of the additional information passing in the soft descriptor Eg : CITY/URL/PHONE.
contact_value
string
Contact value allows the merchant to provide the business location, business phone number or URL to the instrument holder.
model-update_authorization_request
id
string
required
The unique transaction ID for the authorized payment.
status
enum
required
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.PENDING
. The created authorization is in pending state. For more information, seestatus.details
status_details
The details of the authorized order pending status.
model-update_capture_request
id
string
required
The transaction ID for the captured payment.
status
enum
required
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.
model-update_payment_collection_request
authorizations
array (contains the model-update_authorization_request object)
An array of authorized payments for a purchase unit. A purchase unit can have zero or more authorized payments.
captures
array (contains the model-update_capture_request object)
An array of captured payments for a purchase unit. A purchase unit can have zero or more captured payments.
model-update_purchase_unit_request
reference_id
string
required
The API caller-provided external ID for the purchase unit.
The comprehensive summary of payments for the purchase unit.
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
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
name
string
The full name representation like Mr J Smith.
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.
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
name_validation
name_validation
network_transaction_reference
id
string
required
Transaction reference id returned by the scheme. For Visa and Amex, this is the "Tran id" field in response. For MasterCard, this is the "BankNet reference id" field in response. For Discover, this is the "NRID" field in response.
date
string
The date that the transaction was authorized by the scheme. For MasterCard, this is the "BankNet reference date" field in response.
network
enum
required
Name of the card network through which the transaction was routed.
The possible values are:
VISA
. Visa card.MASTERCARD
. Mastecard 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.
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.
payment_source
The payment source used to fund the payment.
intent
The intent to either capture payment immediately or authorize a payment for an order after order creation.
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
The order status.
links
array (contains the link_description object)
An array of request-related HATEOAS links. To complete payer approval, use the
approve
link to redirect the payer. The API caller has 3 hours (default setting, this which can be changed by your account manager to 24/48/72 hours to accommodate your use case) from the time the order is created, to redirect your payer. Once redirected, the API caller has 3 hours for the payer to approve the order and either authorize or capture the order. If you are not using the PayPal JavaScript SDK to initiate PayPal Checkout (in context) ensure that you includeapplication_context.return_url
is specified or you will get "We're sorry, Things don't appear to be working at the moment" after the payer approves the payment.
order_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.NO_PREFERENCE
. When the customer clicks PayPal Checkout, the customer is redirected to either a page to log in to PayPal and approve the payment or to a page to enter credit or debit card and other relevant billing information required to complete the purchase, depending on their previous interaction with PayPal.
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.
The possible values are:
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.
stored_payment_source
Provides additional details to process a payment using a
payment_source
that has been stored or is intended to be stored (also referred to as stored_credential or card-on-file).
Parameter compatibility:payment_type=ONE_TIME
is compatible only withpayment_initiator=CUSTOMER
.usage=FIRST
is compatible only withpayment_initiator=CUSTOMER
.previous_transaction_reference
orprevious_network_transaction_reference
is compatible only withpayment_initiator=MERCHANT
.- Only one of the parameters -
previous_transaction_reference
andprevious_network_transaction_reference
- can be present in the request.
order_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.
application_context
Customizes the payer experience during the approval process for the payment with PayPal.
Note: Partners and Marketplaces might configure
brand_name
andshipping_preference
during partner account setup, which overrides the request values.
order_authorize_request.customized_x_unsupported_2031_order_application_context
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.
stored_payment_source
Provides additional details to process a payment using a
payment_source
that has been stored or is intended to be stored (also referred to as stored_credential or card-on-file).
Parameter compatibility:payment_type=ONE_TIME
is compatible only withpayment_initiator=CUSTOMER
.usage=FIRST
is compatible only withpayment_initiator=CUSTOMER
.previous_transaction_reference
orprevious_network_transaction_reference
is compatible only withpayment_initiator=MERCHANT
.- Only one of the parameters -
previous_transaction_reference
andprevious_network_transaction_reference
- can be present in the request.
order_capture_request
payment_source
The payment source definition.
application_context
Customizes the payer experience during the approval process for the payment with PayPal.
Note: Partners and Marketplaces might configure
brand_name
andshipping_preference
during partner account setup, which overrides the request values.
order_capture_request.customized_x_unsupported_2687_order_application_context
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.
stored_payment_source
Provides additional details to process a payment using a
payment_source
that has been stored or is intended to be stored (also referred to as stored_credential or card-on-file).
Parameter compatibility:payment_type=ONE_TIME
is compatible only withpayment_initiator=CUSTOMER
.usage=FIRST
is compatible only withpayment_initiator=CUSTOMER
.previous_transaction_reference
orprevious_network_transaction_reference
is compatible only withpayment_initiator=MERCHANT
.- Only one of the parameters -
previous_transaction_reference
andprevious_network_transaction_reference
- can be present in the request.
order_confirm_application_context
brand_name
string
Label to present to your payer as part of the PayPal hosted web experience.
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
.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.
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 best captured within three days of authorization 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. This intent is not supported when you have more than one `purchase_unit` within your order.
payer
The customer who approves and pays for the order. The customer is also known as the payer.
An array of purchase units. 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.PAYER_ACTION_REQUIRED
. The order requires an action from the payer (e.g. 3DS authentication). Redirect the payer to the "rel":"payer-action" HATEOAS link returned as part of the response prior to authorizing or capturing the order.
orthography
orthography
enum
The orthography type based on the ISO 15924 names for scripts. Scipts are chosen based on most widely used writing systems.
The possible values are:
Zyyy
. The orthography cannot be determined.Zzzz
. The orthography is unknown.Kana
. An angular form of Japanese writing for words of foreign origin.Cyrl
. The Slavic languages alphabet. Used in eastern Europe.Arab
. The Arabic language alphabet.Armn
. The Armenian alphabet.Beng
. The Bengali alphabet. Used in eastern India.Cans
. The Unified Canadian Aboriginal Syllabics alphabet.Deva
. The Devanagari (Nagari) alphabet.Ethi
. The Ethiopic alphabet.Geor
. The Georgian (Mkhedruli and Mtavruli) alphabet.Grek
. The Greek alphabet.Gujr
. The Gujurati language alphabet. Used in western India.Guru
. The Gurmukhi alphabet. Used in the northern Indian state of Punjab.Hani
. The Han (Hanzi, Kanji, Hanja) alphabet.Hebr
. The Hebrew alphabet.Java
. The Javanese alphabet.Jpan
. The Japanese (alias for Han + Hiragana + Katakana) alphabet.Khmr
. The Khmer alphabet.Knda
. The Kannada alphabet. Used in the southern Indian state of Karnataka.Kore
. Korean (alias for Hangul + Han).Laoo
. The Lao alphabet.Latn
. The Latin alphabet.Mlym
. The Malayalam alphabet. Used in the southern Indian state of Kerala.Mong
. The Mongolian alphabet.Mymr
. The Myanmar (Burmese) alphabet.Orya
. The Oriya (Odia) alphabet. Used in the eastern Indian state of Odisha.Sinh
. The Sinhala alphabet.Sund
. The Sundanese alphabet.Syrc
. The Syriac alphabet.Taml
. The Tamil alphabet. Used in the southern Indian state of Tamilnadu.Telu
. The Telugu language alphabet. Used in the southern Indian state of Andhra pradesh.Thaa
. The Thaana (Maldivian) alphabet.Thai
. The Thai alphabet. Used in Thailand.Tibt
. The Tibetan alphabet.Yiii
. The Yi alphabet.
pares_status
pares_status
enum
Transactions status result identifier. The outcome of the issuer's authentication.
The possible values are:
Y
. Successful authentication.N
. Failed authentication / account not verified / transaction denied.U
. Unable to complete authentication.A
. Successful attempts transaction.C
. Challenge required for authentication.R
. Authentication rejected (merchant must not submit for authorization).D
. Challenge required; decoupled authentication confirmed.I
. Informational only; 3DS requestor challenge preference acknowledged.
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. The
remove
operation does not require a value.from
string
The JSON Pointer to the target document location from which to move the value. Required for the
move
operation.
patch_request
patch_request
array (contains the patch object)
An array of JSON patch objects to apply partial updates to resources.
payee_payment_method_preference
payee_payment_method_preference
enum
The merchant-preferred payment methods.
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.
payer
email_address
The email address of the payer.
payer_id
The PayPal-assigned ID for the payer.
name
The name of the payer. Supports only the
given_name
andsurname
properties.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. The
phone.phone_number
supports onlynational_number
.birth_date
The birth date of the payer in
YYYY-MM-DD
format.tax_info
The tax information of the payer. Required only for Brazilian payer's. Both
tax_id
andtax_id_type
are required.address
The address of the payer. Supports only the
address_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.
payment_collection
authorizations
array (contains the authorization_with_additional_data 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_initiator
payment_initiator
enum
The person or party who initiated or triggered the payment.
The possible values are:
CUSTOMER
. Payment is initiated with the active engagement of the customer. e.g. a customer checking out on a merchant website.MERCHANT
. Payment is initiated by merchant on behalf of the customer without the active engagement of customer. e.g. a merchant charging the monthly payment of a subscription to the customer.
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.
payee_preferred
enum
The merchant-preferred payment methods.
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.
standard_entry_class_code
enum
NACHA (the regulatory body governing the ACH network) requires that API callers (merchants, partners) obtain the consumer’s explicit authorization before initiating a transaction. To stay compliant, you’ll need to make sure that you retain a compliant authorization for each transaction that you originate to the ACH Network using this API. ACH transactions are categorized (using SEC codes) by how you capture authorization from the Receiver (the person whose bank account is being debited or credited). PayPal supports the following SEC codes.
The possible values are:
TEL
. The API caller (merchant/partner) accepts authorization and payment information from a consumer over the telephone.WEB
. The API caller (merchant/partner) accepts Debit transactions from a consumer on their website.CCD
. Cash concentration and disbursement for corporate debit transaction. Used to disburse or consolidate funds. Entries are usually Optional high-dollar, low-volume, and time-critical. (e.g. intra-company transfers or invoice payments to suppliers).PPD
. Prearranged payment and deposit entries. Used for debit payments authorized by a consumer account holder, and usually initiated by a company. These are usually recurring debits (such as insurance premiums).
payment_source
token
The tokenized payment source to fund a payment.
payment_source_response
card
The payment card to use to fund a payment. Card can be a credit or debit card.
percentage
percentage
string
The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as
19.99
.
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
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.
The possible values are:
FAX
. A fax machine.HOME
. A home phone.MOBILE
. A mobile phone.OTHER
. Other.PAGER
. A pager.WORK
. A work phone.
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.
phone_with_type.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).
processor_response
avs_code
enum
The address verification code for Visa, Discover, Mastercard, or American Express transactions.
The possible values are:
A
. For Visa, Mastercard, or Discover transactions, the address matches but the zip code does not match. For American Express transactions, the card holder address is correct.B
. For Visa, Mastercard, or Discover transactions, the address matches. International A.C
. For Visa, Mastercard, or Discover transactions, no values match. International N.D
. For Visa, Mastercard, or Discover transactions, the address and postal code match. International X.E
. For Visa, Mastercard, or Discover transactions, not allowed for Internet or phone transactions. For American Express card holder, the name is incorrect but the address and postal code match.F
. For Visa, Mastercard, or Discover transactions, the address and postal code match. UK-specific X. For American Express card holder, the name is incorrect but the address matches.G
. For Visa, Mastercard, or Discover transactions, global is unavailable. Nothing matches.I
. For Visa, Mastercard, or Discover transactions, international is unavailable. Not applicable.M
. For Visa, Mastercard, or Discover transactions, the address and postal code match. For American Express card holder, the name, address, and postal code match.N
. For Visa, Mastercard, or Discover transactions, nothing matches. For American Express card holder, the address and postal code are both incorrect.P
. For Visa, Mastercard, or Discover transactions, postal international Z. Postal code only.R
. For Visa, Mastercard, or Discover transactions, re-try the request. For American Express, the system is unavailable.S
. For Visa, Mastercard, Discover, or American Express, the service is not supported.U
. For Visa, Mastercard, or Discover transactions, the service is unavailable. For American Express, information is not available. For Maestro, the address is not checked or the acquirer had no response. The service is not available.W
. For Visa, Mastercard, or Discover transactions, whole ZIP code. For American Express, the card holder name, address, and postal code are all incorrect.X
. For Visa, Mastercard, or Discover transactions, exact match of the address and the nine-digit ZIP code. For American Express, the card holder name, address, and postal code are all incorrect.Y
. For Visa, Mastercard, or Discover transactions, the address and five-digit ZIP code match. For American Express, the card holder address and postal code are both correct.Z
. For Visa, Mastercard, or Discover transactions, the five-digit ZIP code matches but no address. For American Express, only the card holder postal code is correct.Null
. For Maestro, no AVS response was obtained.0
. For Maestro, all address information matches.1
. For Maestro, none of the address information matches.2
. For Maestro, part of the address information matches.3
. For Maestro, the merchant did not provide AVS information. It was not processed.4
. For Maestro, the address was not checked or the acquirer had no response. The service is not available.
cvv_code
enum
The card verification value code for for Visa, Discover, Mastercard, or American Express.
The possible values are:
E
. For Visa, Mastercard, Discover, or American Express, error - unrecognized or unknown response.I
. For Visa, Mastercard, Discover, or American Express, invalid or null.M
. For Visa, Mastercard, Discover, or American Express, the CVV2/CSC matches.N
. For Visa, Mastercard, Discover, or American Express, the CVV2/CSC does not match.P
. For Visa, Mastercard, Discover, or American Express, it was not processed.S
. For Visa, Mastercard, Discover, or American Express, the service is not supported.U
. For Visa, Mastercard, Discover, or American Express, unknown - the issuer is not certified.X
. For Visa, Mastercard, Discover, or American Express, no response. For Maestro, the service is not available.All others
. For Visa, Mastercard, Discover, or American Express, error.0
. For Maestro, the CVV2 matched.1
. For Maestro, the CVV2 did not match.2
. For Maestro, the merchant has not implemented CVV2 code handling.3
. For Maestro, the merchant has indicated that CVV2 is not present on card.4
. For Maestro, the service is not available.
response_code
enum
Processor response code for the non-PayPal payment processor errors.
The possible values are:
0000
. APPROVED.0100
. REFERRAL.0800
. BAD_RESPONSE_REVERSAL_REQUIRED.1000
. PARTIAL_AUTHORIZATION.1300
. INVALID_DATA_FORMAT.1310
. INVALID_AMOUNT.1312
. INVALID_TRANSACTION_CARD_ISSUER_ACQUIRER.1317
. INVALID_CAPTURE_DATE.1320
. INVALID_CURRENCY_CODE.1330
. INVALID_ACCOUNT.1335
. INVALID_ACCOUNT_RECURRING.1340
. INVALID_TERMINAL.1350
. INVALID_MERCHANT.1360
. BAD_PROCESSING_CODE.1370
. INVALID_MCC.1380
. INVALID_EXPIRATION.1382
. INVALID_CARD_VERIFICATION_VALUE.1384
. INVALID_LIFE_CYCLE_OF_TRANSACTION.1390
. INVALID_ORDER.1393
. TRANSACTION_CANNOT_BE_COMPLETED.0500
. DO_NOT_HONOR.5100
. GENERIC_DECLINE.5110
. CVV2_FAILURE.5120
. INSUFFICIENT_FUNDS.5130
. INVALID_PIN.5140
. CARD_CLOSED.5150
. PICKUP_CARD_SPECIAL_CONDITIONS. Try using another card. Do not retry the same card.5160
. UNAUTHORIZED_USER.5170
. AVS_FAILURE.5180
. INVALID_OR_RESTRICTED_CARD. Try using another card. Do not retry the same card.5190
. SOFT_AVS.5200
. DUPLICATE_TRANSACTION.5210
. INVALID_TRANSACTION.5400
. EXPIRED_CARD.5500
. INCORRECT_PIN_REENTER.5800
. REVERSAL_REJECTED.5900
. INVALID_ISSUE.5910
. ISSUER_NOT_AVAILABLE_NOT_RETRIABLE.5920
. ISSUER_NOT_AVAILABLE_RETRIABLE.6300
. ACCOUNT_NOT_ON_FILE.7600
. APPROVED_NON_CAPTURE.7700
. ERROR_3DS.7710
. AUTHENTICATION_FAILED.7800
. BIN_ERROR.7900
. PIN_ERROR.8000
. PROCESSOR_SYSTEM_ERROR.8010
. HOST_KEY_ERROR.8020
. CONFIGURATION_ERROR.8030
. UNSUPPORTED_OPERATION.8100
. FATAL_COMMUNICATION_ERROR.8110
. RETRIABLE_COMMUNICATION_ERROR.8220
. SYSTEM_UNAVAILABLE.9100
. DECLINED_PLEASE_RETRY. Retry.9500
. SUSPECTED_FRAUD. Try using another card. Do not retry the same card.9510
. SECURITY_VIOLATION.9520
. LOST_OR_STOLEN. Try using another card. Do not retry the same card.9530
. HOLD_CALL_CENTER. The merchant must call the number on the back of the card. POS scenario.9540
. REFUSED_CARD.9600
. UNRECOGNIZED_RESPONSE_CODE.5930
. CARD_NOT_ACTIVATED.PPMD
. PPMD.PPCE
. CE_REGISTRATION_INCOMPLETE.PPNT
. NETWORK_ERROR.PPCT
. CARD_TYPE_UNSUPPORTED.PPTT
. TRANSACTION_TYPE_UNSUPPORTED.PPCU
. CURRENCY_USED_INVALID.PPQC
. QUASI_CASH_UNSUPPORTED.PPVE
. VALIDATION_ERROR.PPVT
. VIRTUAL_TERMINAL_UNSUPPORTED.PPDC
. DCC_UNSUPPORTED.PPER
. INTERNAL_SYSTEM_ERROR.PPIM
. ID_MISMATCH.PPH1
. H1_ERROR.PPSD
. STATUS_DESCRIPTION.PPAG
. ADULT_GAMING_UNSUPPORTED.PPLS
. LARGE_STATUS_CODE.PPCO
. COUNTRY.PPAD
. BILLING_ADDRESS.PPAU
. MCC_CODE.PPUC
. CURRENCY_CODE_UNSUPPORTED.PPUR
. UNSUPPORTED_REVERSAL.PPVC
. VALIDATE_CURRENCY.PPS0
. BANKAUTH_ROW_MISMATCH.PPS1
. BANKAUTH_ROW_SETTLED.PPS2
. BANKAUTH_ROW_VOIDED.PPS3
. BANKAUTH_EXPIRED.PPS4
. CURRENCY_MISMATCH.PPS5
. CREDITCARD_MISMATCH.PPS6
. AMOUNT_MISMATCH.PPRF
. INVALID_PARENT_TRANSACTION_STATUS.PPEX
. EXPIRY_DATE.PPAX
. AMOUNT_EXCEEDED.PPDV
. AUTH_MESSAGE.PPDI
. DINERS_REJECT.PPAR
. AUTH_RESULT.PPBG
. BAD_GAMING.PPGR
. GAMING_REFUND_ERROR.PPCR
. CREDIT_ERROR.PPAI
. AMOUNT_INCOMPATIBLE.PPIF
. IDEMPOTENCY_FAILURE.PPMC
. BLOCKED_Mastercard.PPAE
. AMEX_DISABLED.PPFV
. FIELD_VALIDATION_FAILED.PPII
. INVALID_INPUT_FAILURE.PPPM
. INVALID_PAYMENT_METHOD.PPUA
. USER_NOT_AUTHORIZED.PPFI
. INVALID_FUNDING_INSTRUMENT.PPEF
. EXPIRED_FUNDING_INSTRUMENT.PPFR
. RESTRICTED_FUNDING_INSTRUMENT.PPEL
. EXCEEDS_FREQUENCY_LIMIT.PCVV
. CVV_FAILURE.PPTV
. INVALID_VERIFICATION_TOKEN.PPTE
. VERIFICATION_TOKEN_EXPIRED.PPPI
. INVALID_PRODUCT.PPIT
. INVALID_TRACE_ID.PPTF
. INVALID_TRACE_REFERENCE.PPFE
. FUNDING_SOURCE_ALREADY_EXISTS.PPTR
. VERIFICATION_TOKEN_REVOKED.PPTI
. INVALID_TRANSACTION_ID.PPD3
. SECURE_ERROR_3DS.PPPH
. NO_PHONE_FOR_DCC_TRANSACTION.PPAV
. ARC_AVS.PPC2
. ARC_CVV.PPLR
. LATE_REVERSAL.PPNC
. NOT_SUPPORTED_NRC.PPRR
. MERCHANT_NOT_REGISTERED.PPSC
. ARC_SCORE.PPSE
. AMEX_DENIED.PPUE
. UNSUPPORT_ENTITY.PPUI
. UNSUPPORT_INSTALLMENT.PPUP
. UNSUPPORT_POS_FLAG.PPRE
. UNSUPPORT_REFUND_ON_PENDING_BC.
payment_advice_code
enum
The declined payment transactions might have payment advice codes. The card networks, like Visa and Mastercard, return payment advice codes.
The possible values are:
01
. For Mastercard, expired card account upgrade or portfolio sale conversion. Obtain new account information before next billing cycle.02
. For Mastercard, over credit limit or insufficient funds. Retry the transaction 72 hours later. For Visa, the card holder wants to stop only one specific payment in the recurring payment relationship. The merchant must NOT resubmit the same transaction. The merchant can continue the billing process in the subsequent billing period.03
. For Mastercard, account closed as fraudulent. Obtain another type of payment from customer due to account being closed or fraud. Possible reason: Account closed as fraudulent. For Visa, the card holder wants to stop all recurring payment transactions for a specific merchant. Stop recurring payment requests.21
. For Mastercard, the card holder has been unsuccessful at canceling recurring payment through merchant. Stop recurring payment requests. For Visa, all recurring payments were canceled for the card number requested. Stop recurring payment requests.
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 through
PATCH
. If you omit this value and the order contains only one purchase unit, PayPal sets this value todefault
.Note: If there are multiple purchase units,
reference_id
is required for each purchase unit.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
minus 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 Commerce Platform customers. Enables features for the PayPal Commerce Platform, 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 calling
v2/checkout/orders/id/save
.soft_descriptor
string
The payment descriptor on account transactions on the customer's credit card statement, that PayPal sends to processors. The maximum length of the soft descriptor information that you can pass in the API field is 22 characters, in the following format:
22 - len(PAYPAL * (8)) - len(Descriptor in Payment Receiving Preferences of Merchant account + 1)
The PAYPAL prefix uses 8 characters.
The soft descriptor supports the following ASCII characters:- Alphanumeric characters
- Dashes
- Asterisks
- Periods (.)
- Spaces
- The merchant descriptor in the Payment Receiving Preferences must be the marketplace name.
- You can't use the remaining space to show the customer service number.
- The remaining spaces can be a combination of seller name and country.
For unbranded payments (Direct Card) marketplace integrations, use a combination of the seller name and phone number.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 API caller-provided external ID for the purchase unit. Required for multiple purchase units when you must update the order through
PATCH
. If you omit this value and the order contains only one purchase unit, PayPal sets this value 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
minus 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 Commerce Platform customers. Enables features for the PayPal Commerce Platform, 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 soft descriptor is the dynamic text used to construct the statement descriptor that appears on a payer's card statement.
If an Order is paid using the "PayPal Wallet", the statement descriptor will appear in following format on the payer's card statement:PAYPAL_prefix+(space)+merchant_descriptor+(space)+ soft_descriptor
Note: The merchant descriptor is the descriptor of the merchant’s payment receiving preferences which can be seen by logging into the merchant account https://www.sandbox.paypal.com/businessprofile/settings/info/edit
ThePAYPAL
prefix uses 8 characters. Only the first 22 characters will be displayed in the statement.
For example, if:- The PayPal prefix toggle is
PAYPAL
. - The merchant descriptor in the profile is
Janes Gift
. - The soft descriptor is
800-123-1234
.
PAYPAL
Janes Gift 80
.- The PayPal prefix toggle is
items
array (contains the item object)
An array of items that the customer purchases from the merchant.
shipping
The name and address of the person to whom to ship the items.
reason
reason
enum
The reason for the risk assessment score.
The possible values are:
UNUSUAL_ENTITY
. The account and transaction is associated with possibly unusual entities.UNUSUAL_ENTITY_DEVICE_RISK
. The account and transaction is associated with stronger correlation to bad devices.HIGH_VELOCITY
. The account or device is associated with a high transaction frequency.HIGH_RISK_CONNECTION
. This transaction is initiated from risky network, such as VPN or proxy.NEGATIVE_HISTORY
. This account and device are associated with a high rate of possibly fraudulent transactions.HIGH_RISK_LINKING
. This account and transaction indicate stronger correlation to a possibly fraudulent network.HIGH_RISK_GENERIC
. The transaction has stronger indicators of fraudulent activity due to multiple reasons.LOW_UNAUTHORIZED_RISK
. This transaction is unlikely to be fraudulent.HIGH_MERCHANDISE_RISK
. This merchant has a history of a stronger correlation to fraud.UNUSUAL_MERCHANT_IDENTITY
. PayPal cannot confirm this merchant’s identity.RISKY_BUSINESS_PROFILE
. The industry or vertical for this merchant is risky.UNUSUAL_ACCOUNT_ENTITIES
. This merchant account is associated with risky entities, such as a possibly stolen or risky credit card, or a device linked to possible fraud.SUBSTANDARD_SELLER
. This merchant has unusually high rates of reversals.UNUSUAL_SELLING_BEHAVIOR
. A change occurred in business models from historical selling for this merchant.INCREASED_RISK_EXPOSURE
. This merchant account is at increased risk due to a change in selling velocity or other changes.INSUFFICIENT_INFORMATION
. The merchant has a limited transaction history.POTENTIAL_COLLUSION
. The merchant shows stronger potential for collusion with the consumer.LOW_MERCHANDISE_RISK
. The merchant is unlikely to be fraudulent.LINKED_PAYPAL_SELLER
. This merchant has an account with PayPal.
reason_code
reason_code
string
A reason for the processing decision. Eg: CUSTOM_BANK_PROCESSING_NOT_ENABLED_FOR_RECEIVER, PRODUCT_UCC_NOT_ENABLED_FOR_RECEIVER Etc.
refund
status
string
The status of the refund.
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 refund.
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 the
PENDING
orFAILED
status.The possible values are:
ECHECK
. The customer's account is funded through an eCheck, which has not yet cleared.
risk_assessment
score
integer
The fine-grained numeric evaluation. Value is from
0
to999
.reasons
array (contains the reason object)
An array of risk assessment reasons.
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 in the currency of the transaction. This fee might not match the PayPal fee that the payee paid when the payment was captured.
paypal_fee_in_receivable_currency
The PayPal fee that was refunded to the payer in the receivable currency. Returned only in cases when the receivable currency is different from transaction currency. Example 'CNY'.
net_amount
The net amount that the payee's account is debited in the transaction currency. The net amount is calculated as
gross_amount
minuspaypal_fee
minusplatform_fees
.net_amount_in_receivable_currency
The net amount that the payee's account is debited in the receivable currency. Returned only in cases when the receivable currency is different from transaction currency. Example 'CNY'.
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 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, the
gross_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 they did not receive an item or the account holder claims that they did not authorize the payment.PARTIALLY_ELIGIBLE
. Your PayPal balance remains intact if the customer claims that they 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
The amount for this captured payment in the currency of the transaction.
paypal_fee
The applicable fee for this captured payment in the currency of the transaction.
paypal_fee_in_receivable_currency
The applicable fee for this captured payment in the receivable currency. Returned only in cases the fee is charged in the receivable currency. Example 'CNY'.
net_amount
The net amount that the payee receives for this captured payment in their PayPal account. The net amount is computed as
gross_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 as
net_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.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 than
admin_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.
shipping_detail.name
full_name
string
When the party is a person, the party's full name.
shipping_option
id
string
required
A unique ID that identifies a payer-selected shipping option.
label
string
required
A description that the payer sees, which helps them choose an appropriate shipping option. For example,
Free Shipping
,USPS Priority Shipping
,Expédition prioritaire USPS
, orUSPS yōuxiān fā huò
. Localize this description to the payer's locale.type
enum
The method by which the payer wants to get their items.
The possible values are:
SHIPPING
. The payer intends to receive the items at a specified address.PICKUP
. The payer intends to pick up the items at a specified address. For example, a store address.
amount
The shipping cost for the selected option.
selected
boolean
required
If the API request sets
selected = true
, it represents the shipping option that the payee or merchant expects to be pre-selected for the payer when they first view theshipping.options
in the PayPal Checkout experience. As part of the response if ashipping.option
containsselected=true
, it represents the shipping option that the payer selected during the course of checkout with PayPal. Only oneshipping.option
can be set toselected=true
.
shipping_type
shipping_type
enum
The method by which the payer wants to get their items.
The possible values are:
SHIPPING
. The payer intends to receive the items at a specified address.PICKUP
. The payer intends to pick up the items at a specified address. For example, a store address.
stored_payment_source
payment_initiator
enum
required
The person or party who initiated or triggered the payment.
The possible values are:
CUSTOMER
. Payment is initiated with the active engagement of the customer. e.g. a customer checking out on a merchant website.MERCHANT
. Payment is initiated by merchant on behalf of the customer without the active engagement of customer. e.g. a merchant charging the monthly payment of a subscription to the customer.
payment_type
enum
required
Indicates the type of the stored payment_source payment.
The possible values are:
ONE_TIME
. One Time payment such as online purchase or donation. (e.g. Checkout with one-click).RECURRING
. Payment which is part of a series of payments with fixed or variable amounts, following a fixed time interval. (e.g. Subscription payments).UNSCHEDULED
. Payment which is part of a series of payments that occur on a non-fixed schedule and/or have variable amounts. (e.g. Account Topup payments).
usage
enum
Indicates if this is a
first
orsubsequent
payment using a stored payment source (also referred to as stored credential or card on file).The possible values are:
FIRST
. Indicates the Initial/First payment with a payment_source that is intended to be stored upon successful processing of the payment.SUBSEQUENT
. Indicates a payment using a stored payment_source which has been successfully used previously for a payment.DERIVED
. Indicates that PayPal will derive the value of `FIRST` or `SUBSEQUENT` based on data available to PayPal.
previous_network_transaction_reference
Reference values used by the card network to identify a transaction.
stored_payment_source_payment_type
stored_payment_source_payment_type
enum
Indicates the type of the stored payment_source payment.
The possible values are:
ONE_TIME
. One Time payment such as online purchase or donation. (e.g. Checkout with one-click).RECURRING
. Payment which is part of a series of payments with fixed or variable amounts, following a fixed time interval. (e.g. Subscription payments).UNSCHEDULED
. Payment which is part of a series of payments that occur on a non-fixed schedule and/or have variable amounts. (e.g. Account Topup payments).
stored_payment_source_usage_type
stored_payment_source_usage_type
enum
Indicates if this is a
first
orsubsequent
payment using a stored payment source (also referred to as stored credential or card on file).The possible values are:
FIRST
. Indicates the Initial/First payment with a payment_source that is intended to be stored upon successful processing of the payment.SUBSEQUENT
. Indicates a payment using a stored payment_source which has been successfully used previously for a payment.DERIVED
. Indicates that PayPal will derive the value of `FIRST` or `SUBSEQUENT` based on data available to PayPal.
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.
three_d_secure_authentication_response
authentication_status
enum
The outcome of the issuer's authentication.
The possible values are:
Y
. Successful authentication.N
. Failed authentication / account not verified / transaction denied.U
. Unable to complete authentication.A
. Successful attempts transaction.C
. Challenge required for authentication.R
. Authentication rejected (merchant must not submit for authorization).D
. Challenge required; decoupled authentication confirmed.I
. Informational only; 3DS requestor challenge preference acknowledged.
enrollment_status
enum
Status of authentication eligibility.
The possible values are:
Y
. Yes. The bank is participating in 3-D Secure protocol and will return the ACSUrl.N
. No. The bank is not participating in 3-D Secure protocol.U
. Unavailable. The DS or ACS is not available for authentication at the time of the request.B
. Bypass. The merchant authentication rule is triggered to bypass authentication.
token
id
string
required
The PayPal-generated ID for the token.
type
enum
required
The tokenization method that generated the ID.
The possible values are:
BILLING_AGREEMENT
. The PayPal billing agreement ID. References an approved recurring payment for goods or services.
Additional API information
Error messages
In addition to the common HTTP status codes that the REST APIs return, the Orders API can return the following errors.