Skip to main content
POST
Refund a Payment of a payment order (v2)

Authorizations

x-api-key
string
header
required

API key for authentication (required)

x-merchant-id
string
header
required

Merchant ID for identifying the merchant (required)

Path Parameters

id
string<uuid>
required

Payment order ID

Body

application/json
amount
number
required

Refund amount in minor currency units (centavos): 5000 = $50.00 MXN. Must be a positive integer. Bounded per Payment by module-payment (cannot exceed that Payment's remaining capturable amount). Note: unlike the legacy v1 refund endpoint, which takes major units, v2 takes minor units.

Required range: x > 0
Example:

1000

reason
string

Optional free-text reason. Persisted on the order's refundReason field for auditing.

Example:

"customer requested"

paymentId
string<uuid>

Which Payment of the order to refund. Required when the order has allowPartials=true. For non-partial orders this can be omitted and the lone Payment is used.

Example:

"a0b0c9d4-6ce9-40e4-873a-e234c1d93639"

Response

Refund accepted by module-payment. The response is a snapshot of the resulting Payment-level refund — the order's aggregate status is materialized asynchronously by the consumer.

id
string<uuid>

Refund event id

status
string
Example:

"COMPLETED"

amount
string

Amount of THIS refund (smallest currency unit)

Example:

"100000"

refundedAmount
string

Cumulative refunded amount of the targeted Payment after this call

Example:

"100000"

paymentMethodType
string
Example:

"CARD"

createdAt
string<date-time>
updatedAt
string<date-time>