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)?_[0-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

Amount for charge in smallest currency unit.

authorize_uri string

URI for payment authorization (e.g. 3-D Secure). Present 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

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

created datetime

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

currency string

Currency for charge as three-letter ISO 4217 code.

customer object_id

CUSTOMER_ID associated with the charge.

description string

Description of the charge.

disputable boolean

Whether the charge is able to be disputed.

dispute dispute

Dispute object (if charge is disputed).

failure_code string

Failure code if status == failed. See testing for possible codes.

failure_message string

Message describing the failure if status == failed.

funding_amount integer

Amount fundable to the merchant after exchange to funding_currency (if currency != funding_currency) in the smallest currency unit.

funding_currency string

Currency of funding_amount.

ip string

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

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

refundable boolean

Whether the charge is able to be refunded.

refunded integer

Amount refunded.

refunds list

List of refund objects.

return_uri string

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.

reversed_at datetime

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

reversible boolean

Whether the charge authorization is able to be reversed.

schedule object

Schedule associated with charge.

source source

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

status string

Charge status. One of failed, expired, pending, reversed or successful.

transaction object_id

TRANSACTION_ID of 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) Offset of the first record returned (i.e. how many records to skip from the beginning).

limit integer

(optional, default: 20, maximum: 100) Number of records to return.

from datetime

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

to datetime

(optional, default: current UTC datetime) Latest UTC datetime for returned records in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

order string

(optional, default: chronological) Order in which to return records. One of 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
amount integer

(required) Amount for charge in the smallest currency unit.

capture boolean

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

card object_id

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

currency string

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

customer object_id

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

description string

(optional) Description to attach to the charge.

ip string

(optional) IP address to attach to the charge.

metadata object

(optional) Custom metadata (e.g. {"customer-id": 42}) to attach to the charge.

return_uri string

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

source object_id

(optional) Valid SOURCE_ID or source request object.

Example

  • Charge a card using a token

  • Charge a card using a customer

  • Charge a card using a customer and a card

  • Create and charge a new source

  • Create an Internet Banking charge

  • Create an Alipay charge

  • Create an Installment 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) Description to attach to the charge.

metadata object

(optional) Custom metadata (e.g. {"customer-id": 42}) 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

Mark a charge as paid in test mode

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

This endpoint allows you to manually mark a test charge as paid. This can be useful for testing purposes. Only charges with an "offline" payment flow (that is, charges from barcode_alipay, bill_payment_tesco_lotus, and econtext payment sources) support this feature for now.

Example

  • Mark a test charge as paid

Mark a charge as failed in test mode

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

This endpoint allows you to manually mark a test charge as failed. This can be useful for testing purposes. Only charges with an "offline" payment flow (that is, charges from barcode_alipay, bill_payment_tesco_lotus, and econtext payment sources) support this feature for now.

Example

  • Mark a test charge as failed