Refund Payment - Yuno API Documentation

POST

payments

{payment_id}

transactions

{transaction_id}

refund

cURL

curl --request POST \
  --url https://api-sandbox.y.uno/v1/payments/<payment_id>/transactions/<transaction_id>/refund \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'public-api-key: YOUR_PUBLIC_API_KEY' \
  --header 'private-secret-key: YOUR_PRIVATE_SECRET_KEY' \
  --data '{
  "merchant_reference": "refund-20260419-001",
  "reason": "REQUESTED_BY_CUSTOMER",
  "description": "Customer returned the product",
  "amount": { "currency": "BRL", "value": 50.00 }
}'

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

Refund a captured payment. Refunds are transaction-scoped. Target the specific transaction you want to reverse (the original purchase or capture), not the payment as a whole. Omit amount to refund the full captured amount. Include amount to issue a partial refund. You can issue multiple partials up to the captured total. For marketplace splits, use split_marketplace to reverse only specific recipients.

Do not issue a refund while another refund is in progress on the same transaction. Wait for the current operation to complete before starting a new one. Concurrent refunds return OPERATION_IN_PROCESS.

X-Idempotency-Key is required. Use a unique UUID per logical refund. Yuno replays the original response on retries with the same key for 24 hours. See Idempotency for the full behavior.

Refund vs. Cancel vs. Cancel-or-Refund. Use Cancel before a payment is captured (void the auth). Use this endpoint after capture. If you’re not sure whether the payment is captured yet, use Cancel or Refund and let Yuno decide.

Test this endpoint in Sandbox with the Yuno Testing Gateway.

Authorizations

public-api-key

string

header

required

Your public API key from the Yuno Dashboard

private-secret-key

string

header

required

Your private secret key (server-side only)

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

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.

Show child attributes

split_marketplace

object[]

Split marketplace array of objects

Show child attributes

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

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

200

Full Refund
Partial Refund

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

Show child attributes

checkout

object

Show child attributes

payment_method

object

Show child attributes

customer_payer

object

Show child attributes

additional_data

any

transactions

object

Show child attributes

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

Cancel or Refund PaymentAutomatically determines whether to cancel or refund a payment based on its current status. If the payment is authorized but not captured, it cancels. If captured, it refunds.

cURL

curl --request POST \
  --url https://api-sandbox.y.uno/v1/payments/<payment_id>/transactions/<transaction_id>/refund \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'public-api-key: YOUR_PUBLIC_API_KEY' \
  --header 'private-secret-key: YOUR_PRIVATE_SECRET_KEY' \
  --data '{
  "merchant_reference": "refund-20260419-001",
  "reason": "REQUESTED_BY_CUSTOMER",
  "description": "Customer returned the product",
  "amount": { "currency": "BRL", "value": 50.00 }
}'

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