---
title: "Cancel or Refund a Payment"
method: POST
path: "/payments/{payment_id}/cancel-or-refund"
---

# Cancel or Refund a Payment

`POST /payments/{payment_id}/cancel-or-refund`

## Path parameters

- `payment_id` string, required

## Request body

- object
  - `description` string — Description of the cancellation or refund. (MAX 255; MIN 3).
  - `reason` 'DUPLICATE' | 'FRAUDULENT' | 'REQUESTED_BY_CUSTOMER' | 'REVERSE', required — Indicating the reason for the cancellation or refund. If set, possible values are `DUPLICATE`, `FRAUDULENT`, `REQUESTED_BY_CUSTOMER`, and `REVERSE`. Use `REVERSE` to request an automatic reverse of the recipient funds when a recipient is involved in the transaction.
  - `merchant_reference` string — 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` object — Specifies the amount object for refund.
    - `currency` string — The currency used to make the payment. For a full list of currency codes, see [Country reference](/reference/country-reference) (MAX 3; MIN 3; ISO 4217).
    - `value` number, float — The payment amount (multiple of 0.0001).
  - `split_marketplace` object[] — Split marketplace array of objects
    - `recipient_id` string — The unique identifier of the recipient in the Yuno system. <br/> You must provide the [`recipient_id`](/reference/create-recipient-1) (Yuno-generated) or the `provider_recipient_id` (external provider's ID) when creating a payment.
    - `provider_recipient_id` string — The recipient ID provided by the external payment provider, if applicable. <br/> You must provide the `provider_recipient_id` or the [`recipient_id`](/reference/create-recipients) (Yuno-generated) when creating a payment.
    - `description` string — Description for the split. (MAX 255; MIN 3).
    - `type` 'PURCHASE' | 'PAYMENTFEE' | 'VAT' | 'COMMISSION' | 'MARKETPLACE' | 'SHIPPING', required — The type of split. `recipient_id` is mandatory for `PURCHASE` and `MARKETPLACE`.
    - `merchant_reference` string — Optional unique identifier for the split transaction (MAX 255; MIN 3).
    - `recipient_type` 'MEAL' | 'FOOD' | 'MULTI_BENEFITS' | 'FLEET' — The type of recipient for the provider.
    - `amount` object — Defines the amount of the split.
      - `value` number, float, required — The split amount (multiple of 0.0001).
      - `currency` string, required — The currency used to make the payment. For a full list of currency codes, see [Country reference](/reference/country-reference) (MAX 3; MIN 3; ISO 4217).
    - `liability` object — Optional information regarding the recipient's liability for fees and chargebacks.
      - `processing_fee` 'MERCHANT' | 'RECIPIENT' | 'SHARED' — Indicates who will be charged the transaction fee.
      - `chargebacks` boolean — The recipient is responsible in case of a chargeback.
  - `simplified_mode` boolean — Indicates if we should try to refund a payment after an error/declined on the first try. It is `false` by default. For more information, access the [guide](transaction-retries).
  - `response_additional_data` object — Specifies additional data for required the transaction response
    - `receipt` boolean — Indicates if a receipt is necessary for the transaction response
    - `receipt_language` 'ES' | 'EN' | 'PT' — Indicates the language of the receipt to be generated
  - `customer_payer` object — Specifies customer object for payments.
    - `first_name` string — The customer's first name (MAX 255; MIN 3).
    - `last_name` string — The customer's last name (MAX 255; MIN 3).
    - `gender` 'M' | 'F' | 'NB' | 'NA' | 'NK' | 'U' — The customer's gender (MAX 2; MIN 1). <br/>- M=Male <br/>- F=Female <br/>- NB=Non Binary <br/>- NA=Not applicable <br/>- NK=Not Known <br/>- U=Undefined.
    - `date_of_birth` string — The customer's date of birth in the `YYYY-MM-DD` format (Length: 10).
    - `email` string — The customer's e-mail (MAX 255; MIN 3).
    - `nationality` string — The customer's nationality (MAX 2; MIN 2; [ISO 3166-1](/reference/country-reference)).
    - `document` object — Specifies the customer's document object, including its number and type.
      - `document_number` string — Document number for customer (MAX 40; MIN 3)
      - `document_type` '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' — The customer's document type (MAX 6, MIN 2). Access [Document Type List](/reference/country-reference) for more details.
    - `phone` object — Specifies the customer's phone object.
      - `country_code` string — The country code of the customer's phone (MAX 3; MIN 1).
      - `number` string — The customer's phone number, without the country code (MAX 32; MIN 1).
    - `billing_address` object — Specifies the customer's billing address object.
      - `address_line_1` string — The primary billing address line of the customer (MAX 255; MIN 3).
      - `address_line_2` string — The secondary billing address line of the customer (MAX 255; MIN 3).
      - `city` string — The city considered for the billing address (MAX 255; MIN 3).
      - `country` 'AR' | 'BO' | 'BR' | 'CL' | 'CO' | 'CR' | 'EC' | 'SV' | 'GT' | 'HN' | 'MX' | 'NI' | 'PA' | 'PY' | 'PE' | 'US' | 'UY' — 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)).
      - `state` string — The state considered for the billing address (MAX 255; MIN 3).
      - `zip_code` string — The zipcode considered for the billing address (MAX 10; MIN 5).
    - `shipping_address` object — Specifies the customer's shipping address object.
      - `address_line_1` string — The primary shipping address line of the customer (MAX 255; MIN 3).
      - `address_line_2` string — The secondary shipping address line of the customer (MAX 255; MIN 3).
      - `city` string — The city considered for the shipping address (MAX 255; MIN 3).
      - `country` 'AR' | 'BO' | 'BR' | 'CL' | 'CO' | 'CR' | 'EC' | 'SV' | 'GT' | 'HN' | 'MX' | 'NI' | 'PA' | 'PY' | 'PE' | 'US' | 'UY' — 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)).
      - `state` string — The state considered for the shipping address (MAX 255; MIN 3).
      - `zip_code` string — The zipcode considered for the shipping address (MAX 10; MIN 5).
  - `payment_method` object — Specifies payment method object for payments.
    - `detail` object — Specifies the payment method detail object.
      - `bank_transfer` object — Specifies bank transfer payment method details.
        - `account_type` 'CHECKINGS' | 'SAVINGS' — Type of bank account (MAX 255; MIN 3)
        - `bank_name` string — Name of the bank (MAX 255; MIN 3)
        - `bank_id` string — ID of the bank (MAX 255; MIN 3)
        - `beneficiary_name` string — Name of the account holder (MAX 255; MIN 3)
        - `bank_account` string — Bank account number (MAX 255; MIN 3)
        - `beneficiary_document_type` string — Document type of the account holder (MAX 255; MIN 3)
        - `beneficiary_document` string — Document number of the account holder (MAX 255; MIN 3)
        - `reference` string — Reference code for the user (MAX 255; MIN 1)
        - `bank_account_mask_number` string — Masked bank account number associated with the bank transfer (for example, ****6789). This is account data, not mandate data.
        - `mandate` object — Direct debit mandate details, for bank transfer methods that operate with mandates (for example, ACH, SEPA, BACS, PAD).
          - `id` string — Mandate identifier, as provided by the payment provider.
          - `info` string — Free-text mandate information.
          - `received_status` string — Provider status indicating whether the mandate was received. Forwarded as provided by the payment provider.
          - `existing_status` string — Provider status of the existing mandate. Forwarded as provided by the payment provider.
          - `created_at` string, date-time — Date and time when the mandate was created (ISO 8601).
          - `updated_at` string, date-time — Date and time when the mandate was last updated (ISO 8601).

## Response `201`

201

- union
  - object
    - `id` string
    - `type` string
    - `status` string
    - `category` string
    - `amount` object
      - `captured` integer
      - `currency` string
      - `refunded` integer
      - `value` integer
    - `merchant_reference` string
    - `created_at` string
    - `updated_at` string
    - `provider_data` object
      - `id` string
      - `transaction_id` string
      - `account_id` string
      - `status` string
      - `status_detail` string
      - `response_message` unknown
      - `response_code` string
      - `iso8583_response_code` string
      - `iso8583_response_message` string
      - `raw_request` object — Obfuscated copy of the request Yuno sent to the provider. Only returned for allowlisted organizations.
      - `raw_response` unknown
      - `third_party_transaction_id` unknown
      - `third_party_account_id` unknown
    - `response_code` string
    - `response_message` string
    - `payment` object
      - `id` string
      - `account_id` string
      - `description` string
      - `country` string
      - `status` string
      - `sub_status` string
      - `merchant_order_id` string
      - `created_at` string
      - `updated_at` string
      - `amount` object
        - `captured` integer
        - `currency` string
        - `refunded` integer
        - `value` integer
      - `additional_data` object
        - `airline` object
          - `pnr` string
          - `legs` object[]
            - `departure_airport` string
            - `departure_datetime` string
            - `departure_airport_timezone` string
            - `arrival_airport` string
            - `arrival_airport_timezone` string
            - `arrival_datetime` string
            - `carrier_code` string
            - `flight_number` string
            - `fare_basis_code` string
            - `fare_class_code` string
            - `base_fare` integer
            - `base_fare_currency` string
            - `stopover_code` string
          - `passengers` object[]
            - `first_name` string
            - `last_name` string
            - `middle_name` string
            - `type` string
            - `date_of_birth` string
            - `nationality` string
            - `document` object
              - …
            - `country` string
            - `loyalty_number` string
            - `loyalty_tier` string
            - `email` string
            - `phone` string
          - `ticket` unknown
          - `tickets` object[]
            - `ticket_number` string
            - `e_ticket` boolean
            - `restricted` boolean
            - `total_fare_amount` integer
            - `total_tax_amount` integer
            - `total_fee_amount` integer
            - `issue` unknown
        - `order` object
          - `fee_amount` integer
          - `shipping_amount` integer
          - `tip_amount` unknown
          - `items` object[]
            - `id` string
            - `name` string
            - `quantity` integer
            - `unit_amount` integer
            - `category` string
            - `brand` string
            - `sku_code` string
            - `manufacture_part_number` string
        - `seller_details` unknown
  - object
    - `id` string
    - `type` string
    - `status` string
    - `category` string
    - `amount` object
      - `captured` integer
      - `currency` string
      - `refunded` integer
      - `value` integer
    - `merchant_reference` string
    - `created_at` string
    - `updated_at` string
    - `provider_data` object
      - `id` string
      - `transaction_id` string
      - `account_id` string
      - `status` string
      - `sub_status` string
      - `status_detail` string
      - `response_message` unknown
      - `response_code` string
      - `iso8583_response_code` string
      - `iso8583_response_message` string
      - `raw_request` object — Obfuscated copy of the request Yuno sent to the provider. Only returned for allowlisted organizations.
      - `raw_response` unknown
      - `third_party_transaction_id` unknown
      - `third_party_account_id` unknown
    - `response_code` string
    - `response_message` string
    - `payment` object
      - `id` string
      - `account_id` string
      - `description` string
      - `country` string
      - `status` string
      - `sub_status` string
      - `merchant_order_id` string
      - `created_at` string
      - `updated_at` string
      - `amount` object
        - `captured` integer
        - `currency` string
        - `refunded` integer
        - `value` integer
      - `additional_data` object
        - `airline` object
          - `pnr` string
          - `legs` object[]
            - `departure_airport` string
            - `departure_datetime` string
            - `departure_airport_timezone` string
            - `arrival_airport` string
            - `arrival_airport_timezone` string
            - `arrival_datetime` string
            - `carrier_code` string
            - `flight_number` string
            - `fare_basis_code` string
            - `fare_class_code` string
            - `base_fare` integer
            - `base_fare_currency` string
            - `stopover_code` string
          - `passengers` object[]
            - `first_name` string
            - `last_name` string
            - `middle_name` string
            - `type` string
            - `date_of_birth` string
            - `nationality` string
            - `document` object
              - …
            - `country` string
            - `loyalty_number` string
            - `loyalty_tier` string
            - `email` string
            - `phone` string
          - `ticket` unknown
          - `tickets` object[]
            - `ticket_number` string
            - `e_ticket` boolean
            - `restricted` boolean
            - `total_fare_amount` integer
            - `total_tax_amount` integer
            - `total_fee_amount` integer
            - `issue` unknown
        - `order` object
          - `fee_amount` integer
          - `shipping_amount` integer
          - `tip_amount` unknown
          - `items` object[]
            - `id` string
            - `name` string
            - `quantity` integer
            - `unit_amount` integer
            - `category` string
            - `brand` string
            - `sku_code` string
            - `manufacture_part_number` string
        - `seller_details` unknown
  - object
    - `id` string
    - `type` string
    - `status` string
    - `category` string
    - `amount` object
      - `captured` integer
      - `currency` string
      - `refunded` integer
      - `value` integer
    - `merchant_reference` string
    - `created_at` string
    - `updated_at` string
    - `provider_data` object
      - `id` string
      - `transaction_id` string
      - `account_id` string
      - `status` string
      - `sub_status` string
      - `status_detail` string
      - `response_message` unknown
      - `response_code` string
      - `iso8583_response_code` string
      - `iso8583_response_message` string
      - `raw_request` object — Obfuscated copy of the request Yuno sent to the provider. Only returned for allowlisted organizations.
      - `raw_response` unknown
      - `third_party_transaction_id` unknown
      - `third_party_account_id` unknown
    - `response_code` string
    - `response_message` string
    - `payment` object
      - `id` string
      - `account_id` string
      - `description` string
      - `country` string
      - `status` string
      - `sub_status` string
      - `merchant_order_id` string
      - `created_at` string
      - `updated_at` string
      - `amount` object
        - `captured` integer
        - `currency` string
        - `refunded` integer
        - `value` integer

## Other responses

- `400` — 400
- `401` — 401
- `403` — 403

---

[API](https://skmtc.net/y/apis/ai-caller.md) · [All operations](https://skmtc.net/y/apis/ai-caller/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/y/ai-caller/revisions/05b629819b49/schema)