Refund API

Create and retrieve refunds on undisputed, captured charges. The charge must have fewer than 15 partial refunds and must also have been captured for no longer than 365 days. If the charge is fully refunded prior to its settlement, the refund is processed as a void.

Note: Some payment methods may have refundable periods shorter than 365 days. Please refer to the documentation for each payment method for more details.

Attributes

Name	Type	Description
object	string	The string `refund`.
id	string	The refund identifier matching `/rfnd(_test)?_[0-9a-z]+/`.
livemode	boolean	Whether this is a live (`true`) or test (`false`) refund.
location	string	API path to retrieve the current `refund` object.
acquirer_reference_number	string	Reference number for the refund initiated by the merchant. This information is sent as part of the settlement report to Visa and Master Card.
amount	integer	Refund amount in smallest unit of charge currency.
approval_code	string	The reference number for approved transactions by issuer banks. This code helps merchants easily investigate issues with banks.
charge	object_id_expandable	Charge identifier associated with this refund.
created_at	string	UTC datetime of refund creation in ISO 8601 format (`YYYY-MM-DDThh:mm:ssZ`).
currency	string	Currency for refund as three-letter ISO 4217 code.
funding_amount	integer	For refunds of multi-currency charges, `amount` after exchange into account funding currency (`funding_currency`) specified in the smallest unit of `funding_currency`. For refunds of non-multi-currency charges, `amount` specified in the smallest unit of `currency`.
funding_currency	string	Currency for account as three-letter ISO 4217 code. This is the settlement currency for all charges.
merchant_name	string	The name of the sub-merchant who initiated the refund. Note: This field is applicable only if the merchant uses the Payfac solution. To enroll in Payfac, contact Opn Support.
merchant_uid	string	The ID of the sub-merchant who initiated the refund. Note: This field is applicable only if the merchant uses the Payfac solution. To enroll in Payfac, contact Opn Support.
metadata	object	Custom metadata (e.g. {answer: 42}) for refund. The maximum field length is 15.000 characters.
status	string	Status of the refund.
terminal	string	Original charge point of sale within a branch.
transaction	object_id_expandable	Transaction identifier associated with this refund.
voided	boolean	Whether refunded charge was voided instead. Charges are voided if refund is processed before settlement time.

Example

JSON Response

{
  "object": "refund",
  "id": "rfnd_test_no1t4tnemucod0e51mo",
  "location": "/charges/chrg_test_no1t4tnemucod0e51mo/refunds/rfnd_test_no1t4tnemucod0e51mo",
  "livemode": false,
  "voided": false,
  "currency": "THB",
  "amount": 10000,
  "metadata": {
    "answer": 42
  },
  "charge": "chrg_test_no1t4tnemucod0e51mo",
  "terminal": null,
  "transaction": "trxn_test_no1t4tnemucod0e51mo",
  "status": "closed",
  "funding_amount": 10000,
  "funding_currency": "THB",
  "created_at": "2019-12-31T12:59:59Z"
}

Create a refund

- POST https://api.omise.co/charges/{id}/refunds

Creates and returns a new refund on charge matching :id.

Request Parameters

Name	Type	Description
amount	integer	(required) Refund amount in smallest unit of charge currency.
metadata	object	(optional) Custom metadata (e.g. {answer: 42}) for refund. The maximum field length is 15.000 characters.
void	boolean	(optional, one of: `true`, `false`) Whether to only process refund as a void, if possible. By default, if refund is requested before charge settlement, it is processed as a void, otherwise it is processed as a normal refund.

Example

Create a refund

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/charges/chrg_test_5g5idked981unmzjzhl/refunds \
  -u $OMISE_SECRET_KEY: \
  -d "amount=10000"

<?php

$charge = OmiseCharge::retrieve("chrg_test_4xso2s8ivdej29pqnhz");
$refund = $charge->refunds()->create(array('amount' => 10000));

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

const charge = await omise.charges.createRefund(
  'chrg_test_no1t4tnemucod0e51mo',
  { amount: 10000 },
);
console.log(charge);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

charge = Omise::Charge.retrieve("chrg_test_4xso2s8ivdej29pqnhz")
refund = charge.refunds.create(amount: 10000)

var charge = RetrieveCharge();
var refund = await Client.Charge(charge.Id).Refunds.Create(new CreateRefundRequest
{
    Amount = charge.Amount,
});

Console.WriteLine($"created refund: {refund.Id}");

Request<Refund> request = new Refund.CreateRequestBuilder("chrg_test_4xso2s8ivdej29pqnhz")
        .amount(10000)
        .build();
Refund refund = client().sendRequest(request);

System.out.printf("Created refund: %s", refund.getId());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

charge = omise.Charge.retrieve("chrg_test_no1t4tnemucod0e51mo")
refund = charge.refund(amount=10000)

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Recipient{}

err := client.Do(result, &operations.CreateRefund{
	ChargeID: "chrg_test_no1t4tnemucod0e51mo",
	Amount:   2000, // THB 1,000.00 or JPY 100,000
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Charge.refund("chrg_test_4ype2jynk2len88i4er", amount: 10000)

Create a refund while adding metadata

curl
php
node.js

curl https://api.omise.co/charges/chrg_test_5g5idked981unmzjzhl/refunds \
  -u $OMISE_SECRET_KEY: \
  -d "amount=10000" \
  -d "metadata[order_id]=ORDER-1234" \
  -d "metadata[color]=black"

<?php

$charge = OmiseCharge::retrieve('chrg_test_6bp9e1mr40jni2imuan');
$refund = $charge->refunds()->create(array(
    'amount'   => 10000,
    'metadata' => array(
        'order_id' => 'ORDER_ID',
        'color'    => 'pink'
    )
));

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

const charge = await omise.charges.createRefund(
  'chrg_test_no1t4tnemucod0e51mo',
  { amount: 10000 },
  {
    metadata: {
      order_id: 'ord_test_no1t4tnemucod0e51mo',
      color: 'black',
    },
  },
);
console.log(charge);

List refunds for charge

- GET https://api.omise.co/charges/{id}/refunds

Returns a list of refunds belonging to charge matching :id.

Request Parameters

Name	Type	Description
from	string	(optional, default: `1970-01-01T00:00:00Z`) Earliest UTC datetime for returned records in ISO 8601 format (`YYYY-MM-DDThh:mm:ssZ`).
limit	integer	(optional, default: `20`) Number of records returned.
offset	integer	(optional, default: `0`) Offset of the first record returned (i.e. how many records to skip from the beginning).
order	string	(optional, default: `chronological`, one of: `chronological`, `reverse_chronological`) Order of records returned.
to	string	(optional) Latest UTC datetime for returned records in ISO 8601 format (`YYYY-MM-DDThh:mm:ssZ`).

Example

List all refunds for a charge

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/charges/chrg_test_5g5idked981unmzjzhl/refunds \
  -u $OMISE_SECRET_KEY:

<?php

$charge = OmiseCharge::retrieve("chrg_test_4xso2s8ivdej29pqnhz");
$refunds = $charge->refunds();

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

const charge = await omise.charges.listRefunds('chrg_test_no1t4tnemucod0e51mo');
console.log(charge);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

charge = Omise::Charge.retrieve("chrg_test_4xso2s8ivdej29pqnhz")
refunds = charge.refunds

var chargeId = "chrg_test_58fkc7mrh99fnymu214";
var refunds = await Client
    .Charge(chargeId)
    .Refunds
    .GetList(order: Ordering.ReverseChronological);

Console.WriteLine($"refunds for this charge: {refunds.Total}");

Request<ScopedList<Refund>> request =
        new Refund.ListRequestBuilder("chrg_test_4xso2s8ivdej29pqnhz").build();
ScopedList<Refund> refunds = client().sendRequest(request);

System.out.printf("Total no. of refunds: %d", refunds.getTotal());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

charge = omise.Charge.retrieve("chrg_test_no1t4tnemucod0e51mo")
refunds = charge.refunds

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.RefundList{}

err := client.Do(result, &operations.ListRefunds{
	ChargeID: "chrg_test_no1t4tnemucod0e51mo",
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Charge.list_refunds("chrg_test_4xso2s8ivdej29pqnhz")

List refunds

- GET https://api.omise.co/refunds

Returns a list of refunds belonging to your account.

Request Parameters

Name	Type	Description
from	string	(optional, default: `1970-01-01T00:00:00Z`) Earliest UTC datetime for returned records in ISO 8601 format (`YYYY-MM-DDThh:mm:ssZ`).
limit	integer	(optional, default: `20`) Number of records returned.
offset	integer	(optional, default: `0`) Offset of the first record returned (i.e. how many records to skip from the beginning).
order	string	(optional, default: `chronological`, one of: `chronological`, `reverse_chronological`) Order of records returned.
to	string	(optional) Latest UTC datetime for returned records in ISO 8601 format (`YYYY-MM-DDThh:mm:ssZ`).

Example

List all refunds

curl
node.js
ruby
C#
elixir

curl https://api.omise.co/refunds \
  -u $OMISE_SECRET_KEY:

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

const charge = await omise.charges.listRefunds('chrg_test_no1t4tnemucod0e51mo');
console.log(charge);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

refunds = Omise::Refund.list

var refunds = await Client
    .Refunds
    .GetList(order: Ordering.ReverseChronological);

Console.WriteLine($"refunds so far: {refunds.Total}");

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Refund.list

Retrieve a refund

- GET https://api.omise.co/charges/{id}/refunds/{refund_id}

Returns the refund matching :refund_id belonging to charge matching :id.

Example

Retrieve a refund

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/charges/chrg_test_5g5idked981unmzjzhl/refunds/rfnd_test_4zgf1d7jcw5kr123puq \
  -u $OMISE_SECRET_KEY:

<?php

$charge = OmiseCharge::retrieve("chrg_test_4xso2s8ivdej29pqnhz");
$refund = $charge->refunds()->retrieve("rfnd_test_4ypebtxon6oye5o8myu");

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

const charge = await omise.charges.retrieveRefund('chrg_test_no1t4tnemucod0e51mo', 'rfnd_test_no1t4tnemucod0e51mo');
console.log(charge);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

charge = Omise::Charge.retrieve("chrg_test_4xso2s8ivdej29pqnhz")
refund = charge.refunds.retrieve("rfnd_test_4zgf1d7jcw5kr123puq")

var chargeId = "chrg_test_58fkc7mrh99fnymu214";
var refundId = "rfnd_test_58fkcxsbyxodfei74kt";
var refund = await Client.Charge(chargeId).Refunds.Get(refundId);
Console.WriteLine($"refunded: {refund.Amount}");

Request<Refund> request =
        new Refund.GetRequestBuilder("chrg_test_4xso2s8ivdej29pqnhz", "rfnd_test_4ypebtxon6oye5o8myu")
                .build();
Refund refund = client().sendRequest(request);

System.out.printf("Refunded amount: %d", refund.getAmount());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

charge = omise.Charge.retrieve("chrg_test_no1t4tnemucod0e51mo")

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Refund{}

err := client.Do(result, &operations.RetrieveRefund{
	ChargeID: "chrg_test_no1t4tnemucod0e51mo",
	RefundID: "rfnd_test_no1t4tnemucod0e51mo",
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Charge.retrieve_refund("chrg_test_4xso2s8ivdej29pqnhz", "rfnd_test_4zgf1d7jcw5kr123puq")