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

For more information about HTTP request headers, see HTTP request headers.
  • 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.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, 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": "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

POST /v2/payments/authorizations/{authorization_id}/capture
Captures an authorized payment, by ID.

Header parameters

For more information about HTTP request headers, see HTTP request headers.
  • PayPal-Request-Id

    string

    The server stores keys for 45 days. For more information about PayPal-Request-Id, see PayPal-Request-Id.
  • Prefer

    string

    The preferred server response upon successful completion of the request. Value is:
    • return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.
    • return=representation. The server returns a complete resource representation, including the current state of the resource.

    Default: return=minimal.

  • 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.

    Default: false.

  • payment_instruction

    object

    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, 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 captured payment.

    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.

  • 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.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

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. You can reauthorize a payment only once from days four to 29.

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

For more information about HTTP request headers, see HTTP request headers.
  • PayPal-Request-Id

    string

    The server stores keys for 45 days. For more information about PayPal-Request-Id, see PayPal-Request-Id.
  • Prefer

    string

    The preferred server response upon successful completion of the request. Value is:
    • return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.
    • return=representation. The server returns a complete resource representation, including the current state of the resource.

    Default: return=minimal.

  • 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.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, 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.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

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

For more information about HTTP request headers, see HTTP request headers.
  • 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.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

For more information about HTTP request headers, see HTTP request headers.
  • 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.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 captured payment.

    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.

  • 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"
    }
  },
  "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

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

For more information about HTTP request headers, see HTTP request headers.
  • PayPal-Request-Id

    string

    The server stores keys for 45 days. For more information about PayPal-Request-Id, see PayPal-Request-Id.
  • Prefer

    string

    The preferred server response upon successful completion of the request. Value is:
    • return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.
    • return=representation. The server returns a complete resource representation, including the current state of the resource.

    Default: return=minimal.

  • 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.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, 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.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

GET /v2/payments/refunds/{refund_id}
Shows details for a refund, by ID.

Header parameters

For more information about HTTP request headers, see HTTP request headers.
  • 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.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, 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.paypal.com/v2/payments/refunds/1JU08902781691411"
    },
    {
      "rel": "up",
      "method": "GET",
      "href": "https://api.paypal.com/v2/payments/captures/2GG279541U471931P"
    }
  ]
}

Common object definitions

activity_timestamps

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.
  • shipping

    object

    The shipping fee for all items within a given purchase_unit.
  • handling

    object

    The handling fee for all items within a given purchase_unit.
  • 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.
  • insurance

    object

    The insurance fee for all items within a given purchase_unit.
  • shipping_discount

    object

    The shipping discount for all items within a given purchase_unit.
  • discount

    object

    The discount for all items within a given purchase_unit.

authorization

  • status

    enum

    The status for the authorized payment. The possible values are:
    • CREATED. The authorized payment is created. No captured payments have been made for this authorized payment.
    • CAPTURED. The authorized payment has one or more captures against it. The sum of these captured payments is greater than the amount of the original authorized payment.
    • DENIED. PayPal cannot authorize funds for this authorized payment.
    • EXPIRED. The authorized payment has expired.
    • PARTIALLY_CAPTURED. A captured payment was made for the authorized payment for an amount that is less than the amount of the original authorized payment.
    • VOIDED. The authorized payment was voided. No more captured payments can be made against this authorized payment.
    • 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.

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, 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.

capture

  • status

    enum

    The status of the captured payment. The possible values are:
    • COMPLETED. The funds for this captured payment were credited to the payee's PayPal account.
    • DECLINED. The funds could not be captured.
    • PARTIALLY_REFUNDED. An amount less than this captured payment's amount was partially refunded to the payer.
    • PENDING. The funds for this captured payment was not yet credited to the payee's PayPal account. For more information, 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 captured payment.

    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.

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.
  • 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.

    Default: false.

  • payment_instruction

    object

    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, 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.

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

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})$.

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.

    Default: INSTANT.

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])+)\]).

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.

    Default: body.

  • 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.

    Read only.

  • target_currency

    string

    The target currency to which to convert an amount.

    Read only.

  • 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.

    Read only.

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

  • 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

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}$.

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.

    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.

    Default: INSTANT.

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.

reauthorize_request

  • amount

    object

    The amount to reauthorize for an authorized payment.

refund

  • status

    enum

    The status of the capture. The possible values are:
    • CANCELLED. The refund was cancelled.
    • PENDING. The refund is pending. For more information, 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.

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 capture. 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.

    Read only.

  • 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.

    Read only.

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

    The amount for this captured payment.

    Read only.

  • paypal_fee

    object

    The applicable fee for this captured payment.

    Read only.

  • 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.

    Read only.

  • 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.

    Read only.

  • 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.

    Read only.

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.

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.

  • AUTH_CAPTURE_CURRENCY_MISMATCH

    Currency of capture must be the same as currency of authorization.
    Verify the currency of the capture and try the request again.

  • AUTHENTICATION_FAILURE

    Authentication failed due to missing authorization header, or invalid authentication credentials.
    Account validations failed for the user.

  • AUTHORIZATION_ALREADY_CAPTURED

    Authorization has already been captured.
    If final_capture is set to to true, additional captures are not possible against the authorization.

  • AUTHORIZATION_DENIED

    A denied authorization cannot be captured.
    You cannot capture a denied authorization.

  • AUTHORIZATION_EXPIRED

    An expired authorization cannot be captured.
    You cannot capture an expired authorization.

  • AUTHORIZATION_VOIDED

    A voided authorization cannot be captured or reauthorized.
    You cannot capture or reauthorize a voided authorization.

  • CANNOT_BE_ZERO_OR_NEGATIVE

    Must be greater than zero. If the currency supports decimals, only two decimal place precision is supported.
    Specify a different value and try the request again.

  • CANNOT_BE_VOIDED

    A reauthorization cannot be voided. Please void the original parent authorization.
    You cannot void a reauthorized payment. You must void the original parent authorized payment.

  • REFUND_NOT_PERMITTED_DUE_TO_CHARGEBACK

    The requested action could not be performed, semantically incorrect, or failed business validation.
    Refunds not allowed on this capture due to a chargeback on the card or bank. Please contact the payee to resolve the chargeback.

  • CAPTURE_DISPUTED_PARTIAL_REFUND_NOT_ALLOWED

    The requested action could not be performed, semantically incorrect, or failed business validation.
    Refund for an amount less than the remaining transaction amount cannot be processed at this time because of an open dispute on the capture. Please visit the PayPal Resolution Center to view the details.

  • CAPTURE_FULLY_REFUNDED

    The capture has already been fully refunded.
    You cannot capture additional refunds against this capture.

  • DECIMAL_PRECISION

    The value of the field should not be more than two decimal places.
    If the currency supports decimals, only two decimal place precision is supported.

  • DECIMALS_NOT_SUPPORTED

    Currency does not support decimals.
    Currency does not support decimals. Please refer to https://developer.paypal.com/docs/integration/direct/rest/currency-codes/ for more information.

  • DUPLICATE_INVOICE_ID

    Requested invoice number has been previously captured. Possible duplicate transaction.
    Payment for this invoice was already captured.

  • INVALID_ACCOUNT_STATUS

    Account validations failed for the user.
    The user account could not be validated.

  • INTERNAL_SERVER_ERROR

    An internal server error has occurred.
    Try your request again later.

  • INVALID_CURRENCY_CODE

    Currency code should be a three-character ISO-4217 currency code.
    Currency code is invalid or is not currently supported. Please refer https://developer.paypal.com/docs/integration/direct/rest/currency-codes/ for list of supported currency codes.

  • INVALID_PARAMETER_SYNTAX

    The value of the field does not conform to the expected format.
    Verify the specification for supported pattern and try the request again.

  • INVALID_PARAMETER_VALUE

    The value of a field is invalid.
    Verify the specification for the allowed values and try the request again.

  • INVALID_PAYEE_ACCOUNT

    Payee account is invalid.
    Verify the payee account information and try the request again.

  • INVALID_PLATFORM_FEES_AMOUNT

    The platform_fees amount cannot be greater than the capture amount.
    Verify the platform_fees amount and try the request again.

  • INVALID_RESOURCE_ID

    Specified resource ID does not exist. Please check the resource ID and try again.
    Verify the resource ID and try the request again.

  • INVALID_STRING_LENGTH

    The value of a field is either too short or too long.
    Verify the specification for the supported min and max values and try the request again.

  • INVALID_STRING_MAX_LENGTH

    The value of a field is too long.
    The parameter string 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.
    Specify a different amount and try the request again. Alternately, contact Customer Support to increase your limits.

  • 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.
    You cannot make additional captures.

  • MAX_NUMBER_OF_REFUNDS_EXCEEDED

    You have exceeded the number of refunds that can be processed per capture.
    Please contact customer support or your account manager to review the number of refunds that can be processed per capture.

  • MISSING_REQUIRED_PARAMETER

    A required field / parameter is missing.
    Verify the specification for required fields and try the request again.

  • NOT_AUTHORIZED

    You do not have permission to access or perform operations on this resource.
    To make API calls on behalf of a merchant, ensure that you have sufficient permissions to proceed with this transaction.

  • PARTIAL_REFUND_NOT_ALLOWED

    You cannot do a refund for an amount less than the original capture amount.
    Specify an amount equal to the capture amount or omit the amount object from the request. Then, try the request again.

  • PAYEE_ACCOUNT_LOCKED_OR_CLOSED

    Transaction could not complete because payee account is locked or closed.
    To get more information about the status of the account, call Customer Support.

  • PAYEE_ACCOUNT_RESTRICTED

    Payee account is restricted.
    To get more information about the status of the account, call Customer Support.

  • PAYER_ACCOUNT_LOCKED_OR_CLOSED

    The payer account cannot be used for this transaction.
    Contact the payer for an alternate payment method.

  • PAYER_CANNOT_PAY

    Payer cannot pay for this transaction. Please contact the payer to find other ways to pay for this transaction.
    Verify that the merchant account does not define rules that automatically decline payments from certain types of payers.

  • PENDING_CAPTURE

    Cannot initiate a refund as the capture is pending.
    Capture is typically pending when the payer has funded the transaction by using an e-check or bank account.

  • PERMISSION_DENIED

    You do not have permission to access or perform operations on this resource.
    To make API calls on behalf of a merchant, ensure that you have sufficient permissions to proceed with this transaction.

  • PERMISSION_NOT_GRANTED

    Payee of the authorization has not granted permission to perform capture on the authorization.
    To make API calls on behalf of a merchant, ensure that you have sufficient permissions to capture the authorization.

  • PREVIOUSLY_CAPTURED

    Authorization has been previously captured and hence cannot be voided.
    This authorized payment was already captured. You cannot capture it again.

  • PREVIOUSLY_VOIDED

    Authorization has been previously voided and hence cannot be voided again.
    This authorized payment was already voided. You cannot void it again.

  • REFUND_AMOUNT_EXCEEDED

    The refund amount must be less than or equal to the capture amount that has not yet been refunded.
    Verify the refund amount and try the request again.

  • REFUND_CAPTURE_CURRENCY_MISMATCH

    Refund must be in the same currency as the capture.
    Verify the currency of the refund and try the request again.

  • REFUND_FAILED_INSUFFICIENT_FUNDS

    Capture could not be refunded due to insufficient funds.
    Verify that either you have sufficient funds in your PayPal account or the bank account that is linked to your PayPal account is verified and has sufficient funds.

  • REFUND_NOT_ALLOWED

    Full refund refused - partial refund has already been done on this payment.
    You cannot refund this capture.

  • REFUND_TIME_LIMIT_EXCEEDED

    You are over the time limit to perform a refund on this capture.
    The refund cannot be issued at this time.

  • TRANSACTION_REFUSED

    PayPal's internal controls prevent authorization from being captured.
    For more information about this transaction, contact customer support.

Popular Search Queries
PayPal Help
FAQ's

FAQ's
Forum

Tech Support Community
PayPal Community