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.

Attributes

Name Type Description
object string

The string charge.

id object_id

The charge identifier 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

Charge amount in smallest unit of charge currency.

authorize_uri string

URI for payment authorization (e.g. 3-D Secure).

authorized boolean

Whether charge has been authorized.

capturable boolean

Whether charge is able to be captured (paid).

capture boolean

Whether charge is set to be automatically captured (paid).

card card

Card that was charged (if card was charged).

created datetime

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

currency currency_lowercase

Currency for charge as three-letter ISO 4217 code.

customer object_id

Customer associated with charge.

description string

Charge description.

disputable boolean

Whether charge is able to be disputed.

dispute dispute

Dispute associated with charge.

expired boolean

Whether charge has expired.

expired_at datetime

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

expires_at datetime

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

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

For multi-currency charges, amount after exchange into account funding currency (funding_currency) specified in the smallest unit of funding_currency.

For non-multi-currency charges, amount specified in the smallest unit of currency.

funding_currency currency_lowercase

Currency for account as three-letter ISO 4217 code. This is the settlement currency for all charges.

ip string

IP address provided to Omise at charge creation.

metadata object

Custom metadata (e.g. {"answer": 42}) for charge.

paid boolean

Whether charge has been captured (paid).

paid_at datetime

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

platform_fee object

Platform fee object as fixed amount and/or percentage of charge amount.

refundable boolean

Whether charge is able to be refunded.

refunded integer

Charge amount refunded.

refunds list

List of refunds.

return_uri string

URI to which customer is redirected after 3-D Secure card authorization or other redirect-based authorization.

reversed boolean

Whether charge authorization has been reversed.

reversed_at datetime

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

reversible boolean

Whether 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 generated by charge.

voided boolean

Whether, in the case of a refund, charge was voided instead. Charges are voided if refund is processed before settlement time.

Deprecated Attribute

Name Type Description
reference string

Charge reference code. Only if return_uri was set.

Example

  • JSON Response

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 errors or else a charge with failure_code set to one of the following:

failure_code Description
failed_fraud_check Card was marked as fraudulent.
failed_processing General payment processing failure.
insufficient_balance/insufficient_fund Insufficient funds in the account or the card has reached the credit limit.
invalid_account_number/invalid_account Valid account for payment method not found.
invalid_security_code Security code invalid or card did not pass preauthorization.
payment_cancelled Payment cancelled by payer.
payment_rejected Payment rejected by issuer.
stolen_or_lost_card Card stolen or lost.
timeout Payer did not take action before charge expiration.

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

Request Parameters

Name Type Description
amount integer

(required) Amount for charge in smallest currency unit. If charging a source, amount must match amount specified in the source at its creation.

currency currency

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

card object_id

(optional, but conditionally required) Unused token identifier or card identifier. If a card identifier is passed, you must also pass the identifier of the customer who owns the card under the customer parameter. If a token identifier is passed, the customer parameter must not be present.

customer object_id

(optional, but conditionally required) A valid identifier for a customer that has at least one card already associated. By default, the default card of the customer will be used. Required if passing a card identifier in the card parameter. If passing a token identifier in the card parameter, this parameter must not be present.

return_uri string

(optional, but conditionally required) URI to which customer is redirected after 3-D Secure card authorization or other redirect-based authorization. Required if account is set to use 3-D Secure or any other redirect-based authorization for payment.

source object_id

(optional, but conditionally required) Valid source identifier or source object. See Source API for source request parameters. Required if card and customer are not present.

description string

(optional, but recommended) Charge description. Supplying information about a purchase (e.g. number of items, type of items, date of delivery) helps Omise better conduct fraud analysis.

ip string

(optional, but recommended) IP address to attach to the charge. Supplying the customer's real IP address helps Omise better conduct fraud analysis.

capture boolean

(optional) Whether charge is set to be automatically captured (paid). Default: true.

expires_at datetime

(optional) UTC datetime of desired charge expiration in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ). Only supported by Convenience Store, Pay-easy, and Online Banking (Japanese) payment methods.

metadata object

(optional) Custom metadata (e.g. {"answer": 42}) for charge.

platform_fee[fixed] integer

(optional) Fixed platform fee in smallest currency unit.

platform_fee[percentage] float

(optional) Platform fee as percentage of charge amount. Note: when setting your platform_fee, be sure to include all relevant local taxes applicable to you and your sub-merchant (e.g. VAT, Withholding tax).

Example

  • Charge a card using a token

  • Charge a card using a customer

  • Charge a card using a customer and a card

  • Charge a card while adding metadata

  • Create an Alipay charge

  • Create an Installment Payment charge

  • Create and charge a new source

  • Create an Internet Banking charge

Retrieve a charge

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

Returns the charge matching :id.

Example

  • Retrieve a charge

Update a charge

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

Update attributes for a charge.

Request Parameters

Name Type Description
description string

(optional, but recommended) Charge description. Supplying information about a purchase (e.g. number of items, type of items, date of delivery) helps Omise better conduct fraud analysis.

metadata object

(optional) Custom metadata (e.g. {"answer": 42}) for charge.

Example

  • Update charge metadata

  • Update charge description

List charges

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

Returns a list of charges belonging to your account.

Request Parameters

Name Type Description
from datetime

(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, maximum: 100) 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) Order of records returned. One of chronological (earliest to latest) or reverse_chronological (latest to earliest).

to datetime

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

Example

  • List all charges

Capture a charge

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

Capture a charge that has not yet been captured (parameter capture=false passed at charge creation). Posting to this endpoint after charge expiration will result in an expired charge error. Any other issue processing capture will result in an failed capture error.

Example

  • Capture a charge

Expire a charge

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

Set a charge that has not yet been authorized (status=pending) to expire. Supported by charges with source[type]=barcode_alipay.

Example

  • Expire a charge

List events

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

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

Request Parameters

Name Type Description
from datetime

(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, maximum: 100) 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) Order of records returned. One of chronological (earliest to latest) or reverse_chronological (latest to earliest).

to datetime

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

Example

  • List charge events

Mark a charge as failed

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

Mark a test charge as failed. Not supported by all payment methods.

Example

  • Mark a test charge as failed

Mark a charge as paid

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

Mark a test charge as paid. Not supported by all payment methods.

Example

  • Mark a test charge as paid

Reverse a charge

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

Reverse a charge that has not yet been captured (parameter capture=false passed at charge creation).

Example

  • Reverse an uncaptured charge