API Version

Payments API

Call the Payments API to authorize payments, capture authorized payments, refund payments that have already been captured, and show payment information. Use the Payments API in conjunction with the Orders API. For more information, see the PayPal Checkout Overview.

Authorizations (resource group)

Use the /authorizations resource to show details for, capture payment for, reauthorize, and void authorized payments.

Show details for authorized payment

GET/v2/payments/authorizations/{authorization_id}

Shows details for an authorized payment, by ID.

Header parameters

Authorization
string
required
To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <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-m.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.
- 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, see status.details.
Read only.
status_details
object
The details of the authorized order pending status.
Read only.
id
string
The PayPal-generated ID for the authorized payment.
Read only.
amount
object
The amount for this authorized payment.
Read only.
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.
Read only.
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.
Maximum length: 127.
seller_protection
object
The level of protection offered as defined by PayPal Seller Protection for Merchants.
Read only.
expiration_time
string
The date and time when the authorized payment expires, in Internet date and time format.
Read only.
Minimum length: 20.
Maximum length: 64.
Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.
links
array (contains the link_description object)
An array of related HATEOAS links.
Read only.
create_time
string
The date and time when the transaction occurred, in Internet date and time format.
Read only.
update_time
string
The date and time when the transaction was last updated, in Internet date and time format.
Read only.

Sample Response

{
  "id": "0VF52814937998046",
  "status": "CREATED",
  "amount": {
    "value": "10.99",
    "currency_code": "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-m.paypal.com/v2/payments/authorizations/0VF52814937998046"
    },
    {
      "rel": "capture",
      "method": "POST",
      "href": "https://api-m.paypal.com/v2/payments/authorizations/0VF52814937998046/capture"
    },
    {
      "rel": "void",
      "method": "POST",
      "href": "https://api-m.paypal.com/v2/payments/authorizations/0VF52814937998046/void"
    },
    {
      "rel": "reauthorize",
      "method": "POST",
      "href": "https://api-m.paypal.com/v2/payments/authorizations/0VF52814937998046/reauthorize"
    }
  ]
}

Capture authorized payment

POST/v2/payments/authorizations/{authorization_id}/capture

Captures an authorized payment, by ID.

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 the id, 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 the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <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.
Maximum length: 127.
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.
Maximum length: 255.
amount
object
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 to false if you intend to capture additional payments against the authorization.
payment_instruction
object
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.
soft_descriptor
string
The payment descriptor on the payer's account statement.
Maximum length: 22.

Sample Request

curl -v -X POST https://api-m.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,
  "note_to_payer": "If the ordered color is not available, we will substitute with a different color free of charge.",
  "soft_descriptor": "Bob's Custom Sweaters"
}'

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, see status.details.
- REFUNDED. An amount greater than or equal to this captured payment's amount was refunded to the payer.
Read only.
status_details
object
The details of the captured payment status.
Read only.
id
string
The PayPal-generated ID for the captured payment.
Read only.
amount
object
The amount for this captured payment.
Read only.
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.
Read only.
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.
Maximum length: 127.
seller_protection
object
The level of protection offered as defined by PayPal Seller Protection for Merchants.
Read only.
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 to false if you intend to capture additional payments against the authorization.
Read only.
seller_receivable_breakdown
object
The detailed breakdown of the capture activity.
Read only.
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.
Read only.
processor_response
object
An object that provides additional processor information for a direct credit card transaction.
supplementary_data
An object that provides supplementary/additional data for a payment transaction that might be sent to the processor if a credit card is involved. This object is designed to pass information that depending on the type of data passed and use case can lead to an improvement in conversion rates, manage risk and ensure compliance. Currently this object allows the API caller to specify airline_itineraries if the transaction includes an airline ticket purchase.
create_time
string
The date and time when the transaction occurred, in Internet date and time format.
Read only.
update_time
string
The date and time when the transaction was last updated, in Internet date and time format.
Read only.

Sample Response

{
  "id": "2GG279541U471931P",
  "status": "COMPLETED",
  "links": [
    {
      "rel": "self",
      "method": "GET",
      "href": "https://api-m.paypal.com/v2/payments/captures/2GG279541U471931P"
    },
    {
      "rel": "refund",
      "method": "POST",
      "href": "https://api-m.paypal.com/v2/payments/captures/2GG279541U471931P/refund"
    },
    {
      "rel": "up",
      "method": "GET",
      "href": "https://api-m.paypal.com/v2/payments/authorizations/0VF52814937998046"
    }
  ]
}

Reauthorize authorized payment

POST/v2/payments/authorizations/{authorization_id}/reauthorize

Reauthorizes an authorized PayPal account payment, by ID. To ensure that funds are still available, reauthorize a payment after its initial three-day honor period expires. Within the 29-day authorization period, you can issue multiple re-authorizations after the honor period expires.

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 the id, 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 the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <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
object
The amount to reauthorize for an authorized payment.

Sample Request

curl -v -X POST https://api-m.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.
- 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, see status.details.
Read only.
status_details
object
The details of the authorized order pending status.
Read only.
id
string
The PayPal-generated ID for the authorized payment.
Read only.
amount
object
The amount for this authorized payment.
Read only.
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.
Read only.
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.
Maximum length: 127.
seller_protection
object
The level of protection offered as defined by PayPal Seller Protection for Merchants.
Read only.
expiration_time
string
The date and time when the authorized payment expires, in Internet date and time format.
Read only.
Minimum length: 20.
Maximum length: 64.
Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.
links
array (contains the link_description object)
An array of related HATEOAS links.
Read only.
create_time
string
The date and time when the transaction occurred, in Internet date and time format.
Read only.
update_time
string
The date and time when the transaction was last updated, in Internet date and time format.
Read only.

Sample Response

{
  "id": "8AA831015G517922L",
  "status": "CREATED",
  "links": [
    {
      "rel": "self",
      "method": "GET",
      "href": "https://api-m.paypal.com/v2/payments/authorizations/8AA831015G517922L"
    },
    {
      "rel": "capture",
      "method": "POST",
      "href": "https://api-m.paypal.com/v2/payments/authorizations/8AA831015G517922L/capture"
    },
    {
      "rel": "void",
      "method": "POST",
      "href": "https://api-m.paypal.com/v2/payments/authorizations/8AA831015G517922L/void"
    },
    {
      "rel": "reauthorize",
      "method": "POST",
      "href": "https://api-m.paypal.com/v2/payments/authorizations/8AA831015G517922L/reauthorize"
    }
  ]
}

Void authorized payment

POST/v2/payments/authorizations/{authorization_id}/void

Voids, or cancels, an authorized payment, by ID. You cannot void an authorized payment that has been fully captured.

Header parameters

Authorization
string
required
To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <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-m.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

GET/v2/payments/captures/{capture_id}

Shows details for a captured payment, by ID.

Header parameters

Authorization
string
required
To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <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-m.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, see status.details.
- REFUNDED. An amount greater than or equal to this captured payment's amount was refunded to the payer.
Read only.
status_details
object
The details of the captured payment status.
Read only.
id
string
The PayPal-generated ID for the captured payment.
Read only.
amount
object
The amount for this captured payment.
Read only.
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.
Read only.
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.
Maximum length: 127.
seller_protection
object
The level of protection offered as defined by PayPal Seller Protection for Merchants.
Read only.
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 to false if you intend to capture additional payments against the authorization.
Read only.
seller_receivable_breakdown
object
The detailed breakdown of the capture activity.
Read only.
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.
Read only.
processor_response
object
An object that provides additional processor information for a direct credit card transaction.
supplementary_data
An object that provides supplementary/additional data for a payment transaction that might be sent to the processor if a credit card is involved. This object is designed to pass information that depending on the type of data passed and use case can lead to an improvement in conversion rates, manage risk and ensure compliance. Currently this object allows the API caller to specify airline_itineraries if the transaction includes an airline ticket purchase.
create_time
string
The date and time when the transaction occurred, in Internet date and time format.
Read only.
update_time
string
The date and time when the transaction was last updated, in Internet date and time format.
Read only.

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"
    },
    "receivable_amount": {
      "currency_code": "CNY",
      "value": "59.26"
    },
    "paypal_fee_in_receivable_currency": {
      "currency_code": "CNY",
      "value": "1.13"
    },
    "exchange_rate": {
      "source_currency": "USD",
      "target_currency": "CNY",
      "value": "5.9483297432325"
    }
  },
  "invoice_id": "INVOICE-123",
  "create_time": "2017-09-11T23:24:01Z",
  "update_time": "2017-09-11T23:24:01Z",
  "links": [
    {
      "href": "https://api-m.paypal.com/v2/payments/captures/2GG279541U471931P",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.paypal.com/v2/payments/captures/2GG279541U471931P/refund",
      "rel": "refund",
      "method": "POST"
    },
    {
      "href": "https://api-m.paypal.com/v2/payments/authorizations/0VF52814937998046",
      "rel": "up",
      "method": "GET"
    }
  ]
}

Refund captured payment

POST/v2/payments/captures/{capture_id}/refund

Refunds a captured payment, by ID. For a full refund, include an empty payload in the JSON request body. For a partial refund, include an 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 the id, 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 the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <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
object
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.
Maximum length: 127.
note_to_payer
string
The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives.
Maximum length: 255.

Sample Request

curl -v -X POST https://api-m.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 refund.
The possible values are:
- CANCELLED. The refund was cancelled.
- PENDING. The refund is pending. For more information, see status_details.reason.
- COMPLETED. The funds for this transaction were debited to the customer's account.
Read only.
status_details
object
The details of the refund status.
Read only.
id
string
The PayPal-generated ID for the refund.
Read only.
amount
object
The amount that the payee refunded to the payer.
Read only.
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.
Read only.
note_to_payer
string
The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives.
Read only.
seller_payable_breakdown
object
The breakdown of the refund.
Read only.
links
array (contains the link_description object)
An array of related HATEOAS links.
Read only.
create_time
string
The date and time when the transaction occurred, in Internet date and time format.
Read only.
update_time
string
The date and time when the transaction was last updated, in Internet date and time format.
Read only.

Sample Response

{
  "id": "1JU08902781691411",
  "status": "COMPLETED",
  "links": [
    {
      "rel": "self",
      "method": "GET",
      "href": "https://api-m.paypal.com/v2/payments/refunds/1JU08902781691411"
    },
    {
      "rel": "up",
      "method": "GET",
      "href": "https://api-m.paypal.com/v2/payments/captures/2GG279541U471931P"
    }
  ]
}

Refunds (resource group)

Use the /refunds resource to show refund details.

Show refund details

GET/v2/payments/refunds/{refund_id}

Shows details for a refund, by ID.

Header parameters

Authorization
string
required
To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <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-m.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 refund.
The possible values are:
- CANCELLED. The refund was cancelled.
- PENDING. The refund is pending. For more information, see status_details.reason.
- COMPLETED. The funds for this transaction were debited to the customer's account.
Read only.
status_details
object
The details of the refund status.
Read only.
id
string
The PayPal-generated ID for the refund.
Read only.
amount
object
The amount that the payee refunded to the payer.
Read only.
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.
Read only.
note_to_payer
string
The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives.
Read only.
seller_payable_breakdown
object
The breakdown of the refund.
Read only.
links
array (contains the link_description object)
An array of related HATEOAS links.
Read only.
create_time
string
The date and time when the transaction occurred, in Internet date and time format.
Read only.
update_time
string
The date and time when the transaction was last updated, in Internet date and time format.
Read only.

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-m.paypal.com/v2/payments/refunds/1JU08902781691411"
    },
    {
      "rel": "up",
      "method": "GET",
      "href": "https://api-m.paypal.com/v2/payments/captures/2GG279541U471931P"
    }
  ]
}

Common object definitions

account_id

account_id
string
The account identifier for a PayPal account.
Minimum length: 13.
Maximum length: 13.
Pattern: ^[2-9A-HJ-NP-Z]{13}$.

ach_debit

account_number
string
required
The US bank account number from which the payment will be debited.
Minimum length: 3.
Maximum length: 17.
Pattern: [0-9]{3,17}.
routing_number
string
required
The 9-digit ABA routing transit number for the bank at which the account is held.
Minimum length: 9.
Maximum length: 9.
Pattern: [0-9]{9}.
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.
Minimum length: 1.
Maximum length: 255.
account_holder_name
string
required
Name of the person or business that owns the bank account.
Minimum length: 1.
Maximum length: 300.

activity_timestamps

create_time
string
The date and time when the transaction occurred, in Internet date and time format.
Read only.
update_time
string
The date and time when the transaction was last updated, in Internet date and time format.
Read only.

address_details

street_number
string
The street number.
Maximum length: 100.
street_name
string
The street name. Just Drury in Drury Lane.
Maximum length: 100.
street_type
string
The street type. For example, avenue, boulevard, road, or expressway.
Maximum length: 100.
delivery_service
string
The delivery service. Post office box, bag number, or post office name.
Maximum length: 100.
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.
Maximum length: 100.
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.
Maximum length: 100.

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.
Maximum length: 300.
address_line_2
string
The second line of the address. For example, suite or apartment number.
Maximum length: 300.
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.
Maximum length: 100.
admin_area_4
string
The neighborhood, ward, or district. Smaller than admin_area_level_3 or sub_locality. Value is:
- The postal sorting code for Guernsey and many French territories, such as French Guiana.
- The fine-grained administrative levels in China.
Maximum length: 100.
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.
Maximum length: 100.
admin_area_2
string
A city, town, or village. Smaller than admin_area_level_1.
Maximum length: 120.
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 not California. Value, by country, is:
- UK. A county.
- US. A state.
- Canada. A province.
- Japan. A prefecture.
- Switzerland. A kanton.
Maximum length: 300.
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.
Maximum length: 60.
country_code
string
required
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
Minimum length: 2.
Maximum length: 2.
Pattern: ^([A-Z]{2}|C2)$.
address_details
object
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 of address_details.street_number, street_name, and street_type.

address_portable_postal_code_validation

address_portable_postal_code_validation

amount_breakdown

item_total
object
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
object
The shipping fee for all items within a given purchase_unit. shipping.value can not be a negative number.
handling
object
The handling fee for all items within a given purchase_unit. handling.value can not be a negative number.
tax_total
object
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
object
The insurance fee for all items within a given purchase_unit. insurance.value can not be a negative number.
shipping_discount
object
The shipping discount for all items within a given purchase_unit. shipping_discount.value can not be a negative number.
discount
object
The discount for all items within a given purchase_unit. discount.value can not be a negative number.

authorization

status
string
The status for the authorized payment.
status_details
object
The details of the authorized order pending status.

id
string
The PayPal-generated ID for the authorized payment.
amount
object
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.
Maximum length: 127.
seller_protection
object
The level of protection offered as defined by PayPal Seller Protection for Merchants.
expiration_time
string
The date and time when the authorized payment expires, in Internet date and time format.
Minimum length: 20.
Maximum length: 64.
Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.
links
array (contains the link_description object)
An array of related HATEOAS links.

create_time
string
The date and time when the transaction occurred, in Internet date and time format.
update_time
string
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, see status.details.
Read only.
status_details
object
The details of the authorized order pending status.
Read only.

authorization_status_details

reason
enum
The reason why the authorized status is PENDING.
The possible values are:
- PENDING_REVIEW. Authorization is pending manual review.

bic

bic
string
The business identification code (BIC). In payments systems, a BIC is used to identify a specific business, most commonly a bank
Minimum length: 8.
Maximum length: 11.

capture

status
string
The status of the captured payment.
status_details
object
The details of the captured payment status.

id
string
The PayPal-generated ID for the captured payment.
amount
object
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.
Maximum length: 127.
seller_protection
object
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 to false if you intend to capture additional payments against the authorization.
seller_receivable_breakdown
object
The detailed breakdown of the capture activity.
disbursement_mode
string
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
object
An object that provides additional processor information for a direct credit card transaction.
supplementary_data
An object that provides supplementary/additional data for a payment transaction that might be sent to the processor if a credit card is involved. This object is designed to pass information that depending on the type of data passed and use case can lead to an improvement in conversion rates, manage risk and ensure compliance. Currently this object allows the API caller to specify airline_itineraries if the transaction includes an airline ticket purchase.

create_time
string
The date and time when the transaction occurred, in Internet date and time format.
update_time
string
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.
Maximum length: 127.
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.
Maximum length: 255.

amount
object
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.
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.
Maximum length: 127.
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 to false if you intend to capture additional payments against the authorization.
payment_instruction
object
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.
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.
Maximum length: 255.
soft_descriptor
string
The payment descriptor on the payer's account statement.
Maximum length: 22.

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, see status.details.
- REFUNDED. An amount greater than or equal to this captured payment's amount was refunded to the payer.
Read only.
status_details
object
The details of the captured payment status.
Read only.

capture_status_details

reason
enum
The reason why the captured payment status is PENDING or DENIED.
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.
Minimum length: 1.
Maximum length: 255.
Pattern: ^[A-Z_]+$.

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 not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
Minimum length: 2.
Maximum length: 2.
Pattern: ^([A-Z]{2}|C2)$.

currency_code

currency_code
string
The three-character ISO-4217 currency code that identifies the currency.
Minimum length: 3.
Maximum length: 3.

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.
Minimum length: 20.
Maximum length: 64.
Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.

date_year_month

date_year_month
string
The year and month, in ISO-8601 YYYY-MM date format. See Internet date and time format.
Minimum length: 7.
Maximum length: 7.
Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$.

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

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.
Maximum length: 254.
Pattern: (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*|(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9])|[a-zA-Z0-9-]*[a-zA-Z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\]).

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.
Minimum length: 3.
Maximum length: 254.
Pattern: ^.+@[^"\-].+$.

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.
Read only.
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.
Read only.

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, or query.
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
string
The source currency from which to convert an amount.
target_currency
string
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. The href 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.
Possible values: GET,POST,PUT,DELETE,HEAD,CONNECT,OPTIONS,PATCH.

merchant_partner_customer_id

merchant_partner_customer_id
string
The unique ID for a customer in merchant's or partner's system of records.
Minimum length: 1.
Maximum length: 22.
Pattern: ^[0-9a-zA-Z_-]+$.

money

currency_code
string
required
The three-character ISO-4217 currency code that identifies the currency.
Minimum length: 3.
Maximum length: 3.
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.
For the required number of decimal places for a currency code, see Currency Codes.
Maximum length: 32.
Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

name

name
string
The full name representation like Mr J Smith
Minimum length: 3.
Maximum length: 300.

name

prefix
string
The prefix, or title, to the party's name.
Maximum length: 140.
given_name
string
When the party is a person, the party's given, or first, name.
Maximum length: 140.
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.
Maximum length: 140.
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.
Maximum length: 140.
suffix
string
The suffix for the party's name.
Maximum length: 140.
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.
Maximum length: 300.
full_name
string
When the party is a person, the party's full name.
Maximum length: 300.

name_validation

name_validation

name_validation

name_validation

net_amount_breakdown

payable_amount
object
The net amount debited from the merchant's PayPal account.
Read only.
converted_amount
object
The converted payable amount.
Read only.
exchange_rate
object
The exchange rate that determines the amount that was debited from the merchant's PayPal account.
Read only.

payee_base

email_address
string
The email address of merchant.
Maximum length: 254.
Pattern: (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*|(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9])|[a-zA-Z0-9-]*[a-zA-Z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\]).
merchant_id
string
The encrypted PayPal account ID of the merchant.
Minimum length: 13.
Maximum length: 13.
Pattern: ^[2-9A-HJ-NP-Z]{13}$.

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).
Minimum length: 1.
Maximum length: 3.
Pattern: ^[0-9]{1,3}?$.
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).
Minimum length: 1.
Maximum length: 14.
Pattern: ^[0-9]{1,14}?$.
extension_number
string
The extension number.
Minimum length: 1.
Maximum length: 15.
Pattern: ^[0-9]{1,15}?$.

platform_fee

amount
object
required
The fee for this transaction.
payee
object
The recipient of the fee for this transaction. If you omit this value, the default is the API caller.

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.
Read only.
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.
Read only.
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.
Read only.
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.
Read only.

reauthorize_request

amount
object
The amount to reauthorize for an authorized payment.

refund

status
string
The status of the refund.
status_details
object
The details of the refund status.

id
string
The PayPal-generated ID for the refund.
amount
object
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
object
The breakdown of the refund.
links
array (contains the link_description object)
An array of related HATEOAS links.

create_time
string
The date and time when the transaction occurred, in Internet date and time format.
update_time
string
The date and time when the transaction was last updated, in Internet date and time format.

refund_request

amount
object
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.
Maximum length: 127.
note_to_payer
string
The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives.
Maximum length: 255.

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, see status_details.reason.
- COMPLETED. The funds for this transaction were debited to the customer's account.
Read only.
status_details
object
The details of the refund status.
Read only.

refund_status_details

reason
enum
The reason why the refund has the PENDING or FAILED 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
object
The amount that the payee refunded to the payer.
Read only.
paypal_fee
object
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.
Read only.
net_amount
object
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 minus paypal_fee minus platform_fees.
Read only.
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.
Read only.
total_refunded_amount
object
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 the total_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.
Read only.
dispute_categories
array (contains the dispute_category object)
An array of conditions that are covered for the transaction.
Read only.

seller_receivable_breakdown

gross_amount
object
required
The amount for this captured payment in the currency of the transaction.
paypal_fee
object
The applicable fee for this captured payment in the currency of the transaction.
paypal_fee_in_receivable_currency
object
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
object
The net amount that the payee receives for this captured payment in their PayPal account. The net amount is computed as gross_amount minus the paypal_fee minus the platform_fees.
receivable_amount
object
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 times exchange_rate.
exchange_rate
object
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.
Read only.
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.
Maximum length: 127.
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.
Maximum length: 255.

token

id
string
required
The PayPal-generated ID for the token.
Minimum length: 1.
Maximum length: 255.
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.
Minimum length: 1.
Maximum length: 255.
Pattern: ^[0-9A-Z_-]+$.

Error messages

In addition to the common HTTP status codes that the REST APIs return, the Payments API can return the following errors.

AUTH_CAPTURE_CURRENCY_MISMATCH
Currency of capture must be the same as currency of authorization.
AUTHENTICATION_FAILURE
Authentication failed due to missing authorization header, or invalid authentication credentials.
AUTHORIZATION_ALREADY_CAPTURED
Authorization has already been captured.
AUTHORIZATION_DENIED
A denied authorization cannot be captured.
AUTHORIZATION_EXPIRED
An expired authorization cannot be captured.
AUTHORIZATION_VOIDED
A voided authorization cannot be captured or reauthorized.
CANNOT_BE_ZERO_OR_NEGATIVE
Must be greater than zero. If the currency supports decimals, only two decimal place precision is supported.
CANNOT_BE_VOIDED
A reauthorization cannot be voided. Please void the original parent authorization.
REFUND_NOT_PERMITTED_DUE_TO_CHARGEBACK
The requested action could not be performed, semantically incorrect, or failed business validation.
CAPTURE_DISPUTED_PARTIAL_REFUND_NOT_ALLOWED
The requested action could not be performed, semantically incorrect, or failed business validation.
CAPTURE_FULLY_REFUNDED
The capture has already been fully refunded.
DECIMAL_PRECISION
The value of the field should not be more than two decimal places.
DECIMALS_NOT_SUPPORTED
Currency does not support decimals.
DUPLICATE_INVOICE_ID
Requested invoice number has been previously captured. Possible duplicate transaction.
INVALID_ACCOUNT_STATUS
Account validations failed for the user.
INTERNAL_SERVER_ERROR
An internal server error has occurred.
INVALID_CURRENCY_CODE
Currency code should be a three-character ISO-4217 currency code.
INVALID_INVOICE_ID
Specified invoice_id does not exist.
INVALID_PARAMETER_SYNTAX
The value of the field does not conform to the expected format.
INVALID_PARAMETER_VALUE
The value of a field is invalid.
INVALID_PAYEE_ACCOUNT
Payee account is invalid.
INVALID_PLATFORM_FEES_AMOUNT
The platform_fees amount cannot be greater than the capture amount.
INVALID_RESOURCE_ID
Specified resource ID does not exist. Please check the resource ID and try again.
INVALID_STRING_LENGTH
The value of a field is either too short or too long.
INVALID_STRING_MAX_LENGTH
The value of a field is too long.
MAX_CAPTURE_AMOUNT_EXCEEDED
Capture amount exceeds allowable limit. Please contact customer service or your account manager to request the change to your overage limit. The default overage limit is 115%, which allows the sum of all captures to be up to 115% of the authorization amount.
MAX_CAPTURE_COUNT_EXCEEDED
Maximum number of allowable captures has been reached. No additional captures are possible for this authorization. Please contact customer service or your account manager to change the number of captures that be made for a given authorization.
MAX_NUMBER_OF_REFUNDS_EXCEEDED
You have exceeded the number of refunds that can be processed per capture.
MISSING_REQUIRED_PARAMETER
A required field / parameter is missing.
MULTIPLE_AUTHORIZATIONS_FOUND
Cannot void multiple authorizations.
NOT_AUTHORIZED
You do not have permission to access or perform operations on this resource.
PARTIAL_REFUND_NOT_ALLOWED
You cannot do a refund for an amount less than the original capture amount.
PAYEE_ACCOUNT_LOCKED_OR_CLOSED
Transaction could not complete because payee account is locked or closed.
PAYEE_ACCOUNT_RESTRICTED
Payee account is restricted.
PAYER_ACCOUNT_LOCKED_OR_CLOSED
The payer account cannot be used for this transaction.
PAYER_CANNOT_PAY
Payer cannot pay for this transaction.
PENDING_CAPTURE
Cannot initiate a refund as the capture is pending.
PERMISSION_DENIED
You do not have permission to access or perform operations on this resource.
PERMISSION_NOT_GRANTED
Payee of the authorization has not granted permission to perform capture on the authorization.
PREVIOUSLY_CAPTURED
Authorization has been previously captured and hence cannot be voided.
PREVIOUSLY_VOIDED
Authorization has been previously voided and hence cannot be voided again.
REFUND_AMOUNT_EXCEEDED
The refund amount must be less than or equal to the capture amount that has not yet been refunded.
REFUND_CAPTURE_CURRENCY_MISMATCH
Refund must be in the same currency as the capture.
REFUND_FAILED_INSUFFICIENT_FUNDS
Capture could not be refunded due to insufficient funds.
REFUND_NOT_ALLOWED
Full refund refused - partial refund has already been done on this payment.
REFUND_TIME_LIMIT_EXCEEDED
You are over the time limit to perform a refund on this capture.
TRANSACTION_REFUSED
PayPal's internal controls prevent authorization from being captured.
REFUND_NOT_SUPPORTED_FOR_PAYMENT_SOURCE
Refund was refused by the payment source.
REFUND_TIME_EXCEEDED_FOR_PAYMENT_SOURCE
Refund was refused by the payment source.
REFUND_FAILED_BY_PAYMENT_SOURCE
Refund was refused by the payment source.

PayPal Commerce Platform for Business

PayPal Commerce Platform for Marketplaces and Platforms

PayPal Commerce Platform for Enterprise

Docs Catalog

Reference

Developer Tools

Regional Codes

Authorization

Content-Type

authorization_id

Sample Request

status

status_details

id

amount

invoice_id

custom_id

seller_protection

expiration_time

links

create_time

update_time

Sample Response

PayPal-Request-Id

Prefer

Authorization

Content-Type

authorization_id

invoice_id

note_to_payer

amount

final_capture

payment_instruction

soft_descriptor

Sample Request

status

status_details

id

amount

invoice_id

custom_id

seller_protection

final_capture

seller_receivable_breakdown

disbursement_mode

links

processor_response

supplementary_data

create_time

update_time

Sample Response

PayPal-Request-Id

Prefer

Authorization

Content-Type

authorization_id

amount

Sample Request

status

status_details

id

amount

invoice_id

custom_id

seller_protection

expiration_time

links

create_time

update_time

Sample Response

Authorization

Content-Type

PayPal-Auth-Assertion

authorization_id

Sample Request

Sample Response

Authorization

Content-Type

capture_id

Sample Request

`Authorization`

`Content-Type`

`authorization_id`

`status`

`status_details`

`id`

`amount`

`invoice_id`

`custom_id`

`seller_protection`

`expiration_time`

`links`

`create_time`

`update_time`

`PayPal-Request-Id`

`Prefer`

`Authorization`

`Content-Type`

`authorization_id`

`invoice_id`

`note_to_payer`

`amount`

`final_capture`

`payment_instruction`

`soft_descriptor`

`status`

`status_details`

`id`

`amount`

`invoice_id`

`custom_id`

`seller_protection`

`final_capture`

`seller_receivable_breakdown`

`disbursement_mode`

`links`

`processor_response`

`supplementary_data`

`create_time`

`update_time`

`PayPal-Request-Id`

`Prefer`

`Authorization`

`Content-Type`

`authorization_id`

`amount`

`status`

`status_details`

`id`

`amount`

`invoice_id`

`custom_id`

`seller_protection`

`expiration_time`

`links`

`create_time`

`update_time`

`Authorization`

`Content-Type`

`PayPal-Auth-Assertion`

`authorization_id`

`Authorization`

`Content-Type`

`capture_id`

`status`

`status_details`

`id`

`amount`

`invoice_id`

`custom_id`

`seller_protection`

`final_capture`

`seller_receivable_breakdown`

`disbursement_mode`

`links`

`processor_response`

`supplementary_data`

`create_time`

`update_time`

`PayPal-Request-Id`