Cancel or Refund a Payment with transaction

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

cURL

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

201

Full Refund

{
  "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.

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

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.

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