Skip to main content
POST
/
payments
/
{payment_id}
/
transactions
/
{transaction_id}
/
cancel-or-refund
curl --request POST \
  --url https://api-sandbox.y.uno/v1/payments/{payment_id}/transactions/{transaction_id}/cancel-or-refund \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <api-key>' \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>' \
  --data '
{
  "description": "Duplicate",
  "reason": "REQUESTED_BY_CUSTOMER",
  "merchant_reference": "AAB01-432245"
}
'
{
  "id": "7fd485f3-bd72-45eb-a3fb-774daa3d79b6",
  "type": "REFUND",
  "status": "REFUNDED",
  "category": "CARD",
  "amount": {
    "captured": 0,
    "currency": "COP",
    "refunded": 0,
    "value": 30000
  },
  "merchant_reference": "0000023",
  "created_at": "2024-06-06T14:06:06.284443Z",
  "updated_at": "2024-06-06T14:06:37.984065Z",
  "provider_data": {
    "id": "YUNO_TEST_PAYMENT_GW",
    "transaction_id": "",
    "account_id": "493e9374-510a-4201-9e09-de669d75f256",
    "status": "",
    "status_detail": "",
    "response_message": null,
    "response_code": "SUCCEEDED",
    "iso8583_response_code": "00",
    "iso8583_response_message": "Approved or completed successfully",
    "raw_response": null,
    "third_party_transaction_id": null,
    "third_party_account_id": null
  },
  "response_code": "SUCCEEDED",
  "response_message": "Transaction successful",
  "payment": {
    "id": "c3583c27-0478-4e02-8827-4d8f2121c670",
    "account_id": "",
    "description": "Test",
    "country": "CO",
    "status": "REFUNDED",
    "sub_status": "REFUNDED",
    "merchant_order_id": "0000023",
    "created_at": "2024-06-06T14:06:06.284443Z",
    "updated_at": "2024-06-06T14:06:06.284443Z",
    "amount": {
      "captured": 0,
      "currency": "COP",
      "refunded": 30000,
      "value": 30000
    },
    "additional_data": {
      "airline": {
        "pnr": "1P-2UUGJW",
        "legs": [
          {
            "departure_airport": "EZE",
            "departure_datetime": "2014-05-12 13:05:00",
            "departure_airport_timezone": "-03:00",
            "arrival_airport": "AMS",
            "arrival_airport_timezone": "+00:00",
            "arrival_datetime": "",
            "carrier_code": "KL",
            "flight_number": "842",
            "fare_basis_code": "HL7LNR",
            "fare_class_code": "FR",
            "base_fare": 200,
            "base_fare_currency": "BRL",
            "stopover_code": "s"
          }
        ],
        "passengers": [
          {
            "first_name": "string",
            "last_name": "string",
            "middle_name": "string",
            "type": "s",
            "date_of_birth": "stringstri",
            "nationality": "st",
            "document": {
              "document_type": "CPF",
              "document_number": "351.040.753-97"
            },
            "country": "st",
            "loyalty_number": "string",
            "loyalty_tier": "strin",
            "email": null,
            "phone": null
          }
        ],
        "ticket": null,
        "tickets": [
          {
            "ticket_number": "123456",
            "e_ticket": false,
            "restricted": false,
            "total_fare_amount": 80,
            "total_tax_amount": 22,
            "total_fee_amount": 14,
            "issue": null
          }
        ]
      },
      "order": {
        "fee_amount": 100,
        "shipping_amount": 100,
        "tip_amount": null,
        "items": [
          {
            "id": "123AD",
            "name": "Skirt",
            "quantity": 1,
            "unit_amount": 29800,
            "category": "Clothes",
            "brand": "XYZ",
            "sku_code": "8765432109",
            "manufacture_part_number": "XYZ123456"
          }
        ]
      },
      "seller_details": null
    }
  }
}
Do not execute a refund while another is in progress. Wait for the current operation to complete before starting a new one.
This service allows you to cancel or refund an existing payment. Our system will identify if a cancellation or a refund is necessary based on the transaction status related to the transaction_id provided on the request. This is for certain scenarios where you want to be more specific about the actions taken on the payments lifecycle. This service performs the following functions based on the status of the transaction:
  • Cancels the payment if it has not been captured.
  • Refunds the payment if it has been captured.
RefundsIf you fill out the amount field, the refund will be partial. Otherwise, it will create a complete refund. The funds will be refunded to the payment method that was originally charged.
Note that this request requires an X-Idempotency-Key. Check the Authentication page for more information.

Authorizations

​
public-api-key
string
header
default:<Your public-api-key>
required
​
private-secret-key
string
header
default:<Your private-secret-key>
required
​
X-Idempotency-Key
string
header
default:<Your X-Idempotency-Key>
required

Path Parameters

​
payment_id
string
required

The unique identifier of the payment (UUID, 36 chars).

​
transaction_id
string
required

The unique identifier of the transaction (UUID, 36 chars).

Body

application/json
​
description
string

Description of the cancellation or refund. (MAX 255; MIN 3).

​
reason
enum<string>

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.

Available options:
DUPLICATE,
FRAUDULENT,
REQUESTED_BY_CUSTOMER,
REVERSE
​
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.

​
split_marketplace
object[]

Split marketplace array of objects

​
simplified_mode
boolean
default:false

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 [blocked].

​
response_additional_data
object

Specifies additional data for required the transaction response

​
customer_payer
object

Specifies customer object for payments.

​
payment_method
object

Specifies payment method object for payments.

Response

201

​
id
string
Example:

"7fd485f3-bd72-45eb-a3fb-774daa3d79b6"

​
type
string
Example:

"REFUND"

​
status
string
Example:

"REFUNDED"

​
category
string
Example:

"CARD"

​
amount
object
​
merchant_reference
string
Example:

"0000023"

​
created_at
string
Example:

"2024-06-06T14:06:06.284443Z"

​
updated_at
string
Example:

"2024-06-06T14:06:37.984065Z"

​
provider_data
object
​
response_code
string
Example:

"SUCCEEDED"

​
response_message
string
Example:

"Transaction successful"

​
payment
object