Hello Clever Developer Docs

The Payment Gateway 3 API (v3), also referred to as Unified Checkout, simplifies how you collect payments from customers across different currencies. Instead of handling payment method UIs, form fields, and checkout pages yourself, you create a single payment link and Hello Clever’s hosted checkout does the rest. Your customers see the right payment methods for their currency, complete their payment, and your server receives a webhook when the status changes. v3 is the fastest way to go live with multi-currency payments: minimal setup, no frontend payment UI to build, and consistent behaviour across all supported currencies.

Supported currencies and payment methods

The v3 gateway supports the currencies configured in your Hello Clever Merchant Dashboard, including recently added support for NZD, HKD, MWK, TZS, and KHQR USD. Contact support@helloclever.co to enable additional currencies. Each currency exposes its own set of payin_method_code values. The codes below are the ones the gateway currently issues:

Currency	Methods (`payin_method_code`)
AUD	`au_card_aud`, `au_payid_npp_aud`
NZD	`nz_card_nzd`
HKD	`hk_card_hkd`
JPY	`jp_bank_jpy`, `jp_card_jpy`
USD	`us_card_usd`, `kh_pay_usd` (KHQR USD)
KRW	`kr_bank_krw`
INR	`in_upi_inr`
MYR	`my_bank_duitnow_myr`, `my_bank_fpx_myr`, `my_ewallet_touchngo_myr`, `my_ewallet_grabpay_myr`, `my_ewallet_boost_myr`, `my_ewallet_shopeepay_myr`
PHP	`ph_bank_php`, `ph_bank_maya_php`, `ph_ewallet_gcash_php`, `ph_qrph_php`
IDR	`id_bank_qris_idr`, `id_ewallet_dana_idr`
VND	`vn_vietqr_vnd`, `vn_other_vietqr_vnd`, `vn_ewallet_momo_vnd`
THB	`th_qrpay_thb`
CAD	`ca_interac_cad`
BRL	`br_pix_brl`
ZAR	`sa_eft_zar`
NGN	`ng_bank_ngn`
KES	`ke_mobile_money_kes`
GHS	`gh_mobile_money_ghs`
MWK	`mw_mobile_money_mwk`, `mw_bank_mwk`
BWP	`bw_bank_bwp`, `bw_mobile_money_bwp`
XAF	`cm_mobile_money_xaf`
XOF	`ci_mobile_money_xof`

Treat this table as orientation, not as configuration. Call GET /v3/payin_methods for the methods actually enabled on your own account, along with each method’s minimum and maximum amount, supported card brands, and available checkout languages. Those limits vary by currency: NZD and HKD card payments cap at 10,000, for example, while MWK methods start at 2,000.

Mobile money payments

Mobile money methods (ke_mobile_money_kes, mw_mobile_money_mwk, bw_mobile_money_bwp, gh_mobile_money_ghs, cm_mobile_money_xaf, ci_mobile_money_xof) settle through a prompt on the customer’s handset rather than on the checkout page. The customer enters their mobile number, receives a PIN or STK push prompt, approves it, and then confirms on the page with I have paid. The hosted checkout shows the network requirements for each market. Points worth reflecting in your own messaging:

Only certain networks are supported per currency. For MWK, only Airtel and TNM mobile numbers work; a number on another network fails.
Prompts expire. The customer must respond promptly. Ignoring or dismissing the prompt causes a timeout, which surfaces as a failed payment rather than a pending one.
The wallet needs sufficient balance before the payment is initiated.
The customer must not close or refresh the page until they have approved the prompt and selected I have paid.

Mobile money payments are neither refundable nor cancellable through the API. Confirm the amount with the customer before creating the payin.

See the multi-currency hosted checkout guide for exactly what the customer sees for each method family. It is useful when you are writing your own support material.

Address collection

Some methods require a billing address before the payment can proceed. On the hosted checkout, the address field autocompletes as the customer types and validates the result against a real address, so the customer selects their address rather than typing it in full. You can pre-fill sender_info.address, city, postal_code, state, and country_code when you create the payin; those values are carried into the form, and the customer only completes what is missing. Validation still applies to anything they change.

Address autocomplete reduces failures on methods that verify the address, but it does not remove the requirement. If you already hold a verified address for the customer, pass it in sender_info so they have less to fill in.

Integration modes

Payment Method

Display available payment methods directly in your UI. Call Get Payin Methods, let the customer choose, then Create Payin with the selected method code. The customer completes checkout on Hello Clever’s hosted page.

Payment Link (Hello Clever brand)

Create a payment link without specifying a method. Redirect the customer to the generated payment_url where they can choose from all available methods on a Hello Clever branded checkout page.

Payment Link (Your brand)

Use a custom domain for your payment checkout page. Contact support@helloclever.co to configure white-label branding.

Base URLs

Environment	Base URL
Sandbox	`https://api.cleverhub.co/api`
Production	`https://api-merchant.helloclever.co/api`

Authentication

All v3 requests require the same app-id and secret-key header pair used in v2.

string

required

Your application identifier from the Hello Clever Merchant Dashboard.

string

required

Your client secret. Never expose this in client-side code.

Step-by-step integration guide

Configure credentials

Each site in your Hello Clever account has a unique app-id. Set the site type to Payment API in your dashboard to activate the credentials. If you operate across multiple currencies, link each site individually to receive the correct app-id and secret-key for each currency.A Webhook Secret Key is issued at the merchant level and shared across all sites under the same merchant. Use it to verify every webhook signature from Hello Clever.

Get available payment methods (optional)

Call GET /v3/payin_methods to retrieve the list of payment methods for your configured currency. You can display these directly in your checkout UI if you want the customer to choose a method before creating the payin.

Example response

{
  "records": [
    {
      "currency": "MYR",
      "payin_method_code": "my_bank_duitnow_myr",
      "payin_method_name": "DuitNow",
      "min_amount": 1,
      "max_amount": 9999999
    }
  ]
}

Create the payment link

Call POST /v3/payin_links with the transaction details. amount, description, and sender_info are required. Include payin_method_code if the customer has already selected a method; omit it to show all available methods on the Hello Clever checkout page. expires_in is in seconds. It defaults to 1800 (30 minutes) and cannot be lower than 900 (15 minutes).

Example request body

{
  "amount": 10000,
  "payin_method_code": null,
  "description": "Order #5678",
  "expires_in": 1800,
  "redirect_url": {
    "success": "https://yoursite.com/success",
    "failure": "https://yoursite.com/failure"
  },
  "webhook_notification": {
    "authorization_header": "Bearer N234jkd85h2h3j4hj234difu892134jh",
    "endpoint_url": "https://yoursite.com/webhooks/payment"
  },
  "sender_info": {
    "email": "customer@example.com",
    "first_name": "Jane",
    "last_name": "Smith"
  }
}

The response includes the payment_url to redirect your customer to.

Example response

{
  "uuid": "Q3NT0K80",
  "payment_url": "https://paylink.cleverhub.co/UTNOVDBLODA",
  "expired_at": "2025-09-11T16:30:02.712Z"
}

Redirect URLs

Use redirect_url to control where the customer lands once checkout finishes. Both fields are optional, and you can set either one independently.

Field	When it is used
`redirect_url.success`	The payment succeeded. Send the customer to your order-confirmation page.
`redirect_url.failure`	The payment failed, was declined, or expired. Send the customer to a page you control where they can retry or choose another method.

If you omit redirect_url.failure, the customer stays on the Hello Clever checkout page after a failed payment and has no route back into your checkout flow. Setting it lets you keep failed customers inside your own funnel.

Never treat a redirect to your success URL as proof of payment. A customer can reach that URL without the payment having settled. Confirm every payment against the webhook, which is the source of truth.

Redirect the customer

Send the customer to the payment_url. Choose a UX mode that fits your product:

Redirect: Send the customer directly to the payment URL in the same tab or a new tab.
Popup: Render the payment URL inside a popup window and listen for payment events via window.addEventListener("message", ...).

Some browsers (Safari, Chrome) block automatic popups. Inform users to allow popups from your domain if you use the popup UX mode.

Handle webhooks

Your server receives a POST webhook at the endpoint_url you specified whenever the payment status changes. Always treat webhooks as the source of truth for payment status. Do not rely solely on redirect URL parameters.See Webhooks for the full webhook object schema and status reference.

Test in sandbox

In the sandbox environment, use the payment simulator to test different payment outcomes without real money. After creating a payment, click “I have paid” on the hosted checkout page to open the simulator popup, then trigger success or failure scenarios as needed.

Managing payments after creation

Endpoint	Purpose
`GET /v3/payin_links`	List your payins, with filters for reconciliation.
`GET /v3/payin_links/{uuid}`	Retrieve the current status and details of a single payin.
`POST /v3/payin_links/refund`	Refund a completed payin.

See the API reference for full request and response schemas. If you embed the checkout in a popup window, listen for payment events to close the popup and update your UI:

Handle popup payment events

window.addEventListener("message", function (event) {
  if (
    !event.data?.hc_payment_event ||
    typeof event.data?.hc_payment_event !== "object"
  ) return;

  if (event.data.hc_payment_event.event_type === "onChange") {
    if (event.data.hc_payment_event.page_state === "success") {
      // Payment succeeded: close the popup and update your UI
      // window.location.href = event.data.hc_payment_event.redirect_url.success;
    }
    if (event.data.hc_payment_event.page_state === "failed") {
      // Payment failed: show an error message
      // window.location.href = event.data.hc_payment_event.redirect_url.failure;
    }
  }
});

The hc_payment_event object contains:

event_type: "onChange" (status changed) or "onDone" (customer clicked Done or countdown reached zero).
page_state: "success" or "failed".

Use popup event listeners only to improve UX with instant feedback. Always rely on webhooks as the authoritative source of payment status.

Demo

Explore the v3 gateway in action at the Hello Clever demo site. The demo lets you test all integration modes (Payment Link, Payment Method, Popup, and Redirect) across multiple currencies.

Basics

Payment Gateway (AUD)

Multi-Currency Payment API

Payment Gateway 3

Card API

Cashback API

Payment Gateway 3 API (v3)

Supported currencies and payment methods

Mobile money payments

Address collection

Integration modes

Payment Method

Payment Link (Hello Clever brand)

Payment Link (Your brand)

Base URLs

Authentication

Step-by-step integration guide

Redirect URLs

Managing payments after creation

Demo

​Supported currencies and payment methods

​Mobile money payments

​Address collection

​Integration modes

Payment Method

Payment Link (Hello Clever brand)

Payment Link (Your brand)

​Base URLs

​Authentication

​Step-by-step integration guide

​Redirect URLs

​Managing payments after creation

​Popup UX event handling

​Demo

Supported currencies and payment methods

Mobile money payments

Address collection

Integration modes

Base URLs

Authentication

Step-by-step integration guide

Redirect URLs

Managing payments after creation

Popup UX event handling

Demo