Skip to main content

Hello Clever Payment API Reference (2.0)

Introduction

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:

  • Integrate Hello Clever Payment Gateway to your website or your application. Currently our Payment Gateway supports PayID, PayTo, and cards. See more
  • Whitelabel our PayID and PayTo solutions at your request and fully customise the user experience your own way. See more

Getting started

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

Postman collection

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.

Authentication

  • 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.

Request

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:
(app-idsecret-key)
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 prefix_static_payid@example.co.

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

Content type
application/json
{
  • "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": {}
}

Response samples

Content type
application/json
{
  • "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": {
    },
  • "payment_request_notification": {},
  • "nonce": "9999",
  • "stage": null,
  • "sender_details": {
    }
}

Callback payload samples

Callback
POST: PayID.PaymentStatus.status Event
Content type
application/json
{
  • "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": {
    },
  • "payee": {
    },
  • "payment_request_notification": {},
  • "nonce": "9999",
  • "stage": null,
  • "sender_details": {
    }
}

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:
(app-idsecret-key)
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

Content type
application/json
{
  • "total": 100,
  • "page": 1,
  • "records": [
    ]
}

Get payment request status

Check the status of a payment request. There are 6 statuses:

  • pending: Your customer hasn't made the requested payment yet
  • received: Your customer has paid successfully
  • expired: The payment request has expired
  • return_pending: A full refund or partial refund request has been triggered on the payment
  • return_received: The refund has been transferred to the original payee
  • return_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:
(app-idsecret-key)
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

Content type
application/json
[
  • {
    },
  • {
    }
]

Get payment request statistics

Authorizations:
(app-idsecret-key)

Responses

Response samples

Content type
application/json
{
  • "gross": 1100,
  • "transactions_count": 10,
  • "pending_count": 5
}

Customer

Create a Static Open PayID

Create a Static Open PayID

Authorizations:
(app-idsecret-key)
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

Content type
application/json
{
  • "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": {}
}

Response samples

Content type
application/json
{
  • "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": {},
  • "status": "active"
}

Callback payload samples

Callback
POST: PayID.PaymentStatus.status Event
Content type
application/json
{
  • "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": {
    },
  • "payee": {
    },
  • "nonce": "9999",
  • "stage": null,
  • "sender_details": {
    }
}

Get a list of all Static Open PayIDs

Get a list of all Static Open PayIDs in your account

Authorizations:
(app-idsecret-key)
query Parameters
email
string

Query by email

payid
string

Query by PayID

customer_id
string

Query by Customer ID

Responses

Response samples

Content type
application/json
{
  • "total": 20,
  • "page": 1,
  • "total_page": 1,
  • "records": [
    ]
}

Refund

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:
(app-idsecret-key)
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

Content type
application/json
{
  • "payment_request_id": 1,
  • "refund_amount": 100,
  • "reason": "Partial Refund Reason"
}

Response samples

Content type
application/json
{
  • "refund_payid": "refund_pay_id@clever.me",
  • "total_amount": "200",
  • "refund_amount": "100",
  • "reason": "Partial refund",
  • "payment_request": {
    }
}

Cancel

Cancel a PayID

Cancel a pending PayID transaction, the PayID will be deregistered and the transaction status will be updated to expired.

Authorizations:
(app-idsecret-key)
Request Body schema: application/json
payid
required
string

PayID

Responses

Request samples

Content type
application/json
{
  • "payid": "abc.xyz@example.co"
}

Response samples

Content type
application/json
{
  • "payid": "abc.xyz@example.co"
}

Payment agreement

Create a payment agreement

There are 2 payment types:

  • pay_id: Payer use PayID as a payment method
  • bsb: Payer use BSB/Account number.no as a payment method
Authorizations:
(app-idsecret-key)
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 bank_account_details or pay_id_details

required
object

Merchant Callback Details

Responses

Callbacks

Request samples

Content type
application/json
{
  • "client_transaction_id": "30597959-a853-44d4-bdab-54332bf7a98e",
  • "limit_amount": 1000,
  • "description": "Description",
  • "external_id": "343h.te",
  • "payment_agreement_type": "MORTGAGE",
  • "agreement_details": {
    },
  • "payer_details": {
    },
  • "payment_agreement_notification": {}
}

Response samples

Content type
application/json
{
  • "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": {
    },
  • "payer_details": {
    },
  • "payment_agreement_notification": {}
}

Callback payload samples

Callback
POST: PaymentAgreementStatus.status Event
Content type
application/json
{
  • "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": {
    },
  • "payer_details": {
    },
  • "payment_agreement_notification": {}
}

Amend a payment agreement

Authorizations:
(app-idsecret-key)
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

Content type
application/json
{
  • "id": 4,
  • "limit_amount": 1000,
  • "agreement_details": {
    },
  • "payment_agreement_notification": {}
}

Response samples

Content type
application/json
{
  • "payment_agreement_amendment": {
    },
  • "payment_agreement_amendment_status": {
    }
}

Callback payload samples

Callback
POST: PaymentAgreementAmendmentStatus.status Event
Content type
application/json
{
  • "payment_agreement_amendment": {
    },
  • "payment_agreement_amendment_status": {
    }
}

Change status a payment agreement

Authorizations:
(app-idsecret-key)
Request Body schema: application/json
id
required
number

Hello Clever payment ID

status
required
string
Enum: "active" "cancelled" "suspended"

Responses

Request samples

Content type
application/json
{
  • "id": 4,
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "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": {
    },
  • "payer_details": {
    },
  • "payment_agreement_notification": {}
}

Get payment agreement detail

Check the status of a payment request. There are 5 statuses:

  • created: Your customer triggered a Payment Agreement creation
  • active: The payment agreement is active
  • suspended: The payment agreement is suspended
  • cancelled: The payment agreement has been cancelled
  • failed: 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 created
  • failed: PayID error@example.com will result in an error and set the created payment agreement with the status failed
  • cancelled: PayID cancel-agreement@example.com will create a payment agreement with the status cancelled
  • suspended: PayID suspend-agreement@example.com will create a payment agreement with the status suspended
Authorizations:
(app-idsecret-key)
query Parameters
id
required
integer

Hello Clever payment ID

Responses

Response samples

Content type
application/json
{
  • "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": {
    },
  • "payer_details": {
    },
  • "payment_agreement_notification": {}
}

Get payment agreements

Authorizations:
(app-idsecret-key)
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

Content type
application/json
{
  • "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": [
    ]
}

Payment initiation

Create a payment initiation

Create a payment initiation

Authorizations:
(app-idsecret-key)
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

Content type
application/json
{
  • "client_transaction_id": "30597959-a853-44d4-bdab-54332bf7a98e",
  • "amount": 10.5,
  • "id": 56,
  • "external_id": "9999",
  • "description": "Clever test here",
  • "payment_initiation_notification": {}
}

Response samples

Content type
application/json
{
  • "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": {},
  • "payment_initiation_id": "VatpdiYL7EmcV9g+--IvqBL0cT39bvW5eS--RRJg+B58qveWdxPTJ0FMSg==",
  • "status": "pending",
  • "created_at": "2022-01-01T00:00:00.000+0000",
  • "payee": {
    }
}

Callback payload samples

Callback
POST: PaymentInitiationStatus.status Event
Content type
application/json
{
  • "client_transaction_id": "30597959-a853-44d4-bdab-54332bf7a98e",
  • "amount": 10.5,
  • "payment_agreement_id": "VatpdiYL7EmcV9g+--IvqBL0cT39bvW5eS--RRJg+B58qveWdxPTJ0FMSg==",
  • "external_id": "9999",
  • "payment_initiation_notification": {},
  • "payment_initiation_id": "VatpdiYL7EmcV9g+--IvqBL0cT39bvW5eS--RRJg+B58qveWdxPTJ0FMSg==",
  • "status": "received",
  • "created_at": "2022-01-01T00:00:00.000+0000"
}

Get payment initiations

Authorizations:
(app-idsecret-key)
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

Content type
application/json
{
  • "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": [
    ]
}

Refund a payment initiation

Authorizations:
(app-idsecret-key)
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

Content type
application/json
{
  • "id": 234,
  • "refund_amount": 0.5,
  • "reason": "My wife wants to refund."
}

Response samples

Content type
application/json
{
  • "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": {},
  • "payment_initiation_id": "VatpdiYL7EmcV9g+--IvqBL0cT39bvW5eS--RRJg+B58qveWdxPTJ0FMSg==",
  • "status": "return_pending",
  • "created_at": "2022-01-01T00:00:00.000+0000",
  • "payee": {
    },
  • "refund_information": {
    }
}

Get payment initiation detail


Check the status of a payment request. There are 6 statuses:

  • pending: Your customer hasn't made the requested payment yet
  • received: Your customer has paid successfully
  • return_pending: A full refund or partial refund request has been triggered on the payment
  • return_received: The refund has been transferred to the original payee
  • return_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:
(app-idsecret-key)
query Parameters
id
required
integer

Hello Clever payment ID

Responses

Response samples

Content type
application/json
{
  • "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": {},
  • "payment_initiation_id": "VatpdiYL7EmcV9g+--IvqBL0cT39bvW5eS--RRJg+B58qveWdxPTJ0FMSg==",
  • "status": "received",
  • "created_at": "2022-01-01T00:00:00.000+0000",
  • "payee": {
    },
  • "refund_information": {
    }
}

Payout - Currency AUD

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 be johw1ck@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:
(app-idsecret-key)
Request Body schema:
file
required
string <File (.csv or .xlsx)>
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

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

Content type
application/json
{
  • "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",
  • "payout_notification": {},
  • "error_code": "HC_PAYOUT1",
  • "error_message": "Insufficient available funds. Top up your balance.",
  • "is_retry": true,
  • "external_id": "123"
}

Callback payload samples

Callback
POST: PayoutStatus.status Event
Content type
application/json
{
  • "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_notification": {},
  • "payout_transactions": [
    ]
}

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:
(app-idsecret-key)
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

Content type
application/json
{
  • "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": [
    ]
}

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:
(app-idsecret-key)
query Parameters
id
required
integer

Hello Clever payout payment ID

uuid
string

Hello Clever payout payment UUID

Responses

Response samples

Content type
application/json
{
  • "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",
  • "payout_notification": {},
  • "error_code": "HC_PAYOUT1",
  • "error_message": "Insufficient available funds. Top up your balance.",
  • "is_retry": true,
  • "external_id": "123",
  • "payout_transactions": [
    ]
}

Cancel a scheduled payout payment

You can cancel a payout payment scheduled to run in the future.

Authorizations:
(app-idsecret-key)
Request Body schema: application/json
payout_payment_uuid
required
string

Payout payment UUID

Responses

Request samples

Content type
application/json
{
  • "payout_payment_uuid": "OHXTEF9M"
}

Response samples

Content type
application/json
{
  • "status": "OK"
}

Create KYC

Create KYC for Payouts. For payouts above 5000 AUD, it is mandatory to complete the KYC process.

Authorizations:
(app-idsecret-key)
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

Content type
application/json
{
  • "status": "ok"
}

Authentication

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:
(app-idsecret-key)

Responses

Response samples

Content type
application/json
{
  • "access_token": "19d2f50fe935f06d3f521862b61eda08dd4796dda81167904c7c7f29424a1011",
  • "expires_in": 3600
}

Payment request

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 yet
  • waiting: Your customer has paid successfully but payment has not been sent to you
  • received: Your customer has paid and you should receoved the payment
  • expired: The payment request has expired
  • return_pending: A full refund or partial refund request has been triggered on the transaction
  • return_received: The refund has been transferred to the original payee
  • return_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:
access-token
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

Content type
application/json
{
  • "order_id": "30597959-a853-44d4-bdab-54332bf7a98e",
  • "amount": 99.9,
  • "description": "Description",
  • "order_success_url": "https://helloclever.co/order/success",
  • "order_details": {
    },
  • "payment_gateway_notification": {}
}

Response samples

Content type
application/json
{
  • "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_success_url": "https://helloclever.co/order/success",
  • "status": "received",
  • "order_details": {
    },
  • "payment_gateway_notification": {},
  • "nonce": "9999",
  • "stage": null,
  • "site_id": "1234ABCD"
}

Callback payload samples

Callback
POST: PaymentGatewayStatus.status Event
Content type
application/json
{
  • "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_success_url": "https://helloclever.co/order/success",
  • "order_details": {
    },
  • "payment_gateway_notification": {},
  • "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:
access-token
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

Content type
application/json
{
  • "payment_id": "30597959-a853-44d4-bdab-54332bf7a98e",
  • "amount": 99.9,
  • "reason": "Reason"
}

Response samples

Content type
application/json
{
  • "refund_payid": "refund_pay_id@clever.me",
  • "refund_amount": 99.9,
  • "reason": "Refund payment",
  • "payment": {
    }
}

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:
access-token
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

Content type
application/json
{
  • "page": 1,
  • "total": 10,
  • "records": [
    ]
}

Get the full details of payment

Detail of Payment

Authorizations:
access-token
Request Body schema: application/json
payment_id
required
string

Payment ID

site_id
string

Site ID

Responses

Request samples

Content type
application/json
{
  • "payment_id": "02e74f10e0327ad868d138f2b4fdd6f0",
  • "site_id": "1234ABCD"
}

Response samples

Content type
application/json
{
  • "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_success_url": "https://helloclever.co/order/success",
  • "order_details": {
    },
  • "payment_gateway_notification": {},
  • "created_at": "2022-01-01T00:00:00.000+0000",
  • "status": "received",
  • "nonce": "9999",
  • "stage": null,
  • "site_id": "1234ABCD",
  • "refund_information": {
    }
}

Balance

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:
(app-idsecret-key)

Responses

Response samples

Content type
application/json
{
  • "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:
(app-idsecret-key)
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

Content type
application/json
{
  • "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": [
    ]
}

BSB/Account number

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:
(app-idsecret-key)
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

Content type
application/json
{
  • "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": {}
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "payee_detail": {
    },
  • "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": {},
  • "nonce": "9999",
  • "stage": null
}

Callback payload samples

Callback
POST: BSB/Account number.PaymentStatus.status Event
Content type
application/json
{
  • "id": 1,
  • "payee": {
    },
  • "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": {
    },
  • "payment_request_notification": {},
  • "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:
(app-idsecret-key)
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

Content type
application/json
{
  • "total": 100,
  • "page": 1,
  • "records": [
    ]
}

Get payment request status

Check the status of a payment request. There are 6 statuses:

  • pending: Your customer hasn't made the requested payment yet
  • received: Your customer has paid successfully
  • expired: The payment request has expired
  • return_pending: A full refund or partial refund request has been triggered on the payment
  • return_received: The refund has been transferred to the original payee
  • return_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:
(app-idsecret-key)
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

Content type
application/json
[
  • {
    }
]