AUD PayTo

Amend Payment Agreement

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.

POST

pay_to

payment_agreement

amendment

Amend Payment Agreement

curl --request POST \
  --url https://api.cleverhub.co/api/v1/pay_to/payment_agreement/amendment \
  --header 'Content-Type: application/json' \
  --header 'app-id: <api-key>' \
  --header 'secret-key: <api-key>' \
  --data '
{
  "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"
  }
}
'

import requests

url = "https://api.cleverhub.co/api/v1/pay_to/payment_agreement/amendment"

payload = {
    "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"
    }
}
headers = {
    "app-id": "<api-key>",
    "secret-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'app-id': '<api-key>',
    'secret-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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'
    }
  })
};

fetch('https://api.cleverhub.co/api/v1/pay_to/payment_agreement/amendment', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cleverhub.co/api/v1/pay_to/payment_agreement/amendment",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "app-id: <api-key>",
    "secret-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cleverhub.co/api/v1/pay_to/payment_agreement/amendment"

	payload := strings.NewReader("{\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}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("app-id", "<api-key>")
	req.Header.Add("secret-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cleverhub.co/api/v1/pay_to/payment_agreement/amendment")
  .header("app-id", "<api-key>")
  .header("secret-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\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}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cleverhub.co/api/v1/pay_to/payment_agreement/amendment")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["app-id"] = '<api-key>'
request["secret-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\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}"

response = http.request(request)
puts response.read_body

{
  "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"
  }
}

Authorizations

app-id

string

header

required

A unique identifier assigned to each application.

secret-key

string

header

required

A secure token associated with the app-id.

Body

application/json

number

required

The unique Hello Clever payment ID for the agreement being amended.

Example:

123456

limit_amount

number

required

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

object

required

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.

Option 1
Option 2
Option 3
Option 4

Show child attributes

payment_agreement_notification

object

required

Configuration for callback notifications to inform the merchant when the amendment status changes.

Show child attributes

Callbacks

POST

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

Body

application/json

integer

A unique identifier for the payment agreement, used for tracking and management.

Example:

12345

payment_agreement_id

string

The unique identifier for the payment agreement, providing a reference to the specific agreement being handled.

Example:

"agreement-12345"

client_transaction_id

string

A unique ID for the transaction as provided by the merchant, used to ensure transactions can be uniquely tracked.

Required string length: 1 - 90

Example:

"client-trans-001"

limit_amount

number

The maximum allowable amount for each payment under this agreement, helping to manage the scope of transactions.

Example:

5000

description

string

A description of the payment agreement, providing context and information for the payer and merchant.

Required string length: 5 - 140

Example:

"Monthly utility bill payment agreement."

external_id

string

A custom identifier assigned to the payment agreement, typically used for tracking and reference purposes.

Maximum string length: 255

Example:

"custom-agreement-id-7890"

status

enum<string>

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.

Available options:

created,

active,

suspended,

cancelled,

failed

Example:

"active"

created_at

string<date-time>

The timestamp indicating when the payment agreement was created, in UTC.

Example:

"2024-01-01T00:00:00Z"

payment_agreement_type

enum<string>

The type of payment agreement, indicating the nature of the payments involved.

Available options:

MORTGAGE,

UTILITY,

LOAN,

DEPENDANT SUPPORT,

GAMBLING,

RETAIL,

SALARY,

PERSONAL,

GOVERNMENT,

PENSION,

TAX,

OTHER SERVICE

Example:

"UTILITY"

agreement_details

object

Option 1
Option 2
Option 3
Option 4

Show child attributes

payer_details

object

Details about the payer, including either bank account information or PayID details.

Show child attributes

payment_agreement_notification

object

Details for the merchant callback, including endpoint URL and authorization header for receiving status updates on the payment agreement.

Show child attributes

Response

Callback received successfully

Response

Payment agreement amended successfully.

payment_agreement_amendment

object

Show child attributes

payment_agreement_amendment_status

object

Show child attributes

Create Payment Agreement

Change Payment Agreement Status

Amend Payment Agreement

curl --request POST \
  --url https://api.cleverhub.co/api/v1/pay_to/payment_agreement/amendment \
  --header 'Content-Type: application/json' \
  --header 'app-id: <api-key>' \
  --header 'secret-key: <api-key>' \
  --data '
{
  "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"
  }
}
'

import requests

url = "https://api.cleverhub.co/api/v1/pay_to/payment_agreement/amendment"

payload = {
    "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"
    }
}
headers = {
    "app-id": "<api-key>",
    "secret-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'app-id': '<api-key>',
    'secret-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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'
    }
  })
};

fetch('https://api.cleverhub.co/api/v1/pay_to/payment_agreement/amendment', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cleverhub.co/api/v1/pay_to/payment_agreement/amendment",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "app-id: <api-key>",
    "secret-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cleverhub.co/api/v1/pay_to/payment_agreement/amendment"

	payload := strings.NewReader("{\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}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("app-id", "<api-key>")
	req.Header.Add("secret-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cleverhub.co/api/v1/pay_to/payment_agreement/amendment")
  .header("app-id", "<api-key>")
  .header("secret-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\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}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cleverhub.co/api/v1/pay_to/payment_agreement/amendment")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["app-id"] = '<api-key>'
request["secret-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\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}"

response = http.request(request)
puts response.read_body

{
  "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"
  }
}

Overview

Payment Gateway (AUD)

Multi-currency Payment APIs

Multi-currency Gateway

Card API

Cashback API

Amend Payment Agreement

Authorizations

Body

Callbacks

Body

Response

Response