> ## 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.
# Cancel or Refund a Payment (two cards)
> Cancels or refunds a whole two-card payment, or an amount spread across both cards, without a transaction id.
This request cancels or refunds a payment created with [Create Payment (two cards)](https://docs.y.uno/reference/payments/create-payment-v2.md). No `transaction_id` is needed: Yuno cancels each card that is only authorized and refunds each card that was charged.
> [!NOTE]
>
> **Partial amounts**
>
> `amount` is optional. If you omit it, the whole payment is canceled or refunded. If you send it, Yuno spreads it across the cards, starting with the card that has the most refundable amount. An `amount` above the total refundable amount of the payment is rejected.
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/cancel-or-refund-a-payment-v2.json POST /payments/{payment_id}/cancel-or-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}/cancel-or-refund:
post:
summary: Cancel or Refund a Payment (two cards)
description: >-
Cancels or refunds the whole payment. An optional `amount` is spread
across the cards, the card with the most refundable amount first.
operationId: cancel-or-refund-a-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
requestBody:
content:
application/json:
schema:
type: object
properties:
description:
type: string
description: Description of the cancellation or 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. If no merchant_reference is defined, the
merchant_order_id of the payment will be associated to the
transaction. (MAX 255; MIN 3).
amount:
type: object
description: >-
Optional. Amount to refund across both cards, the card with
the most refundable amount first. Above the total refundable
amount, the request is rejected. If you omit it, the whole
payment is canceled or refunded.
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.
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).
required:
- reason
responses:
'201':
description: The payment after the operation, in the v2 shape
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentV2'
examples:
Both cards refunded:
value:
id: 7c1b6e2a-5f3d-4a8e-9b21-3e4f5a6b7c8d
account_id: 493e9374-510a-4201-9e09-de669d75f256
description: Order paid with two cards
country: BR
status: REFUNDED
sub_status: 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'
- id: d8a0f2b4-7c9e-4a1b-8d3f-5e6f7a8b9c0d
type: REFUND
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.