Installment [Beta]

Installment payments allows customers to split up a full payment into smaller amounts, which is paid off at regular intervals over a fixed period. Currently, you can offer your customers upto 36 installments (terms depend on chosen bank). The minimum charge amount is THB 5,000.

Omise currently supports 5 card brands including;

  • Krungsri credit card
  • Krungsri First Choice card
  • Kasikorn bank credit card
  • Krungthai card (KTC)
  • Bangkok bank credit card

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.

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. Upon completion, the customer is automatically redirected back to the merchant's website.

Creating a charge by using Payment Source

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: \
-d "description=Installment Payment" \
-d "amount=500000" \
-d "currency=thb" \
-d "type=installment_kbank" \
-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 source created as shown below.

{
  "object": "source",
  "id": "src_test_5b6wvv9oq1wvola1zv4",
  "livemode": true,
  "location": "/sources/src_test_5b6wvv9oq1wvola1zv4",
  "type": "installment_kbank",
  "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 the 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_kbank",
        "flow": "redirect",
        "amount": 500000,
        "currency": "thb"
    }
}

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

Failure codes

Code Description
insufficient_balance There is insufficient balance in the bank account to complete the payment
payment_cancelled The payment has been cancelled by the payer
timeout The 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_kbank" \
-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 payments is only available for merchants that have registered with Omise in Thailand.

- Users already with a live account will be required to review Terms & Conditions before using the live API.