Atome App Redirection

Accept online payments from Atome users through your website using the Atome payment method.

Atome is a buy now, pay later (BNPL) service that lets customers split a purchase into installments. This document covers the online redirect checkout flow, where the customer authorizes payment on Atome's hosted checkout page. For the in-person, QR-code-based flow, see Atome QR.

This guide walks you through the payment flow and details how to implement it.

🔓 How to enable

• Supported Countries: Thailand, Singapore, Malaysia
• Minimum API version: 2017-11-02

To enable Atome, send an email requesting this feature to support@omise.co. You will need to review and accept new terms and conditions.

💳 Payment flow

Atome supports payments on both desktop and mobile websites. Customers paying via Atome go through a redirect payment flow: they are redirected from your website to Atome's secure checkout page, where they authorize and confirm the payment. The following screenshots demonstrate the flow throughout the journey.

Payment via desktop

❶ The customer pays with Atome ❷ and gets redirected to Atome's secure checkout page. ❸ The customer opens the Atome app on their phone and scans the QR on the payment page with their app. ❹ The customer is then presented with the installment plan and confirms the payment. ❺ After completing the payment, the customer is automatically redirected to the merchant's payment confirmation page.

Payment via mobile (payment via browser)

❶ The customer pays with Atome ❷ and gets redirected to Atome's secure checkout page. ❸ The customer clicks to pay in the browser. ❹ The customer is presented with a login form. ❺ After the customer logs in, they are presented with the installment plan. ❻ The customer confirms the payment and is automatically redirected to the merchant's payment confirmation page.

Payment via mobile (payment via app)

❶ The customer pays with Atome ❷ and gets redirected to Atome's secure checkout page. ❸ The customer clicks to pay using an app. ❹ The customer is redirected to their app and presented with the installment plan. ❺ The customer confirms the payment and is automatically redirected to the merchant's payment confirmation page.

🛠️ Implementation

To create a charge using Atome, make the following API requests.

1. Create a payment source (type: atome) using Omise.js or one of the mobile SDKs (iOS and Android).
2. Create a charge using the identifier of the source created in Step 1.
3. After receiving the charge completion webhook event, retrieve the charge to verify its status (optional, but recommended).

Use your public key to create the Atome source on the client (a customer's browser or mobile phone). Use your secret key to create the Atome charge on the server.

Creating an Atome source

When the customer confirms that they wish to pay with this payment method, create a source specifying the amount, currency, items, phone_number, shipping, and type.

The following examples demonstrate the creation of a new Atome source for ฿500. Replace the omise_public_key and $OMISE_PUBLIC_KEY variables with the test public key on your dashboard.

Omise.setPublicKey(omise_public_key);

Omise.createSource('atome', {
  "amount": 50000,
  "currency": "THB",
  "phone_number": "+66876543210",
  "shipping":
    {
      "street1": "1448/4 Praditmanutham Road",
      "postal_code": "10320",
      "country": "TH"
    },
  "items":
    [
      {
        "sku": "AAA111",
        "name": "water bottle",
        "amount": 25000,
        "quantity": 2
      }
    ],
}, function(statusCode, response) {
  console.log(response)
});

For testing, you can create the same request using curl.

curl https://api.omise.co/sources \
  -u $OMISE_PUBLIC_KEY: \
  -d "amount=50000" \
  -d "currency=THB" \
  -d "type=atome" \
  --data-urlencode "phone_number=+66876543210" \
  -d "shipping[postal_code]=10320" \
  -d "shipping[country]=TH" \
  -d "shipping[street1]=1448/4 Praditmanutham Road" \
  -d "items[0][sku]=AAA111" \
  -d "items[0][name]=water bottle" \
  -d "items[0][quantity]=2" \
  -d "items[0][amount]=25000"

{
  "object": "source",
  "id": "src_test_5vz4s25jpdlpt9ggmem",
  "livemode": false,
  "location": "/sources/src_test_5vz4s25jpdlpt9ggmem",
  "amount": 50000,
  "barcode": null,
  "bank": null,
  "created_at": "2023-06-02T08:53:34Z",
  "currency": "THB",
  "email": null,
  "flow": "redirect",
  "installment_term": null,
  "absorption_type": null,
  "name": null,
  "mobile_number": "+66876543210",
  "phone_number": "+66876543210",
  "platform_type": null,
  "scannable_code": null,
  "billing": null,
  "shipping": {
    "city": null,
    "country": "TH",
    "postal_code": "10320",
    "state": null,
    "street1": "1448/4 Praditmanutham Road",
    "street2": null
  },
  "items": [
    {
      "sku": "AAA111",
      "name": "water bottle",
      "brand": null,
      "category": null,
      "amount": 25000,
      "quantity": 2,
      "item_uri": null,
      "image_uri": null
    }
  ],
  "references": null,
  "store_id": null,
  "store_name": null,
  "terminal_id": null,
  "type": "atome",
  "zero_interest_installments": null,
  "charge_status": "unknown",
  "receipt_amount": null,
  "discounts": []
}

The id attribute is the source identifier (begins with src).

Creating an Atome Thailand source without shipping

Since shipping is optional for Thailand, you can omit it entirely when creating a Thailand source.

curl https://api.omise.co/sources \
  -u $OMISE_PUBLIC_KEY: \
  -d "amount=50000" \
  -d "currency=THB" \
  -d "type=atome" \
  --data-urlencode "phone_number=+66876543210" \
  -d "items[0][sku]=AAA111" \
  -d "items[0][name]=water bottle" \
  -d "items[0][quantity]=2" \
  -d "items[0][amount]=25000"

The response is the same as for a Thailand source with shipping supplied, except shipping is null. Some fields are omitted below for brevity — the full response includes all the same fields shown in the first example.

{
  "object": "source",
  "id": "src_test_5vz4s25jpdlpt9ggmem",
  "livemode": false,
  "location": "/sources/src_test_5vz4s25jpdlpt9ggmem",
  "amount": 50000,
  "currency": "THB",
  "flow": "redirect",
  "mobile_number": "+66876543210",
  "phone_number": "+66876543210",
  "billing": null,
  "shipping": null,
  "items": [
    {
      "sku": "AAA111",
      "name": "water bottle",
      "amount": 25000,
      "quantity": 2
    }
  ],
  "type": "atome",
  "charge_status": "unknown"
}

Creating an Atome charge

Create a charge specifying the parameters return_uri, source, amount, and currency.

• return_uri specifies the location on your website to which the customer should be redirected after completing the payment authorization step. Requirement: the URL must be in HTTPS format.
• source specifies the source identifier.
• amount and currency must match the source's amount and currency.

The following example demonstrates how to create a charge using curl. Replace $OMISE_SECRET_KEY with the test secret key on your dashboard. Replace $SOURCE_ID with the id of the source.

curl https://api.omise.co/charges \
  -u $OMISE_SECRET_KEY: \
  -d "amount=50000" \
  -d "currency=THB" \
  -d "return_uri=http://example.com/orders/345678/complete" \
  -d "source=$SOURCE_ID"

{
  "object": "charge",
  "id": "chrg_test_5vz4s29fbc4obd1tym0",
  "location": "/charges/chrg_test_5vz4s29fbc4obd1tym0",
  "amount": 50000,
  "net": 47250,
  "fee": 2750,
  "fee_vat": 0,
  "interest": 0,
  "interest_vat": 0,
  "funding_amount": 50000,
  "refunded_amount": 0,
  "transaction_fees": {
    "fee_flat": "0.0",
    "fee_rate": "5.5",
    "vat_rate": "0.0"
  },
  "platform_fee": {
    "fixed": null,
    "amount": null,
    "percentage": null
  },
  "currency": "THB",
  "funding_currency": "THB",
  "ip": null,
  "refunds": {
    "object": "list",
    "data": [],
    "limit": 20,
    "offset": 0,
    "total": 0,
    "location": "/charges/chrg_test_5vz4s29fbc4obd1tym0/refunds",
    "order": "chronological",
    "from": "1970-01-01T00:00:00Z",
    "to": "2023-06-02T08:53:35Z"
  },
  "link": null,
  "description": null,
  "metadata": {},
  "card": null,
  "source": {
    "object": "source",
    "id": "src_test_5vz4s25jpdlpt9ggmem",
    "livemode": false,
    "location": "/sources/src_test_5vz4s25jpdlpt9ggmem",
    "amount": 50000,
    "barcode": null,
    "bank": null,
    "created_at": "2023-06-02T08:53:34Z",
    "currency": "THB",
    "email": null,
    "flow": "redirect",
    "installment_term": null,
    "absorption_type": null,
    "name": null,
    "mobile_number": "+66876543210",
    "phone_number": "+66876543210",
    "platform_type": null,
    "scannable_code": null,
    "billing": null,
    "shipping": {
      "city": null,
      "country": "TH",
      "postal_code": "10320",
      "state": null,
      "street1": "1448/4 Praditmanutham Road",
      "street2": null
    },
    "items": [
      {
        "sku": "AAA111",
        "name": "water bottle",
        "brand": null,
        "category": null,
        "amount": 25000,
        "quantity": 2,
        "item_uri": null,
        "image_uri": null
      }
    ],
    "references": null,
    "store_id": null,
    "store_name": null,
    "terminal_id": null,
    "type": "atome",
    "zero_interest_installments": null,
    "charge_status": "pending",
    "receipt_amount": null,
    "discounts": []
  },
  "schedule": null,
  "customer": null,
  "dispute": null,
  "transaction": null,
  "failure_code": null,
  "failure_message": null,
  "status": "pending",
  "authorize_uri": "https://pay.omise.co/payments/pay2_test_5vz4s29ibio0cyi0j15/authorize",
  "return_uri": "http://example.com/orders/345678/complete",
  "created_at": "2023-06-02T08:53:34Z",
  "paid_at": null,
  "expires_at": "2023-06-09T08:53:34Z",
  "expired_at": null,
  "reversed_at": null,
  "zero_interest_installments": false,
  "branch": null,
  "terminal": null,
  "device": null,
  "authorized": false,
  "capturable": false,
  "capture": true,
  "disputable": false,
  "livemode": false,
  "refundable": false,
  "reversed": false,
  "reversible": false,
  "voided": false,
  "paid": false,
  "expired": false
}

Creating an Atome source and charge

Alternatively, you can create and charge a source in a single API request.

curl https://api.omise.co/charges \
  -u $OMISE_SECRET_KEY: \
  -d "amount=50000" \
  -d "currency=THB" \
  -d "return_uri=http://example.com/orders/345678/complete" \
  -d "source[type]=atome" \
  --data-urlencode "source[phone_number]=+66876543210" \
  -d "source[shipping][postal_code]=10320" \
  -d "source[shipping][country]=TH" \
  -d "source[shipping][street1]=1448/4 Praditmanutham Road" \
  -d "source[items][0][sku]=AAA111" \
  -d "source[items][0][name]=water bottle" \
  -d "source[items][0][quantity]=2" \
  -d "source[items][0][amount]=25000"

Setting an Atome charge to expire

By default, the charge expires 12 hours after creation.

You can assign different expiration periods to each charge by entering a timestamp between 30 seconds and 12 hours from the current time in the expires_at field of the Charge API. If the timestamp is entered correctly, the charge expires at the designated time instead of the default period.

After creating the charge, you can manually call the Expire API to expire a pending charge.

curl https://api.omise.co/charges \
  -u $OMISE_SECRET_KEY: \
  -d "amount=50000" \
  -d "currency=THB" \
  -d "source[type]=atome" \
  --data-urlencode "source[phone_number]=+66876543210" \
  -d "source[shipping][postal_code]=10320" \
  -d "source[shipping][country]=TH" \
  -d "source[shipping][street1]=1448/4 Praditmanutham Road" \
  -d "source[items][0][sku]=AAA111" \
  -d "source[items][0][name]=water bottle" \
  -d "source[items][0][quantity]=2" \
  -d "source[items][0][amount]=25000" \
  -d "expires_at=2020-12-17T00:00:00Z"

Completing an Atome charge

You have created a new charge with its status set to pending. Other possible values for charge status are successful, failed, and expired.

The following sections detail how to authorize a charge, receive its completion webhook event, and update its status.

This sequence diagram shows the entire flow.

Authorizing an Atome charge

Redirect the customer to the location specified in authorize_uri so they can authorize the charge.

You can simulate this authorization phase in test mode by visiting the authorize_uri to manually mark the charge as Successful or Failed. After the customer completes the authorization phase, they are redirected to the location you specified in return_uri.

Receiving the Atome charge completion event

The best way to be notified of a charge completion is by using webhook events. Set up a location on your server to receive webhook events, and add this location as a webhook endpoint on the dashboard.

Once a charge is completed, a POST request with the charge response embedded is sent to this endpoint.

The key attribute for the event object contains charge.complete, and the data attribute contains the charge object. See Events API for the event object structure.

Checking an Atome charge status

After receiving this event, retrieve the charge using its id and confirm that its status matches the status of the charge contained in the event.

If the value of status is successful, the payment succeeded. If the value of status is failed, check the failure_code and failure_message in the charge object for an explanation.

Possible failure codes are listed as follows.

💸 Voids and refunds

Atome charges can be partially or fully refunded within 60 days of the transaction date.

📊 Limits

Thailand

• Minimum: 2000 (THB 20.00)
• Maximum: Subject to the customer's individual Atome credit limit.

Singapore

• Minimum: 150 (SGD 1.50)
• Maximum: 300000 (SGD 3,000.00)

Malaysia

• Minimum: 1000 (MYR 10.00)
• Maximum: 500000 (MYR 5,000.00)

❓ FAQ

What's the difference between Atome and Atome QR? This document (Atome) uses a redirect flow: the customer is sent to Atome's hosted checkout page to authorize the payment online. Atome QR uses an offline flow instead: your site generates a QR code, and the customer scans it with the Atome app (for example, at a POS device) to authorize the payment.

What happens if the customer doesn't complete authorization before the charge expires? The charge's status changes to expired and it can no longer be authorized. Create a new source and charge to let the customer try again.

What happens if the customer cancels or fails authentication on Atome's checkout page? The charge's status changes to failed. Check the failure_code (payment_expired, payment_rejected, or failed_processing) and failure_message on the charge object to determine the cause.

How do I test failure scenarios before going live? In test mode, visit the authorize_uri yourself and manually mark the charge as Successful or Failed to simulate either outcome without a real Atome account.

Can I issue more than one partial refund within the 60-day window? ✅ Yes — multiple partial refunds are supported on the same charge, up until the full amount has been refunded.

Does Atome support recurring or scheduled payments? 🚫 No — Atome doesn't support recurring or scheduled payments.

Do the minimum/maximum limits apply per charge or per customer? 📌 Per transaction — the minimum and maximum limits are enforced per transaction.

👉 Next steps

• Atome QR (offline QR-code checkout flow)
• Charge API
• Source API
• Webhooks API