Hello Clever Developer Docs

The v2 Payin API lets you collect payments from customers in multiple currencies using a single, consistent schema. You can accept bank transfers, e-wallets, QR payments, mobile money, and more, all through the same set of endpoints. This page documents every Payin endpoint, including sandbox simulation for testing.

Before creating a payin, call Get Payin Methods and Get Required Fields to discover which payment methods and customer fields are available for your configured currency.

Get Payin Methods

GET /v2/payins/payin_methods Returns all payment methods available for your app-id. The methods returned depend on the country and currency configured in your Hello Clever Merchant Dashboard.

Response fields

object[]

Array of available payin methods.

Show properties

string

ISO 4217 currency code (e.g., MYR, VND).

string

The method identifier (e.g., my_bank_duitnow_myr). Pass this value as payin_method_name when you create a payin.

v2 identifies payment methods by payin_method_name. The payin_method_code field belongs to Payment Gateway 3 and is not returned or accepted here. Call Get Payin Required Fields for a method’s limits, logo, and required parameters.

curl --request GET \
  --url https://api.cleverhub.co/api/v2/payins/payin_methods \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY'

{
  "records": [
    {
      "currency": "MYR",
      "payin_method_name": "my_bank_duitnow_myr"
    }
  ]
}

Get Payin Required Fields

GET /v2/payins/payin_method/params Returns the fields required (or optional) to create a payin for a specific payment method. Call this once per method to understand what customer data you need to collect.

Query parameters

string

required

The method identifier returned from Get Payin Methods (e.g., my_bank_duitnow_myr).

Response fields

object

Details for the requested payment method.

Show properties

string

ISO 4217 currency code.

string

Currency symbol.

string

URL of the bank or e-wallet logo.

string

The method identifier.

string

Human-readable description of the method.

object

The parameters to send in payin_method_params when creating the payin. Each entry is formatted as type:Mandatory|Optional <description>.

object[]

Supported banks or e-wallets for the method, each with a code and name. Empty for methods that do not require a provider selection.

string

pay_in for payin methods.

boolean

Whether a completed payin using this method can be refunded.

boolean

Whether a pending payin using this method can be cancelled.

boolean

Whether you must create a contact record before initiating a payin.

boolean

Whether KYC verification is required for this method.

number

Minimum transaction amount in the currency’s base unit.

number

Maximum transaction amount in the currency’s base unit.

curl --request GET \
  --url 'https://api.cleverhub.co/api/v2/payins/payin_method/params?payin_method_name=au_payid_npp_aud' \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY'

{
  "record": {
    "currency": "AUD",
    "symbol": "$",
    "logo": "",
    "payin_method_name": "au_payid_npp_aud",
    "description": "New Payments Platform (NPP)",
    "payin_method_params": {
      "callback_url": "string:Mandatory callback URL"
    },
    "payment_type": "pay_in",
    "is_refundable": false,
    "is_cancellable": false,
    "require_contact": true,
    "require_kyc": false,
    "min_amount": 20,
    "max_amount": 10000
  }
}

Create Payin

POST /v2/payins Creates a new payin request. You must first call Get Payin Methods and Get Required Fields to gather the correct method code and required fields.

For payin methods jp_bank_jpy, ar_bank_ars, and kr_bank_va_kyc_krw, payment credentials such as virtual account numbers are delivered asynchronously via webhook after the payin is created, not in the API response.

Body parameters

string

required

The method identifier returned by Get Payin Methods (e.g., my_bank_duitnow_myr).

object

required

Method-specific parameters. Call Get Payin Required Fields for the exact keys this method expects. They differ per method, and some are mandatory. Send {} for methods that require none.

Show properties

boolean

default:"false"

Converts the customer’s name into the bank’s required script before submitting. Supported only for jp_bank_jpy, which converts first_name / last_name into full-width Katakana. Input must be romaji using Latin letters only; invalid input returns a validation error. Ignored by other methods.

number

required

The payment amount in the currency’s base unit. For VND, JPY, XAF, KRW, and XOF, this value is rounded to the precision the currency supports. See amount rounding.

string

required

ISO 4217 currency code (e.g., MYR, VND, AUD).

string

required

Customer name.

string

required

Customer email address. If the method reports require_contact: true, this must match the email used to create the contact.

string

required

A description for this payment.

boolean

required

Include GST in the transaction. Set to true only for AUD transactions by AU merchants.

object

required

Webhook configuration for this payin.

Show properties

string

required

Your webhook endpoint URL. Must be TLS 1.2 with a certificate from a well-known commercial authority. Self-signed and internally signed certificates are rejected.

string

required

Authorization header value sent with each webhook call. Use a unique value per payment for security.

string

Your own identifier for this transaction. Returned on the payin and usable as a filter on Get Payins in a Period.

string

Expiry timestamp in YYYY-MM-DDTHH:mm:ss format. Applies only to vn_vietqr_vnd; every other method uses a fixed default that cannot be overridden. Must be at least 15 minutes in the future.

object

Optional custom key-value data to attach to the transaction. Returned unchanged on the payin and in webhook payloads.

There is no sender_info, expire_in, or redirect_url in v2. Those belong to Payment Gateway 3. Send the customer as top-level name and email, and use expired_at for expiry.

Response fields

string

Unique identifier for this payin transaction.

string

Current status: pending, waiting, received, expired, return_pending, return_received, return_expired, or return_rejected. See payment statuses for the full lifecycle.

string

Where the payment sits in its authorisation flow: normal_stage, authorize_otp, or authorize_stk.

object

The details the customer uses to complete payment. Contents vary by method: payment_url for hosted flows, or bank fields such as account_name, account_number, and bank_name for bank transfers. For jp_bank_jpy, ar_bank_ars, and kr_bank_va_kyc_krw this arrives by webhook rather than in the response.

string

The payin_method_name used for this transaction.

number

Transaction amount, alongside gst_amount, total, and paid_amount.

boolean

Whether this payin can be refunded.

string

Timestamp when the payin expires. pay_by returns the deadline for the customer to pay.

curl --request POST \
  --url https://api.cleverhub.co/api/v2/payins \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "currency": "MYR",
    "amount": 10000,
    "name": "Jane Smith",
    "email": "customer@example.com",
    "gst": false,
    "external_id": "123456",
    "description": "Invoice #1234",
    "payin_method_name": "my_bank_duitnow_myr",
    "payin_method_params": {},
    "webhook_notification": {
      "endpoint_url": "https://yoursite.com/webhooks/payin",
      "authorization_header": "Bearer abc123xyz"
    },
    "metadata": {
      "custom_note": "Priority customer"
    }
  }'

{
  "uuid": "Q3NT0K80",
  "name": "Jane Smith",
  "description": "Invoice #1234",
  "email": "customer@example.com",
  "external_id": "123456",
  "status": "pending",
  "stage": "normal_stage",
  "pay_code": {
    "payment_url": "https://paylink.cleverhub.co/UTNOVDBLODA"
  },
  "currency": "MYR",
  "gst": false,
  "amount": "10000.0",
  "gst_amount": "0",
  "total": "10000.0",
  "paid_amount": "0",
  "payment_method": "my_bank_duitnow_myr",
  "is_refundable": "true",
  "expired_at": "2025-09-11T16:30:02.712Z",
  "pay_by": "2025-09-11T16:30:02.712Z"
}

Webhooks are called on a best-effort basis. If your endpoint does not return HTTP 200, Hello Clever retries 3 times with 15-minute delays between attempts. Design your webhook handler to be idempotent.

Get Payin Details

GET /v2/payins/detail Returns the full details of a specific payin request by UUID.

Query parameters

string

required

The unique identifier of the payin transaction.

curl --request GET \
  --url 'https://api.cleverhub.co/api/v2/payins/detail?uuid=Q3NT0K80' \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY'

{
  "uuid": "Q3NT0K80",
  "status": "received",
  "amount": 10000,
  "currency": "MYR",
  "payin_method_name": "my_bank_duitnow_myr",
  "created_at": "2025-09-11T10:30:02.000Z",
  "expired_at": "2025-09-11T16:30:02.712Z",
  "is_refundable": true,
  "is_cancellable": false
}

Get Payins in a Period

GET /v2/payins/all Returns a paginated list of payin transactions linked to your app-id, filtered by date range and optional status. Returns 20 records per page by default.

Query parameters

string

required

Start of the date range in ISO 8601 format (e.g., 2025-01-01T00:00:00Z).

string

required

End of the date range in ISO 8601 format.

string

Filter to the payin matching your own identifier.

number

default:"1"

Page number for pagination.

number

default:"20"

Number of records per page.

curl --request GET \
  --url 'https://api.cleverhub.co/api/v2/payins/all?from_date=2025-01-01T00:00:00Z&to_date=2025-01-31T23:59:59Z&page=1&per_page=20' \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY'

{
  "total": 45,
  "page": 1,
  "limit": 20,
  "records": [
    {
      "uuid": "Q3NT0K80",
      "status": "received",
      "amount": 10000,
      "currency": "MYR",
      "created_at": "2025-01-15T10:30:00.000Z"
    }
  ]
}

Cancel Payin

POST /v2/payins/cancel Cancels a pending payin transaction. The status transitions to expired. Check is_cancellable == true on the payin method before calling this endpoint.

Body parameters

string

required

The UUID of the pending payin to cancel.

curl --request POST \
  --url https://api.cleverhub.co/api/v2/payins/cancel \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "uuid": "Q3NT0K80" }'

{
  "uuid": "Q3NT0K80",
  "status": "expired",
  "message": "Payin cancelled successfully"
}

Refund Payin

POST /v2/payins/refund Initiates a refund on a completed (received) payin. Check is_refundable == true on the transaction before calling this endpoint.

If you initiate a refund immediately after a successful payin, the refund must be for the full amount. Partial refunds are only supported 30 minutes to 1 hour after the payin completes.

Body parameters

string

required

The UUID of the received payin to refund.

string

required

Reason for the refund. Must be at least 5 characters.

number

The amount to refund. If omitted, the full amount is refunded. Partial refunds are only allowed 30–60 minutes after payin completion.

curl --request POST \
  --url https://api.cleverhub.co/api/v2/payins/refund \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "uuid": "Q3NT0K80",
    "amount": 5000,
    "description": "Partial refund requested by customer"
  }'

{
  "uuid": "Q3NT0K80",
  "refund_status": "return_pending",
  "refund_amount": 5000,
  "message": "Refund initiated"
}

Payin Simulation (sandbox only)

POST /v2/payins/simulate Simulates the outcome of a pending payin in the sandbox environment. The payin must be in pending status. This endpoint is not available in production.

Body parameters

string

required

The UUID of the pending payin to simulate.

string

required

The outcome to simulate: completed or failed.

number

Amount to simulate as paid. Defaults to the full payin amount.

curl --request POST \
  --url https://api.cleverhub.co/api/v2/payins/simulate \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "uuid": "Q3NT0K80", "status": "completed" }'

{
  "uuid": "Q3NT0K80",
  "status": "received",
  "message": "Payin simulation successful"
}

Authorize OTP Transaction

POST /v2/payins/confirm_otp After creating a payin using a mobile money method (e.g., gh_mobile_money_ghs), if the response stage is authorize_otp, an OTP has been sent to the customer’s phone. Collect the OTP from the customer and submit it to this endpoint. On success, an STK push is sent to the customer’s phone to confirm the payment with their PIN.

Body parameters

string

required

The UUID of the payin awaiting OTP authorization.

string

required

The OTP received on the customer’s phone.

curl --request POST \
  --url https://api.cleverhub.co/api/v2/payins/confirm_otp \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "uuid": "Q3NT0K80", "code": "123456" }'

{
  "uuid": "Q3NT0K80",
  "status": "pending",
  "message": "OTP verified. STK push sent to customer."
}

Resend OTP

POST /v2/payins/resend_otp Resends the OTP for a mobile money payin when the original OTP has expired or was not received by the customer.

Body parameters

string

required

The UUID of the payin for which to resend the OTP.

curl --request POST \
  --url https://api.cleverhub.co/api/v2/payins/resend_otp \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "uuid": "Q3NT0K80" }'

{
  "uuid": "Q3NT0K80",
  "message": "OTP resent successfully"
}

Basics

Payment APIs

Card API

Cashback API

Multi-Currency Payin API Reference

Get Payin Methods

Response fields

Get Payin Required Fields

Query parameters

Response fields

Create Payin

Body parameters

Response fields

Get Payin Details

Query parameters

Get Payins in a Period

Query parameters

Cancel Payin

Body parameters

Refund Payin

Body parameters

Payin Simulation (sandbox only)

Body parameters

Authorize OTP Transaction

Body parameters

Resend OTP

Body parameters

​Get Payin Methods

​Response fields

​Get Payin Required Fields

​Query parameters

​Response fields

​Create Payin

​Body parameters

​Response fields

​Get Payin Details

​Query parameters

​Get Payins in a Period

​Query parameters

​Cancel Payin

​Body parameters

​Refund Payin

​Body parameters

​Payin Simulation (sandbox only)

​Body parameters

​Authorize OTP Transaction

​Body parameters

​Resend OTP

​Body parameters

Get Payin Methods

Response fields

Get Payin Required Fields

Query parameters

Response fields

Create Payin

Body parameters

Response fields

Get Payin Details

Query parameters

Get Payins in a Period

Query parameters

Cancel Payin

Body parameters

Refund Payin

Body parameters

Payin Simulation (sandbox only)

Body parameters

Authorize OTP Transaction

Body parameters

Resend OTP

Body parameters