Charging a Credit Card

This article explains how to charge a credit card using the Omise API.

The direct charge example requires you to first collect your customer card information in a token. All tokens are for one-time use, so you must choose wisely between charging the card directly or associating that card with a customer for future use.

The main advantage of attaching a card to a customer is that it allows you to charge their card more than once. Recurring customers can benefit from not having to repeatedly type their card details for every purchase.

Charging the Card Directly

This is the easiest way to charge a card. Once you receive a card token, send it to our charges API with the amount you want to charge. Within a few seconds, the card will be charged.

Note: The token is voided after use. You will not be able to charge the card or create a customer with it again.

Here's an example using the Omise Ruby library:

charge = Omise::Charge.create({
  amount: 100025,
  currency: "thb",
  description: "Order-345678",
  return_uri: "http://localhost/orders/345678/complete",
  card: params[:omise_token]
})

return_uri — The URL used to redirect your customer when 3-D Secure is enabled.

Charging a Customer

Creating a customer with a token lets you charge a card multiple times. Using the customers API, you can build checkout flows where customers do not have to re-enter their card information on every purchase. This significantly reduces cart abandonment.

There are two ways to charge a customer.

Charging the Default Card

Pass only the customer ID to charge the default card. This approach works best when each customer has a single card on file.

charge = Omise::Charge.create({
  amount: 100025,
  currency: "thb",
  description: "Order-345678",
  return_uri: "http://localhost/orders/345678/complete",
  customer: user.omise_customer_id
})

Charging a Specific Card

Pass both the customer ID and the specific card ID when a customer has multiple cards attached to their account.

Note: Unlike charging a card directly with a token, you must pass the actual card ID rather than the token ID. See list all customer cards and the pagination documentation for instructions on retrieving a customer's card list.

charge = Omise::Charge.create({
  amount: 100025,
  currency: "thb",
  description: "Order-345678",
  return_uri: "http://localhost/orders/345678/complete",
  customer: customer.omise_id,
  card: customer.cards.find_by(id: params[:id]).omise_id
})

Charge Statuses

With 3-D Secure Enabled

With 3-D Secure Disabled

Limits

Thailand

Singapore

Malaysia

Japan

FAQ

Q: Can I reuse a card token?
No. Tokens are single-use. Once a token has been used to create a charge or a customer, it is immediately voided and cannot be used again.

Q: What is the difference between charging a card directly and charging a customer?
Charging a card directly using a token is a one-time transaction. Charging a customer stores the card against a customer record, allowing you to charge the same card multiple times without requiring the customer to re-enter their details.

Q: Can a customer have more than one card?
Yes. You can attach multiple cards to a single customer. When creating a charge, specify the card ID alongside the customer ID to charge a particular card. If no card ID is provided, the default card is charged.

Q: What should I do if a charge fails?
Check the failure_code and failure_message fields returned in the charge object. These provide the reason for the failure, such as insufficient funds or a declined card.

Q: What is 3-D Secure and when is it triggered?
3-D Secure (3DS) is an additional authentication step that some card issuers require before authorizing a charge. When triggered, the customer is redirected to their bank's verification page and then returned to the return_uri you specified. See the 3-D Secure documentation for details.

Q: What happens if a charge is left in pending status?
A pending charge that is awaiting manual capture will expire if no capture action is taken within the holding period. The charge will move to expired status and the held amount will be released.

Q: How do I retrieve a list of cards for a customer?
Use the list all customer cards endpoint. Refer to the pagination documentation for instructions on handling paginated results.

Q: Are there minimum and maximum charge amounts?
Yes. Limits vary by country and currency. See the Limits section above for values by region.