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.

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

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

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.

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

  • Charge a card using a customer

  • Charge a card using a customer and a card

Retrieve a charge

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

Example

  • Retrieve a 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.

Example

  • Update a charge description

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

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