> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rc.cleverhub.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Payment Gateway 3 API (v3)
> Hello Clever’s v3 gateway lets you accept any supported currency with a single API call that returns a hosted checkout link your customers complete.
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](mailto: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](/platform-overview/customer-guides/multi-currency-checkout) 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
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.
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.
Use a custom domain for your payment checkout page. Contact [support@helloclever.co](mailto: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.
Your application identifier from the Hello Clever Merchant Dashboard.
Your client secret. Never expose this in client-side code.
## Step-by-step integration guide
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.
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.
```json Example response theme={null}
{
"records": [
{
"currency": "MYR",
"payin_method_code": "my_bank_duitnow_myr",
"payin_method_name": "DuitNow",
"min_amount": 1,
"max_amount": 9999999
}
]
}
```
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).
```json Example request body theme={null}
{
"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.
```json Example response theme={null}
{
"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.
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.
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](/api/webhooks) for the full webhook object schema and status reference.
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](/api/) for full request and response schemas.
## Popup UX event handling
If you embed the checkout in a popup window, listen for payment events to close the popup and update your UI:
```javascript Handle popup payment events theme={null}
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](https://testing-minimoo.cleverpay.store/). The demo lets you test all integration modes (Payment Link, Payment Method, Popup, and Redirect) across multiple currencies.
## Related topics
- [Multi-Currency Payment API (v2)](/api/v2/introduction.md)
- [Multi-Currency Payin API Reference (v2)](/api/v2/payin.md)
- [Authenticate with the Hello Clever API](/api/authentication.md)