RefundPayment

POST 
/v1/refund/orders

Refunds a payment, by ID. For a full refund, include an empty refund units in the JSON request body. For a partial refund, include an refund units in the JSON request body.

Request

application/json

Body

required

origin_id

object

origin_order_id string

ID of the origin order.

origin_reference_id string

Outside reference number of the origin order.

reference_id string

non-empty

Outside reference number of the refund order.

refund_units

object[]

>= 1

An array of refund units. Each refund unit establishes a contract between a payer and the payee. Each refund unit represents amount to be refund.

Array [

origin_reference_id string

The API caller-provided external ID for the origin order unit.

reference_id string

The API caller-provided external ID for the refund unit.

amount

object

currency_code string

The three-character ISO-4217 currency code that identifies the currency. see: https://en.wikipedia.org/wiki/ISO_4217#Active_codes

value string

Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

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.

description string

<= 1000 characters

The refund description.

refund_reference string

The refund reference.

amount_with_breakdown

object

currency_code string

The three-character ISO-4217 currency code that identifies the currency.see: https://en.wikipedia.org/wiki/ISO_4217#Active_codes

value string

Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

The value as the summary of all kinds of total_amount in breakdown, 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.

breakdown

object

tax_total

object

currency_code string

The three-character ISO-4217 currency code that identifies the currency. see: https://en.wikipedia.org/wiki/ISO_4217#Active_codes

value string

Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

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.

taxes

object[]

The tax with breakdown

Array [

tax_type enum

[UNKNOWN, ECOMMERCE_CONSUMPTION_TAX]

tax type

tax_name string

non-empty

tax name

tax_rate string

Tax as a percentage of total amount example: value 8 means the tax as a percentage of total amount is 8%

tax_amount

object

currency_code string

The three-character ISO-4217 currency code that identifies the currency. see: https://en.wikipedia.org/wiki/ISO_4217#Active_codes

value string

Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

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.

]

tax_reference string

tax reference

item_total

object

currency_code string

The three-character ISO-4217 currency code that identifies the currency. see: https://en.wikipedia.org/wiki/ISO_4217#Active_codes

value string

Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

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.

tax_check_mode enum

[UNKNOWN, TOTAL_AMOUNT, ITEM_AMOUNT]

Tax check mode, check tax by total amount or item amount. If merchant use payment_method=CHECKOUT_PAGE, this field is optional, and no need present tax_check_mode, tax_total of breakdown, taxes of breakdown. Otherwise, this field is required, and merchant should present tax_check_mode, tax_total of breakdown, taxes of breakdown.

tax_mode enum

[UNKNOWN, TAX_INCLUSIVE, TAX_EXCLUSIVE, NOT_TAX, TAX_DELAY]

tax mode This field is provided by system, merchant should not set it.

discount_display

object

currency_code string

The three-character ISO-4217 currency code that identifies the currency. see: https://en.wikipedia.org/wiki/ISO_4217#Active_codes

value string

Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

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.

remaining_discount_display

object

currency_code string

The three-character ISO-4217 currency code that identifies the currency. see: https://en.wikipedia.org/wiki/ISO_4217#Active_codes

value string

Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

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.

before_discount_display

object

currency_code string

The three-character ISO-4217 currency code that identifies the currency. see: https://en.wikipedia.org/wiki/ISO_4217#Active_codes

value string

Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

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.

]

refund_reason string

<= 128 characters

refund reason

webhook_url uri

The URL where the merchant receive the refund event after the order updated.

merchant_id string

<= 64 characters

The id of merchant. If empty, defaults to the merchant_id of the signature authentication

metadata

object

The additional data.

property name* string

Responses

200

OK

application/json

Response

Response

create_time string

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

The date and time when the transaction occurred, in Internet date and time format. see: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6

update_time string

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

The date and time when the transaction was last updated, in Internet date and time format see: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6

id string

The refund id of the order.

status enum

[UNKNOWN, CREATED, SAVED, APPROVED, VOIDED, COMPLETED, PAYER_ACTION_REQUIRED, REFUNDING, REFUNDED, CAPTURE_REQUIRED, CAPTURE_FAILED, REFUND_REVERSED, CHARGEBACK, CHARGEBACK_REVERSED, SECOND_CHARGEBACK, ...]

The order status. Deprecated: use refund_status to instead this status

... an additional 9 values ›

refund_units

object[]

An array of refund units. Each refund unit establishes a contract between a payer and the payee. Each refund unit represents amount to be refund.

Array [

origin_reference_id string

The API caller-provided external ID for the origin order unit.

reference_id string

The API caller-provided external ID for the refund unit.

amount

object

currency_code string

The three-character ISO-4217 currency code that identifies the currency. see: https://en.wikipedia.org/wiki/ISO_4217#Active_codes

value string

Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

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.

description string

<= 1000 characters

The refund description.

refund_reference string

The refund reference.

amount_with_breakdown

object

currency_code string

The three-character ISO-4217 currency code that identifies the currency.see: https://en.wikipedia.org/wiki/ISO_4217#Active_codes

value string

Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

The value as the summary of all kinds of total_amount in breakdown, 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.

breakdown

object

tax_total

object

currency_code string

The three-character ISO-4217 currency code that identifies the currency. see: https://en.wikipedia.org/wiki/ISO_4217#Active_codes

value string

Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

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.

taxes

object[]

The tax with breakdown

Array [

tax_type enum

[UNKNOWN, ECOMMERCE_CONSUMPTION_TAX]

tax type

tax_name string

non-empty

tax name

tax_rate string

Tax as a percentage of total amount example: value 8 means the tax as a percentage of total amount is 8%

tax_amount

object

currency_code string

The three-character ISO-4217 currency code that identifies the currency. see: https://en.wikipedia.org/wiki/ISO_4217#Active_codes

value string

Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

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.

]

tax_reference string

tax reference

item_total

object

currency_code string

The three-character ISO-4217 currency code that identifies the currency. see: https://en.wikipedia.org/wiki/ISO_4217#Active_codes

value string

Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

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.

tax_check_mode enum

[UNKNOWN, TOTAL_AMOUNT, ITEM_AMOUNT]

Tax check mode, check tax by total amount or item amount. If merchant use payment_method=CHECKOUT_PAGE, this field is optional, and no need present tax_check_mode, tax_total of breakdown, taxes of breakdown. Otherwise, this field is required, and merchant should present tax_check_mode, tax_total of breakdown, taxes of breakdown.

tax_mode enum

[UNKNOWN, TAX_INCLUSIVE, TAX_EXCLUSIVE, NOT_TAX, TAX_DELAY]

tax mode This field is provided by system, merchant should not set it.

discount_display

object

currency_code string

The three-character ISO-4217 currency code that identifies the currency. see: https://en.wikipedia.org/wiki/ISO_4217#Active_codes

value string

Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

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.

remaining_discount_display

object

currency_code string

The three-character ISO-4217 currency code that identifies the currency. see: https://en.wikipedia.org/wiki/ISO_4217#Active_codes

value string

Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

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.

before_discount_display

object

currency_code string

The three-character ISO-4217 currency code that identifies the currency. see: https://en.wikipedia.org/wiki/ISO_4217#Active_codes

value string

Value must match regular expression ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

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.

]

refund_status enum

[UNKNOWN, REFUND_REJECTED, REFUND_REVIEWING, REFUND_REVIEW_REJECTED, REFUNDING, REFUNDED, REFUND_FAILED]

The refund order status

status_detail

object

The error struct contains name and message

name string

Value must match regular expression [A-Z0-9_]+

Name of the error.

message string

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.

details

object[]

A list of messages that carry the error details. There is a common set of message types for APIs to use.

Array [

@type string

The type of the serialized message.

]

links

object[]

Links is for help

Array [

description string

Describes what the link offers.

url uri

The URL of the link.

]

metadata

object

The addition data

property name* string

Example

{
  "create_time": "string",
  "update_time": "string",
  "id": "string",
  "status": "UNKNOWN",
  "refund_units": [
    {
      "origin_reference_id": "string",
      "reference_id": "string",
      "amount": {
        "currency_code": "string",
        "value": "string"
      },
      "description": "string",
      "refund_reference": "string",
      "amount_with_breakdown": {
        "currency_code": "string",
        "value": "string",
        "breakdown": {
          "tax_total": {
            "currency_code": "string",
            "value": "string"
          },
          "taxes": [
            {
              "tax_type": "UNKNOWN",
              "tax_name": "string",
              "tax_rate": "string",
              "tax_amount": {
                "currency_code": "string",
                "value": "string"
              }
            }
          ],
          "tax_reference": "string",
          "item_total": {
            "currency_code": "string",
            "value": "string"
          }
        },
        "tax_check_mode": "UNKNOWN",
        "tax_mode": "UNKNOWN",
        "discount_display": {
          "currency_code": "string",
          "value": "string"
        },
        "remaining_discount_display": {
          "currency_code": "string",
          "value": "string"
        },
        "before_discount_display": {
          "currency_code": "string",
          "value": "string"
        }
      }
    }
  ],
  "refund_status": "UNKNOWN",
  "status_detail": {
    "name": "string",
    "message": "string",
    "details": [
      {
        "@type": "string"
      }
    ],
    "links": [
      {
        "description": "string",
        "url": "string"
      }
    ]
  },
  "metadata": {}
}

default

Error response structure

application/json

Response

Response

name string
message string

details

object[]

Array [

@type string

The type of the serialized message.

]

debug_id string

causes

object[]

Array [

cause string

solution string

]

Example

{
  "name": "string",
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ],
  "debug_id": "string",
  "causes": [
    {
      "cause": "string",
      "solution": "string"
    }
  ]
}

Loading...