Payin

Create a Payin

To be able to successfully create a payin request you would need the following APIs in consideration:

Step 1: Call the Get payin methods to retrieve the list of supported methods.
Step 2: Call the Get payin required fields to get specific required fields for each method.
Step 3: Create the payment using the method and required fields from the previous step.
Step 4: On sandbox environment, you can call the Simulate payin to simulate the payment.

Please note: GST should only be set to true for AU Merchants for AUD currency only. For all other currencies, set GST to false.

Note:

If the payin_method_name is either jp_bank_jpy, ar_bank_ars and kr_bank_va_kyc_krw, the pay_code will be sent to the webhook after a certain period with the following fields:

For jp_bank_jpy:
- bank_name: The recipient’s bank name.
- transfer_id: The transfer identifier on the provider side.
- branch_code: The code of the recipient’s bank branch.
- branch_name: The name of the recipient’s bank branch.
- account_number: The recipient’s account number.
- account_name: The recipient’s account name.
- expired_timestamp: The payment expiration time.
- account_type: The recipient’s account type.
- transfer_name: The name associated with the transfer.
For ar_bank_ars:
- bank_name: The recipient’s bank name.
- account_number: The recipient’s account number.
- account_name: The recipient’s account name.
- expired_timestamp: The payment expiration time.
- alias: The letter code used in the Argentine banking system to identify an account instead of an account number (for Argentine accounts).
For kr_bank_va_kyc_krw:
- virtual_bank_code: The recipient’s bank code.
- virtual_account_number: The recipient’s account number.
- virtual_bank_name: The recipient’s bank name.

If you use one of the following payin methods, please check the list of supported providers before proceeding:

sa_eft_zar: View supported
my_bank_fpx_myr: View supported
my_bank_myr: View supported
th_qrpay_thb: View supported
bw_bank_bwp: View supported
mwk_mobile_money_network: View supported
br_pix_brl (crypto settlement): Please find crypto_ticker and crypto_wallet_address in View supported
jp_cvs_jpy: Please find store_type in View supported
jp_ewallet_merpay_jpy: Please find category_id in View supported

❗ Important:

If you select mobile_money as the payin method in Step 3, please refer to the implementation guidelines in the Mobile Money tab.
- Example payin method: gh_mobile_money_ghs
If you select kr_bank_va_kyc_krw as the payin method in Step 3, please refer to the implementation guidelines in the Bank Transfer tab.
- Example payin method: kr_bank_va_kyc_krw
If you select kh_pay_khr or us_pay_usd, merchants must not use any parameters returned in the callback_url or failure_callback_url to update or change the payment status, all payment updates and final transaction status must be handled exclusively via Hello Clever webhooks.
- Example payin method: kh_pay_khr

POST

payins

curl --request POST \
  --url https://api.cleverhub.co/api/v2/payins \
  --header 'Content-Type: application/json' \
  --header 'app-id: <api-key>' \
  --header 'secret-key: <api-key>' \
  --data '
{
  "currency": "AUD",
  "amount": 500,
  "name": "Hello Clever",
  "gst": false,
  "email": "test@example.com",
  "external_id": "123456",
  "payin_method_name": "au_payid_npp_aud",
  "payin_method_params": {
    "callback_url": "https://yourwebsite.com/callback"
  },
  "description": "Test Payin",
  "webhook_notification": {
    "endpoint_url": "https://yourserver.co/notifications",
    "authorization_header": "****"
  },
  "expired_at": "2021-12-23T06:00:00.000+0000",
  "metadata": {
    "custom_note": "Priority customer"
  }
}
'

{
  "uuid": "VMMAOTFQ",
  "name": "Hello Clever",
  "description": "description",
  "email": "test@example.com",
  "external_id": "123456",
  "status": "pending",
  "pay_code": {
    "payment_url": "https://sandbox-api.lightningpay.me/v1/shorted_url?hash=o10MJUBg"
  },
  "currency": "AUD",
  "gst": false,
  "amount": "1000.0",
  "gst_amount": "0",
  "total": "1000.0",
  "paid_amount": "0",
  "payment_method": "au_payid_npp_aud",
  "is_refundable": "false",
  "expired_at": "2021-12-23T06:00:00.000+0000",
  "pay_by": "2021-12-23T06:00:00.000+0000",
  "webhook_notification": {
    "endpoint_url": "https://yourserver.co/notifications",
    "authorization_header": "****"
  },
  "metadata": {
    "custom_note": "Priority customer"
  }
}

Authorizations

app-id

string

header

required

A unique identifier assigned to each application.

secret-key

string

header

required

A secure token associated with the app-id.

Body

application/json

currency

string

required

Transaction currency. It has to be a valid ISO 4217 currency codes. For example, 'PHP' for Philippine Peso, 'AUD' for Australian Dollar.

gst

boolean

required

Goods and Services Tax.

amount

number

required

Amount.

name

string

required

Customer name.

string

required

If required_contact == true, this email must be the same email that was used to create the contact.

description

string

required

Description.

payin_method_name

string

required

Payin method name to be used for this payment. You will receive this from the Get payin methods API.

payin_method_params

object

required

Payin method parameters. You will receive this from the Get payin’s required fields API.

Show child attributes

webhook_notification

object

required

Merchant Callback Details

Show child attributes

external_id

string

Custom ID.

expired_at

string<YYYY-MM-DDTHH:mm:ss>

This setting only applies to the payment method vn_vietqr_vnd.
Other methods are either fixed to default values or not configurable, and therefore cannot be edited.
The scheduled expiry must be set to at least 15 minutes later than the current time.

metadata

object

Optional custom metadata to attach to the transaction.

allocation_profile

object

Optional. Splits the payin across Payments Accounts with a platform fee (Clever Connect, Dedicated Balance only, and fund splitting must be enabled for the currency). See Platform Fees.

Show child attributes

Callbacks

POST

{$request.body#/webhook_notification/endpoint_url}myEvent

Body

application/json

uuid

string

Unique Id for the order created by Hello Clever system

Example:

"VMMAOTFQ"

name

string

Customer name.

Example:

"Test."

string

Customer email.

Example:

"test@example.com."

external_id

string

Custom ID.

Example:

"123456"

status

string<received | return_pending | return_received>

Status of Payin.

Example:

"received"

pay_code

object

Code using pay

Show child attributes

gst

boolean

GST for merchant.

Example:

"false,"

currency

string

Currency payin.

Example:

"PHP"

amount

number

Amount.

Example:

"1000.0"

gst_amount

number

GST amount.

Example:

"100.0"

total

number

Total amount.

Example:

"1100.0"

paid_amount

number

Paid Amount.

Example:

"1100.0"

description

string

Description

Example:

"The message that you want to send to the payee."

is_refundable

boolean

Available refund.

Example:

"false,"

expired_at

string<date-time>

This setting only applies to the payment method vn_vietqr_vnd.
Other methods are either fixed to default values or not configurable, and therefore cannot be edited.
The scheduled expiry must be set to at least 15 minutes later than the current time.

Example:

"2021-12-23T06:00:00.000+0000"

pay_by

string<date-time>

Pay by time of payment. This datetime would be in the UTC timezone. Must set the schedule bigger 15 minutes from the current time.

Example:

"2021-12-23T06:00:00.000+0000"

webhook_notification

object

Payment request notification

Show child attributes

Response

200

The merchant's server should return this code

Response

Created

uuid

string

name

string

description

string

external_id

string

status

Status of the transaction:

pending: Customer started a new payment but hasn't proceeded yet.
received: Funds have been received.
waiting: Payment has been approved, awaiting funds to settle.
expired: Payment session expired before completion.
return_pending: Refund request initiated, awaiting processing.
return_received: Full amount has been refunded to the customer.
return_expired: The refund request has expired. Expiration time is set to be 10 days.
return_rejected: Refund request was denied. The system will not retry again.

stage

string<authorize_otp | authorize_stk | normal_stage>

pay_code

object

Code using pay

Show child attributes

currency

string

gst

boolean

amount

number

gst_amount

number

total

number

paid_amount

number

payment_method

string

is_refundable

boolean

expired_at

string<date-time>

pay_by

string<date-time>

webhook_notification

object

Show child attributes

allocation_profile

object

The split applied to the payin. Only returned when the payin was split.

Show child attributes

curl --request POST \
  --url https://api.cleverhub.co/api/v2/payins \
  --header 'Content-Type: application/json' \
  --header 'app-id: <api-key>' \
  --header 'secret-key: <api-key>' \
  --data '
{
  "currency": "AUD",
  "amount": 500,
  "name": "Hello Clever",
  "gst": false,
  "email": "test@example.com",
  "external_id": "123456",
  "payin_method_name": "au_payid_npp_aud",
  "payin_method_params": {
    "callback_url": "https://yourwebsite.com/callback"
  },
  "description": "Test Payin",
  "webhook_notification": {
    "endpoint_url": "https://yourserver.co/notifications",
    "authorization_header": "****"
  },
  "expired_at": "2021-12-23T06:00:00.000+0000",
  "metadata": {
    "custom_note": "Priority customer"
  }
}
'

{
  "uuid": "VMMAOTFQ",
  "name": "Hello Clever",
  "description": "description",
  "email": "test@example.com",
  "external_id": "123456",
  "status": "pending",
  "pay_code": {
    "payment_url": "https://sandbox-api.lightningpay.me/v1/shorted_url?hash=o10MJUBg"
  },
  "currency": "AUD",
  "gst": false,
  "amount": "1000.0",
  "gst_amount": "0",
  "total": "1000.0",
  "paid_amount": "0",
  "payment_method": "au_payid_npp_aud",
  "is_refundable": "false",
  "expired_at": "2021-12-23T06:00:00.000+0000",
  "pay_by": "2021-12-23T06:00:00.000+0000",
  "webhook_notification": {
    "endpoint_url": "https://yourserver.co/notifications",
    "authorization_header": "****"
  },
  "metadata": {
    "custom_note": "Priority customer"
  }
}

Basics

Payment APIs

Card API

Cashback API

Reporting API

Create a Payin

Authorizations

Body

Callbacks

Body

Response

Response