Charge API

The Charge API is the most important of all. Whenever you create a charge, Omise sends the order to charge the given amount on the card. This API offers various ways to decide which card is charged and whether it is charged right away or if the amount is held for you to capture later.

Attribute

Name	Type	Description
object	string	The string `charge`.
id	object_id	A `CHARGE_ID` matching `/chrg(_test)?_[1-9a-z]+/`.
livemode	boolean	Whether this is a live (`true`) or test (`false`) charge.
location	string	Path to retrieve the charge.
status	string	The charge status. Value can one be one of `failed`, `pending`, `reversed` or `successful`.
amount	integer	A positive integer in the amount charged in the smallest currency unit. (e.g. 100 satangs to charge THB 1) The minimum charge amount is THB 20 and the maximum is THB 1000000. #Maximum and Minimum amount by supported currencies
currency	string	The currency as its lower-cased international 3-letter code, defined by the ISO 4217 standard. #Supported Currencies
description	string	The charge description as received.
metadata	Hash	Metadata JSON hash.
capture	boolean	Whether the charge is set to be auto-captured or not.
authorized	boolean	Whether the charge has been authorized or not.
reversed	boolean	Whether the charge has been reversed authorization or not.
paid	boolean	Whether the charge has been paid for or not.
transaction	string	The `TRANSACTION_ID` of that charge.
card	card	The card object that was charged.
refunded	integer	An amount of money that has been refunded.
refunds	list	A list of refund objects.
failure_code	string	A failure code.
failure_message	string	A short explanation about the failure message.
customer	string	The `CUSTOMER_ID` to which the charge belongs.
ip	string	The customer IP, as sent to Omise.
dispute	dispute	If the charge is disputed, this contains the `dispute` object.
created	datetime	Creation date of the charge in ISO 8601 format.
return_uri	string	The url where the customer is redirected after authorization with 3-D Secure.
authorize_uri	string	Url for charge authorization using 3-D Secure and Internet Banking. Only if `return_uri` was set.

Deprecated Attribute

Name	Type	Description
reference	string	Charge reference code. Only if `return_uri` was set.

Example

Json Response

{
  "object": "charge",
  "id": "chrg_test_5086xlsx4lghk9bpb75",
  "livemode": false,
  "location": "/charges/chrg_test_5086xlsx4lghk9bpb75",
  "amount": 100000,
  "currency": "thb",
  "description": null,
  "capture": true,
  "authorized": true,
  "reversed": false,
  "paid": true,
  "transaction": "trxn_test_5086xltqqbv4qpmu0ri",
  "refunded": 0,
  "refunds": {
    "object": "list",
    "from": "1970-01-01T00:00:00+00:00",
    "to": "2015-06-02T05:41:49+00:00",
    "offset": 0,
    "limit": 20,
    "total": 0,
    "data": [

    ],
    "location": "/charges/chrg_test_5086xlsx4lghk9bpb75/refunds"
  },
  "failure_code": null,
  "failure_message": null,
  "card": {
    "object": "card",
    "id": "card_test_5086xl7amxfysl0ac5l",
    "livemode": false,
    "location": "/customers/cust_test_5086xleuh9ft4bn0ac2/cards/card_test_5086xl7amxfysl0ac5l",
    "country": "us",
    "city": "Bangkok",
    "postal_code": "10320",
    "financing": "",
    "last_digits": "4242",
    "brand": "Visa",
    "expiration_month": 10,
    "expiration_year": 2018,
    "fingerprint": "mKleiBfwp+PoJWB/ipngANuECUmRKjyxROwFW5IO7TM=",
    "name": "Somchai Prasert",
    "security_code_check": true,
    "created": "2015-06-02T05:41:46Z"
  },
  "customer": "cust_test_5086xleuh9ft4bn0ac2",
  "ip": null,
  "dispute": null,
  "created": "2015-06-02T05:41:49Z"
}

List all charges

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

Returns a list of charge objects.

Return all charges that belongs to your account since the beginning of time. You can learn more about lists in the pagination documentation.

Query Parameter

Name	Type	Description
offset	integer	(optional, default: 0) The offset of the first record returned. I.e.: How many records to skip from the beginning.
limit	integer	(optional, default: 20, maximum: 100) The maximum amount of records returned.
from	datetime	(optional, default: `1970-01-01T00:00:00Z`, format: ISO 8601) The UTC date and time limiting the beginning of returned records. E.g.: `2014-10-20T00:00:00Z`
to	datetime	(optional, default: current UTC Datetime, format: ISO 8601) The UTC date and time limiting the end of returned records. E.g.: `2015-01-20T00:00:00Z`
order	string	(optional, default: chronological) The order of the list returned. I.e.: `chronological` (from earliest to latest), `reverse_chronological` (from latest to earliest).

Example

List all charges

curl
ruby
python
php
C#
node.js
java
go

curl -X GET https://api.omise.co/charges \
  -u skey_test_4xsjvwfnvb2g0l81sjz:

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

charges = Omise::Charge.list

import omise

omise.api_secret = 'skey_test_4xs8breq3htbkj03d2x'

charges = omise.Charge.retrieve()

<?php

$charges = OmiseCharge::retrieve();

var charges = await Client.Charges.GetList(order: Ordering.Chronological);
Console.WriteLine($"total charges: {charges.Total}");

omise.charges.list(function(error, list) {
  /* Response. */
});

ScopedList<Charge> charges = client.charges().list();
System.out.printf("returned charges: %d", charges.getData().size());
System.out.printf("total no. of charges: %d", charges.getTotal());

charges, list := &omise.ChargeList{}, &operations.ListCharge{
	operations.List{
		Limit: 100,
		From:  time.Now().Add(-1 * time.Hour),
	},
}

if e := client.Do(charges, list); e != nil {
	log.Fatalln(e)
}

log.Println("# of charges made in the last hour:", len(charges.Data))

Create a charge

- POST https://api.omise.co/charges

Posting to this endpoint will either authorize or capture an amount of money on a card. The card on which the money is taken depends if the card is passed with a token, with a customer, or with both a customer and a card.

In case the charge fails to process the failure code attribute will be filled with one the following codes:

Code	Description
`insufficient_fund`	Insufficient funds in the account or the card has reached the credit limit.
`stolen_or_lost_card`	Card is stolen or lost.
`failed_processing`	Card processing has failed, you may retry this transaction.
`payment_rejected`	The payment was rejected by the issuer or the acquirer with no specific reason.
`invalid_security_code`	The security code was invalid or the card didn't pass preauth.
`failed_fraud_check`	Card was marked as fraudulent.
`invalid_account_number`	This number is not attributed or has been deactivated.

Request Parameter

Name	Type	Description
customer	object_id	(required or optional) A valid `CUSTOMER_ID` that has at least one card already associated. By default the default card of the customer will be used. This parameter is required unless passing a `TOKEN_ID` in the card parameter.
card	object_id	(required or optional) A valid unused `TOKEN_ID` or `CARD_ID`. In the case of the `CARD_ID` the customer parameter must be present and be the owner of the card. For the `TOKEN_ID`, the customer must not be passed.
amount	integer	(required, minimum: 2000, maximum: 100000000) The amount in the smallest subunits of the currency used. For `thb` (Thai Baht) you'll need to pass the amount in satangs. #Maxmum and Minimum amount by supported currencies
currency	string	(required) The currency in which you want the charge to be done. The default and only valid value is `thb`. #Supported Currencies
description	string	(optional) A custom description for the charge. This value can be searched for in your dashboard.
metadata	Hash	(optional) Any JSON hash you would like to attach to this charge. You can use this key to store order ID or internal reference ID.
capture	boolean	(optional) Whether or not you want the charge to be captured right away, when not specified it is set to `true`.
return_uri	url	(optional) The url where we will return the customer after the charge has been authorized with 3-D Secure.

Example

Charge a card using a token

curl
ruby
python
php
C#
node.js
java
go

curl https://api.omise.co/charges \
  -X POST \
  -u skey_test_4xsjvwfnvb2g0l81sjz: \
  -d "amount=100000" \
  -d "currency=thb" \
  -d "card=tokn_test_4xs9408a642a1htto8z"

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

charge = Omise::Charge.create({
  amount: 100000,
  currency: "thb",
  card: "tokn_test_4xs9408a642a1htto8z"
})

import omise

omise.api_secret = 'skey_test_4xs8breq3htbkj03d2x'

charge = omise.Charge.create(
  amount=100000,
  currency="thb",
  card="tokn_test_4xs9408a642a1htto8z"
)

<?php

$charge = OmiseCharge::create(array(
  'amount' => 100000,
  'currency' => 'thb',
  'card' => 'tokn_test_4xs9408a642a1htto8z'
));

var token = await RetrieveToken();
var charge = await Client.Charges.Create(new CreateChargeRequest
{
    Amount = 2000,
    Currency = "thb",
    Card = token.Id,
    Metadata = new Dictionary<string, object>
    {
        { "order_id", "123" }
    }
});

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

omise.charges.create({
  'amount': '100000',
  'currency': 'thb',
  'card': 'tokn_test_4xs9408a642a1htto8z'
}, function(err, charge) {
  /* Response. */
});

Charge charge = client.charges()
  .create(new Charge.Create()
          .amount(100000) // 1,000 THB
          .currency("thb")
          .card("tokn_test_4xs9408a642a1htto8z"));
System.out.printf("created charge: %s", charge.getId());

charge, create := &omise.Charge{}, &operations.CreateCharge{
	Amount:   204842, // THB 2,048.42
	Currency: "thb",
	Card:     "tokn_test_4xs9408a642a1htto8z",
}

if e := client.Do(charge, create); e != nil {
	log.Fatalln(e)
}

log.Printf("created charge: %#v\n", charge)

Charge a card using a customer

curl
ruby
python
php
C#
node.js
java
go

curl https://api.omise.co/charges \
  -X POST \
  -u skey_test_4xsjvwfnvb2g0l81sjz: \
  -d "amount=100000" \
  -d "currency=thb" \
  -d "customer=cust_test_4xtrb759599jsxlhkrb"

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

charge = Omise::Charge.create({
  amount: 100000,
  currency: "thb",
  customer: "cust_test_4xtrb759599jsxlhkrb"
})

import omise

omise.api_secret = 'skey_test_4xs8breq3htbkj03d2x'

charge = omise.Charge.create(
  amount=100000,
  currency="thb",
  customer="cust_test_4xtrb759599jsxlhkrb"
)

<?php

$charge = OmiseCharge::create(array(
  'amount' => 100000,
  'currency' => 'thb',
  'customer' => 'cust_test_4xtrb759599jsxlhkrb'
));

var customerId = "cust_test_5665swqhhb3mioax1y7";
var charge = await Client.Charges.Create(new CreateChargeRequest
{
    Amount = 2000,
    Currency = "thb",
    Customer = customerId,
});

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

omise.charges.create({
  'amount': '100000',
  'currency': 'thb',
  'customer': 'cust_test_4xtrb759599jsxlhkrb'
}, function(error, charge) {
  /* Response. */
});

Charge charge = client.charges()
  .create(new Charge.Create()
          .amount(100000) // 1,000 THB
          .currency("thb")
          .customer("cust_test_4xtrb759599jsxlhkrb"));
System.out.printf("created charge: %s", charge.getId());

charge, create := &omise.Charge{}, &operations.CreateCharge{
	Amount:   204842, // THB 2,048.42
	Currency: "thb",
	Customer: "cust_test_4xtrb759599jsxlhkrb",
}

if e := client.Do(charge, create); e != nil {
	log.Fatalln(e)
}

log.Printf("created charge: %#v\n", charge)

Charge a card using a customer and a card

curl
ruby
python
php
C#
node.js
java
go

curl https://api.omise.co/charges \
  -X POST \
  -u skey_test_4xsjvwfnvb2g0l81sjz: \
  -d "amount=100000" \
  -d "currency=thb" \
  -d "customer=cust_test_4xtrb759599jsxlhkrb" \
  -d "card=card_test_4xtsoy2nbfs7ujngyyq"

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

charge = Omise::Charge.create({
  amount: 100000,
  currency: "thb",
  customer: "cust_test_4xtrb759599jsxlhkrb",
  card: "card_test_4xtsoy2nbfs7ujngyyq"
})

import omise

omise.api_secret = 'skey_test_4xs8breq3htbkj03d2x'

charge = omise.Charge.create(
  amount=100000,
  currency="thb",
  customer="cust_test_4xtrb759599jsxlhkrb",
  card="card_test_4xtsoy2nbfs7ujngyyq"
)

<?php

$charge = OmiseCharge::create(array(
  'amount' => 100000,
  'currency' => 'thb',
  'customer' => 'cust_test_4xtrb759599jsxlhkrb',
  'card' => 'card_test_4xtsoy2nbfs7ujngyyq'
));

var customerId = "cust_test_5665swqhhb3mioax1y7";
var cardId = "card_test_5665swpkm6tv47htmuv";
var charge = await Client.Charges.Create(new CreateChargeRequest
{
    Amount = 2000,
    Currency = "thb",
    Customer = customerId,
    Card = cardId,
});

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

omise.charges.create({
  'amount': '100000',
  'currency': 'thb',
  'customer': 'cust_test_4xtrb759599jsxlhkrb',
  'card': 'card_test_52ydv7jkwu6rp6qt96m'
}, function(error, charge) {
  /* Response. */
});

Charge charge = client.charges()
  .create(new Charge.Create()
          .amount(100000) // 1,000 THB
          .currency("thb")
          .customer("cust_test_4xtrb759599jsxlhkrb")
          .card("card_test_4xtsoy2nbfs7ujngyyq"));
System.out.printf("created charge: %s", charge.getId());

charge, create := &omise.Charge{}, &operations.CreateCharge{
	Amount:      204842, // THB 2,048.42
	Currency:    "thb",
	Description: "example charge.",
	Card:        "card_test_4xtsoy2nbfs7ujngyyq",
}

if e := client.Do(charge, create); e != nil {
	log.Fatalln(e)
}

log.Println("created charge: %#v\n", charge)

Retrieve a charge

- GET https://api.omise.co/charges/CHARGE_ID

Example

Retrieve a charge

curl
ruby
python
php
C#
node.js
java
go

curl https://api.omise.co/charges/chrg_test_4xso2s8ivdej29pqnhz \
  -u skey_test_4xsjvwfnvb2g0l81sjz:

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

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

import omise

omise.api_secret = 'skey_test_4xs8breq3htbkj03d2x'

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

<?php

$charge = OmiseCharge::retrieve("chrg_test_4xso2s8ivdej29pqnhz");

var chargeId = "chrg_test_58e1ybdog1y8f5z97l8";
var charge = await Client.Charges.Get(chargeId);
Console.WriteLine($"charge amount: {charge.Amount}");

omise.charges.retrieve('chrg_test_4xso2s8ivdej29pqnhz', function(error, charge) {
  /* Response. */
});

Charge charge = client.charges().get("chrg_test_4xso2s8ivdej29pqnhz");
System.out.printf("charge amount: %d", charge.getAmount());

charge, retrieve := &omise.Charge{}, &operations.RetrieveCharge{"chrg_test_4xso2s8ivdej29pqnhz"}
if e := client.Do(charge, retrieve); e != nil {
	log.Fatalln(e)
}

log.Printf("retrieved charge: %#v\n", charge)

Update a charge

- PATCH https://api.omise.co/charges/CHARGE_ID

Update a charge. At this time the only charge attribute that can be modified is its description.

Request Parameter

Name	Type	Description
description	string	(optional) A custom description for the charge. This value can be searched for in your dashboard.
metadata	Hash	(optional) Any JSON hash you would like to attach to this charge. You can use this key to store order ID or internal reference ID.

Example

Update a charge description

curl
ruby
python
php
C#
node.js
java
go

curl https://api.omise.co/charges/chrg_test_4xso2s8ivdej29pqnhz \
  -X PATCH \
  -u skey_test_4xsjvwfnvb2g0l81sjz: \
  -d "description=Another description"

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

charge = Omise::Charge.retrieve("chrg_test_4xso2s8ivdej29pqnhz")
charge.update(description: "Another description")

import omise

omise.api_secret = 'skey_test_4xs8breq3htbkj03d2x'

charge = omise.Charge.retrieve("chrg_test_4xso2s8ivdej29pqnhz")
charge.update(description="Another description")

# Or alternatively:
charge.description = "Another description"
charge.update()

<?php

$charge = OmiseCharge::retrieve('chrg_test_4xso2s8ivdej29pqnhz');
$charge->update(array(
  'description' => 'Another description'
));

var charge = RetrieveUncapturedCharge();
charge = await Client.Charges.Update(charge.Id, new UpdateChargeRequest
{
    Description = "hello",
    Metadata = new Dictionary<string, object>
    {
        { "order_id", "123" },
    }
});

Console.WriteLine($"updated charge: {charge.Id} {charge.Description}");

omise.charges.update(
  'chrg_test_4xso2s8ivdej29pqnhz',
  {description: 'Another description'},
  function(error, charge) {
    /* Response. */
  }
);

Charge charge = client.charges()
  .update("chrg_test_4xso2s8ivdej29pqnhz", new Charge.Update()
          .description("updated description"));
System.out.printf("updated description: %s", charge.getDescription());

charge, update := &omise.Charge{}, &operations.UpdateCharge{
	ChargeID:    "chrg_test_4xso2s8ivdej29pqnhz",
	Description: "Made on Monday",
}

if e := client.Do(charge, update); e != nil {
	log.Fatalln(e)
}

log.Printf("updated charge: %#v\n", charge)

Capture an authorized charge

- POST https://api.omise.co/charges/CHARGE_ID/capture

If you have created a charge and passed capture=false, you'll have an authorized only charge that you can capture anytime within 7 days. After that, the charge will expire.

Example

Capture an authorized charge

curl
ruby
python
php
C#
node.js
java
go

curl https://api.omise.co/charges/chrg_test_4xso2s8ivdej29pqnhz/capture \
  -X POST \
  -u skey_test_4xsjvwfnvb2g0l81sjz:

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

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

import omise

omise.api_secret = 'skey_test_4xs8breq3htbkj03d2x'

charge = omise.Charge.retrieve("chrg_test_4xso2s8ivdej29pqnhz")
charge.capture()

<?php

$charge = OmiseCharge::retrieve('chrg_test_4xso2s8ivdej29pqnhz');
$charge->capture();

var charge = RetrieveUncapturedCharge();
charge = await Client.Charges.Capture(charge.Id);
Console.WriteLine($"captured charge: ({charge.Paid}) {charge.Id}");

omise.charges.capture('chrg_test_4xso2s8ivdej29pqnhz', function(error, charge) {
  /* Response. */
});

Charge charge = client.charges().capture("chrg_test_4xso2s8ivdej29pqnhz");
System.out.printf("captured charge: %s",charge.getId());

charge, capture := &omise.Charge{}, &operations.CaptureCharge{
	ChargeID: "chrg_test_4xso2s8ivdej29pqnhz",
}

if e := client.Do(charge, capture); e != nil {
	log.Fatalln(e)
}

log.Printf("captured charge: %#v\n", charge)

Reverse an uncaptured charge

- POST https://api.omise.co/charges/CHARGE_ID/reverse

If you have created a charge and passed capture=false you'll have an authorized only charge that can be reversed, release hold money, at a later time.

Example

Reverse an uncaptured charge

curl
ruby
python
php
C#
node.js
java
go

curl https://api.omise.co/charges/chrg_test_4xso2s8ivdej29pqnhz/reverse \
  -X POST \
  -u skey_test_4xsjvwfnvb2g0l81sjz:

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

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

import omise

omise.api_secret = 'skey_test_4xs8breq3htbkj03d2x'

charge = omise.Charge.retrieve("chrg_test_4xso2s8ivdej29pqnhz")
charge.reverse()

$charge = OmiseCharge::retrieve('chrg_test_4xso2s8ivdej29pqnhz');
$charge->reverse();

var charge = RetrieveUncapturedCharge();
charge = await Client.Charges.Reverse(charge.Id);
Console.WriteLine($"reversed charge: ({charge.Reversed}) {charge.Id}");

omise.charges.reverse('chrg_test_4xso2s8ivdej29pqnhz', function(error, charge) {
  /* Response. */
});

Charge charge = client.charges().reverse("chrg_test_4xso2s8ivdej29pqnhz");
System.out.printf("charge reversal: %s", Boolean.toString(charge.isReversed()));

// Not available yet