Show refund details

GET 
/refunds/:refund_id

Shows details for a refund, by ID.

Request

Path Parameters

refund_id stringrequired

The PayPal-generated ID for the refund for which to show details.

Header Parameters

Authorization stringrequired

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 stringrequired

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.

Responses

200

A successful request returns the HTTP 200 OK status code and a JSON response body that shows refund details.

application/json

Schema

Schema

object
status Refund Status With Details (string)

The status of the refund.

Possible values: [CANCELLED, FAILED, PENDING, COMPLETED]

status_details

object

The details of the refund status.

reason Refund Incomplete Reason (string)

The reason why the refund has the PENDING or FAILED status.

Possible values: [ECHECK]

id string

The PayPal-generated ID for the refund.

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.

Possible values: non-empty and <= 255 characters, Value must match regular expression ^[A-Za-z0-9-_.,]*$

acquirer_reference_number string

Reference ID issued for the card transaction. This ID can be used to track the transaction across processors, card brands and issuing banks.

Possible values: non-empty and <= 36 characters, Value must match regular expression ^[a-zA-Z0-9]+$

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.

platform_fees

object[]

An array of platform or partner fees, commissions, or brokerage fees for the refund.

Possible values: <= 1

Array [

amount

object

required

The fee for this transaction.

currency_code ppaas_common_currency_code_v2required

The three-character ISO-4217 currency code that identifies the currency.

Possible values: >= 3 characters and <= 3 characters

value stringrequired

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.

Possible values: <= 32 characters, Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

payee

object

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

email_address merchant_common_email_address_v2

The email address of merchant.

Possible values: >= 3 characters and <= 254 characters, Value must match regular expression (?:[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 ppaas_payer_id_v3

The encrypted PayPal account ID of the merchant.

Possible values: >= 13 characters and <= 13 characters, Value must match regular expression ^[2-9A-HJ-NP-Z]{13}$

]

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.

Array [

payable_amount

object

The net amount debited from the merchant's PayPal account.

currency_code ppaas_common_currency_code_v2required

The three-character ISO-4217 currency code that identifies the currency.

Possible values: >= 3 characters and <= 3 characters

value stringrequired

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.

Possible values: <= 32 characters, Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

converted_amount

object

The converted payable amount.

currency_code ppaas_common_currency_code_v2required

The three-character ISO-4217 currency code that identifies the currency.

Possible values: >= 3 characters and <= 3 characters

value stringrequired

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.

Possible values: <= 32 characters, Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

exchange_rate

object

The exchange rate that determines the amount that was debited from the merchant's PayPal account.

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.

source_currency ppaas_common_currency_code_v2

The source currency from which to convert an amount.

Possible values: >= 3 characters and <= 3 characters

target_currency ppaas_common_currency_code_v2

The target currency to which to convert an amount.

Possible values: >= 3 characters and <= 3 characters

]

gross_amount

object

The amount that the payee refunded to the payer.

currency_code ppaas_common_currency_code_v2required

The three-character ISO-4217 currency code that identifies the currency.

Possible values: >= 3 characters and <= 3 characters

value stringrequired

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.

Possible values: <= 32 characters, Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

paypal_fee

object

The PayPal fee that was refunded to the payer in the currency of the transaction. This fee might not match the PayPal fee that the payee paid when the payment was captured.

currency_code ppaas_common_currency_code_v2required

The three-character ISO-4217 currency code that identifies the currency.

Possible values: >= 3 characters and <= 3 characters

value stringrequired

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.

Possible values: <= 32 characters, Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

paypal_fee_in_receivable_currency

object

The PayPal fee that was refunded to the payer in the receivable currency. Returned only in cases when the receivable currency is different from transaction currency. Example 'CNY'.

currency_code ppaas_common_currency_code_v2required

The three-character ISO-4217 currency code that identifies the currency.

Possible values: >= 3 characters and <= 3 characters

value stringrequired

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.

Possible values: <= 32 characters, Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

net_amount

object

The net amount that the payee's account is debited in the transaction currency. The net amount is calculated as gross_amount minus paypal_fee minus platform_fees.

currency_code ppaas_common_currency_code_v2required

The three-character ISO-4217 currency code that identifies the currency.

Possible values: >= 3 characters and <= 3 characters

value stringrequired

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.

Possible values: <= 32 characters, Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

net_amount_in_receivable_currency

object

The net amount that the payee's account is debited in the receivable currency. Returned only in cases when the receivable currency is different from transaction currency. Example 'CNY'.

currency_code ppaas_common_currency_code_v2required

The three-character ISO-4217 currency code that identifies the currency.

Possible values: >= 3 characters and <= 3 characters

value stringrequired

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.

Possible values: <= 32 characters, Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

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.

currency_code ppaas_common_currency_code_v2required

The three-character ISO-4217 currency code that identifies the currency.

Possible values: >= 3 characters and <= 3 characters

value stringrequired

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.

Possible values: <= 32 characters, Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

links

object[]

An array of related HATEOAS links.

Array [

href stringrequired

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 stringrequired

The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.

method string

The HTTP method required to make the related call.

Possible values: [GET, POST, PUT, DELETE, HEAD, CONNECT, OPTIONS, PATCH]

]

amount

object

The amount that the payee refunded to the payer.

currency_code ppaas_common_currency_code_v2required

The three-character ISO-4217 currency code that identifies the currency.

Possible values: >= 3 characters and <= 3 characters

value stringrequired

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.

Possible values: <= 32 characters, Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

payer

object

The details associated with the merchant for this transaction.

email_address merchant_common_email_address_v2

The email address of merchant.

Possible values: >= 3 characters and <= 254 characters, Value must match regular expression (?:[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 ppaas_payer_id_v3

The encrypted PayPal account ID of the merchant.

Possible values: >= 13 characters and <= 13 characters, Value must match regular expression ^[2-9A-HJ-NP-Z]{13}$

create_time ppaas_date_time_v3

The date and time when the transaction occurred, in Internet date and time format.

Possible values: >= 20 characters and <= 64 characters, Value must match regular expression ^[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})$

update_time ppaas_date_time_v3

The date and time when the transaction was last updated, in Internet date and time format.

Possible values: >= 20 characters and <= 64 characters, Value must match regular expression ^[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})$

Example (from schema)

{
  "status": "CANCELLED",
  "status_details": {
    "reason": "ECHECK"
  },
  "id": "string",
  "invoice_id": "string",
  "custom_id": "string",
  "acquirer_reference_number": "string",
  "note_to_payer": "string",
  "seller_payable_breakdown": {
    "platform_fees": [
      {
        "amount": {
          "currency_code": "string",
          "value": "string"
        },
        "payee": {
          "email_address": "string",
          "merchant_id": "string"
        }
      }
    ],
    "net_amount_breakdown": [
      {
        "payable_amount": {
          "currency_code": "string",
          "value": "string"
        },
        "converted_amount": {
          "currency_code": "string",
          "value": "string"
        },
        "exchange_rate": {
          "value": "string",
          "source_currency": "string",
          "target_currency": "string"
        }
      }
    ],
    "gross_amount": {
      "currency_code": "string",
      "value": "string"
    },
    "paypal_fee": {
      "currency_code": "string",
      "value": "string"
    },
    "paypal_fee_in_receivable_currency": {
      "currency_code": "string",
      "value": "string"
    },
    "net_amount": {
      "currency_code": "string",
      "value": "string"
    },
    "net_amount_in_receivable_currency": {
      "currency_code": "string",
      "value": "string"
    },
    "total_refunded_amount": {
      "currency_code": "string",
      "value": "string"
    }
  },
  "links": [
    {
      "href": "string",
      "rel": "string",
      "method": "GET"
    }
  ],
  "amount": {
    "currency_code": "string",
    "value": "string"
  },
  "payer": {
    "email_address": "string",
    "merchant_id": "string"
  },
  "create_time": "string",
  "update_time": "string"
}

401

Authentication failed due to missing authorization header, or invalid authentication credentials.

application/json

Schema

Schema

name stringrequired

The human-readable, unique name of the error.

message stringrequired

The message that describes the error.

debug_id stringrequired

The PayPal internal ID. Used for correlation purposes.

details object[]

An array of additional details about the error.

links object[]

An array of request-related HATEOAS links.

Example (from schema)

{
  "name": "string",
  "message": "string",
  "debug_id": "string",
  "details": [
    {
      "field": "string",
      "value": "string",
      "location": "body",
      "issue": "string",
      "links": [
        {
          "href": "string",
          "rel": "string",
          "method": "GET"
        }
      ],
      "description": "string"
    }
  ],
  "links": [
    {
      "href": "string",
      "rel": "string",
      "method": "GET"
    }
  ]
}

403

The request failed because the caller has insufficient permissions.

application/json

Schema

Schema

name stringrequired

The human-readable, unique name of the error.

message stringrequired

The message that describes the error.

debug_id stringrequired

The PayPal internal ID. Used for correlation purposes.

details object[]

An array of additional details about the error.

links object[]

An array of request-related HATEOAS links.

Example (from schema)

{
  "name": "string",
  "message": "string",
  "debug_id": "string",
  "details": [
    {
      "field": "string",
      "value": "string",
      "location": "body",
      "issue": "string",
      "links": [
        {
          "href": "string",
          "rel": "string",
          "method": "GET"
        }
      ],
      "description": "string"
    }
  ],
  "links": [
    {
      "href": "string",
      "rel": "string",
      "method": "GET"
    }
  ]
}

404

The request failed because the resource does not exist.

application/json

Schema

Schema

name stringrequired

The human-readable, unique name of the error.

message stringrequired

The message that describes the error.

debug_id stringrequired

The PayPal internal ID. Used for correlation purposes.

details object[]

An array of additional details about the error.

links object[]

An array of request-related HATEOAS links.

Example (from schema)

{
  "name": "string",
  "message": "string",
  "debug_id": "string",
  "details": [
    {
      "field": "string",
      "value": "string",
      "location": "body",
      "issue": "string",
      "links": [
        {
          "href": "string",
          "rel": "string",
          "method": "GET"
        }
      ],
      "description": "string"
    }
  ],
  "links": [
    {
      "href": "string",
      "rel": "string",
      "method": "GET"
    }
  ]
}

500

The request failed because an internal server error occurred.

default

The error response.

application/json

Schema

Schema

name stringrequired

The human-readable, unique name of the error.

message stringrequired

The message that describes the error.

debug_id stringrequired

The PayPal internal ID. Used for correlation purposes.

details object[]

An array of additional details about the error.

links object[]

An array of request-related HATEOAS links.

Example (from schema)

{
  "name": "string",
  "message": "string",
  "debug_id": "string",
  "details": [
    {
      "field": "string",
      "value": "string",
      "location": "body",
      "issue": "string",
      "links": [
        {
          "href": "string",
          "rel": "string",
          "method": "GET"
        }
      ],
      "description": "string"
    }
  ],
  "links": [
    {
      "href": "string",
      "rel": "string",
      "method": "GET"
    }
  ]
}

Loading...