Multi-Currency Gateway API (v3)

The Multi-Currency Gateway API (v3) 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.

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://sandbox-api.cleverhub.co/api/v3/`
Production	`https://api-merchant.helloclever.co/api/v3`

Authentication

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

app-id

string

required

Your application identifier from the Hello Clever Merchant Dashboard.

secret-key

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

Example request body

{
  "amount": 10000,
  "payin_method_code": null,
  "description": "Order #5678",
  "expire_in": 720000,
  "redirect_url": {
    "success": "https://yoursite.com/success"
  },
  "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 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 Gateway PayIn 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.Alternatively, call POST /v3/payin_links/simulate with the payment UUID to simulate completion via API.

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
    }
  }
});

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.

Overview

Payment Gateway (AUD)

Multi-currency Payment APIs