Amend Payment Agreement

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

Amend an existing payment agreement to modify its parameters, such as the limit amount or agreement details. This endpoint allows the merchant to adjust various settings of the payment agreement, including payment limits and specific agreement terms, providing flexibility to accommodate different payment scenarios or changes in the payment structure.

Use this endpoint to update agreement settings in response to new conditions or requirements. Notification settings can also be configured to receive updates on the status of the amended agreement.

Request

application/json

Bodyrequired

idnumberrequired
The unique Hello Clever payment ID for the agreement being amended.
Example: 123456
limit_amountnumberrequired
The maximum payment amount allowed for each transaction within this amended agreement. This should reflect the updated limit you intend to set.
Example: 1000
agreement_details objectrequired
Details of the payment agreement, specifying the type of agreement. Choose one of the defined schema objects to reflect the nature of the amended agreement.
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
payment_agreement_notification objectrequired
Configuration for callback notifications to inform the merchant when the amendment status changes.
endpoint_urlurirequired
An internet-accessible URL that the Payment Agreement API will invoke when the status of the transaction changes.
Example: https://merchant.example.com/payment_status_callback
authorization_headerstringrequired
The authorization token that will be included in the Authorization header of the callback request for security.
Example: Bearer your_secret_token

Responses

200

Payment agreement amended successfully.

application/json

Schema

Schema

payment_agreement_amendment object
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
payment_agreement_amendment_status object
bilateral_amendment_statusstring
Status of the bilateral amendment.
Possible values: [pending, completed, declined, recalled, timedout]
Example: completed
payment_agreement_amendment_idstring
Unique ID for the payment agreement amendment.
Example: 30597959a853444dbadb54332bf7a98e

Example (auto)

{
  "payment_agreement_amendment": {
    "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"
    }
  },
  "payment_agreement_amendment_status": {
    "bilateral_amendment_status": "completed",
    "payment_agreement_amendment_id": "30597959a853444dbadb54332bf7a98e"
  }
}

400

Bad Request

401

Unauthorized

404

Not Found

422

Unprocessable Entity

Callbacks

POST PaymentAgreementAmendmentStatus

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

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/amendment");
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\": 123456,\n  \"limit_amount\": 1000,\n  \"agreement_details\": {\n    \"variable_agreement_details_obj\": {\n      \"start_date\": \"15/07/24\",\n      \"frequency\": \"MONTHLY\"\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

{
  "id": 123456,
  "limit_amount": 1000,
  "agreement_details": {
    "variable_agreement_details_obj": {
      "start_date": "15/07/24",
      "frequency": "MONTHLY"
    }
  },
  "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!