Cancel or Refund a Payment

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

cURL

Full 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"
}
'

201

Full Refund

{
  "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": "[e-mail]",
            "phone": "[phone]"
          }
        ],
        "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.

Refunds

If 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.

Show child attributes

split_marketplace · object[]

Split marketplace array of objects

Show child attributes

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

Show child attributes

customer_payer · object

Specifies customer object for payments.

Show child attributes

payment_method · object

Specifies payment method object for payments.

Show child attributes

Response

201

application/json

201

Full Refund

Partial Refund

Cancel

id · string

Example:

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

type · string

Example:

"REFUND"

status · string

Example:

"REFUNDED"

category · string

Example:

"CARD"

amount · object

Show child attributes

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

Show child attributes

response_code · string

Example:

"SUCCEEDED"

response_message · string

Example:

"Transaction successful"

payment · object

Show child attributes