Installment [Beta]

Installment payments allows customers to divide their payment into a series of smaller amounts that is paid over a fixed period up to 36 months subjected to bank's terms and condition. The minimum charge amount is 5,000 THB.

Omise currently supports 4 major banks, which are:

  • Bank of Ayudhya (Krungsri)
  • Kasikorn Bank (KBank)
  • Krungthai Card
  • Bangkok Bank

The payment flow

Customers who choose to pay via installments go through a redirect payment flow, meaning they are sent from the merchant's site to a secure bank-operated page to authorize and confirm the payment amount. Upon completion, the customer is automatically redirected back to the merchant's website.

installment 1

The customer selects Installment as their preferred payment method and is redirected to the bank's page.

nstallment 2

The payment amount and reference numbers are pre-filled. The customer only has to review the information and confirm the payment.

Creating a charge by using Payment Source

In order to create an installment charge, you need to create a source object using the Source API. The supported values for the type and installment_terms parameter are

type installment_terms (months)
installment_bay 3, 4, 6, 9, 10
installment_first_choice 3, 4, 6, 9, 10, 12, 18, 24, 36
installment_bbl 4, 6, 8, 9, 10
installment_ktc 3, 4, 5, 6, 7, 8, 9, 10
installment_kbank 3, 4, 6, 10

The following code demonstrates how to create a source with cUrl command.

curl https://api.omise.co/sources \
-X POST \
-u pkey_test_511yxv4dtvyj3xvewee: \
-H 'Omise-version: 20840905' \
-d "description=Installment Payment" \
-d "amount=500000" \
-d "currency=thb" \
-d "type=installment_bay" \
-d "installment_terms=4"

*Note that when creating a source object, you can use either the Secret Key or the Public Key.

JSON Response

You will then get the result of the created source as below.

{
  "object": "source",
  "id": "src_test_5b6wvv9oq1wvola1zv4",
  "livemode": true,
  "location": "/sources/src_test_5b6wvv9oq1wvola1zv4",
  "type": "installment_bay",
  "flow": "redirect",
  "amount": 500000,
  "currency": "thb",
  "installment_terms": "4",
  "absorption_type": "customer"
}

The most important attribute is the id, which will be used to create an installment charge. The id used in the example here is src_5b6wvv9oq1wvola1zv4.

Creating an installment charge

The following is a cURL snippet for creating an installment charge:

curl https://api.omise.co/charges \
-X POST \
-u skey_test_5945rfj11gmvd89as2a: \
-d "source=src_test_5bvkdbtqrp86tpvmvem" \
-d "description=Charge with source" \
-d "amount=500000" \
-d "currency=thb" \
-d "return_uri=https://merchant.website.com/"

Redirecting a user to the bank's payment page

You will get a JSON response similar to the example below:

{
    "object": "charge",
    "id": "chrg_5axwhtzwhz5xro3qnvg",
    "livemode": true,
    "location": "/charges/chrg_5axwhtzwhz5xro3qnvg",
    "amount": 500000,
    "currency": "thb",
    "description": "test charge",
    "metadata": {},
    "status": "pending",
    "capture": true,
    "authorized": false,
    "reversed": false,
    "paid": false,
    "transaction": null,
    "refunded": 0,
    "return_uri": "https://omise.co",
    "reference": "ofsp_5axwhu0zwgp2ojwc47i",
    "authorize_uri": "http://pay.omise.co/offsites/ofsp_5axwhu0zwgp2ojwc47i/pay",    
    "source": {
        "object": "source",
        "id": "src_test_5b6wvv9oq1wvola1zv4",
        "type": "installment_bay",
        "flow": "redirect",
        "amount": 500000,
        "currency": "thb"
    }
}

To proceed to the bank's page for payment, the merchant would need to redirect the customer to the authorize_uri.

Failure codes

Code Description
insufficient_balance There are not enough funds in the bank account for making payment
payment_cancelled The payment has been cancelled by the payer
timeout User did not take any action within 24 hours after the charge was created
failed_processing Payment failed due to other reasons
bad_request Currency is currently not supported
bad_request type is currently not supported
bad_request invalid source
bad_request return_uri is required
not_found Source source_id was not found

Webhooks

Rather than relying on the redirect back to the return_uri, we suggest merchants to make use of our Webhook API . Whenever a transaction is completed a webhook is sent to the URL that is specified in the dashboard with the event name charge.complete

Creating a charge by adding the attribute source[type]

curl https://api.omise.co/charges \
-X POST \
-u skey_test_59rnqoboimgxvjk894d: \
-d "source[type]=installment_bay" \
-d "source[installment_terms]=4" \
-d "currency=thb" \
-d "amount=500000" \
-d "return_uri=https://merchant.website.com" \
-d "description=Charge with source object"

A charge can also be created by adding the source[type] attribute, but we recommend you create a charge by using the payment Source API.

Note

- Installment is only available for merchants with a Thai-registered Omise account.

- For users with a live account, you will be required to review Terms & Conditions before using the live API.