List charge refunds

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

List all refunds for a specific charge. Returns refunds sorted by creation date with pagination capabilities.

---

Request Parameters

Required - 1 fieldRequired Parameters

▼

`id`STRING(required)

The charge ID to retrieve refunds for. Must be a valid charge ID from your account.

Example:"chrg_test_5xuy4w91xqz7d1w9u0t"

Constraints:Must start with chrg_, Test charges: chrg_test_, Live charges: chrg_live_

Recommended - 3 fieldsRecommended Parameters

▼

`limit`INTEGER(optional)

Number of refunds to return per page.

Example:20

Constraints:Minimum: 1, Maximum: 100

Default:20

`offset`INTEGER(optional)

Number of refunds to skip for pagination. Use with limit to navigate through pages.

Example:0

Default:0

`order`STRING(optional)

Sort order by creation date.

Example:"chronological"

Values:chronological, reverse_chronological

Default:"chronological"

Additional - 2 fieldsAdditional Parameters

▼

---

Responses

200

Successful list retrieval

Returns a list object containing refund data array and pagination metadata.

Response includes:

• data - Array of refund objects
• total - Total number of refunds for this charge
• limit - Number of items per page
• offset - Current pagination offset
• order - Sort order applied
• from / to - Date range applied

400

Bad request

Invalid parameters provided.

Common causes:

• Invalid date format (must be ISO 8601)
• Limit out of range (must be 1-100)
• Invalid offset value

401

Unauthorized

Authentication failed. Invalid or missing API key.

Common causes:

• Missing Authorization header
• Invalid secret key
• Using public key instead of secret key

404

Not found

Charge ID does not exist.

Common causes:

• Incorrect charge ID
• Charge from different account
• Using test key for live charge (or vice versa)

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?limit=20&offset=0" \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

Ruby

require 'omise'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

charge = Omise::Charge.retrieve('chrg_test_5xuy4w91xqz7d1w9u0t')
refunds = charge.refunds(limit: 20, offset: 0)

Python

import omise

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

charge = omise.Charge.retrieve('chrg_test_5xuy4w91xqz7d1w9u0t')
refunds = charge.refunds(limit=20, offset=0)

Node.js

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

const refunds = await omise.charges.listRefunds('chrg_test_5xuy4w91xqz7d1w9u0t', {
  limit: 20,
  offset: 0
});

PHP

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

$charge = OmiseCharge::retrieve('chrg_test_5xuy4w91xqz7d1w9u0t');
$refunds = $charge->refunds(array(
    'limit' => 20,
    'offset' => 0
));

Java

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

ScopedList<Refund> refunds = client.charges()
    .get("chrg_test_5xuy4w91xqz7d1w9u0t")
    .refunds()
    .limit(20)
    .offset(0)
    .send();

C#

var client = new Client("skey_test_5xuy4w91xqz7d1w9u0t");

var refunds = await client.Charges.ListRefunds("chrg_test_5xuy4w91xqz7d1w9u0t", new ListOptions {
    Limit = 20,
    Offset = 0
});

Go

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

refunds, _ := client.ListChargeRefunds("chrg_test_5xuy4w91xqz7d1w9u0t", &operations.ListChargeRefunds{
    List: operations.List{
        Limit:  20,
        Offset: 0,
    },
})

---

Error and result codes

Refund Status Values

Status	Description	Next Steps
pending	Refund is being processed	Wait for completion
closed	Refund completed successfully	Funds returned to customer
failed	Refund failed	Check failure reason

Pagination Calculation

Field	Calculation	Use
Next page	offset + limit	Get next set of results
Previous page	offset - limit (min 0)	Go back to previous page
Has more	offset + limit < total	Check if more pages exist
Page number	(offset / limit) + 1	Current page number

---

🔑API Credentials

▼

Try it out

Required - 1 fields

▼

id(Required)

Recommended - 3 fields

▼

Additional - 2 fields

▼

Your IP: ...Loading...