Skip to main content
POST
/
{id}
/
transactions
/
{transaction_id}
/
refund
curl --request POST \
  --url https://api-sandbox.y.uno/v1/payments/{id}/transactions/{transaction_id}/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": "f2d6884a-f737-4565-ae32-ff60b19089e3",
  "account_id": "",
  "description": "Duplicate",
  "country": "US",
  "status": "REFUNDED",
  "sub_status": "REFUNDED",
  "merchant_order_id": "AAB01-432245",
  "created_at": "2025-04-14T17:51:45.179645Z",
  "updated_at": "2025-04-14T17:52:07.908698Z",
  "amount": {
    "captured": 0,
    "currency": "USD",
    "currency_conversion": null,
    "refunded": 30000,
    "value": 30000
  },
  "checkout": {
    "session": "",
    "sdk_action_required": false
  },
  "payment_method": {
    "vaulted_token": "",
    "type": "CARD",
    "vault_on_success": false,
    "token": "",
    "parent_payment_method_type": null,
    "payment_method_detail": {
      "card": {
        "verify": false,
        "capture": false,
        "installments": 1,
        "installments_plan_id": null,
        "first_installment_deferral": 0,
        "installments_type": "MERCHANT",
        "installment_amount": null,
        "soft_descriptor": "",
        "authorization_code": "216303",
        "retrieval_reference_number": "",
        "voucher": null,
        "card_data": {
          "holder_name": "John Doe",
          "iin": "41111111",
          "lfd": "1111",
          "number_length": 16,
          "security_code_length": 3,
          "brand": "VISA",
          "issuer_name": "CHASE BANK USA",
          "issuer_code": null,
          "country_code": "US",
          "category": "CLASSIC",
          "type": "DEBIT",
          "three_d_secure": {
            "version": null,
            "electronic_commerce_indicator": null,
            "cryptogram": null,
            "transaction_id": null,
            "directory_server_transaction_id": null,
            "pares_status": null,
            "acs_id": null
          },
          "fingerprint": "d244e20d-43a1-43f7-9b48-0a76423be35e",
          "expiration_month": 3,
          "expiration_year": 26
        },
        "stored_credentials": {
          "reason": null,
          "usage": null,
          "subscription_agreement_id": null,
          "network_transaction_id": null
        }
      }
    }
  },
  "customer_payer": {
    "id": null,
    "merchant_customer_id": "1744653105",
    "first_name": "John",
    "last_name": "Doe",
    "gender": "M",
    "date_of_birth": "1990-02-28",
    "email": "john.doe@example.com",
    "nationality": "US",
    "ip_address": "192.168.1.1",
    "device_fingerprint": null,
    "device_fingerprints": [],
    "browser_info": null,
    "document": {
      "document_type": "SSN",
      "document_number": "123-45-6789"
    },
    "phone": {
      "number": "5551234567",
      "country_code": "1"
    },
    "billing_address": {
      "address_line_1": "1234 Elm Street",
      "address_line_2": "Apt 5B",
      "country": "US",
      "state": "California",
      "city": "Los Angeles",
      "zip_code": "90001",
      "neighborhood": null
    },
    "shipping_address": {
      "address_line_1": "1234 Elm Street",
      "address_line_2": "Apt 5B",
      "country": "US",
      "state": "California",
      "city": "Los Angeles",
      "zip_code": "90001",
      "neighborhood": null
    },
    "merchant_customer_created_at": null
  },
  "additional_data": null,
  "transactions": {
    "id": "5414f862-51e6-433f-a54c-b46b176e87a0",
    "type": "REFUND",
    "status": "SUCCEEDED",
    "category": "CARD",
    "amount": 30000,
    "provider_id": "YUNO_TEST_PAYMENT_GW",
    "payment_method": {
      "vaulted_token": "",
      "type": "CARD",
      "vault_on_success": false,
      "token": "",
      "parent_payment_method_type": null,
      "detail": {
        "card": {
          "verify": false,
          "capture": false,
          "installments": 1,
          "installments_plan_id": null,
          "first_installment_deferral": 0,
          "installments_type": "MERCHANT",
          "installment_amount": null,
          "soft_descriptor": "",
          "authorization_code": "216303",
          "retrieval_reference_number": "",
          "voucher": null,
          "card_data": {
            "holder_name": "John Doe",
            "iin": "41111111",
            "lfd": "1111",
            "number_length": 16,
            "security_code_length": 3,
            "brand": "VISA",
            "issuer_name": "CHASE BANK USA",
            "issuer_code": null,
            "country_code": "US",
            "category": "CLASSIC",
            "type": "DEBIT",
            "three_d_secure": {
              "version": null,
              "electronic_commerce_indicator": null,
              "cryptogram": null,
              "transaction_id": null,
              "directory_server_transaction_id": null,
              "pares_status": null,
              "acs_id": null
            },
            "fingerprint": "d244e20d-43a1-43f7-9b48-0a76423be35e",
            "expiration_month": 3,
            "expiration_year": 26
          },
          "stored_credentials": {
            "reason": null,
            "usage": null,
            "subscription_agreement_id": null,
            "network_transaction_id": null
          }
        }
      }
    },
    "response_code": "SUCCEEDED",
    "response_message": "Transaction successful",
    "reason": "REQUESTED_BY_CUSTOMER",
    "description": "Test refund",
    "merchant_reference": "REFUND_001",
    "provider_data": {
      "id": "YUNO_TEST_PAYMENT_GW",
      "transaction_id": "2e5c04d5-4cf7-4d2a-b57a-dd5eb9a687bc",
      "account_id": "",
      "status": "",
      "sub_status": "",
      "status_detail": "",
      "response_message": null,
      "response_code": "SUCCEEDED",
      "raw_response": {
        "message": "provider response"
      },
      "third_party_transaction_id": null,
      "third_party_account_id": null,
      "iso8583_response_code": null,
      "iso8583_response_message": null
    },
    "connection_data": null,
    "created_at": "2025-04-14T17:52:07.768528Z",
    "updated_at": "2025-04-14T17:52:07.862912Z"
  },
  "transactions_history": null,
  "metadata": [],
  "fraud_screening": null,
  "payment_link_id": "",
  "subscription_code": null,
  "routing_rules": null,
  "simplified_mode": false
}
Do not execute a refund while another is in progress. Wait for the current operation to complete before starting a new one.
This endpoint allows you to issue a refund for an existing payment. If you specify an amount, a partial refund will be created. If the amount is omitted, a full refund of the original payment will be processed. Refunds can only be created for charges that have not been refunded yet. The refunded amount will be returned to the original payment method used in the transaction. 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

​
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
​
merchant_reference
string
required

Identification of the payment transaction defined by the merchant (MAX 255; MIN 3).

​
description
string

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

​
reason
enum<string>

Indicating the reason for the 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
​
amount
object

Specifies the amount object for refund. Only required for partial refunds.

​
split_marketplace
object[]

Split marketplace array of objects

​
simplified_mode
boolean

Determines whether Yuno should automatically attempt to refund a payment after an initial error or decline. When set to true, Yuno will retry the process if the first attempt fails. By default, this is set to false. Access Transaction Retries for more details.

​
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

200

​
id
string
Example:

"f2d6884a-f737-4565-ae32-ff60b19089e3"

​
account_id
string
Example:

""

​
description
string
Example:

"Duplicate"

​
country
string
Example:

"US"

​
status
string
Example:

"REFUNDED"

​
sub_status
string
Example:

"REFUNDED"

​
merchant_order_id
string
Example:

"AAB01-432245"

​
created_at
string
Example:

"2025-04-14T17:51:45.179645Z"

​
updated_at
string
Example:

"2025-04-14T17:52:07.908698Z"

​
amount
object
​
checkout
object
​
payment_method
object
​
customer_payer
object
​
additional_data
any
​
transactions
object
​
transactions_history
any
​
metadata
array
​
fraud_screening
any
​
payment_link_id
string
Example:

""

​
subscription_code
any
​
routing_rules
any
​
simplified_mode
boolean
default:true
Example:

false