DuitNow Online Banking/Wallets

Accept online payments from DuitNow users through your website using the DuitNow Online Banking/Wallets (DuitNow OBW) payment method. This guide walks you through the payment flow and details how to implement it.

🔓 How to enable

• Supported countries: Malaysia
• Minimum API version: 2017-11-02

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

💳 Payment flow

Customers paying via DuitNow Online Banking/Wallets go through a redirect payment flow. This means they are redirected from your website to DuitNow Online Banking/Wallets's secure checkout page, where they authorize and confirm the payment. Upon completion, the customer is redirected to the receipt page and your website.

Using a mobile

❶ The customer chooses DuitNow Online Banking/Wallets and the bank they want to pay with. ❷ After choosing the bank, the customer is redirected to the external page operated by the bank. ❸ The customer is shown a summary page before confirming payment. ❹ The customer receives an OTP from the corresponding wallet app ❺ and fills it in. ❻ A payment confirmation slip is shown. Omise sends a webhook completion event, and the customer can be redirected to the merchant's payment confirmation page.

Using a desktop browser

❶ The customer chooses DuitNow Online Banking/Wallets and the bank they want to pay with. ❷ After choosing the bank, the customer is redirected to the external page operated by the bank. ❸ The customer is shown a summary page before confirming payment. ❹ The customer receives an OTP from the corresponding wallet app ❺ and fills it in. ❻ A payment confirmation slip is shown. Omise sends a webhook completion event, and the customer can be redirected to the merchant's payment confirmation page.

🛠️ Implementation

Make the following API requests to create a charge using DuitNow Online Banking/Wallets.

1. Create a new payment source (type: duitnow_obw) using Omise.js or one of the mobile SDKs (iOS and Android).
2. Create a new 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 DuitNow Online Banking/Wallets source on the client (a customer's browser or mobile phone). Use your secret key to create the server's DuitNow Online Banking/Wallets charge.

Creating a source

When the customer confirms that they wish to pay with this payment method, create a new source specifying the amount, bank, currency, platform_type, and type.

*Available bank codes are as follows.

The following examples demonstrate the creation of a new DuitNow Online Banking/Wallets source for RM 1,500. Replace the omise_public_key and $OMISE_PUBLIC_KEY variables with the test public key found on your dashboard.

Omise.setPublicKey(omise_public_key);

Omise.createSource('duitnow_obw', {
  "amount": 150000,
  "currency": "MYR",
  "bank": "maybank2u"
}, 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=150000" \
  -d "currency=MYR" \
  -d "type=duitnow_obw" \
  -d "bank=maybank2u"

{
  "object": "source",
  "id": "src_test_0001",
  "livemode": false,
  "location": "/sources/src_test_0001",
  "amount": 150000,
  "barcode": null,
  "bank": "maybank2u",
  "created_at": "2023-11-16T13:41:39Z",
  "currency": "MYR",
  "email": null,
  "flow": "redirect",
  "installment_term": null,
  "ip": null,
  "absorption_type": null,
  "name": null,
  "mobile_number": null,
  "phone_number": null,
  "platform_type": null,
  "scannable_code": null,
  "billing": null,
  "shipping": null,
  "items": [],
  "references": null,
  "provider_references": null,
  "store_id": null,
  "store_name": null,
  "terminal_id": null,
  "type": "duitnow_obw",
  "zero_interest_installments": null,
  "charge_status": "unknown",
  "receipt_amount": null,
  "discounts": []
}

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

Creating a 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.

• source specifies the source identifier.
• amount and currency must match the source's amount and currency.

The following example demonstrates how to create a new 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=150000" \
  -d "currency=MYR" \
  -d "return_uri=http://example.com/orders/345678/complete" \
  -d "source=$SOURCE_ID"

{
  "object": "charge",
  "id": "chrg_test_0001",
  "location": "/charges/chrg_test_0001",
  "amount": 150000,
  "net": 149850,
  "fee": 150,
  "fee_vat": 0,
  "interest": 0,
  "interest_vat": 0,
  "funding_amount": 150000,
  "refunded_amount": 0,
  "transaction_fees": {
    "fee_flat": "1.5",
    "fee_rate": "0.0",
    "vat_rate": "0.0"
  },
  "platform_fee": {
    "fixed": null,
    "amount": null,
    "percentage": null
  },
  "currency": "MYR",
  "funding_currency": "MYR",
  "ip": null,
  "refunds": {
    "object": "list",
    "data": [],
    "limit": 20,
    "offset": 0,
    "total": 0,
    "location": "/charges/chrg_test_0001/refunds",
    "order": "chronological",
    "from": "1970-01-01T00:00:00Z",
    "to": "2023-11-16T13:41:40Z"
  },
  "link": null,
  "description": null,
  "metadata": {},
  "card": null,
  "source": {
    "object": "source",
    "id": "src_test_0001",
    "livemode": false,
    "location": "/sources/src_test_0001",
    "amount": 150000,
    "barcode": null,
    "bank": "maybank2u",
    "created_at": "2023-11-16T13:41:38Z",
    "currency": "MYR",
    "email": null,
    "flow": "redirect",
    "installment_term": null,
    "ip": null,
    "absorption_type": null,
    "name": null,
    "mobile_number": null,
    "phone_number": null,
    "platform_type": null,
    "scannable_code": null,
    "billing": null,
    "shipping": null,
    "items": [],
    "references": null,
    "provider_references": null,
    "store_id": null,
    "store_name": null,
    "terminal_id": null,
    "type": "duitnow_obw",
    "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_0001/authorize",
  "return_uri": "http://example.com/orders/345678/complete",
  "created_at": "2023-11-16T13:41:40Z",
  "paid_at": null,
  "expires_at": "2023-11-23T13:41:40Z",
  "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,
  "partially_refundable": false,
  "reversed": false,
  "reversible": false,
  "voided": false,
  "paid": false,
  "expired": false
}

Creating a 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=150000" \
  -d "currency=MYR" \
  -d "return_uri=http://example.com/orders/345678/complete" \
  -d "source[type]=duitnow_obw" \
  -d "source[bank]=maybank2u"

Completing the 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.

The following diagram shows the full round trip: your frontend requests a source via Omise.js, your server exchanges that source for a charge, the customer authorizes payment at the authorize_uri, and your server receives a charge.complete webhook once the payment finishes.

1. The customer submits their payment details on your checkout page, and Omise.js sends them to api.omise.co to request a source.
2. api.omise.co returns the source to Omise.js, which passes it to your merchant server.
3. Your server sends the source and purchase details to api.omise.co to request a charge.
4. api.omise.co sends your server a charge.create webhook, then returns the newly created charge (status: pending).
5. Your server redirects the customer to the charge's authorize_uri.
6. The customer authorizes the payment at authorize_uri, and api.omise.co redirects them back to your return_uri.
7. api.omise.co sends your server a charge.complete webhook once the payment finishes.
8. Your server sends the final charge result to the customer, for example by email.

Authorizing the charge

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

The merchant can simulate this authorization phase in test mode by visiting authorize_uri and manually marking the charge as Successful or Failed.

After the customer has completed the authorization phase, they are redirected to the location specified in return_uri.

Receiving the charge completion event

The best way to be notified about the completion of a charge is by using webhook events.

Set up a location on the merchant server to receive webhook events and add this location as a webhook endpoint on your dashboard.

Checking the 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, you got paid.

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 as follows.

💸 Voids and Refunds

DuitNow Online Banking/Wallets charges can be partially or fully refunded within 180 days of the transaction date.

📊 Limits

• Minimum: 100 (MYR1.00)
• Maximum: 2000000 (MYR20,000.00)

The RM 1,500 example used earlier in this guide falls well within these limits.

📚 Related API documentation

• Charge
• Source
• Webhook

🔑 How to check the public key and secret key

For information on obtaining and checking the public and secret keys, please refer to this document.

❓ FAQ

Is DuitNow Online Banking/Wallets available outside Malaysia? No. DuitNow OBW is currently only supported for merchants operating in Malaysia, and charges must be created in MYR.

Does the customer need a DuitNow-linked bank account to pay? Yes. The customer authorizes payment through their own online banking or wallet app, using the bank they select at checkout.

Can I test the payment flow before going live? Yes. In test mode, visiting the authorize_uri lets you manually mark a charge as Successful or Failed to simulate the customer's authorization step.

Why did my charge fail? Check the failure_code and failure_message fields on the charge object. Common causes include an expired payment window, rejection by the issuing bank, or insufficient funds.

Can I capture a DuitNow OBW charge manually instead of automatically? Yes, both manual and automatic capture are supported.

How will I know when a charge is complete? Set up a webhook endpoint to receive the charge.complete event, then retrieve the charge to confirm its final status.

👉 Next steps

• Sources API reference
• Charges API reference
• Setting up webhooks
• Authorization and capture
• Finding your API keys