Multi-Currency PayIn API Reference (v2)

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

records

object[]

Array of available payin methods.

Show properties

payin_method_code

string

Unique code for the payment method (e.g., my_bank_duitnow_myr).

payin_method_name

string

Human-readable name of the payment method.

currency

string

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

logo

string

URL of the payment method logo.

min_amount

number

Minimum transaction amount in the currency’s base unit.

max_amount

number

Maximum transaction amount in the currency’s base unit.

is_cancellable

boolean

Whether a pending payin using this method can be cancelled.

is_refundable

boolean

Whether a completed payin using this method can be refunded.

require_contact

boolean

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

require_kyc

boolean

Whether KYC verification is required for this method.

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

{
  "records": [
    {
      "currency": "MYR",
      "payin_method_code": "my_bank_duitnow_myr",
      "payin_method_name": "DuitNow",
      "logo": "https://aircrexlandingpageprod.azureedge.net/static/clever/pgv3/payment_methods/duit_now.png",
      "min_amount": 1,
      "max_amount": 9999999,
      "is_cancellable": true,
      "is_refundable": true,
      "require_contact": false,
      "require_kyc": false
    }
  ]
}

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

payin_method_code

string

required

The payment method code returned from Get PayIn Methods.

Response fields

params

object[]

List of parameters for the payment method.

Show properties

param_name

string

Field name to include in the Create PayIn request.

is_required

boolean

Whether this field is mandatory.

description

string

Description of the field and accepted values.

curl --request GET \
  --url 'https://api.lightningpay.me/api/v2/payins/payin_method/params?payin_method_code=my_bank_duitnow_myr' \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY'

{
  "params": [
    {
      "param_name": "account_number",
      "is_required": true,
      "description": "The customer's bank account number"
    }
  ]
}

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

payin_method_name

string

required

The payment method code (e.g., my_bank_duitnow_myr).

amount

number

required

The payment amount in the currency’s base unit.

currency

string

required

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

description

string

A description for this payment.

gst

boolean

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

expire_in

number

Time in seconds before the payin request expires.

sender_info

object

Customer details for the transaction.

Show properties

string

required

Customer’s email address.

first_name

string

Customer’s first name.

last_name

string

Customer’s last name.

phone

string

Customer’s phone number.

country_code

string

ISO 3166-1 alpha-2 country code.

webhook_notification

object

Webhook configuration for this payin. If omitted, your dashboard default is used.

Show properties

endpoint_url

string

required

Your webhook endpoint URL.

authorization_header

string

required

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

redirect_url

object

Redirect URLs after payment completion.

Show properties

success

string

URL to redirect the customer after a successful payment.

failure

string

URL to redirect the customer after a failed payment.

Response fields

uuid

string

Unique identifier for this payin transaction.

status

string

Current status: pending, received, expired, return_received, or failed.

payment_url

string

URL for the customer to complete payment (if applicable for the method).

pay_code

string

The payment code or reference number the customer uses to pay (e.g., for bank transfers).

expired_at

string

ISO 8601 timestamp when the payin expires.

curl --request POST \
  --url https://api.lightningpay.me/api/v2/payins \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "payin_method_name": "my_bank_duitnow_myr",
    "amount": 10000,
    "currency": "MYR",
    "description": "Invoice #1234",
    "sender_info": {
      "email": "customer@example.com",
      "first_name": "Jane",
      "last_name": "Smith"
    },
    "webhook_notification": {
      "endpoint_url": "https://yoursite.com/webhooks/payin",
      "authorization_header": "Bearer abc123xyz"
    },
    "redirect_url": {
      "success": "https://yoursite.com/order/success"
    }
  }'

{
  "uuid": "Q3NT0K80",
  "status": "pending",
  "payment_url": "https://paylink.cleverhub.co/UTNOVDBLODA",
  "pay_code": "2001234567890",
  "expired_at": "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

uuid

string

required

The unique identifier of the payin transaction.

curl --request GET \
  --url 'https://api.lightningpay.me/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

from_date

string

required

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

to_date

string

required

End of the date range in ISO 8601 format.

status

string

Filter by payment status: pending, received, expired, return_received, failed.

page

number

default:"1"

Page number for pagination.

limit

number

default:"20"

Number of records per page.

curl --request GET \
  --url 'https://api.lightningpay.me/api/v2/payins/all?from_date=2025-01-01T00:00:00Z&to_date=2025-01-31T23:59:59Z&page=1&limit=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

uuid

string

required

The UUID of the pending payin to cancel.

curl --request POST \
  --url https://api.lightningpay.me/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

uuid

string

required

The UUID of the received payin to refund.

amount

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.lightningpay.me/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
  }'

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

PayIn Simulation (sandbox only)

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

Body parameters

uuid

string

required

The UUID of the pending payin to simulate as completed.

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

{
  "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

uuid

string

required

The UUID of the payin awaiting OTP authorization.

otp

string

required

The OTP received on the customer’s phone.

curl --request POST \
  --url https://api.lightningpay.me/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", "otp": "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

uuid

string

required

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

curl --request POST \
  --url https://api.lightningpay.me/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"
}

Overview

Payment Gateway (AUD)

Multi-currency Payment APIs

Multi-currency Gateway

Card API

Cashback API

Multi-Currency PayIn API Reference (v2)

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