Hello Clever Payment API Reference (2.0)
Hello Clever Payment is an instant payment solution empowered by the New Payments Platform with PayID and PayTo supported. Hello Clever also supports debit/credit cards with a competitive rates. With Hello Clever, you can create and monitor payment requests with powerful AI-powered insights, real-time enrichment, detailed classification, accurate and latest transaction information. Hello Clever Payment APIs are based on REST.
Hello Clever provides core API services enabling developers to build innovative payment solutions. You can use this documentation to integrate your application with Hello Clever.
Please note that, Hello Clever provides two ways of the API solution you can utilise depending on your business direction:
To use our API solution, you will need to register and have a merchant account (https://merchant.helloclever.co) to generate and obtain an access key. The merchant account will also enables you to manage and view payments from your customers, set up cashback rates, and manage payout accounts. You can reach out to our sales team via https://helloclever.typeform.com/enquiry to open an account free of charge. We provide a dedicated support team to guide you through the integration journey.
API Endpoint
- Sandbox API Endpoint: https://api.cleverhub.co
- Production API Endpoint: https://api-merchant.helloclever.co
We understand that starting a new service can be overwhelming. That's why we want to make the process as easy as possible for you. To get started quickly and smoothly, we recommend using our example Postman collection .
This collection is designed to give you a clear understanding of how our service works and how you can use it to achieve your goals. With this collection, you can easily explore our API and try out the different functionalities that we offer. So, if you're ready to dive in and start exploring, we encourage you to use our example Postman collection and let us know if you have any questions or feedback.
- The Hello Clever API uses API keys to authenticate requests. You can view and manage your API keys within the Hello Clever Dashboard.
- Our API is organised around REST and has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
- You can use our API in test mode within our sandbox environment, which does not affect your live data or interact with the banking networks. The API key you use to authenticate the request determines whether the request is live mode or test mode.
Create payment request
Create a PayID payment request for customers by sending the amount to charge and your customer's attributes along with the required currency. For now, Hello Clever only supports Australian Currency, if you would like to use Hello Clever with other currencies please get in touch with our team to discuss further.
Authorizations:
Request Body schema: application/json
name required | string/\A(?![ ])(?![ ]*$)[a-zA-Z0-9 ]*(?<![ ])\z/ Customer's name. |
gst required | boolean Goods and Services Tax for Australian merchants. |
amount required | number Amount. |
description required | string/\A(?![ ])(?![ ]*$)[a-zA-Z0-9 -._]*(?<![ ])\z... Description. |
emails required | string/^([a-z0-9_\-\.]+)@([a-z0-9_\-\.]+)\.([a-z]+)... Each emails split by comma. Please not that only lowercase letters are allowed. |
prefix_static_payid | string/\A(?=.{3,35}$)[a-z0-9.]*\z/ A static prefix for the PayID. The generated PayID will be in the format of |
expired_at | string <YYYY-MM-DDTHH:mm:ss> Expired time of payID. This datetime would be in the UTC timezone. Must set the schedule bigger 15 minutes from the current time. |
external_id | string Custom ID. |
object Merchant Callback Details |
Responses
Callbacks
Request samples
- Payload
{- "name": "Luyx",
- "gst": true,
- "amount": 1000,
- "description": "The message for the payee",
- "emails": "abc@gmail.com, xyz@gmail.com",
- "prefix_static_payid": "clever.pay.anything",
- "expired_at": "2021-12-23T06:00:00.000+0000",
- "external_id": "9999",
- "payment_request_notification": {
- "authorization_header": "helloclever token"
}
}
Response samples
- 200
- 401
- 422
{- "id": 1,
- "name": "Luyx",
- "request_payid": "t43.xnk@example.com",
- "merchant_name": "Clever Test",
- "gst": true,
- "amount": "1000.0",
- "total": "1100.0",
- "gst_amount": "100.0",
- "expired_at": "2021-12-23T06:00:00.000+0000",
- "external_id": "9999",
- "cashback_amount": 0,
- "pay_by": "2021-12-10T06:00:00.000+0000",
- "paid_at": "2021-12-10T06:00:00.000+0000",
- "status": "pending",
- "description": "description",
- "payee": {
- "name": "helloclever"
}, - "payment_request_notification": {
- "authorization_header": "****"
}, - "nonce": "9999",
- "stage": null,
- "sender_details": {
- "reference": "Example reference",
- "description": "Example description",
- "bsb": "123456",
- "account_number": "123456789",
- "account_name": "Example account name"
}
}
Callback payload samples
{- "id": 1,
- "balance_id": "8B035153-I1458G27",
- "name": "Jim",
- "request_payid": "t43.xnk@example.com",
- "merchant_name": "Hello Clever",
- "gst": true,
- "amount": "1000.0",
- "total": "1100.0",
- "gst_amount": "100.0",
- "expired_at": "2021-12-23T06:00:00.000+0000",
- "external_id": "9999",
- "cashback_amount": "100.0",
- "pay_by": "2021-12-10T06:00:00.000+0000",
- "paid_at": "2021-12-23T06:00:00.000+0000",
- "status": "received",
- "description": "The message that you want to send to the payee.",
- "refund_information": {
- "refund_payid": "refund_pay_id@example.me",
- "refund_amount": "10.99",
- "request_date": "2022-07-01T00:00:00.000+10:00",
- "reason": "Refund for payment",
- "processing_refund_time": {
- "start_time": "2022-07-01T00:00:00.000+10:00",
- "pending_time": "2022-07-01T00:00:00.000+10:00",
- "complete_time": "2022-07-01T00:00:00.000+10:00"
}
}, - "payee": {
- "name": "Jim"
}, - "payment_request_notification": {
- "authorization_header": "****"
}, - "nonce": "9999",
- "stage": null,
- "sender_details": {
- "reference": "Example reference",
- "description": "Example description",
- "bsb": "123456",
- "account_number": "123456789",
- "account_name": "Example account name"
}
}
Get payment requests in a period of time
You can easily query payment requests in a period of time. Currently we support up to 1 year period. Please get in touch with our team if you need to query payment requests for more than 1 year period.
Authorizations:
query Parameters
from_date | string Example: from_date=2022-01-01T00:00:00 Start date to query payment requests from, format 'DD/MM/YY' or 'YYYY-MM-DDThh:mm:ss'. This datetime would be in UTC timezone |
to_date | string Example: to_date=2022-01-01T00:00:00 End date to query payment requests, format 'DD/MM/YY' or 'YYYY-MM-DDThh:mm:ss'. The datetime would be in UTC timezone |
page | string Page number to query. Currently we support 20 records per page |
Responses
Response samples
- 200
- 401
{- "total": 100,
- "page": 1,
- "records": [
- {
- "id": 1,
- "balance_id": "8B035153-I1458G27",
- "request_payid": "t43.xnk@example.com",
- "gst": true,
- "amount": "1000.0",
- "total": "1100.0",
- "gst_amount": "100.0",
- "expired_at": "2021-12-25T06:00:00.000+0000",
- "external_id": "9999",
- "pay_to": "clever",
- "pay_by": "2021-12-10T06:00:00.000+0000",
- "paid_at": "2021-12-10T06:00:00.000+0000",
- "status": "pending",
- "to_pay_id": "testbank@gmail.com",
- "description": "description",
- "payee": {
- "name": "Luyx"
}, - "refund_infomation": {
- "refund_payid": "refund_pay_id@clever.me",
- "refund_amount": "200",
- "reason": "Refund reason",
- "request_date": "2022-02-17T01:33:23.691+0000"
}, - "nonce": "9999",
- "stage": "overpaid",
- "sender_details": null
}
]
}
Get payment request status
Check the status of a payment request. There are 6 statuses:
pending
: Your customer hasn't made the requested payment yetreceived
: Your customer has paid successfullyexpired
: The payment request has expiredreturn_pending
: A full refund or partial refund request has been triggered on the paymentreturn_received
: The refund has been transferred to the original payeereturn_expired
: The refund request has expired. Expiration time is set to be 10 days.return_rejected
: A refund failed due to problems with the destination account. HelloClever will not retry again.
Authorizations:
query Parameters
id required | integer Hello Clever ID that you request your customers for the Payment Request |
payid required | string Hello Clever PayID that you request your customers of the Payment Request |
Responses
Response samples
- 200
- 401
- 404
[- {
- "id": 1,
- "request_payid": "payid1@example.com",
- "name": "name",
- "gst": true,
- "amount": "1000.0",
- "total": "1100.0",
- "gst_amount": "100.0",
- "expired_at": "2021-12-23T06:00:00.000+0000",
- "external_id": "9999",
- "pay_to": "clever",
- "pay_by": "2021-12-10T06:00:00.000+0000",
- "paid_at": "2021-12-10T06:00:00.000+0000",
- "status": "pending",
- "to_pay_id": "testbank@gmail.com",
- "description": "description 1",
- "payee": {
- "name": "Luyx"
}, - "nonce": "9999",
- "stage": null,
- "sender_details": null
}, - {
- "id": 2,
- "request_payid": "payid2@example.com",
- "name": "name",
- "gst": true,
- "amount": "100.0",
- "total": "100.0",
- "gst_amount": "100.0",
- "expired_at": "2022-12-23T06:00:00.000+0000",
- "pay_to": "clever",
- "pay_by": "2021-12-23T06:00:00.000+0000",
- "paid_at": "2021-12-10T06:00:00.000+0000",
- "status": "received",
- "to_pay_id": "testbank@gmail.com",
- "description": "description 2",
- "refund_infomation": {
- "refund_payid": "refund_pay_id@clever.me",
- "refund_amount": "200",
- "reason": "Refund reason",
- "request_date": "2022-02-17T01:33:23.691+0000"
}, - "payee": {
- "name": "Luyx1"
}, - "nonce": "9999",
- "stage": null,
- "sender_details": {
- "description": "test",
- "reference": "test"
}
}
]
Create a Static Open PayID
Create a Static Open PayID
Authorizations:
Request Body schema: application/json
name required | string/\A(?![ ])(?![ ]*$)[a-zA-Z0-9 ]*(?<![ ])\z/ Name of Static Open PayID |
email required | string Email of Static Open PayID |
prefix_static_payid required | string/\A(?=.{3,35}$)[a-z0-9.]*\z/ Generate prefix PayID to customer |
address | string |
phone | string |
city | string |
zip_code | string |
state | string |
external_id | string A custom PayID you can refer to in the future |
object Merchant Callback Details |
Responses
Callbacks
Request samples
- Payload
{- "name": "Luyx",
- "email": "test@test.com",
- "prefix_static_payid": "static.payid",
- "address": "123 abc",
- "phone": "123456789",
- "city": "Abc",
- "zip_code": "12345",
- "state": "Abc",
- "external_id": "123",
- "customer_notification": {
- "authorization_header": "helloclever token"
}
}
Response samples
- 200
- 401
- 422
{- "name": "Luyx",
- "email": "test@test.com",
- "address": "123 abc",
- "phone": "123456789",
- "zip_code": "12345",
- "city": "abc",
- "state": "VN",
- "static_payid": "static.payid@example.com",
- "external_id": "123",
- "cusomter_notification": {
- "authorization_header": "hellocelver authorization"
}, - "status": "active"
}
Callback payload samples
{- "id": 1,
- "name": "Jim",
- "request_payid": "static.payid@example.com",
- "merchant_name": "Hello Clever",
- "gst": true,
- "amount": "1000.0",
- "total": "1100.0",
- "gst_amount": "100.0",
- "expired_at": "2021-12-23T06:00:00.000+0000",
- "external_id": "9999",
- "cashback_amount": "100.0",
- "pay_by": "2021-12-10T06:00:00.000+0000",
- "status": "received",
- "description": "The message that you want to send to the payee.",
- "refund_information": {
- "refund_payid": "refund_pay_id@example.me",
- "refund_amount": "10.99",
- "request_date": "2022-07-01T00:00:00.000+10:00",
- "reason": "Refund for payment",
- "processing_refund_time": {
- "start_time": "2022-07-01T00:00:00.000+10:00",
- "pending_time": "2022-07-01T00:00:00.000+10:00",
- "complete_time": "2022-07-01T00:00:00.000+10:00"
}
}, - "payee": {
- "name": "Jim",
- "email": "test@test.com",
- "address": "123 abc",
- "phone": "123456789",
- "zip_code": "12345",
- "city": "abc",
- "state": "VN",
- "external_id": "123",
- "status": "active"
}, - "nonce": "9999",
- "stage": null,
- "sender_details": {
- "description": "description",
- "reference": "reference",
- "account_name": "Hello Clever",
- "account_number": "12345678",
- "bsb": "123456"
}
}
Get a list of all Static Open PayIDs
Get a list of all Static Open PayIDs in your account
Authorizations:
query Parameters
string Query by email | |
payid | string Query by PayID |
customer_id | string Query by Customer ID |
Responses
Response samples
- 200
- 401
{- "total": 20,
- "page": 1,
- "total_page": 1,
- "records": [
- {
- "id": 1,
- "name": "Luyx",
- "address": "123 abc",
- "email": "abc@test.com",
- "city": "Abc",
- "state_name": "Abc",
- "zip_code": "12345",
- "static_payid": "luyx@abc.com",
- "external_id": "123",
- "status": "active"
}, - {
- "id": 2,
- "name": "Luyx1",
- "address": "123 abc",
- "email": "abc@test.com",
- "city": "Abc",
- "state_name": "Abc",
- "zip_code": "12345",
- "static_payid": "luyx@abc.com",
- "external_id": "123",
- "status": "active"
}
]
}
Refund a payment
Initiate a refund request on a completed payment (with received
status). Once the refund request is triggered, a refund PayID
will be generated which you (the merchant) can use to top up your balance (if needed) to refund the original payee.
Authorizations:
Request Body schema: application/json
payment_request_id required | integer Payment request ID |
refund_amount | number Refund amount, must be numeric. If not specified, the refund amount will be the same as the total amount. |
reason required | string Partial refund reason, must be at least 5 characters long |
Responses
Request samples
- Payload
{- "payment_request_id": 1,
- "refund_amount": 100,
- "reason": "Partial Refund Reason"
}
Response samples
- 200
- 401
- 422
{- "refund_payid": "refund_pay_id@clever.me",
- "total_amount": "200",
- "refund_amount": "100",
- "reason": "Partial refund",
- "payment_request": {
- "id": 1,
- "request_payid": "payid1@example.com",
- "name": "name",
- "gst": true,
- "amount": "1000.0",
- "total": "1100.0",
- "gst_amount": "100.0",
- "expired_at": "2021-12-23T06:00:00.000+0000",
- "pay_to": "clever",
- "pay_by": "2021-12-10T06:00:00.000+0000",
- "status": "pending",
- "to_pay_id": "testbank@gmail.com",
- "description": "description 1",
- "payee": {
- "name": "Luyx"
}, - "refund_infomation": {
- "refund_payid": "refund_pay_id@clever.me",
- "refund_amount": "200",
- "reason": "Partial refund",
- "request_date": "2022-02-17T01:33:23.691+0000"
}, - "nonce": "9999",
- "stage": null
}
}
Cancel a PayID
Cancel a pending
PayID transaction, the PayID will be deregistered and the transaction status will be updated to expired
.
Authorizations:
Request Body schema: application/json
payid required | string PayID |
Responses
Request samples
- Payload
{- "payid": "abc.xyz@example.co"
}
Response samples
- 200
- 401
- 422
{- "payid": "abc.xyz@example.co"
}
Create a payment agreement
There are 2 payment types:
pay_id
: Payer use PayID as a payment methodbsb
: Payer use BSB/Account number.no as a payment method
Authorizations:
Request Body schema: application/json
client_transaction_id required | string [ 1 .. 90 ] characters Unique Id for the transaction created by merchant system |
limit_amount required | number Amount limit of each payment agreement. If the agreement_details below specify a fixed agreement, the limit amount must match the exact amount that you intend to charge. In other words, if you want to use fixed agreement details, the limit amount should be exactly equal to the amount you are charging." |
description required | string [ 5 .. 140 ] characters Description |
external_id | string [ 0 .. 255 ] characters Custom ID |
payment_agreement_type required | string Enum: "MORTGAGE" "UTILITY" "LOAN" "DEPENDANT SUPPORT" "GAMBLING" "RETAIL" "SALARY" "PERSONAL" "GOVERNMENT" "PENSION" "TAX" "OTHER SERVICE" |
required | object or fixed_agreement_details_obj (object) or usage_bases_agreement_details_obj (object) or balloon_agreement_details_obj (object) |
required | object Provide either |
required | object Merchant Callback Details |
Responses
Callbacks
Request samples
- Payload
{- "client_transaction_id": "30597959-a853-44d4-bdab-54332bf7a98e",
- "limit_amount": 1000,
- "description": "Description",
- "external_id": "343h.te",
- "payment_agreement_type": "MORTGAGE",
- "agreement_details": {
- "variable_agreement_details": {
- "start_date": "01/01/22",
- "frequency": "ADHOC"
}
}, - "payer_details": {
- "name": "Hello Clever",
- "bank_account_details": {
- "bsb": "123456",
- "account_number": "123555555"
}, - "pay_id_details": {
- "pay_id": "helloclever@example.com",
- "pay_id_type": "email"
}
}, - "payment_agreement_notification": {
- "authorization_header": "SECRET"
}
}
Response samples
- 200
- 401
- 404
- 422
{- "id": 5,
- "payment_agreement_id": "30597959a85344d4bdab54332bf7a98e",
- "client_transaction_id": "30597959-a853-44d4-bdab-54332bf7a98e",
- "limit_amount": 1000,
- "description": "Description",
- "external_id": "343h.te",
- "status": "created",
- "created_at": "2022-01-01T00:00:00.000+0000",
- "payment_agreement_type": "MORTGAGE",
- "agreement_details": {
- "variable_agreement_details": {
- "start_date": "01/01/22",
- "frequency": "ADHOC"
}
}, - "payer_details": {
- "name": "Hello Clever",
- "bank_account_details": {
- "bsb": "123456",
- "account_number": "123555555"
}, - "pay_id_details": {
- "pay_id": "helloclever@example.com",
- "pay_id_type": "EMAIL"
}
}, - "payment_agreement_notification": {
- "authorization_header": "SECRET"
}
}
Callback payload samples
{- "payment_agreement_id": "30597959a85344d4bdab54332bf7a98e",
- "client_transaction_id": "30597959-a853-44d4-bdab-54332bf7a98e",
- "limit_amount": 1000,
- "description": "Description",
- "status": "created",
- "created_at": "2022-01-01T00:00:00.000+0000",
- "payment_agreement_type": "MORTGAGE",
- "agreement_details": {
- "variable_agreement_details": {
- "start_date": "01/01/22",
- "frequency": "ADHOC"
}
}, - "payer_details": {
- "name": "Hello Clever",
- "bank_account_details": {
- "bsb": "123456",
- "account_number": "123555555"
}, - "pay_id_details": {
- "pay_id": "helloclever@example.com",
- "pay_id_type": "EMAIL"
}
}, - "payment_agreement_notification": {
- "authorization_header": "SECRET"
}
}
Amend a payment agreement
Authorizations:
Request Body schema: application/json
id required | number Hello Clever payment ID |
limit_amount required | number Amount limit of each payment agreement |
required | variable_agreement_amendment_details_obj (object) or fixed_agreement_amendment_details_obj (object) or usage_bases_agreement_amendment_details_obj (object) or balloon_agreement_amendment_details_obj (object) |
object Merchant Callback Details |
Responses
Callbacks
Request samples
- Payload
{- "id": 4,
- "limit_amount": 1000,
- "agreement_details": {
- "variable_agreement_details": {
- "frequency": "ADHOC"
}
}, - "payment_agreement_notification": {
- "authorization_header": "SECRET"
}
}
Response samples
- 200
- 401
- 404
- 422
{- "payment_agreement_amendment": {
- "id": 5,
- "payment_agreement_id": "30597959a85344d4bdab54332bf7a98e",
- "client_transaction_id": "30597959-a853-44d4-bdab-54332bf7a98e",
- "limit_amount": 1000,
- "description": "Description",
- "external_id": "2t2.t3",
- "created_at": "2022-01-01T00:00:00.000+0000",
- "payment_agreement_type": "MORTGAGE",
- "agreement_details": {
- "variable_agreement_details": {
- "start_date": "01/01/22",
- "frequency": "ADHOC"
}
}, - "payer_details": {
- "name": "Hello Clever",
- "bank_account_details": {
- "bsb": "123456",
- "account_number": "123555555"
}, - "pay_id_details": {
- "pay_id": "helloclever@example.com",
- "pay_id_type": "EMAIL"
}
}, - "payment_agreement_notification": {
- "authorization_header": "SECRET"
}
}, - "payment_agreement_amendment_status": {
- "bilateral_amendment_status": "created",
- "payment_agreement_amendment_id": "30597959a85344d4bdab54332bf7a98e"
}
}
Callback payload samples
{- "payment_agreement_amendment": {
- "id": 5,
- "payment_agreement_id": "30597959a85344d4bdab54332bf7a98e",
- "client_transaction_id": "30597959-a853-44d4-bdab-54332bf7a98e",
- "limit_amount": 1000,
- "description": "Description",
- "external_id": "2t2.t3",
- "created_at": "2022-01-01T00:00:00.000+0000",
- "payment_agreement_type": "MORTGAGE",
- "agreement_details": {
- "variable_agreement_details": {
- "start_date": "01/01/22",
- "frequency": "ADHOC"
}
}, - "payer_details": {
- "name": "Hello Clever",
- "bank_account_details": {
- "bsb": "123456",
- "account_number": "123555555"
}, - "pay_id_details": {
- "pay_id": "helloclever@example.com",
- "pay_id_type": "EMAIL"
}
}, - "payment_agreement_notification": {
- "authorization_header": "SECRET"
}
}, - "payment_agreement_amendment_status": {
- "bilateral_amendment_status": "created",
- "payment_agreement_amendment_id": "30597959a85344d4bdab54332bf7a98e"
}
}
Change status a payment agreement
Authorizations:
Request Body schema: application/json
id required | number Hello Clever payment ID |
status required | string Enum: "active" "cancelled" "suspended" |
Responses
Request samples
- Payload
{- "id": 4,
- "status": "active"
}
Response samples
- 200
- 401
- 404
- 422
{- "id": 5,
- "payment_agreement_id": "30597959a85344d4bdab54332bf7a98e",
- "client_transaction_id": "30597959-a853-44d4-bdab-54332bf7a98e",
- "limit_amount": 1000,
- "description": "Description",
- "external_id": "2t2.t3",
- "status": "created",
- "created_at": "2022-01-01T00:00:00.000+0000",
- "payment_agreement_type": "MORTGAGE",
- "agreement_details": {
- "variable_agreement_details": {
- "start_date": "01/01/22",
- "frequency": "ADHOC"
}
}, - "payer_details": {
- "name": "Hello Clever",
- "bank_account_details": {
- "bsb": "123456",
- "account_number": "123555555"
}, - "pay_id_details": {
- "pay_id": "helloclever@example.com",
- "pay_id_type": "EMAIL"
}
}, - "payment_agreement_notification": {
- "authorization_header": "SECRET"
}
}
Get payment agreement detail
Check the status of a payment request. There are 5 statuses:
created
: Your customer triggered a Payment Agreement creationactive
: The payment agreement is activesuspended
: The payment agreement is suspendedcancelled
: The payment agreement has been cancelledfailed
: The Payment agreement has failed
Using PayID to test the status:created
: PayID no-action@example.com will keep the payment agreement in the status createdfailed
: PayID error@example.com will result in an error and set the created payment agreement with the status failedcancelled
: PayID cancel-agreement@example.com will create a payment agreement with the status cancelledsuspended
: PayID suspend-agreement@example.com will create a payment agreement with the status suspended
Authorizations:
query Parameters
id required | integer Hello Clever payment ID |
Responses
Response samples
- 200
- 401
- 422
{- "id": 234,
- "payment_agreement_id": "30597959a85344d4bdab54332bf7a98e",
- "client_transaction_id": "30597959-a853-44d4-bdab-54332bf7a98e",
- "limit_amount": 1000,
- "description": "Description",
- "status": "created",
- "created_at": "2022-01-01T00:00:00.000+0000",
- "payment_agreement_type": "MORTGAGE",
- "agreement_details": {
- "variable_agreement_details": {
- "start_date": "01/01/22",
- "frequency": "ADHOC"
}
}, - "payer_details": {
- "name": "Hello Clever",
- "bank_account_details": {
- "bsb": "123456",
- "account_number": "123555555"
}, - "pay_id_details": {
- "pay_id": "helloclever@example.com",
- "pay_id_type": "EMAIL"
}
}, - "payment_agreement_notification": {
- "authorization_header": "SECRET"
}
}
Get payment agreements
Authorizations:
query Parameters
from_date | string <date-time> Example: from_date=2022-01-01T00:00:00 Start date to query payment agreements, format 'DD/MM/YY' or 'YYYY-MM-DDThh:mm:ss'. This datetime is in UTC. |
to_date | string <date-time> Example: to_date=2022-01-01T00:00:00 End date to query payment agreements, format 'DD/MM/YY' or 'YYYY-MM-DDThh:mm:ss'. This datetime is in UTC. |
page | string |
size | string |
Responses
Response samples
- 200
- 401
- 422
{- "from_date": "2022-01-01T00:00:00.000+0000",
- "to_date": "2022-12-01T00:00:00.000+0000",
- "page": 1,
- "size": 10,
- "next_page": 2,
- "total_page": 1,
- "total_count": 10,
- "records": [
- {
- "id": 5,
- "payment_agreement_id": "30597959a85344d4bdab54332bf7a98e",
- "client_transaction_id": "30597959-a853-44d4-bdab-54332bf7a98e",
- "limit_amount": 1000,
- "description": "Description",
- "status": "return_received",
- "created_at": "2022-01-01T00:00:00.000+0000",
- "payment_agreement_type": "MORTGAGE",
- "agreement_details": {
- "variable_agreement_details": {
- "start_date": "01/01/22",
- "frequency": "ADHOC"
}
}, - "payer_details": {
- "name": "Hello Clever",
- "bank_account_details": {
- "bsb": "123456",
- "account_number": "123555555"
}, - "pay_id_details": {
- "pay_id": "helloclever@example.com",
- "pay_id_type": "EMAIL"
}
}, - "payment_agreement_notification": {
- "authorization_header": "SECRET"
}
}
]
}
Create a payment initiation
Create a payment initiation
Authorizations:
Request Body schema: application/json
client_transaction_id required | string [ 1 .. 95 ] characters Unique Id for the transaction created by merchant |
amount required | number Amount of payment |
id required | number Hello Clever Id response when creating a payment agreement |
external_id | string Custom ID |
description | string Description payment initiation |
required | object Merchant Callback Details |
Responses
Callbacks
Request samples
- Payload
{- "client_transaction_id": "30597959-a853-44d4-bdab-54332bf7a98e",
- "amount": 10.5,
- "id": 56,
- "external_id": "9999",
- "description": "Clever test here",
- "payment_initiation_notification": {
- "authorization_header": "SECRET"
}
}
Response samples
- 200
- 401
- 422
{- "id": 234,
- "gst": true,
- "gst_amount": 23.2,
- "description": "Hello clever",
- "client_transaction_id": "30597959-a853-44d4-bdab-54332bf7a98e",
- "total": 10.5,
- "amount": 10.5,
- "payment_agreement_id": "VatpdiYL7EmcV9g+--IvqBL0cT39bvW5eS--RRJg+B58qveWdxPTJ0FMSg==",
- "payment_initiation_notification": {
- "authorization_header": "SECRET"
}, - "payment_initiation_id": "VatpdiYL7EmcV9g+--IvqBL0cT39bvW5eS--RRJg+B58qveWdxPTJ0FMSg==",
- "status": "pending",
- "created_at": "2022-01-01T00:00:00.000+0000",
- "payee": {
- "name": "Clever",
- "external_id": "9999"
}
}
Callback payload samples
{- "client_transaction_id": "30597959-a853-44d4-bdab-54332bf7a98e",
- "amount": 10.5,
- "payment_agreement_id": "VatpdiYL7EmcV9g+--IvqBL0cT39bvW5eS--RRJg+B58qveWdxPTJ0FMSg==",
- "external_id": "9999",
- "payment_initiation_notification": {
- "authorization_header": "SECRET"
}, - "payment_initiation_id": "VatpdiYL7EmcV9g+--IvqBL0cT39bvW5eS--RRJg+B58qveWdxPTJ0FMSg==",
- "status": "received",
- "created_at": "2022-01-01T00:00:00.000+0000"
}
Get payment initiations
Authorizations:
query Parameters
from_date | string <date-time> Example: from_date=2022-01-01T00:00:00 Start date to query payment agreements, format 'DD/MM/YY' or 'YYYY-MM-DDThh:mm:ss'. This datetime is in UTC. |
to_date | string <date-time> Example: to_date=2022-01-01T00:00:00 End date to query payment agreements, format 'DD/MM/YY' or 'YYYY-MM-DDThh:mm:ss'. The datetime is in UTC timezone. |
page | string |
size | string |
Responses
Response samples
- 200
- 401
- 422
{- "from_date": "2022-01-01T00:00:00.000+0000",
- "to_date": "2022-12-01T00:00:00.000+0000",
- "page": 1,
- "size": 10,
- "next_page": 2,
- "total_page": 1,
- "total_count": 10,
- "records": [
- {
- "id": 234,
- "gst": true,
- "gst_amount": 23.2,
- "description": "Hello clever",
- "client_transaction_id": "30597959-a853-44d4-bdab-54332bf7a98e",
- "total": 10.5,
- "amount": 10.5,
- "payment_agreement_id": "VatpdiYL7EmcV9g+--IvqBL0cT39bvW5eS--RRJg+B58qveWdxPTJ0FMSg==",
- "payment_initiation_notification": {
- "authorization_header": "SECRET"
}, - "payment_initiation_id": "VatpdiYL7EmcV9g+--IvqBL0cT39bvW5eS--RRJg+B58qveWdxPTJ0FMSg==",
- "status": "received",
- "created_at": "2022-01-01T00:00:00.000+0000",
- "payee": {
- "name": "Hello Clever",
- "external_id": "9999"
}, - "refund_information": {
- "refund_payid": "refund_pay_id@clever.me",
- "refund_amount": "10.99",
- "request_date": "2022-07-01T00:00:00.000+10:00",
- "reason": "Refund for payment",
- "processing_refund_time": {
- "start_time": "2022-07-01T00:00:00.000+10:00",
- "pending_time": "2022-07-01T00:00:00.000+10:00",
- "complete_time": "2022-07-01T00:00:00.000+10:00"
}
}
}
]
}
Refund a payment initiation
Authorizations:
Request Body schema: application/json
id required | integer Unique Id for the payment |
refund_amount | number Refund amount, must be numeric |
reason required | string Refund reason, must be at least 5 characters long |
Responses
Request samples
- Payload
{- "id": 234,
- "refund_amount": 0.5,
- "reason": "My wife wants to refund."
}
Response samples
- 200
- 401
- 422
{- "id": 234,
- "gst": true,
- "gst_amount": 23.2,
- "description": "Hello clever",
- "client_transaction_id": "30597959-a853-44d4-bdab-54332bf7a98e",
- "total": 10.5,
- "amount": 10.5,
- "payment_agreement_id": "VatpdiYL7EmcV9g+--IvqBL0cT39bvW5eS--RRJg+B58qveWdxPTJ0FMSg==",
- "payment_initiation_notification": {
- "authorization_header": "SECRET"
}, - "payment_initiation_id": "VatpdiYL7EmcV9g+--IvqBL0cT39bvW5eS--RRJg+B58qveWdxPTJ0FMSg==",
- "status": "return_pending",
- "created_at": "2022-01-01T00:00:00.000+0000",
- "payee": {
- "name": "Clever",
- "external_id": "9999"
}, - "refund_information": {
- "refund_payid": "refund_pay_id@clever.me",
- "refund_amount": "10.99",
- "request_date": "2022-07-01T00:00:00.000+10:00",
- "reason": "Refund for payment",
- "processing_refund_time": {
- "start_time": "2022-07-01T00:00:00.000+10:00",
- "pending_time": "2022-07-01T00:00:00.000+10:00",
- "complete_time": "2022-07-01T00:00:00.000+10:00"
}
}
}
Get payment initiation detail
Check the status of a payment request. There are 6 statuses:
pending
: Your customer hasn't made the requested payment yetreceived
: Your customer has paid successfullyreturn_pending
: A full refund or partial refund request has been triggered on the paymentreturn_received
: The refund has been transferred to the original payeereturn_expired
: The refund request has expired.return_rejected
: A refund failed due to problems with the destination account. HelloClever will not retry again.failed
: The payment has failed
Authorizations:
query Parameters
id required | integer Hello Clever payment ID |
Responses
Response samples
- 200
- 401
- 422
{- "id": 234,
- "gst": true,
- "gst_amount": 23.2,
- "description": "Hello clever",
- "client_transaction_id": "30597959-a853-44d4-bdab-54332bf7a98e",
- "total": 10.5,
- "amount": 10.5,
- "payment_agreement_id": "VatpdiYL7EmcV9g+--IvqBL0cT39bvW5eS--RRJg+B58qveWdxPTJ0FMSg==",
- "payment_initiation_notification": {
- "authorization_header": "SECRET"
}, - "payment_initiation_id": "VatpdiYL7EmcV9g+--IvqBL0cT39bvW5eS--RRJg+B58qveWdxPTJ0FMSg==",
- "status": "received",
- "created_at": "2022-01-01T00:00:00.000+0000",
- "payee": {
- "name": "Clever",
- "external_id": "9999"
}, - "refund_information": {
- "refund_payid": "refund_pay_id@clever.me",
- "refund_amount": "10.99",
- "request_date": "2022-07-01T00:00:00.000+10:00",
- "reason": "Refund for payment",
- "processing_refund_time": {
- "start_time": "2022-07-01T00:00:00.000+10:00",
- "pending_time": "2022-07-01T00:00:00.000+10:00",
- "complete_time": "2022-07-01T00:00:00.000+10:00"
}
}
}
Create a payout payment
This API allows you to make outbound payments to PayID or NPP enabled BSB accounts. If a payout cannot be processed due to lack of funds and the is_retry flag is true, the system will continue to try to process it until the balance is sufficient, either through a top-up or new payments.
There are 4 statuses of the payment:
created
: Payout payment created.processing
: Payout has been topped up to the corresponding payID.scheduled
: Waiting for fund to be charged to the payee.completed
: Payout payment has been completed for the entire batch, not for individual transactions. Please note that if any of the transactions fail, it will not affect the completion of the entire batch.
Please note that:
- If you use a phone number as the PayID, you need to add the country code in front of the phone number and a dash. For example:
+61-412345678
. - If you use an email as the PayID, it needs to be lower case. For example:
JohW1ck@gmail.com
is NOT a valid email, it should bejohw1ck@gmail.com
We support two methods of creating a payout payment: Creating from a file or an array JSON object. You need to adjust the Content-Type for each method, so please refer to the request body schema below.
Authorizations:
Request Body schema:
file required | string <File (.csv or .xlsx)> Get file example from https://helloclever.co/static/assets/payout/post-request-example.zip |
scheduled_at | string <YYYY-MM-DDTHH:mm:ss> Payout transaction to payee in this time. This datetime would be in UTC timezone. |
description required | string [ 5 .. 140 ] characters Description of payout payment |
is_retry | boolean Retry to payout payment. Default value is false. If is_retry is true, the system will continue to try to process it until the balance is sufficient, either through a top-up or new payments. |
external_id | string Custom ID |
endpoint_url required | string <url (endpoint_url)> An internet accessible url which Hello Clever will invoke when the status of the transaction has changed. The call will be done using the HTTP POST method. The endpoint exposed by the client must be TLS 1.2 and the server certificate must be issued by a well known commercial certificate authority and that self-signed or internally signed certs are not acceptable. |
authorization_header required | string <(authorization_header)> The string that Hello Clever will put into the Authorization request header when calling the Callback url. |
Responses
Callbacks
Request samples
- Payload
{ "file": "Payout-Payment.csv", "scheduled_at": "2023-04-01T00:00:00.000+0000", "description": "Payout payment 2023", "is_retry": true, "external_id": "123", "endpoint_url": "https://example.org", "authorization_header": "SECRET" }
Response samples
- 200
- 400
- 401
- 404
- 422
{- "id": 5,
- "uuid": "OHXTEF9M",
- "description": "Payout payment 2023",
- "payid": "business@helloclever.co",
- "total_amount": "1000",
- "total_refund": 300,
- "total_failed_transactions": 5,
- "scheduled_at": "2023-04-01T00:00:00.000+0000",
- "status": "completed",
- "error_code": "HC_PAYOUT1",
- "error_message": "Insufficient available funds. Top up your balance.",
- "is_retry": true,
- "external_id": "123"
}
Callback payload samples
{- "id": 5,
- "uuid": "OHXTEF9M",
- "description": "Payout payment 2023",
- "payid": "business@helloclever.co",
- "external_id": "123",
- "total_amount": "1000",
- "total_refund": 300,
- "total_failed_transactions": 5,
- "scheduled_at": "2023-04-01T00:00:00.000+0000",
- "status": "completed",
- "payout_transactions": [
- {
- "id": 5,
- "balance_id": "808C75EF-988143EB",
- "payee": "Join",
- "payid": "business@helloclever.co",
- "payid_type": "email",
- "bsb": "1000",
- "account_number": "1000",
- "amount": "100.00",
- "status": "settled",
- "error_code": "PO01",
- "error_message": "PayID not found",
- "created_at": "2022-01-01T00:00:00.000+0000"
}
]
}
List of payout payments
You can easily query payout payments in a period of time. Currently we support up to 1 year period. Should you need more, please contact us directly.
Authorizations:
query Parameters
from_date required | string Example: from_date=2022-01-01T00:00:00 Start date to queries payment requests from, format 'DD/MM/YY' or 'YYYY-MM-DDThh:mm:ss'. This datetime would be in UTC timezone |
to_date required | string Example: to_date=2022-01-01T00:00:00 End date to queries payment requests, format 'DD/MM/YY' or 'YYYY-MM-DDThh:mm:ss'. This datetime would be in UTC timezone |
page required | string Page number to query. Currently we support 20 records per page |
Responses
Response samples
- 200
- 401
- 404
- 422
{- "from_date": "2022-01-01T00:00:00.000+0000",
- "to_date": "2022-12-01T00:00:00.000+0000",
- "page": 1,
- "size": 10,
- "next_page": 2,
- "total_page": 1,
- "total_count": 10,
- "records": [
- {
- "id": 5,
- "uuid": "OHXTEF9M",
- "description": "Payout payment 2023",
- "payid": "business@helloclever.co",
- "total_amount": "1000",
- "total_refund": 300,
- "total_failed_transactions": 5,
- "scheduled_at": "2023-04-01T00:00:00.000+0000",
- "status": "completed",
- "export_url": "string",
- "error_code": "HC_PAYOUT1",
- "error_message": "Insufficient available funds. Top up your balance.",
- "is_retry": true,
- "external_id": "123",
- "payout_transactions": [
- {
- "id": 5,
- "balance_id": "808C75EF-988143EB",
- "payee": "Join",
- "payid": "business@helloclever.co",
- "payid_type": "email",
- "bsb": "1000",
- "account_number": "1000",
- "amount": "100.00",
- "status": "settled",
- "error_message": "PayID not found",
- "created_at": "2022-01-01T00:00:00.000+0000"
}
]
}
]
}
Get payout payment detail
Check the status of a payout payment. There are 4 statuses:
created
: Payout payment created.processing
: Payout has been topup to payID response.scheduled
: Waiting charge fund to payee.completed
: Payout payment completed.
Authorizations:
query Parameters
id required | integer Hello Clever payout payment ID |
uuid | string Hello Clever payout payment UUID |
Responses
Response samples
- 200
- 401
- 422
{- "id": 5,
- "uuid": "0PSGX71S",
- "description": "Payout payment 2023",
- "payid": "business@helloclever.co",
- "total_amount": "1000",
- "total_refund": 300,
- "total_failed_transactions": 5,
- "scheduled_at": "2023-04-01T00:00:00.000+0000",
- "status": "completed",
- "export_url": "string",
- "error_code": "HC_PAYOUT1",
- "error_message": "Insufficient available funds. Top up your balance.",
- "is_retry": true,
- "external_id": "123",
- "payout_transactions": [
- {
- "id": 5,
- "balance_id": "94AFB7D6-QVIA6QU0",
- "payee": "Join",
- "payid": "business@helloclever.co",
- "payid_type": "email",
- "bsb": "1000",
- "account_number": "1000",
- "amount": "100.00",
- "status": "settled",
- "error_code": "PO01",
- "error_message": "PayID not found",
- "created_at": "2022-01-01T00:00:00.000+0000"
}
]
}
Cancel a scheduled payout payment
You can cancel a payout payment scheduled to run in the future.
Authorizations:
Request Body schema: application/json
payout_payment_uuid required | string Payout payment UUID |
Responses
Request samples
- Payload
{- "payout_payment_uuid": "OHXTEF9M"
}
Response samples
- 200
- 401
- 422
{- "status": "OK"
}
Create KYC
Create KYC for Payouts. For payouts above 5000 AUD, it is mandatory to complete the KYC process.
Authorizations:
Request Body schema: multipart/form-data
email required | string Email associated with the KYC process. |
id_doc_type required | string Enum: "id_card" "passport" Type of ID Document. |
id_doc_front_side required | string <binary> The front side of the ID Document. File format must be PDF. |
id_doc_back_side required | string <binary> The back side of the ID Document. File format must be PDF. |
selfie required | string <binary> Selfie image of the user. File format must be JPEG. |
Responses
Response samples
- 200
- 400
- 401
- 422
{- "status": "ok"
}
Generate access token
Generate an access token to initiate a payment with Hello Clever payment gateway. You need to exchange your app-id and secret key for this access token. The access token can be used in clients and has an expiration time. By default, this access token will expire within 3600 seconds after generation.
Authorizations:
Responses
Response samples
- 200
- 401
{- "access_token": "19d2f50fe935f06d3f521862b61eda08dd4796dda81167904c7c7f29424a1011",
- "expires_in": 3600
}
Create a Hello Clever payment gateway link
You can create a Hello Clever payment gateway link which you can redirect your customer to. Once the payment is made successfully, Hello Clever payment gateway will notify the status of the payment to an endpoint you specify and will redirect your user back to your website/app. The payment request has different statuses during its life cycle. There are 7 statuses:
pending
: Your customer hasn't made the requested payment yetwaiting
: Your customer has paid successfully but payment has not been sent to youreceived
: Your customer has paid and you should receoved the paymentexpired
: The payment request has expiredreturn_pending
: A full refund or partial refund request has been triggered on the transactionreturn_received
: The refund has been transferred to the original payeereturn_expired
: The refund request has expired. Expiration time is set to be expired in 10 days.return_rejected
: A refund failed due to problems with the destination account. HelloClever will not retry again.
payment_gateway_notification
is where you specify an endpoint to get notified when the status of the payment is changed to received
or waiting
or return_received
Authorizations:
Request Body schema: application/json
order_id required | string Unique Id for the order created by the merchant system |
amount required | number Amount of payment |
description required | string [ 5 .. 140 ] characters Description |
order_success_url required | string URL to redirect to after the payment has been made successfully, usually your Order Success URL |
required | object Order details |
required | object Merchant Callback Details |
Responses
Callbacks
Request samples
- Payload
{- "order_id": "30597959-a853-44d4-bdab-54332bf7a98e",
- "amount": 99.9,
- "description": "Description",
- "order_details": {
- "billing_details": {
- "first_name": "Luyx",
- "last_name": "Tran",
- "phone": "123456789",
- "email": "abc@gmail.com",
- "company": "HelloClever",
- "country_code": "AU",
- "state": "Australian Capital Territory",
- "postal_code": "2601",
- "city": "Acton",
- "address": "123 Abc Street"
}, - "shipping_details": {
- "first_name": "Luyx",
- "last_name": "Tran",
- "phone": "123456789",
- "email": "abc@gmail.com",
- "company": "HelloClever",
- "country_code": "AU",
- "state": "Australian Capital Territory",
- "postal_code": "2601",
- "city": "Acton",
- "address": "123 Abc Street"
}, - "items": [
- {
- "id": "1",
- "name": "name",
- "variant_id": "",
- "quantity": "2",
- "price": "199.0",
- "enable_cashback": true
}
]
}, - "payment_gateway_notification": {
- "authorization_header": "SECRET"
}
}
Response samples
- 200
- 401
- 404
- 422
{- "payment_id": "02e74f10e0327ad868d138f2b4fdd6f0",
- "order_id": "30597959-a853-44d4-bdab-54332bf7a98e",
- "amount": 99.9,
- "cashback_amount": 1,
- "transaction_fee": 2,
- "actual_receive_amount": 96.9,
- "description": "Description",
- "status": "received",
- "order_details": {
- "billing_details": {
- "first_name": "Luyx",
- "last_name": "Tran",
- "phone": "123456789",
- "email": "abc@gmail.com",
- "company": "HelloClever",
- "country_code": "AU",
- "state": "Australian Capital Territory",
- "postal_code": "2601",
- "city": "Acton",
- "address": "123 Abc Street"
}, - "shipping_details": {
- "first_name": "Luyx",
- "last_name": "Tran",
- "phone": "123456789",
- "email": "abc@gmail.com",
- "company": "HelloClever",
- "country_code": "AU",
- "state": "Australian Capital Territory",
- "postal_code": "2601",
- "city": "Acton",
- "address": "123 Abc Street"
}, - "items": [
- {
- "id": "1",
- "name": "name",
- "variant_id": "",
- "quantity": "2",
- "price": "199.0",
- "enable_cashback": true
}
]
}, - "payment_gateway_notification": {
- "authorization_header": "SECRET"
}, - "nonce": "9999",
- "stage": null,
- "site_id": "1234ABCD"
}
Callback payload samples
{- "payment_id": "02e74f10e0327ad868d138f2b4fdd6f0",
- "order_id": "30597959-a853-44d4-bdab-54332bf7a98e",
- "amount": 99.9,
- "cashback_amount": 1,
- "transaction_fee": 2,
- "actual_receive_amount": 96.9,
- "description": "Description",
- "order_details": {
- "billing_details": {
- "first_name": "Luyx",
- "last_name": "Tran",
- "phone": "123456789",
- "email": "abc@gmail.com",
- "company": "HelloClever",
- "country_code": "AU",
- "state": "Australian Capital Territory",
- "postal_code": "2601",
- "city": "Acton",
- "address": "123 Abc Street"
}, - "shipping_details": {
- "first_name": "Luyx",
- "last_name": "Tran",
- "phone": "123456789",
- "email": "abc@gmail.com",
- "company": "HelloClever",
- "country_code": "AU",
- "state": "Australian Capital Territory",
- "postal_code": "2601",
- "city": "Acton",
- "address": "123 Abc Street"
}, - "items": [
- {
- "id": "1",
- "name": "name",
- "variant_id": "",
- "quantity": "2",
- "price": "199.0",
- "enable_cashback": true
}
]
}, - "payment_gateway_notification": {
- "authorization_header": "SECRET"
}, - "created_at": "2022-01-01T00:00:00.000+0000",
- "status": "received",
- "nonce": "9999",
- "stage": null,
- "site_id": "1234ABCD"
}
Refund a Payment
Initiate a refund request on a completed payment (with received
status). Once the refund request is triggered, a refund PayID
will be generated which you (the merchant) can use to refund the original payee.
Authorizations:
Request Body schema: application/json
payment_id required | string Unique Id for the payment created by the Hello Clever system. |
amount | number Refund amount, must be numeric |
reason required | string [ 5 .. 140 ] characters Refund reason, must be at least 5 characters long |
Responses
Request samples
- Payload
{- "payment_id": "30597959-a853-44d4-bdab-54332bf7a98e",
- "amount": 99.9,
- "reason": "Reason"
}
Response samples
- 200
- 401
- 404
- 422
{- "refund_payid": "refund_pay_id@clever.me",
- "refund_amount": 99.9,
- "reason": "Refund payment",
- "payment": {
- "payment_id": "02e74f10e0327ad868d138f2b4fdd6f0",
- "order_id": "30597959-a853-44d4-bdab-54332bf7a98e",
- "amount": 99.9,
- "cashback_amount": 1,
- "transaction_fee": 2,
- "actual_receive_amount": 96.9,
- "description": "Description",
- "order_details": {
- "billing_details": {
- "first_name": "Luyx",
- "last_name": "Tran",
- "phone": "123456789",
- "email": "abc@gmail.com",
- "company": "HelloClever",
- "country_code": "AU",
- "state": "Australian Capital Territory",
- "postal_code": "2601",
- "city": "Acton",
- "address": "123 Abc Street"
}, - "shipping_details": {
- "first_name": "Luyx",
- "last_name": "Tran",
- "phone": "123456789",
- "email": "abc@gmail.com",
- "company": "HelloClever",
- "country_code": "AU",
- "state": "Australian Capital Territory",
- "postal_code": "2601",
- "city": "Acton",
- "address": "123 Abc Street"
}, - "items": [
- {
- "id": "1",
- "name": "name",
- "variant_id": "",
- "quantity": "2",
- "price": "199.0",
- "enable_cashback": true
}
]
}, - "payment_gateway_notification": {
- "authorization_header": "SECRET"
}, - "created_at": "2022-01-01T00:00:00.000+0000",
- "status": "received",
- "nonce": "9999",
- "stage": null,
- "site_id": "1234ABCD"
}
}
List of payments
You can easily query payment requests in a period of time. Currently we support up to 1 year period. Should you need more, please contact us directly.
Authorizations:
query Parameters
from_date | string Example: from_date=2022-01-01T00:00:00 Start date to query payment requests from, format 'DD/MM/YY' or 'YYYY-MM-DDThh:mm:ss'. This datetime would be in UTC timezone |
to_date | string Example: to_date=2022-01-01T00:00:00 End date to query payment requests, format 'DD/MM/YY' or 'YYYY-MM-DDThh:mm:ss'. This datetime would be in UTC timezone |
page | string Page number to query. Currently we support 20 records per page |
site_id | string Site ID |
Responses
Response samples
- 200
- 401
- 404
- 422
{- "page": 1,
- "total": 10,
- "records": [
- {
- "payment_id": "02e74f10e0327ad868d138f2b4fdd6f0",
- "order_id": "30597959-a853-44d4-bdab-54332bf7a98e",
- "amount": 99.9,
- "cashback_amount": 1,
- "transaction_fee": 2,
- "actual_receive_amount": 96.9,
- "description": "Description",
- "order_details": {
- "billing_details": {
- "first_name": "Luyx",
- "last_name": "Tran",
- "phone": "123456789",
- "email": "abc@gmail.com",
- "company": "HelloClever",
- "country_code": "AU",
- "state": "Australian Capital Territory",
- "postal_code": "2601",
- "city": "Acton",
- "address": "123 Abc Street"
}, - "shipping_details": {
- "first_name": "Luyx",
- "last_name": "Tran",
- "phone": "123456789",
- "email": "abc@gmail.com",
- "company": "HelloClever",
- "country_code": "AU",
- "state": "Australian Capital Territory",
- "postal_code": "2601",
- "city": "Acton",
- "address": "123 Abc Street"
}, - "items": [
- {
- "id": "1",
- "name": "name",
- "variant_id": "",
- "quantity": "2",
- "price": "199.0",
- "enable_cashback": true
}
]
}, - "payment_gateway_notification": {
- "authorization_header": "SECRET"
}, - "created_at": "2022-01-01T00:00:00.000+0000",
- "status": "received",
- "nonce": "9999",
- "stage": null,
- "site_id": "1234ABCD",
- "refund_information": {
- "refund_payid": "refund_pay_id@clever.me",
- "refund_amount": "10.99",
- "request_date": "2022-07-01T00:00:00.000+10:00",
- "reason": "Refund for payment",
- "processing_refund_time": {
- "start_time": "2022-07-01T00:00:00.000+10:00",
- "pending_time": "2022-07-01T00:00:00.000+10:00",
- "complete_time": "2022-07-01T00:00:00.000+10:00"
}
}
}
]
}
Get the full details of payment
Detail of Payment
Authorizations:
Request Body schema: application/json
payment_id required | string Payment ID |
site_id | string Site ID |
Responses
Request samples
- Payload
{- "payment_id": "02e74f10e0327ad868d138f2b4fdd6f0",
- "site_id": "1234ABCD"
}
Response samples
- 200
- 401
- 404
- 422
{- "payment_id": "02e74f10e0327ad868d138f2b4fdd6f0",
- "order_id": "30597959-a853-44d4-bdab-54332bf7a98e",
- "amount": 99.9,
- "cashback_amount": 1,
- "transaction_fee": 2,
- "actual_receive_amount": 96.9,
- "description": "Description",
- "order_details": {
- "billing_details": {
- "first_name": "Luyx",
- "last_name": "Tran",
- "phone": "123456789",
- "email": "abc@gmail.com",
- "company": "HelloClever",
- "country_code": "AU",
- "state": "Australian Capital Territory",
- "postal_code": "2601",
- "city": "Acton",
- "address": "123 Abc Street"
}, - "shipping_details": {
- "first_name": "Luyx",
- "last_name": "Tran",
- "phone": "123456789",
- "email": "abc@gmail.com",
- "company": "HelloClever",
- "country_code": "AU",
- "state": "Australian Capital Territory",
- "postal_code": "2601",
- "city": "Acton",
- "address": "123 Abc Street"
}, - "items": [
- {
- "id": "1",
- "name": "name",
- "variant_id": "",
- "quantity": "2",
- "price": "199.0",
- "enable_cashback": true
}
]
}, - "payment_gateway_notification": {
- "authorization_header": "SECRET"
}, - "created_at": "2022-01-01T00:00:00.000+0000",
- "status": "received",
- "nonce": "9999",
- "stage": null,
- "site_id": "1234ABCD",
- "refund_information": {
- "refund_payid": "refund_pay_id@clever.me",
- "refund_amount": "10.99",
- "request_date": "2022-07-01T00:00:00.000+10:00",
- "reason": "Refund for payment",
- "processing_refund_time": {
- "start_time": "2022-07-01T00:00:00.000+10:00",
- "pending_time": "2022-07-01T00:00:00.000+10:00",
- "complete_time": "2022-07-01T00:00:00.000+10:00"
}
}
}
Get balance detail
There are 3 balance types:
available_balance
: The balance available for all transactions.incoming_balance
: The balance shows successful payments but the 3rd party device has not yet paid for it (payment card).outgoing_balance
: The balance being transferred is waiting to be taken from the available balance to process actions (refund, dispute, payout ).rolling_reserve_balance
: The floating amount a merchant keeps in their balance. Rolling reserve balance is not mandatory. The merchant can request to reserve balance by contacting tech support.withdrawable_balance
: The amount you can withdraw excludes rolling reserves.
Authorizations:
Responses
Response samples
- 200
- 401
{- "available_balance": 1000,
- "incoming_balance": 1000,
- "outgoing_balance": 1000,
- "rolling_reserve_balance": 1000,
- "withdrawable_balance": 1000
}
Get balance history
Get the history of balance fluctuations.
Authorizations:
query Parameters
from_date | string <date-time> Example: from_date=2022-01-01T00:00:00 Start date to query balance transactions, format 'DD/MM/YY' or 'YYYY-MM-DDThh:mm:ss'. This datetime is in UTC. |
to_date | string <date-time> Example: to_date=2022-01-01T00:00:00 End date to query balance transactions, format 'DD/MM/YY' or 'YYYY-MM-DDThh:mm:ss'. This datetime is in UTC. |
page | string |
size | string |
Responses
Response samples
- 200
- 401
- 422
{- "from_date": "2022-01-01T00:00:00.000+0000",
- "to_date": "2022-12-01T00:00:00.000+0000",
- "page": 1,
- "size": 10,
- "next_page": 2,
- "total_page": 1,
- "total_count": 10,
- "records": [
- {
- "id": "03928C2C-9DD2C653",
- "amount": -11,
- "request_type": "money_out",
- "transaction_type": "settlement",
- "currency": "AUD",
- "payment_method": "bsb",
- "status": "done",
- "reference_id": "BAL_R93dC3/tVX76Kn2",
- "balance_detail": {
- "outgoing": -10,
- "total": -11,
- "fees": -1
}, - "created_at": "2022-01-01T00:00:00.000+0000"
}
]
}
Create BSB/Account number payment
Create a BSB and account number payment for a customer by sending the amount to charge and the customer's attributes, including the currency. For now, Hello Clever only supports Australian Currency (AUD). If you would like to use Hello Clever with other currencies, please contact our support team.
We would like to request merchants to send us the customer’s information (name, email) through the API so that we can identify the customer and protect the merchants with ease.
Please ensure that separate API keys are established and integrated for each merchant/website.
Transactions are rejected if any of the following fields are incorrect: Account Name, BSB Number, Account Number, Description (Nonce returned from the payment request) , Amount.
Authorizations:
Request Body schema: application/json
name required | string/\A(?![ ])(?![ ]*$)[a-zA-Z0-9 ]*(?<![ ])\z/ Customer's name. |
gst required | boolean Goods and Services Tax for Australian merchants. |
amount required | number Amount. |
description required | string/\A(?![ ])(?![ ]*$)[a-zA-Z0-9 -._]*(?<![ ])\z... Description. |
emails required | string/^([a-z0-9_\-\.]+)@([a-z0-9_\-\.]+)\.([a-z]+)... Each emails split by comma. Please not that only lowercase letters are allowed. |
expired_at | string <YYYY-MM-DDTHH:mm:ss> Expired time of payment. This datetime would be in the UTC timezone. Must set the schedule bigger 15 minutes from the current time. |
external_id | string Custom ID. |
object Merchant Callback Details |
Responses
Callbacks
Request samples
- Payload
{- "name": "Luyx Ng",
- "gst": true,
- "amount": 1000,
- "description": "The message for the payee",
- "emails": "abc@gmail.com, xyz@gmail.com",
- "expired_at": "2021-12-23T06:00:00",
- "payment_request_notification": {
- "authorization_header": "helloclever token"
}
}
Response samples
- 200
- 401
- 422
{- "id": 1,
- "payee_detail": {
- "account_holder_name": "Pay HC2024",
- "bsb": "123456",
- "account_number": "12345678"
}, - "name": "Luyx Ng",
- "merchant_name": "HC2024",
- "gst": true,
- "amount": "1000.0",
- "total": "1100.0",
- "gst_amount": "100.0",
- "expired_at": "2021-12-23T06:00:00.000+0000",
- "external_id": "9999",
- "pay_by": "2021-12-10T06:00:00.000+0000",
- "status": "pending",
- "description": "description",
- "payment_request_notification": {
- "authorization_header": "****"
}, - "nonce": "9999",
- "stage": null
}
Callback payload samples
{- "id": 1,
- "payee": {
- "name": "Luyx Ng"
}, - "name": "Luyx Ng",
- "gst": true,
- "amount": "1000.0",
- "total": "1100.0",
- "gst_amount": "100.0",
- "expired_at": "2021-12-23T06:00:00.000+0000",
- "external_id": "9999",
- "cashback_amount": "100.0",
- "pay_by": "2021-12-10T06:00:00.000+0000",
- "paid_at": "2021-12-10T07:00:00.000+0000",
- "status": "received",
- "description": "The message that you want to send to the payee.",
- "refund_information": {
- "refund_bsb": "123456",
- "refund_account_number": "123456789",
- "refund_amount": "10.99",
- "request_date": "2022-07-01T00:00:00.000+10:00",
- "reason": "Refund for payment",
- "processing_refund_time": {
- "start_time": "2022-07-01T00:00:00.000+10:00",
- "pending_time": "2022-07-01T00:00:00.000+10:00",
- "complete_time": "2022-07-01T00:00:00.000+10:00"
}
}, - "payment_request_notification": {
- "authorization_header": "****"
}, - "nonce": "9999",
- "stage": null
}
Get payment requests in a period of time
You can easily query payment requests in a period of time. Currently we support up to 1 year period. Please get in touch with our team if you need to query payment requests for more than 1 year period.
Authorizations:
query Parameters
from_date | string Example: from_date=2022-01-01T00:00:00 Start date to query payment requests from, format 'DD/MM/YY' or 'YYYY-MM-DDThh:mm:ss'. This datetime would be in UTC timezone |
to_date | string Example: to_date=2022-01-01T00:00:00 End date to query payment requests, format 'DD/MM/YY' or 'YYYY-MM-DDThh:mm:ss'. The datetime would be in UTC timezone |
page | string Page number to query. Currently we support 20 records per page |
Responses
Response samples
- 200
- 401
{- "total": 100,
- "page": 1,
- "records": [
- {
- "id": 1,
- "payee": {
- "name": "helloclever",
- "bsb": "123456",
- "account_number": "123456789"
}, - "name": "Luyx",
- "gst": true,
- "amount": "1000.0",
- "total": "1100.0",
- "gst_amount": "100.0",
- "expired_at": "2021-12-23T06:00:00.000+0000",
- "external_id": "9999",
- "pay_by": "2021-12-10T06:00:00.000+0000",
- "status": "pending",
- "description": "description",
- "payment_request_notification": {
- "authorization_header": "****"
}, - "nonce": "9999",
- "stage": null
}
]
}
Get payment request status
Check the status of a payment request. There are 6 statuses:
pending
: Your customer hasn't made the requested payment yetreceived
: Your customer has paid successfullyexpired
: The payment request has expiredreturn_pending
: A full refund or partial refund request has been triggered on the paymentreturn_received
: The refund has been transferred to the original payeereturn_expired
: The refund request has expired. Expiration time is set to be 10 days.return_rejected
: A refund failed due to problems with the destination account. HelloClever will not retry again.
Authorizations:
query Parameters
id required | integer Hello Clever ID that you request your customers for the Payment Request |
bsb required | string Hello Clever BSB that you request your customers of the Payment Request |
account_number required | string Hello Clever account number that you request your customers of the Payment Request |
Responses
Response samples
- 200
- 401
- 404
[- {
- "id": 1,
- "payee_detail": {
- "account_name": "Jim Tr",
- "bsb": "123456",
- "account_number": "123456789"
}, - "name": "Jim Tr",
- "gst": true,
- "amount": "1000.0",
- "total": "1100.0",
- "gst_amount": "100.0",
- "expired_at": "2021-12-23T06:00:00.000+0000",
- "external_id": "9999",
- "cashback_amount": "100.0",
- "pay_by": "2021-12-10T06:00:00.000+0000",
- "status": "received",
- "description": "The message that you want to send to the payee.",
- "refund_information": {
- "refund_bsb": "123456",
- "refund_account_number": "123456789",
- "refund_amount": "10.99",
- "request_date": "2022-07-01T00:00:00.000+10:00",
- "reason": "Refund for payment",
- "processing_refund_time": {
- "start_time": "2022-07-01T00:00:00.000+10:00",
- "pending_time": "2022-07-01T00:00:00.000+10:00",
- "complete_time": "2022-07-01T00:00:00.000+10:00"
}
}, - "payment_request_notification": {
- "authorization_header": "****"
}, - "nonce": "9999",
- "stage": null
}
]