> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.
# Refund Payment (two cards)
> Refunds one card of a two-card payment, fully or partially, using that card's transaction id.
This request refunds one card of a payment created with [Create Payment (two cards)](https://docs.y.uno/reference/payments/create-payment-v2.md). Refund is per card: send the `id` of that card's `PURCHASE` or `CAPTURE` transaction from `payment_method.payment_methods[].transactions`.
If you omit `amount`, the card is refunded in full. A refund on a card is capped at that card's amount minus what was already refunded on it. After one card is refunded, the payment is `SUCCEEDED / PARTIALLY_REFUNDED`; after both, it is `REFUNDED / REFUNDED`. The response is `201` with the payment in the v2 shape.
> [!WARNING]
>
> While a card has an open chargeback, refunds are rejected with `INVALID_STATUS`.
This request requires an `X-Idempotency-Key`. See [Authentication](https://docs.y.uno/reference/getting-started/authentication.md#idempotency) for details.
## OpenAPI
````yaml openapi/payments/refund-payment-v2.json POST /payments/{payment_id}/transactions/{transaction_id}/refund
openapi: 3.1.0
info:
title: payments-v2
version: 2.0.0
servers:
- url: https://api-sandbox.y.uno/v2
description: Sandbox
- url: https://api.y.uno/v2
description: Production (US)
- url: https://api.eu.y.uno/v2
description: Production (EMEA)
security:
- sec0: []
sec1: []
paths:
/payments/{payment_id}/transactions/{transaction_id}/refund:
post:
summary: Refund Payment (two cards)
description: >-
Refunds one card, fully or partially. The refund is capped at that
card's amount minus what was already refunded on it.
operationId: refund-payment-v2
parameters:
- name: X-Idempotency-Key
in: header
required: true
description: >-
Unique key for this request. Required on every v2 payment request.
Retry an unclear outcome with the same key. Without it the request
is rejected with `400 INVALID_PARAMETERS`: "The header
'x-idempotency-key' is required."
schema:
type: string
format: uuid
- name: payment_id
in: path
required: true
description: The `id` of the payment returned by `POST /v2/payments`.
schema:
type: string
format: uuid
- name: transaction_id
in: path
required: true
description: >-
The `id` of the card transaction to operate on, from
`payment_method.payment_methods[].transactions[]`.
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
type: object
required:
- merchant_reference
properties:
description:
type: string
description: Description of the refund. (MAX 255; MIN 3).
reason:
type: string
description: >-
Reason for the operation. Possible values are `DUPLICATE`,
`FRAUDULENT` and `REQUESTED_BY_CUSTOMER`.
enum:
- DUPLICATE
- FRAUDULENT
- REQUESTED_BY_CUSTOMER
merchant_reference:
type: string
description: >-
Identification of the payment transaction defined by the
merchant (MAX 255; MIN 3).
amount:
type: object
description: >-
Optional. Amount to refund on this card. If you omit it, the
card is refunded in full.
required:
- currency
- value
properties:
currency:
type: string
description: ISO 4217 currency code (3 characters).
example: BRL
value:
type: number
description: Amount in major units (multiple of 0.0001).
example: 300
customer_payer:
type: object
description: Specifies customer object for payments.
properties:
first_name:
type: string
description: The customer's first name (MAX 255; MIN 3).
last_name:
type: string
description: The customer's last name (MAX 255; MIN 3).
gender:
type: string
description: >-
The customer's gender (MAX 2; MIN 1).
- M=Male
- F=Female
- NB=Non Binary
- NA=Not
applicable
- NK=Not Known
- U=Undefined.
enum:
- M
- F
- NB
- NA
- NK
- U
date_of_birth:
type: string
description: >-
The customer's date of birth in the `YYYY-MM-DD` format
(Length: 10).
email:
type: string
description: The customer's e-mail (MAX 255; MIN 3).
nationality:
type: string
description: >-
The customer's nationality (MAX 2; MIN 2; [ISO
3166-1](/reference/country-reference)).
document:
type: object
description: >-
Specifies the customer's document object, including its
number and type.
required:
- document_number
- document_type
properties:
document_number:
type: string
description: Document number for customer (MAX 40; MIN 3)
document_type:
type: string
description: >-
The customer's document type (MAX 6, MIN 2). Access
[Document Type List](/reference/country-reference)
for more details.
enum:
- DNI
- CI
- LC
- LE
- CUIT
- CUIL
- PAS
- CPF
- RG
- CNH
- CNPJ
- RUT
- RUN
- CC
- CE
- NIT
- DUI
- PIC
- DPI
- IFR
- INE
- CP
- RFC
- CURP
- CIP
- CIC
- CUI
- RUC
phone:
type: object
description: Specifies the customer's phone object.
properties:
country_code:
type: string
description: >-
The country code of the customer's phone (MAX 3; MIN
1).
number:
type: string
description: >-
The customer's phone number, without the country
code (MAX 32; MIN 1).
billing_address:
type: object
description: Specifies the customer's billing address object.
properties:
address_line_1:
type: string
description: >-
The primary billing address line of the customer
(MAX 255; MIN 3).
address_line_2:
type: string
description: >-
The secondary billing address line of the customer
(MAX 255; MIN 3).
city:
type: string
description: >-
The city considered for the billing address (MAX
255; MIN 3).
country:
type: string
description: >-
The country considered for the billing address (MAX
2; MIN 2; [ISO
3166-1](https://docs.y.uno/reference/customer-object#country-code-list-iso-3166-1)).
enum:
- AR
- BO
- BR
- CL
- CO
- CR
- EC
- SV
- GT
- HN
- MX
- NI
- PA
- PY
- PE
- US
- UY
state:
type: string
description: >-
The state considered for the billing address (MAX
255; MIN 3).
zip_code:
type: string
description: >-
The zipcode considered for the billing address (MAX
10; MIN 5).
shipping_address:
type: object
description: Specifies the customer's shipping address object.
properties:
address_line_1:
type: string
description: >-
The primary shipping address line of the customer
(MAX 255; MIN 3).
address_line_2:
type: string
description: >-
The secondary shipping address line of the customer
(MAX 255; MIN 3).
city:
type: string
description: >-
The city considered for the shipping address (MAX
255; MIN 3).
country:
type: string
description: >-
The country considered for the shipping address (MAX
2; MIN 2; [ISO
3166-1](https://docs.y.uno/reference/customer-object#country-code-list-iso-3166-1)).
enum:
- AR
- BO
- BR
- CL
- CO
- CR
- EC
- SV
- GT
- HN
- MX
- NI
- PA
- PY
- PE
- US
- UY
state:
type: string
description: >-
The state considered for the shipping address (MAX
255; MIN 3).
zip_code:
type: string
description: >-
The zipcode considered for the shipping address (MAX
10; MIN 5).
payment_method:
type: object
description: Specifies payment method object for payments.
properties:
detail:
type: object
description: Specifies the payment method detail object.
properties:
bank_transfer:
type: object
description: Specifies bank transfer payment method details.
properties:
account_type:
type: string
description: Type of bank account (MAX 255; MIN 3)
enum:
- CHECKINGS
- SAVINGS
bank_name:
type: string
description: Name of the bank (MAX 255; MIN 3)
bank_id:
type: string
description: ID of the bank (MAX 255; MIN 3)
beneficiary_name:
type: string
description: Name of the account holder (MAX 255; MIN 3)
bank_account:
type: string
description: Bank account number (MAX 255; MIN 3)
beneficiary_document_type:
type: string
description: >-
Document type of the account holder (MAX 255;
MIN 3)
beneficiary_document:
type: string
description: >-
Document number of the account holder (MAX 255;
MIN 3)
reference:
type: string
description: Reference code for the user (MAX 255; MIN 1)
bank_account_mask_number:
type: string
description: >-
Masked bank account number associated with the
bank transfer (for example, ****6789). This is
account data, not mandate data.
mandate:
type: object
description: >-
Direct debit mandate details, for bank transfer
methods that operate with mandates (for example,
ACH, SEPA, BACS, PAD).
properties:
id:
type: string
description: >-
Mandate identifier, as provided by the
payment provider.
info:
type: string
description: Free-text mandate information.
received_status:
type: string
description: >-
Provider status indicating whether the
mandate was received. Forwarded as provided
by the payment provider.
existing_status:
type: string
description: >-
Provider status of the existing mandate.
Forwarded as provided by the payment
provider.
created_at:
type: string
format: date-time
description: >-
Date and time when the mandate was created
(ISO 8601).
updated_at:
type: string
format: date-time
description: >-
Date and time when the mandate was last
updated (ISO 8601).
responses:
'201':
description: The payment after the operation, in the v2 shape
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentV2'
examples:
One card refunded:
value:
id: 7c1b6e2a-5f3d-4a8e-9b21-3e4f5a6b7c8d
account_id: 493e9374-510a-4201-9e09-de669d75f256
description: Order paid with two cards
country: BR
status: SUCCEEDED
sub_status: PARTIALLY_REFUNDED
merchant_order_id: order-10045
created_at: '2026-10-27T14:02:11.120Z'
updated_at: '2026-10-27T14:02:12.300Z'
split_payment_methods: true
payment_methods_count: 2
sdk_action_required: false
amount:
currency: BRL
value: 300
checkout:
session: null
payment_method:
capture: true
account_updater: false
payment_methods:
- sequence: 1
type: CARD
amount:
currency: BRL
value: 200
transactions:
- id: d2a4f6b8-1c3e-4a5b-8d7f-9e0a1b2c3d4e
type: PURCHASE
status: SUCCEEDED
category: CARD
amount: 200
provider_id: YUNO_TEST_PAYMENT_GATEWAY
response_code: SUCCEEDED
response_message: Transaction successful
reason: null
description: null
merchant_reference: null
three_d_secure_action_required: false
created_at: '2026-10-27T14:02:11.402Z'
updated_at: '2026-10-27T14:02:12.118Z'
- id: b6e8d0f2-5a7c-4e9f-8b1d-3c4d5e6f7a8b
type: REFUND
status: SUCCEEDED
category: CARD
amount: 200
provider_id: YUNO_TEST_PAYMENT_GATEWAY
response_code: SUCCEEDED
response_message: Transaction successful
reason: null
description: null
merchant_reference: null
three_d_secure_action_required: false
created_at: '2026-10-27T14:02:11.402Z'
updated_at: '2026-10-27T14:02:12.118Z'
- sequence: 2
type: CARD
amount:
currency: BRL
value: 100
transactions:
- id: e3b5a7c9-2d4f-4b6c-9e8a-0f1b2c3d4e5f
type: PURCHASE
status: SUCCEEDED
category: CARD
amount: 100
provider_id: YUNO_TEST_PAYMENT_GATEWAY
response_code: SUCCEEDED
response_message: Transaction successful
reason: null
description: null
merchant_reference: null
three_d_secure_action_required: false
created_at: '2026-10-27T14:02:11.402Z'
updated_at: '2026-10-27T14:02:12.118Z'
customer_payer:
id: cfae0941-7234-427a-a739-ef4fce966c79
first_name: Ana
last_name: Souza
email: ana.souza@example.com
workflow: DIRECT
callback_url: https://merchant.example.com/checkout/return
metadata: []
'400':
description: >-
Invalid request. `INVALID_PARAMETERS` for a missing idempotency key
or an amount above what can be operated on; `INVALID_STATUS` when
the card cannot take the operation, for example a refund while the
card has an open chargeback, or a capture or cancel while the
payment is in `REFUND_RETRY_IN_PROCESS` or
`CANCEL_RETRY_IN_PROCESS`.
content:
application/json:
schema:
type: object
properties:
code:
type: string
messages:
type: array
items:
type: string
examples:
Missing idempotency key:
value:
code: INVALID_PARAMETERS
messages:
- The header 'x-idempotency-key' is required.
'401':
description: Invalid credentials
content:
application/json:
schema:
type: object
properties:
code:
type: string
messages:
type: array
items:
type: string
example:
code: INVALID_CREDENTIALS
messages:
- Invalid credentials
components:
schemas:
PaymentV2:
type: object
description: A payment funded by two cards.
properties:
id:
type: string
format: uuid
account_id:
type: string
format: uuid
description:
type: string
country:
type: string
status:
type: string
description: >-
Aggregated status of the payment. See [Pay with two
cards](/docs/payment-features/pay-with-two-cards#statuses).
sub_status:
type: string
description: >-
Aggregated sub status, for example `APPROVED`, `AUTHORIZED`,
`PARTIALLY_CAPTURED`, `PARTIALLY_REFUNDED`,
`REFUND_RETRY_IN_PROCESS` or `CANCEL_RETRY_IN_PROCESS`.
merchant_order_id:
type: string
merchant_reference:
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
split_payment_methods:
type: boolean
description: '`true` for a payment funded by two cards.'
payment_methods_count:
type: integer
description: 'Number of cards that fund the payment: `2`.'
sdk_action_required:
type: boolean
description: >-
`true` when the SDK must continue the payment, for example to run a
3DS challenge.
amount:
type: object
description: Total of the payment.
required:
- currency
- value
properties:
currency:
type: string
description: ISO 4217 currency code (3 characters).
example: BRL
value:
type: number
description: Amount in major units (multiple of 0.0001).
example: 300
checkout:
type: object
properties:
session:
type:
- string
- 'null'
payment_method:
type: object
properties:
capture:
type: boolean
description: Capture setting shared by both cards.
account_updater:
type:
- boolean
- 'null'
payment_methods:
type: array
description: >-
One entry per card. There is no status per card: read each
card's outcome from its `transactions`.
minItems: 2
maxItems: 2
items:
type: object
properties:
sequence:
type: integer
description: 'Position of the card: `1` or `2`.'
type:
type: string
enum:
- CARD
amount:
type: object
description: Part of the total that this card pays.
required:
- currency
- value
properties:
currency:
type: string
description: ISO 4217 currency code (3 characters).
example: BRL
value:
type: number
description: Amount in major units (multiple of 0.0001).
example: 300
payment_method_detail:
type: object
description: Card details, as in the v1 payment object.
payment_method_owner:
type: object
description: Cardholder, when sent in the request.
transactions:
type: array
description: >-
Transactions of this card. A card that went through 3DS
shows `THREE_D_SECURE` followed by `PURCHASE` or
`AUTHORIZE`.
items:
type: object
description: >-
One transaction of the card. Read the outcome of the
card from its transactions.
properties:
id:
type: string
format: uuid
description: >-
Transaction id. Use it in the per-transaction
operations.
type:
type: string
description: >-
Transaction type, for example `THREE_D_SECURE`,
`PURCHASE`, `AUTHORIZE`, `CAPTURE`, `CANCEL` or
`REFUND`.
status:
type: string
description: >-
Status of this transaction, for example `SUCCEEDED`,
`DECLINED`, `PENDING` or `ERROR`.
category:
type: string
example: CARD
amount:
type: number
description: Amount of this transaction.
provider_id:
type: string
description: Provider that processed the transaction.
response_code:
type: string
description: Yuno response code of the transaction.
response_message:
type: string
reason:
type:
- string
- 'null'
description:
type:
- string
- 'null'
merchant_reference:
type:
- string
- 'null'
three_d_secure_action_required:
type:
- boolean
- 'null'
created_at:
type: string
format: date-time
updated_at:
type:
- string
- 'null'
format: date-time
customer_payer:
type: object
description: The payer, as sent in the request.
additional_data:
type:
- object
- 'null'
callback_url:
type: string
workflow:
type: string
enum:
- DIRECT
- REDIRECT
- SDK_CHECKOUT
metadata:
type: array
items:
type: object
securitySchemes:
sec0:
type: apiKey
in: header
name: public-api-key
x-default:
sec1:
type: apiKey
in: header
name: private-secret-key
x-default:
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.