Change Payment Agreement Status

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

Update the status of an existing payment agreement. This endpoint allows merchants to manage the status of payment agreements based on their business requirements. The status options available are:

• active: Set the agreement to active status, allowing it to process payments as per the agreement terms.
• cancelled: Cancel the agreement, making it inactive and preventing any further transactions.
• suspended: Temporarily suspend the agreement, pausing all associated transactions until reactivated.

This feature is useful for controlling and managing payment workflows in response to specific business needs or customer requests.

Request

application/json

Bodyrequired

idnumberrequired
The unique Hello Clever payment ID associated with the payment agreement.
Example: 4
statusstringrequired
The new status to apply to the payment agreement.
Possible values: [active, cancelled, suspended]
Example: active

Responses

200

Status updated 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

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/change_status");
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  \"id\": 4,\n  \"status\": \"active\"\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

{
  "id": 4,
  "status": "active"
}

ResponseClear

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