Get Payment Agreements

GET 
https://api.cleverhub.co/api/v1/pay_to/payment_agreement/search

Retrieve a paginated list of payment agreements within a specified time range. This endpoint enables merchants to query and filter payment agreements based on date parameters, allowing for efficient management and monitoring of agreement records over a specified period.

The query supports pagination, making it possible to navigate through large datasets by specifying the page number and the number of records per page.

Request

Query Parameters

from_date date-timerequired
The start date for querying payment agreements. Accepted formats are 'DD/MM/YY' or 'YYYY-MM-DDThh:mm:ss'. This date-time is in UTC.
Example: 2022-01-01T00:00:00
to_date date-timerequired
The end date for querying payment agreements. Accepted formats are 'DD/MM/YY' or 'YYYY-MM-DDThh:mm:ss'. This date-time is in UTC.
Example: 2022-12-01T00:00:00
page integer
The page number to retrieve. Each page contains a subset of results based on the specified size parameter.
Example: 1
size integer
The number of records to return per page. This allows you to control the volume of data returned in each response, aiding in efficient data management.
Example: 20

Responses

200

Request processed successfully.

application/json

Schema

Schema

from_datedate-time
The start date of the queried payment agreements, as specified in the request.
Example: 2022-01-01T00:00:00
to_datedate-time
The end date of the queried payment agreements, as specified in the request.
Example: 2022-12-01T00:00:00
pageinteger
The current page number of the returned results.
Example: 1
sizeinteger
The number of records per page as specified in the query.
Example: 20
next_pageinteger
The page number for the next set of results, if available.
Example: 2
total_pageinteger
The total number of pages available based on the query parameters.
Example: 5
total_countinteger
The total number of payment agreement records available within the specified date range.
Example: 100
records object[]
Array [
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)

{
  "from_date": "2022-01-01T00:00:00",
  "to_date": "2022-12-01T00:00:00",
  "page": 1,
  "size": 20,
  "next_page": 2,
  "total_page": 5,
  "total_count": 100,
  "records": [
    {
      "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

422

Unprocessable Entity

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.Get, "https://api.cleverhub.co/api/v1/pay_to/payment_agreement/search");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("app-id", "<app-id>");
request.Headers.Add("secret-key", "<app-id>");
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

Parameters

from_date — queryrequired

to_date — queryrequired

page — query

size — query

ResponseClear

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