Get Payment Agreement Detail

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

Retrieve the details of a specific payment agreement, including its current status. This endpoint provides insight into the lifecycle and status of a payment agreement, which can be one of the following:

• created: The customer has initiated the creation of the Payment Agreement.
• active: The Payment Agreement is active and ready to process payments.
• suspended: The Payment Agreement is temporarily suspended, pausing all associated transactions.
• cancelled: The Payment Agreement has been cancelled, and no further payments can be processed.
• failed: The Payment Agreement has failed due to an error.

For testing purposes, specific PayIDs can be used to simulate different statuses:

• created: Use PayID no-action@example.com to keep the agreement status as created.
• failed: Use PayID error@example.com to trigger a failure status.
• cancelled: Use PayID cancel-agreement@example.com to simulate a cancelled status.
• suspended: Use PayID suspend-agreement@example.com to simulate a suspended status.

Request

Query Parameters

id integerrequired
The unique Hello Clever payment ID for the payment agreement.
Example: 12345

Responses

200

Request processed 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

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/detail");
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

id — queryrequired

ResponseClear

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