Charge API

The Charge API allows you to create, retrieve, and update a charge for a given amount in a given currency to a given card, customer (i.e. a customer's default card), or source. Authorized charges can be deferred for later capture, and uncaptured charges can be reversed. Custom metadata can be appended to charges.

Attribute

Name Type Description
object string

The string charge.

id object_id

The CHARGE_ID matching /chrg(_test)?_[1-9a-z]+/.

livemode boolean

Whether this is a live (true) or test (false) charge.

location string

API path to retrieve the current charge object.

amount integer

The amount expressed as a positive integer in the smallest unit for a given currency (e.g. 100 satangs equals THB 1). See supported currencies by country for maximum and minimum.

authorize_uri string

The URI for authorization (e.g. 3-D Secure in the case of cards). Only if return_uri was set.

authorized boolean

Whether the charge has been authorized.

capturable boolean

Whether the charge is able to be captured.

capture boolean

Whether the charge is set to be auto-captured.

card card

The card object that was charged (if a card was charged).

created datetime

The UTC datetime of the creation of the charge in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

currency string

The currency expressed as its lower-cased international 3-letter code defined by the ISO 4217 standard (see supported currencies by country).

customer object_id

The CUSTOMER_ID associated with the charge.

description string

The human-readable description of the charge.

disputable boolean

Whether the charge is able to be disputed.

dispute dispute

The dispute object (if the charge is disputed).

failure_code string

The failure code if status == failed. See testing for possible codes.

failure_message string

The human-readable message describing the failure if status == failed.

funding_amount integer

The amount expressed as a positive integer in the smallest unit of the merchant's currency.

funding_currency string

The currency of funding_amount.

ip string

The customer IP provided to Omise.

metadata Object

Custom metadata (e.g. {"customer-id": 42}) for charge.

paid boolean

Whether the charge has been paid.

paid_at datetime

The UTC datetime the charge was paid in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

refundable boolean

Whether the charge is able to be refunded.

refunded integer

The amount of money that has been refunded.

refunds list

A list of refund objects.

return_uri string

The URI to which the customer is redirected after authorization (e.g. 3-D Secure in the case of cards).

reversed boolean

Whether the charge authorization has been reversed.

reversible boolean

Whether the charge authorization is able to be reversed.

source Source

The source that was charged (if a source was charged).

status string

The charge status. One of failed, expired, pending, reversed or successful.

transaction object_id

The TRANSACTION_ID of the charge.

voided boolean

Whether the charge has been voided.

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 all charge objects belonging to your account.

Request 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 number of records returned.

from datetime

(optional, default: 1970-01-01T00:00:00Z) The earliest UTC date and time for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

to datetime

(optional, default: current UTC datetime) The latest UTC date and time for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

order string

(optional, default: chronological) The order of the list returned. Either chronological (earliest to latest) or reverse_chronological (latest to earliest).

Example

  • List all charges

Create a charge

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

Successfully posting to this endpoint will either authorize a charge on a card (for later capture) or directly capture a charge from a card or source.

In case the charge fails, this endpoint will either return one of several error objects or else a charge object with failure_code set to one of the following:

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 did not pass preauth.
failed_fraud_check Card was marked as fraudulent.
invalid_account_number This number is not attributed or has been deactivated.

When testing credit cards charges, you can make the API return the above responses using special test credit card numbers.

Request Parameter

Name Type Description
customer object_id

(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 or SOURCE_ID in the appropriate parameter.

card object_id

(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.

source object_id

(optional) A valid SOURCE_ID.

amount integer

(required, minimum: 2000, maximum: 100000000) The amount in the smallest subunits of the currency used. If you are charging a source, the amount specified here must match the amount specified in the source at its creation.

currency string

(required) The currency for the charge. If you are charging a source, the currency must match the currency specified in the source at its creation.

return_uri string

(optional) Required if source is specified. The URI to which the customer is redirected after payment authorization (e.g. 3-D Secure in the case of cards).

description string

(optional) A custom description for the charge. This value can be searched for in your dashboard.

metadata Object

(optional) Custom metadata (e.g. internal reference ID) you would like to attach to the charge.

capture boolean

(optional, default: true) Whether or not you want the charge to be captured right away.

ip string

(optional) The IP address you would like to attach to this charge.

Example

  • Charge a card using a token

  • Charge a card using a customer

  • Charge a card using a customer and a card

  • Create an offsite internet banking charge

  • Create an offsite Alipay charge

  • Create an installment payment charge

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 attributes that can be modified are its description and metadata.

Request Parameter

Name Type Description
description string

(optional) A custom description for the charge. This value can be searched for in your dashboard.

metadata Object

(optional) Custom metadata (e.g. internal reference ID) you would like to attach to the charge.

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 can be captured anytime within 7 days. After that, the charge will expire and posting to this endpoint will result in an expired charge error. Any other failure will result in an failed capture error

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 (i.e. the amount released), at a later time.

Example

  • Reverse an uncaptured charge