Skip to main content
POST
/
payments
/
{payment_id}
/
cancel-or-refund
curl --request POST \
  --url https://api-sandbox.y.uno/v1/payments/{payment_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": "USD",
    "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 Bank of America",
    "country": "US",
    "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": "USD",
      "refunded": 30000,
      "value": 30000
    },
    "additional_data": {
      "airline": {
        "pnr": "1P-2UUGJW",
        "legs": [
          {
            "departure_airport": "EWR",
            "departure_datetime": "2014-05-12 13:05:00",
            "departure_airport_timezone": "-05:00",
            "arrival_airport": "SFO",
            "arrival_airport_timezone": "-08:00",
            "arrival_datetime": "",
            "carrier_code": "UA",
            "flight_number": "842",
            "fare_basis_code": "HL7LNR",
            "fare_class_code": "FR",
            "base_fare": 200,
            "base_fare_currency": "USD",
            "stopover_code": "s"
          }
        ],
        "passengers": [
          {
            "first_name": "John",
            "last_name": "Doe",
            "middle_name": "A",
            "type": "adult",
            "date_of_birth": "1980-01-01",
            "nationality": "US",
            "document": {
              "document_type": "SSN",
              "document_number": "123-45-6789"
            },
            "country": "US",
            "loyalty_number": "UA123456",
            "loyalty_tier": "Gold",
            "email": "johndoe@example.com",
            "phone": "+15555555555"
          }
        ],
        "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 payment, no transaction_id is needed in this case. 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).

Body

application/json
​
reason
enum<string>
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.

Available options:
DUPLICATE,
FRAUDULENT,
REQUESTED_BY_CUSTOMER,
REVERSE
​
description
string

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

​
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