Refund Payment

POST /payments/{id}/transactions/{transaction_id}/refund

cURL

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

200

Full Refund

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

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

application/json

200

Full Refund

Partial Refund

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

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