Create a Refund

POSThttps://api.omise.co/charges/:id/refunds

Issue a full or partial refund for a successful charge. Funds are automatically returned to the customer's original payment method.

---

Request Parameters

Required - 1 fieldRequired Parameters

▼

`id`STRING(required)

Charge ID to refund (path parameter). The charge must be successful, captured, and refundable.

Example:"chrg_test_5xuy4w91xqz7d1w9u0t"

Recommended - 1 fieldRecommended Parameters

▼

Additional - 2 fieldsAdditional Parameters

▼

---

Responses

200

Successful refund

Refund created successfully. Check the status field to determine processing state.

Response includes:

• object - The value "refund"
• id - Refund identifier (rfnd_*)
• livemode - Live or test mode
• location - API path to the refund object
• acquirer_reference_number - Reference number sent to card networks
• amount - Refund amount in smallest currency unit
• approval_code - Reference number for approved transactions
• capture - Capture reference
• charge - Associated charge ID (expandable)
• currency - Three-letter ISO 4217 currency code
• funding_amount - Amount in settlement currency
• funding_currency - Settlement currency code
• merchant_name - Sub-merchant name (Payfac only)
• merchant_uid - Sub-merchant ID (Payfac only)
• metadata - Custom metadata attached to refund
• status - Current refund status (pending, successful, failed)
• terminal - Original point of sale location
• transaction - Associated transaction ID (expandable)
• voided - Whether refund was processed as a void
• created_at - Refund creation timestamp (ISO 8601)

400

Bad request

Request validation failed. Check the error message for details.

Common causes:

• Invalid charge ID format
• Amount exceeds refundable balance
• Invalid metadata format
• Amount below minimum (1 unit)

401

Unauthorized

Authentication failed. Invalid or missing API key.

Common causes:

• Missing Authorization header
• Invalid secret key
• Using public key instead of secret key
• Incorrect HTTP Basic Auth format

404

Not found

Charge not found.

Common causes:

• Incorrect charge ID
• Charge belongs to different account
• Charge ID typo or formatting error

422

Unprocessable entity

Charge cannot be refunded.

Common causes:

• Charge not successful (still pending or failed)
• Charge already fully refunded
• Refund amount exceeds available balance
• Charge has 15 or more partial refunds (maximum limit)
• Charge older than 365 days (or shorter for some payment methods)

5xx

Server error

Server-side error occurred. These are rare but should be handled gracefully.

How to handle:

• Retry the request with exponential backoff
• Check status.omise.co for service incidents
• See Error Handling for detailed guidance

---

Code samples

cURL

curl https://api.omise.co/charges/chrg_test_5xuy4w91xqz7d1w9u0t/refunds \
  -X POST \
  -u skey_test_5xuy4w91xqz7d1w9u0t: \
  -d "amount=50000"

Ruby

require 'omise'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

refund = Omise::Charge.refund('chrg_test_5xuy4w91xqz7d1w9u0t', {
  amount: 50000
})

Python

import omise

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

refund = omise.Charge.refund('chrg_test_5xuy4w91xqz7d1w9u0t',
    amount=50000
)

Node.js

const omise = require('omise')({
  secretKey: 'skey_test_5xuy4w91xqz7d1w9u0t'
});

const refund = await omise.charges.refund('chrg_test_5xuy4w91xqz7d1w9u0t', {
  amount: 50000
});

PHP

<?php
define('OMISE_SECRET_KEY', 'skey_test_5xuy4w91xqz7d1w9u0t');

$charge = OmiseCharge::retrieve('chrg_test_5xuy4w91xqz7d1w9u0t');
$refund = $charge->refund([
    'amount' => 50000
]);

Java

Client client = new Client.Builder()
    .secretKey("skey_test_5xuy4w91xqz7d1w9u0t")
    .build();

Refund refund = client.charges().refund("chrg_test_5xuy4w91xqz7d1w9u0t")
    .amount(50000L)
    .send();

C#

var client = new Client("skey_test_5xuy4w91xqz7d1w9u0t");

var refund = await client.Charges.Refund("chrg_test_5xuy4w91xqz7d1w9u0t", new CreateRefundRequest
{
    Amount = 50000
});

Go

client, _ := omise.NewClient(
    "pkey_test_5xuy4w91xqz7d1w9u0t",
    "skey_test_5xuy4w91xqz7d1w9u0t",
)

refund, _ := client.CreateRefund(&operations.CreateRefund{
    ChargeID: "chrg_test_5xuy4w91xqz7d1w9u0t",
    Amount:   50000,
})

---

Error and result codes

Common Error Codes

Code	Description	Resolution
bad_request	Missing or invalid parameters	Check all required fields are provided
authentication_failure	Invalid API key	Verify your secret key is correct
not_found	Charge ID does not exist	Check charge ID is correct
charge_not_refundable	Charge cannot be refunded	Verify charge status is successful
insufficient_refundable_amount	Amount exceeds available balance	Check charge.amount - charge.refunded_amount
too_many_refunds	15 refunds already created	Maximum 15 partial refunds per charge
refund_period_expired	Charge older than refund window	Charges must be under 365 days old

Refund Status Codes

Status	Description
pending	Refund being processed
successful	Refund completed successfully
failed	Refund failed (rare)

---

🔑API Credentials

▼

Try it out

Required - 1 fields

▼

id(Required)

Recommended - 1 fields

▼

Additional - 2 fields

▼

Your IP: ...Loading...