Create Payment Agreement

POST 
https://api.cleverhub.co/api/v1/pay_to/payment_agreement

Create a payment agreement that enables recurring or one-time payments between merchants and payers. This agreement specifies the transaction structure, including payment limits, agreement type, and callback details for status notifications.

Available payment methods:

• pay_id: Use PayID as the payment method, which can be an email, phone number, or Australian Business Number (ABN). This provides a secure and streamlined payment option using a unique identifier.
• bsb: Use BSB (Bank-State-Branch) and account number as the payment method, which is suitable for direct bank transfers within Australia.

The endpoint also supports merchant callback configurations to notify merchants of status changes in the payment agreement.

Request

application/json

Bodyrequired

client_transaction_idstringrequired
Unique identifier for the transaction created by the merchant’s system.
Possible values: non-empty and <= 90 characters
Example: txn-12345
limit_amountnumberrequired
Maximum payment amount allowed for each transaction under this agreement. If using a fixed agreement, this amount should match the intended charge.
Example: 500
descriptionstringrequired
Brief description of the payment agreement.
Possible values: >= 5 characters and <= 140 characters
Example: Monthly utility payment
external_idstring
Custom identifier provided by the merchant for tracking purposes.
Possible values: <= 255 characters
Example: ext-123456
payment_agreement_typestringrequired
Type of the payment agreement.
Possible values: [MORTGAGE, UTILITY, LOAN, DEPENDANT_SUPPORT, GAMBLING, RETAIL, SALARY, PERSONAL, GOVERNMENT, PENSION, TAX, OTHER_SERVICE]
Example: UTILITY
agreement_details objectrequired
oneOf
variable_agreement_details_obj
variable_agreement_details_obj object
start_datestring
The start date for the variable payment agreement, expressed in the format DD/MM/YY. This date is in the UTC timezone.
Example: 15/07/24
frequencystring
The frequency of payments for the agreement, indicating how often payments will occur.
Possible values: [ADHOC, DAILY, FORTNIGHTLY, INTRADAY, SEMIANNUAL, MONTHLY, QUARTERLY, WEEKLY, ANNUAL]
Example: MONTHLY
fixed_agreement_details_obj
fixed_agreement_details_obj object
start_datestring
The start date for the fixed payment agreement, expressed in the format DD/MM/YY. This date is in the UTC timezone.
Example: 01/01/24
frequencystring
The frequency of payments for the agreement, indicating how often payments will occur.
Possible values: [ADHOC, DAILY, FORTNIGHTLY, INTRADAY, SEMIANNUAL, MONTHLY, QUARTERLY, WEEKLY, ANNUAL]
Example: ANNUAL
usage_bases_agreement_details_obj
usage_bases_agreement_details_obj object
start_datestring
The start date for the usage-based payment agreement, expressed in the format DD/MM/YY. This date is in the UTC timezone.
Example: 10/03/24
frequencystring
The frequency of payments for the agreement, indicating how often payments will occur.
Possible values: [ADHOC, DAILY, FORTNIGHTLY, INTRADAY, SEMIANNUAL, MONTHLY, QUARTERLY, WEEKLY, ANNUAL]
Example: WEEKLY
balloon_agreement_details_obj
balloon_agreement_details_obj object
start_datestring
The start date for the balloon payment agreement, expressed in the format DD/MM/YY. This date is in the UTC timezone.
Example: 20/11/24
frequencystring
The frequency of payments for the agreement, indicating how often payments will occur.
Possible values: [ADHOC, DAILY, FORTNIGHTLY, INTRADAY, SEMIANNUAL, MONTHLY, QUARTERLY, WEEKLY, ANNUAL]
Example: FORTNIGHTLY
payer_details objectrequired
Payer details, with either bank_account_details or pay_id_details required.
namestringrequired
The payer's full name.
Possible values: Value must match regular expression ^(?![! ](?![!]*$))[a-zA-Z0-9 ]*(?![ ])$
Example: John Doe
bank_account_details objectrequired
Details of the payer’s bank account.
bsbstringrequired
Bank State Branch (BSB) number for the account.
Example: 123456
account_numberstringrequired
Account number associated with the BSB.
Example: 987654321
pay_id_details objectrequired
Details of the payer’s PayID.
pay_idstringrequired
The payer's PayID.
Example: payer@example.com
pay_id_typestringrequired
Type of PayID:
• EMAIL: Email address.
• PHONE: Phone number, including area code (e.g., +61-32832832).
• ABN: Australian Business Number.
Possible values: [EMAIL, PHONE, ABN]
Example: EMAIL
payment_agreement_notification objectrequired
Callback configuration for receiving payment agreement status updates.
endpoint_urlurirequired
URL for receiving payment agreement status notifications. Must be internet-accessible.
Example: https://merchant.example.com/payment_status_callback
authorization_headerstringrequired
Token for the Authorization header in the callback request for security.
Example: Bearer your_secret_token

Responses

200

Payment agreement created successfully.

application/json

Schema

Schema

idinteger
A unique identifier for the payment agreement, used for tracking and management.
Example: 12345
payment_agreement_idstring
The unique identifier for the payment agreement, providing a reference to the specific agreement being handled.
Example: agreement-12345
client_transaction_idstring
A unique ID for the transaction as provided by the merchant, used to ensure transactions can be uniquely tracked.
Possible values: non-empty and <= 90 characters
Example: client-trans-001
limit_amountnumber
The maximum allowable amount for each payment under this agreement, helping to manage the scope of transactions.
Example: 5000
descriptionstring
A description of the payment agreement, providing context and information for the payer and merchant.
Possible values: >= 5 characters and <= 140 characters
Example: Monthly utility bill payment agreement.
external_idstring
A custom identifier assigned to the payment agreement, typically used for tracking and reference purposes.
Possible values: <= 255 characters
Example: custom-agreement-id-7890
statusstring
The current status of the payment agreement. Possible values include:
• created: Agreement has been created but not yet activated.
• active: Agreement is currently active.
• suspended: Agreement has been temporarily suspended.
• cancelled: Agreement has been cancelled.
• failed: Agreement creation or payment has failed.
Possible values: [created, active, suspended, cancelled, failed]
Example: active
created_atdate-time
The timestamp indicating when the payment agreement was created, in UTC.
Example: 2024-01-01T00:00:00Z
payment_agreement_typestring
The type of payment agreement, indicating the nature of the payments involved.
Possible values: [MORTGAGE, UTILITY, LOAN, DEPENDANT SUPPORT, GAMBLING, RETAIL, SALARY, PERSONAL, GOVERNMENT, PENSION, TAX, OTHER SERVICE]
Example: UTILITY
agreement_details object
oneOf
variable_agreement_details_obj
variable_agreement_details_obj object
start_datestring
The start date for the variable payment agreement, expressed in the format DD/MM/YY. This date is in the UTC timezone.
Example: 15/07/24
frequencystring
The frequency of payments for the agreement, indicating how often payments will occur.
Possible values: [ADHOC, DAILY, FORTNIGHTLY, INTRADAY, SEMIANNUAL, MONTHLY, QUARTERLY, WEEKLY, ANNUAL]
Example: MONTHLY
fixed_agreement_details_obj
fixed_agreement_details_obj object
start_datestring
The start date for the fixed payment agreement, expressed in the format DD/MM/YY. This date is in the UTC timezone.
Example: 01/01/24
frequencystring
The frequency of payments for the agreement, indicating how often payments will occur.
Possible values: [ADHOC, DAILY, FORTNIGHTLY, INTRADAY, SEMIANNUAL, MONTHLY, QUARTERLY, WEEKLY, ANNUAL]
Example: ANNUAL
usage_bases_agreement_details_obj
usage_bases_agreement_details_obj object
start_datestring
The start date for the usage-based payment agreement, expressed in the format DD/MM/YY. This date is in the UTC timezone.
Example: 10/03/24
frequencystring
The frequency of payments for the agreement, indicating how often payments will occur.
Possible values: [ADHOC, DAILY, FORTNIGHTLY, INTRADAY, SEMIANNUAL, MONTHLY, QUARTERLY, WEEKLY, ANNUAL]
Example: WEEKLY
balloon_agreement_details_obj
balloon_agreement_details_obj object
start_datestring
The start date for the balloon payment agreement, expressed in the format DD/MM/YY. This date is in the UTC timezone.
Example: 20/11/24
frequencystring
The frequency of payments for the agreement, indicating how often payments will occur.
Possible values: [ADHOC, DAILY, FORTNIGHTLY, INTRADAY, SEMIANNUAL, MONTHLY, QUARTERLY, WEEKLY, ANNUAL]
Example: FORTNIGHTLY
payer_details object
Details about the payer, including either bank account information or PayID details.
namestring
The name of the payer, used for identification and verification.
Possible values: Value must match regular expression ^(?![! ](?![!]*$))[a-zA-Z0-9 ]*(?![ ])$
Example: Jane Doe
bank_account_details object
Information about the payer's bank account, used for transactions involving bank details.
bsbstring
The BSB (Bank-State-Branch) number of the payer's account, used to identify the bank and branch.
Example: 123456
account_numberstring
The account number associated with the payer's bank account.
Example: 987654321
pay_id_details object
Information about the payer's PayID, used for transactions involving a PayID.
pay_idstring
The PayID associated with the payer, allowing payments to be routed via this ID.
Example: payer@payid.com
pay_id_typestring
The type of PayID being used. Valid values include:
• EMAIL: An email address.
• PHONE: A mobile or landline number.
• ABN: An Australian Business Number.
Possible values: [EMAIL, PHONE, ABN]
Example: EMAIL
payment_agreement_notification object
Details for the merchant callback, including endpoint URL and authorization header for receiving status updates on the payment agreement.
endpoint_urluri
The URL to which Hello Clever will send notifications when the status of a transaction changes. The endpoint must be internet accessible and secured by TLS 1.2 or higher.
Example: https://merchant.com/payment_callback
authorization_headerstring
The authorization value that Hello Clever will include in the callback request header to authenticate the request.
Example: Bearer your_token

Example (auto)

{
  "id": 12345,
  "payment_agreement_id": "agreement-12345",
  "client_transaction_id": "client-trans-001",
  "limit_amount": 5000,
  "description": "Monthly utility bill payment agreement.",
  "external_id": "custom-agreement-id-7890",
  "status": "active",
  "created_at": "2024-01-01T00:00:00Z",
  "payment_agreement_type": "UTILITY",
  "agreement_details": {
    "variable_agreement_details_obj": {
      "start_date": "15/07/24",
      "frequency": "MONTHLY"
    }
  },
  "payer_details": {
    "name": "Jane Doe",
    "bank_account_details": {
      "bsb": "123456",
      "account_number": "987654321"
    },
    "pay_id_details": {
      "pay_id": "payer@payid.com",
      "pay_id_type": "EMAIL"
    }
  },
  "payment_agreement_notification": {
    "endpoint_url": "https://merchant.com/payment_callback",
    "authorization_header": "Bearer your_token"
  }
}

400

Bad Request

401

Unauthorized

404

Not Found

422

Unprocessable Entity

Callbacks

POST PaymentAgreementStatus

POST 
{$request.body#/payment_agreement_notification/endpoint_url}

application/json

Bodyrequired

idinteger
A unique identifier for the payment agreement, used for tracking and management.
Example: 12345
payment_agreement_idstring
The unique identifier for the payment agreement, providing a reference to the specific agreement being handled.
Example: agreement-12345
client_transaction_idstring
A unique ID for the transaction as provided by the merchant, used to ensure transactions can be uniquely tracked.
Possible values: non-empty and <= 90 characters
Example: client-trans-001
limit_amountnumber
The maximum allowable amount for each payment under this agreement, helping to manage the scope of transactions.
Example: 5000
descriptionstring
A description of the payment agreement, providing context and information for the payer and merchant.
Possible values: >= 5 characters and <= 140 characters
Example: Monthly utility bill payment agreement.
external_idstring
A custom identifier assigned to the payment agreement, typically used for tracking and reference purposes.
Possible values: <= 255 characters
Example: custom-agreement-id-7890
statusstring
The current status of the payment agreement. Possible values include:
• created: Agreement has been created but not yet activated.
• active: Agreement is currently active.
• suspended: Agreement has been temporarily suspended.
• cancelled: Agreement has been cancelled.
• failed: Agreement creation or payment has failed.
Possible values: [created, active, suspended, cancelled, failed]
Example: active
created_atdate-time
The timestamp indicating when the payment agreement was created, in UTC.
Example: 2024-01-01T00:00:00Z
payment_agreement_typestring
The type of payment agreement, indicating the nature of the payments involved.
Possible values: [MORTGAGE, UTILITY, LOAN, DEPENDANT SUPPORT, GAMBLING, RETAIL, SALARY, PERSONAL, GOVERNMENT, PENSION, TAX, OTHER SERVICE]
Example: UTILITY
agreement_details object
oneOf
variable_agreement_details_obj
variable_agreement_details_obj object
start_datestring
The start date for the variable payment agreement, expressed in the format DD/MM/YY. This date is in the UTC timezone.
Example: 15/07/24
frequencystring
The frequency of payments for the agreement, indicating how often payments will occur.
Possible values: [ADHOC, DAILY, FORTNIGHTLY, INTRADAY, SEMIANNUAL, MONTHLY, QUARTERLY, WEEKLY, ANNUAL]
Example: MONTHLY
fixed_agreement_details_obj
fixed_agreement_details_obj object
start_datestring
The start date for the fixed payment agreement, expressed in the format DD/MM/YY. This date is in the UTC timezone.
Example: 01/01/24
frequencystring
The frequency of payments for the agreement, indicating how often payments will occur.
Possible values: [ADHOC, DAILY, FORTNIGHTLY, INTRADAY, SEMIANNUAL, MONTHLY, QUARTERLY, WEEKLY, ANNUAL]
Example: ANNUAL
usage_bases_agreement_details_obj
usage_bases_agreement_details_obj object
start_datestring
The start date for the usage-based payment agreement, expressed in the format DD/MM/YY. This date is in the UTC timezone.
Example: 10/03/24
frequencystring
The frequency of payments for the agreement, indicating how often payments will occur.
Possible values: [ADHOC, DAILY, FORTNIGHTLY, INTRADAY, SEMIANNUAL, MONTHLY, QUARTERLY, WEEKLY, ANNUAL]
Example: WEEKLY
balloon_agreement_details_obj
balloon_agreement_details_obj object
start_datestring
The start date for the balloon payment agreement, expressed in the format DD/MM/YY. This date is in the UTC timezone.
Example: 20/11/24
frequencystring
The frequency of payments for the agreement, indicating how often payments will occur.
Possible values: [ADHOC, DAILY, FORTNIGHTLY, INTRADAY, SEMIANNUAL, MONTHLY, QUARTERLY, WEEKLY, ANNUAL]
Example: FORTNIGHTLY
payer_details object
Details about the payer, including either bank account information or PayID details.
namestring
The name of the payer, used for identification and verification.
Possible values: Value must match regular expression ^(?![! ](?![!]*$))[a-zA-Z0-9 ]*(?![ ])$
Example: Jane Doe
bank_account_details object
Information about the payer's bank account, used for transactions involving bank details.
bsbstring
The BSB (Bank-State-Branch) number of the payer's account, used to identify the bank and branch.
Example: 123456
account_numberstring
The account number associated with the payer's bank account.
Example: 987654321
pay_id_details object
Information about the payer's PayID, used for transactions involving a PayID.
pay_idstring
The PayID associated with the payer, allowing payments to be routed via this ID.
Example: payer@payid.com
pay_id_typestring
The type of PayID being used. Valid values include:
• EMAIL: An email address.
• PHONE: A mobile or landline number.
• ABN: An Australian Business Number.
Possible values: [EMAIL, PHONE, ABN]
Example: EMAIL
payment_agreement_notification object
Details for the merchant callback, including endpoint URL and authorization header for receiving status updates on the payment agreement.
endpoint_urluri
The URL to which Hello Clever will send notifications when the status of a transaction changes. The endpoint must be internet accessible and secured by TLS 1.2 or higher.
Example: https://merchant.com/payment_callback
authorization_headerstring
The authorization value that Hello Clever will include in the callback request header to authenticate the request.
Example: Bearer your_token

Callbacks Responses

200

Callback received successfully.

400

Bad request.

401

Unauthorized access.

Authorization: app-id

name: app-idtype: apiKeyin: headerdescription: A unique identifier assigned to each application.

name: secret-keytype: apiKeyin: headerdescription: A secure token associated with the `app-id`.

• csharp
• curl
• dart
• go
• http
• java
• javascript
• kotlin
• c
• nodejs
• objective-c
• ocaml
• php
• powershell
• python
• r
• ruby
• rust
• shell
• swift

• HTTPCLIENT
• RESTSHARP

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.cleverhub.co/api/v1/pay_to/payment_agreement");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("app-id", "<app-id>");
request.Headers.Add("secret-key", "<app-id>");
var content = new StringContent("{\n  \"client_transaction_id\": \"txn-12345\",\n  \"limit_amount\": 500,\n  \"description\": \"Monthly utility payment\",\n  \"external_id\": \"ext-123456\",\n  \"payment_agreement_type\": \"UTILITY\",\n  \"agreement_details\": {\n    \"variable_agreement_details_obj\": {\n      \"start_date\": \"15/07/24\",\n      \"frequency\": \"MONTHLY\"\n    }\n  },\n  \"payer_details\": {\n    \"name\": \"John Doe\",\n    \"bank_account_details\": {\n      \"bsb\": \"123456\",\n      \"account_number\": \"987654321\"\n    },\n    \"pay_id_details\": {\n      \"pay_id\": \"payer@example.com\",\n      \"pay_id_type\": \"EMAIL\"\n    }\n  },\n  \"payment_agreement_notification\": {\n    \"endpoint_url\": \"https://merchant.example.com/payment_status_callback\",\n    \"authorization_header\": \"Bearer your_secret_token\"\n  }\n}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Request Collapse all

Base URL

https://api.cleverhub.co/api

Auth

app-id

secret-key

Body required

{
  "client_transaction_id": "txn-12345",
  "limit_amount": 500,
  "description": "Monthly utility payment",
  "external_id": "ext-123456",
  "payment_agreement_type": "UTILITY",
  "agreement_details": {
    "variable_agreement_details_obj": {
      "start_date": "15/07/24",
      "frequency": "MONTHLY"
    }
  },
  "payer_details": {
    "name": "John Doe",
    "bank_account_details": {
      "bsb": "123456",
      "account_number": "987654321"
    },
    "pay_id_details": {
      "pay_id": "payer@example.com",
      "pay_id_type": "EMAIL"
    }
  },
  "payment_agreement_notification": {
    "endpoint_url": "https://merchant.example.com/payment_status_callback",
    "authorization_header": "Bearer your_secret_token"
  }
}

ResponseClear

Click the Send API Request button above and see the response here!