Payments API
Authorizations (resource group)
Use the /authorizations
resource to show details for, capture payment for, reauthorize, and void authorized payments.
Show details for authorized payment
Header parameters
Authorization
string
required
To make REST API calls, include the bearer token in the
Authorization
header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id>:<secret>
.Content-Type
string
required
Required for operations with a request body. The value is application/
. Where the 'format' is 'json'.
Path parameters
authorization_id
string
required
The ID of the authorized payment for which to show details.
Sample Request
curl -v -X GET https://api.sandbox.paypal.com/v2/payments/authorizations/0VF52814937998046 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
Response
A successful request returns the HTTP 200 OK
status code and a JSON response body that shows authorization details.
status
enum
The status for the authorized payment.
The possible values are:
CREATED
. The authorized payment is created. No captured payments have been made for this authorized payment.CAPTURED
. The authorized payment has one or more captures against it. The sum of these captured payments is greater than the amount of the original authorized payment.DENIED
. PayPal cannot authorize funds for this authorized payment.EXPIRED
. The authorized payment has expired.PARTIALLY_CAPTURED
. A captured payment was made for the authorized payment for an amount that is less than the amount of the original authorized payment.VOIDED
. The authorized payment was voided. No more captured payments can be made against this authorized payment.PENDING
. The created authorization is in pending state. For more information, seestatus.details
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.
Sample Response
{
"id": "0VF52814937998046",
"status": "AUTHORIZED",
"amount": {
"total": "10.99",
"currency": "USD"
},
"invoice_id": "INVOICE-123",
"seller_protection": {
"status": "ELIGIBLE",
"dispute_categories": [
"ITEM_NOT_RECEIVED",
"UNAUTHORIZED_TRANSACTION"
]
},
"expiration_time": "2017-10-10T23:23:45Z",
"create_time": "2017-09-11T23:23:45Z",
"update_time": "2017-09-11T23:23:45Z",
"links": [
{
"rel": "self",
"method": "GET",
"href": "https://api.paypal.com/v2/payments/authorizations/0VF52814937998046"
},
{
"rel": "capture",
"method": "POST",
"href": "https://api.paypal.com/v2/payments/authorizations/0VF52814937998046/capture"
},
{
"rel": "void",
"method": "POST",
"href": "https://api.paypal.com/v2/payments/authorizations/0VF52814937998046/void"
},
{
"rel": "reauthorize",
"method": "POST",
"href": "https://api.paypal.com/v2/payments/authorizations/0VF52814937998046/reauthorize"
}
]
}
Capture authorized payment
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.
Authorization
string
required
To make REST API calls, include the bearer token in the
Authorization
header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id>:<secret>
.Content-Type
string
required
Required for operations with a request body. The value is application/
. Where the 'format' is 'json'.
Path parameters
authorization_id
string
required
The PayPal-generated ID for the authorized payment to capture.
Request body
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
An informational note about this settlement. Appears in both the payer's transaction history and the emails that the payer receives.
amount
The amount to capture. To capture a portion of the full authorized amount, specify an amount. If amount is not specified, the full authorized amount is captured. The amount must be a positive number and in the same currency as the authorization against which the payment is being captured.
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.payment_instruction
Any additional payment instructions for PayPal for Partner customers. Enables features for partners and marketplaces, such as delayed disbursement and collection of a platform fee. Applies during order creation for captured payments or during capture of authorized payments.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v2/payments/authorizations/0VF52814937998046/capture \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-H "PayPal-Request-Id: 123e4567-e89b-12d3-a456-426655440010" \
-d '{
"amount": {
"value": "10.99",
"currency_code": "USD"
},
"invoice_id": "INVOICE-123",
"final_capture": true
}'
Response
A successful request returns the HTTP 201 Created
status code and a JSON response body that shows captured payment details.
status
enum
The status of the captured payment.
The possible values are:
COMPLETED
. The funds for this captured payment were credited to the payee's PayPal account.DECLINED
. The funds could not be captured.PARTIALLY_REFUNDED
. An amount less than this captured payment's amount was partially refunded to the payer.PENDING
. The funds for this captured payment was not yet credited to the payee's PayPal account. For more information, seestatus.details
REFUNDED
. An amount greater than or equal to this captured payment's amount was refunded to the payer.
status_details
The details of the captured payment status.
id
string
The PayPal-generated ID for the captured payment.
amount
The amount for this captured payment.
invoice_id
string
The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.
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 captured payment.
disbursement_mode
enum
The funds that are held on behalf of the merchant.
The possible values are:
INSTANT
. The funds are released to the merchant immediately.DELAYED
. The funds are held for a finite number of days. The actual duration depends on the region and type of integration. You can release the funds through a referenced payout. Otherwise, the funds disbursed automatically after the specified duration.
links
array (contains the link_description object)
An array of related HATEOAS links.
create_time
The date and time when the transaction occurred, in Internet date and time format.
update_time
The date and time when the transaction was last updated, in Internet date and time format.
Sample Response
{
"id": "2GG279541U471931P",
"status": "COMPLETED",
"links": [
{
"rel": "self",
"method": "GET",
"href": "https://api.paypal.com/v2/payments/captures/2GG279541U471931P"
},
{
"rel": "refund",
"method": "POST",
"href": "https://api.paypal.com/v2/payments/captures/2GG279541U471931P/refund"
},
{
"rel": "up",
"method": "GET",
"href": "https://api.paypal.com/v2/payments/authorizations/0VF52814937998046"
}
]
}
Reauthorize authorized payment
If 30 days have transpired since the date of the original authorization, you must create an authorized payment instead of reauthorizing the original authorized payment.
A reauthorized payment itself has a new honor period of three days.
You can reauthorize an authorized payment once for up to 115% of the original authorized amount, not to exceed an increase of $75 USD.
Supports only the `amount` request parameter.
Note: This request is currently not supported for Partner use cases.
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.
Authorization
string
required
To make REST API calls, include the bearer token in the
Authorization
header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id>:<secret>
.Content-Type
string
required
Required for operations with a request body. The value is application/
. Where the 'format' is 'json'.
Path parameters
authorization_id
string
required
The PayPal-generated ID for the authorized payment to reauthorize.
Request body
amount
The amount to reauthorize for an authorized payment.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v2/payments/authorizations/0VF52814937998046/reauthorize \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-H "PayPal-Request-Id: 123e4567-e89b-12d3-a456-426655440040" \
-d '{
"amount": {
"value": "10.99",
"currency_code": "USD"
}
}'
Response
A successful request returns the HTTP 201 Created
status code and a JSON response body that shows the reauthorized payment details.
status
enum
The status for the authorized payment.
The possible values are:
CREATED
. The authorized payment is created. No captured payments have been made for this authorized payment.CAPTURED
. The authorized payment has one or more captures against it. The sum of these captured payments is greater than the amount of the original authorized payment.DENIED
. PayPal cannot authorize funds for this authorized payment.EXPIRED
. The authorized payment has expired.PARTIALLY_CAPTURED
. A captured payment was made for the authorized payment for an amount that is less than the amount of the original authorized payment.VOIDED
. The authorized payment was voided. No more captured payments can be made against this authorized payment.PENDING
. The created authorization is in pending state. For more information, seestatus.details
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.
Sample Response
{
"id": "8AA831015G517922L",
"status": "CREATED",
"links": [
{
"rel": "self",
"method": "GET",
"href": "https://api.paypal.com/v2/payments/authorizations/8AA831015G517922L"
},
{
"rel": "capture",
"method": "POST",
"href": "https://api.paypal.com/v2/payments/authorizations/8AA831015G517922L/capture"
},
{
"rel": "void",
"method": "POST",
"href": "https://api.paypal.com/v2/payments/authorizations/8AA831015G517922L/void"
},
{
"rel": "reauthorize",
"method": "POST",
"href": "https://api.paypal.com/v2/payments/authorizations/8AA831015G517922L/reauthorize"
}
]
}
Void authorized payment
Header parameters
Authorization
string
required
To make REST API calls, include the bearer token in the
Authorization
header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id>:<secret>
.Content-Type
string
required
Required for operations with a request body. The value is application/
. Where the 'format' is 'json'. PayPal-Auth-Assertion
string
An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see PayPal-Auth-Assertion.
Note:For three party transactions in which a partner is managing the API calls on behalf of a merchant, the partner must identify the merchant using either a PayPal-Auth-Assertion header or an access token with target_subject.
Path parameters
authorization_id
string
required
The PayPal-generated ID for the authorized payment to void.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v2/payments/authorizations/0VF52814937998046/void \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
Response
A successful request returns the HTTP 204 No Content
status code with no JSON response body.
Sample Response
204 No Content
Captures (resource group)
Use the /captures
resource to show details for and refund a captured payment.
Show captured payment details
Header parameters
Authorization
string
required
To make REST API calls, include the bearer token in the
Authorization
header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id>:<secret>
.Content-Type
string
required
Required for operations with a request body. The value is application/
. Where the 'format' is 'json'.
Path parameters
capture_id
string
required
The PayPal-generated ID for the captured payment for which to show details.
Sample Request
curl -v -X GET https://api.sandbox.paypal.com/v2/payments/captures/2GG279541U471931P \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
Response
A successful request returns the HTTP 200 OK
status code and a JSON response body that shows captured payment details.
status
enum
The status of the captured payment.
The possible values are:
COMPLETED
. The funds for this captured payment were credited to the payee's PayPal account.DECLINED
. The funds could not be captured.PARTIALLY_REFUNDED
. An amount less than this captured payment's amount was partially refunded to the payer.PENDING
. The funds for this captured payment was not yet credited to the payee's PayPal account. For more information, seestatus.details
REFUNDED
. An amount greater than or equal to this captured payment's amount was refunded to the payer.
status_details
The details of the captured payment status.
id
string
The PayPal-generated ID for the captured payment.
amount
The amount for this captured payment.
invoice_id
string
The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.
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 captured payment.
disbursement_mode
enum
The funds that are held on behalf of the merchant.
The possible values are:
INSTANT
. The funds are released to the merchant immediately.DELAYED
. The funds are held for a finite number of days. The actual duration depends on the region and type of integration. You can release the funds through a referenced payout. Otherwise, the funds disbursed automatically after the specified duration.
links
array (contains the link_description object)
An array of related HATEOAS links.
create_time
The date and time when the transaction occurred, in Internet date and time format.
update_time
The date and time when the transaction was last updated, in Internet date and time format.
Sample Response
{
"id": "2GG279541U471931P",
"status": "COMPLETED",
"status_details": {},
"amount": {
"total": "10.99",
"currency": "USD"
},
"final_capture": true,
"seller_protection": {
"status": "ELIGIBLE",
"dispute_categories": [
"ITEM_NOT_RECEIVED",
"UNAUTHORIZED_TRANSACTION"
]
},
"seller_receivable_breakdown": {
"gross_amount": {
"total": "10.99",
"currency": "USD"
},
"paypal_fee": {
"value": "0.33",
"currency": "USD"
},
"net_amount": {
"value": "10.66",
"currency": "USD"
}
},
"invoice_id": "INVOICE-123",
"create_time": "2017-09-11T23:24:01Z",
"update_time": "2017-09-11T23:24:01Z",
"links": [
{
"href": "https://api.paypal.com/v2/payments/captures/2GG279541U471931P",
"rel": "self",
"method": "GET"
},
{
"href": "https://api.paypal.com/v2/payments/captures/2GG279541U471931P/refund",
"rel": "refund",
"method": "POST"
},
{
"href": "https://api.paypal.com/v2/payments/authorizations/0VF52814937998046",
"rel": "up",
"method": "GET"
}
]
}
Refund captured payment
amount
object in the JSON request body.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.
Authorization
string
required
To make REST API calls, include the bearer token in the
Authorization
header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id>:<secret>
.Content-Type
string
required
Required for operations with a request body. The value is application/
. Where the 'format' is 'json'. PayPal-Auth-Assertion
string
An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see PayPal-Auth-Assertion.
Note:For three party transactions in which a partner is managing the API calls on behalf of a merchant, the partner must identify the merchant using either a PayPal-Auth-Assertion header or an access token with target_subject.
Path parameters
capture_id
string
required
The PayPal-generated ID for the captured payment to refund.
Request body
amount
The amount to refund. To refund a portion of the captured amount, specify an amount. If amount is not specified, an amount equal to
captured amount - previous refunds
is refunded. The amount must be a positive number and in the same currency as the one in which the payment was captured.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.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v2/payments/captures/2GG279541U471931P/refund \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-H "PayPal-Request-Id: 123e4567-e89b-12d3-a456-426655440020" \
-d '{
"amount": {
"value": "10.99",
"currency_code": "USD"
},
"invoice_id": "INVOICE-123",
"note_to_payer": "Defective product"
}'
Response
A successful request returns the HTTP 201 Created
status code and a JSON response body that shows refund details.
status
enum
The status of the capture.
The possible values are:
CANCELLED
. The refund was cancelled.PENDING
. The refund is pending. For more information, seestatus_details.reason
.COMPLETED
. The funds for this transaction were debited to the customer's account.
status_details
The details of the refund status.
id
string
The PayPal-generated ID for the refund.
amount
The amount that the payee refunded to the payer.
invoice_id
string
The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.
note_to_payer
string
The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives.
seller_payable_breakdown
The breakdown of the refund.
links
array (contains the link_description object)
An array of related HATEOAS links.
create_time
The date and time when the transaction occurred, in Internet date and time format.
update_time
The date and time when the transaction was last updated, in Internet date and time format.
Sample Response
{
"id": "1JU08902781691411",
"status": "COMPLETED",
"links": [
{
"rel": "self",
"method": "GET",
"href": "https://api.paypal.com/v2/payments/refunds/1JU08902781691411"
},
{
"rel": "up",
"method": "GET",
"href": "https://api.paypal.com/v2/payments/captures/2GG279541U471931P"
}
]
}
Refunds (resource group)
Use the /refunds
resource to show refund details.
Show refund details
Header parameters
Authorization
string
required
To make REST API calls, include the bearer token in the
Authorization
header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id>:<secret>
.Content-Type
string
required
Required for operations with a request body. The value is application/
. Where the 'format' is 'json'.
Path parameters
refund_id
string
required
The PayPal-generated ID for the refund for which to show details.
Sample Request
curl -v -X GET https://api.sandbox.paypal.com/v2/payments/refunds/1JU08902781691411 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
Response
A successful request returns the HTTP 200 OK
status code and a JSON response body that shows refund details.
status
enum
The status of the capture.
The possible values are:
CANCELLED
. The refund was cancelled.PENDING
. The refund is pending. For more information, seestatus_details.reason
.COMPLETED
. The funds for this transaction were debited to the customer's account.
status_details
The details of the refund status.
id
string
The PayPal-generated ID for the refund.
amount
The amount that the payee refunded to the payer.
invoice_id
string
The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.
note_to_payer
string
The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives.
seller_payable_breakdown
The breakdown of the refund.
links
array (contains the link_description object)
An array of related HATEOAS links.
create_time
The date and time when the transaction occurred, in Internet date and time format.
update_time
The date and time when the transaction was last updated, in Internet date and time format.
Sample Response
{
"id": "1JU08902781691411",
"amount": {
"value": "10.99",
"currency_code": "USD"
},
"status": "COMPLETED",
"note_to_payer": "Defective product",
"seller_payable_breakdown": {
"gross_amount": {
"value": "10.99",
"currency_code": "USD"
},
"paypal_fee": {
"value": "0",
"currency_code": "USD"
},
"net_amount": {
"value": "10.99",
"currency_code": "USD"
},
"total_refunded_amount": {
"value": "10.99",
"currency_code": "USD"
}
},
"invoice_id": "INVOICE-123",
"create_time": "2018-09-11T23:24:19Z",
"update_time": "2018-09-11T23:24:19Z",
"links": [
{
"rel": "self",
"method": "GET",
"href": "https://api.paypal.com/v2/payments/refunds/1JU08902781691411"
},
{
"rel": "up",
"method": "GET",
"href": "https://api.paypal.com/v2/payments/captures/2GG279541U471931P"
}
]
}
Common object definitions
activity_timestamps
create_time
The date and time when the transaction occurred, in Internet date and time format.
update_time
The date and time when the transaction was last updated, in Internet date and time format.
address_details
street_number
string
The street number.
street_name
string
The street name. 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_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
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.shipping
The shipping fee for all items within a given
purchase_unit
.handling
The handling fee for all items within a given
purchase_unit
.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.insurance
The insurance fee for all items within a given
purchase_unit
.shipping_discount
The shipping discount for all items within a given
purchase_unit
.discount
The discount for all items within a given
purchase_unit
.
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.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.
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 captured payment.
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.
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_request
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
An informational note about this settlement. Appears in both the payer's transaction history and the emails that the payer receives.
amount
The amount to capture. To capture a portion of the full authorized amount, specify an amount. If amount is not specified, the full authorized amount is captured. The amount must be a positive number and in the same currency as the authorization against which the payment is being captured.
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.payment_instruction
Any additional payment instructions for PayPal for Partner customers. Enables features for partners and marketplaces, such as delayed disbursement and collection of a platform fee. Applies during order creation for captured payments or during capture of authorized payments.
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.
country_code
country_code
string
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is
GB
and notUK
as used in the top-level domain names for that country. Use theC2
country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
currency_code
currency_code
string
The three-character ISO-4217 currency code that identifies the currency.
date_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.
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.
email
string
The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the
@
sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@
sign exists.
error
name
string
required
The human-readable, unique name of the error.
message
string
required
The message that describes the error.
debug_id
string
required
The PayPal internal ID. Used for correlation purposes.
information_link
string
The information link, or URI, that shows detailed information about this error for the developer.
details
array (contains the error_details object)
An array of additional details about the error.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
error_details
field
string
The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors.
value
string
The value of the field that caused the error.
location
string
The location of the field that caused the error. Value 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.
link_description
href
string
required
The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the
$
,(
, and)
characters. Thehref
is the key HATEOAS component that links a completed call with a subsequent call.rel
string
required
The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
method
enum
The HTTP method required to make the related call.
money
The three-character ISO-4217 currency code that identifies the currency.
value
string
required
The value, which might be:
- An integer for currencies like
JPY
that are not typically fractional. - A decimal fraction for currencies like
TND
that are subdivided into thousandths.
- An integer for currencies like
name
prefix
string
The prefix, or title, to the party's name.
given_name
string
When the party is a person, the party's given, or first, name.
surname
string
When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.
middle_name
string
When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.
suffix
string
The suffix for the party's name.
alternate_full_name
string
DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business.
full_name
string
When the party is a person, the party's full name.
name_validation
name_validation
payer_id
payer_id
string
The PayPal payer ID, which is a masked version of the PayPal account number intended for use with third parties. The account number is reversibly encrypted and a proprietary variant of Base32 is used to encode the result.
payment_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.
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.
reauthorize_request
amount
The amount to reauthorize for an authorized payment.
refund
status
string
The status of the capture.
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_request
amount
The amount to refund. To refund a portion of the captured amount, specify an amount. If amount is not specified, an amount equal to
captured amount - previous refunds
is refunded. The amount must be a positive number and in the same currency as the one in which the payment was captured.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.
refund_status
status
enum
The status of the capture.
The possible values are:
CANCELLED
. The refund was cancelled.PENDING
. The refund is pending. For more information, seestatus_details.reason
.COMPLETED
. The funds for this transaction were debited to the customer's account.
status_details
The details of the refund status.
refund_status_details
reason
enum
The reason why the refund has the
PENDING
orFAILED
status.The possible values are:
ECHECK
. The customer's account is funded through an eCheck, which has not yet cleared.
seller_payable_breakdown
gross_amount
The amount that the payee refunded to the payer.
paypal_fee
The PayPal fee that was refunded to the payer. This fee might not match the PayPal fee that the payee paid when the payment was captured.
net_amount
The net amount that the payee's account is debited, if the payee holds funds in the currency for this refund. The net amount is calculated as
gross_amount
minuspaypal_fee
minusplatform_fees
.platform_fees
array (contains the platform_fee object)
An array of platform or partner fees, commissions, or brokerage fees for the refund.
net_amount_breakdown
array (contains the net_amount_breakdown 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
gross_amount
The amount for this captured payment.
paypal_fee
The applicable fee for this captured payment.
net_amount
The net amount that the payee receives for this captured payment in their PayPal account. The net amount is computed 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_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.
supplementary_purchase_data
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
An informational note about this settlement. Appears in both the payer's transaction history and the emails that the payer receives.
Additional API information
Error messages
In addition to the common HTTP status codes that the REST APIs return, the Payments API can return the following errors.