AUD PayTo
Create Payment Agreement
Create a payment agreement that enables recurring or one-time payments between merchants and payers. This agreement specifies the transaction structure, including payment limits, agreement type, and callback details for status notifications.
Available payment methods:
pay_id: Use PayID as the payment method, which can be an email, phone number, or Australian Business Number (ABN). This provides a secure and streamlined payment option using a unique identifier.bsb: Use BSB (Bank-State-Branch) and account number as the payment method, which is suitable for direct bank transfers within Australia.
The endpoint also supports merchant callback configurations to notify merchants of status changes in the payment agreement.
POST
/
v1
/
pay_to
/
payment_agreement
Create Payment Agreement
curl --request POST \
--url https://api.cleverhub.co/api/v1/pay_to/payment_agreement \
--header 'Content-Type: application/json' \
--header 'app-id: <api-key>' \
--header 'secret-key: <api-key>' \
--data '
{
"client_transaction_id": "txn-12345",
"limit_amount": 500,
"description": "Monthly utility payment",
"payment_agreement_type": "UTILITY",
"agreement_details": {
"variable_agreement_details_obj": {
"start_date": "15/07/24",
"frequency": "MONTHLY"
}
},
"payer_details": {
"name": "John Doe",
"bank_account_details": {
"bsb": "123456",
"account_number": "987654321"
},
"pay_id_details": {
"pay_id": "payer@example.com",
"pay_id_type": "EMAIL"
}
},
"payment_agreement_notification": {
"endpoint_url": "https://merchant.example.com/payment_status_callback",
"authorization_header": "Bearer your_secret_token"
},
"external_id": "ext-123456"
}
'import requests
url = "https://api.cleverhub.co/api/v1/pay_to/payment_agreement"
payload = {
"client_transaction_id": "txn-12345",
"limit_amount": 500,
"description": "Monthly utility payment",
"payment_agreement_type": "UTILITY",
"agreement_details": { "variable_agreement_details_obj": {
"start_date": "15/07/24",
"frequency": "MONTHLY"
} },
"payer_details": {
"name": "John Doe",
"bank_account_details": {
"bsb": "123456",
"account_number": "987654321"
},
"pay_id_details": {
"pay_id": "payer@example.com",
"pay_id_type": "EMAIL"
}
},
"payment_agreement_notification": {
"endpoint_url": "https://merchant.example.com/payment_status_callback",
"authorization_header": "Bearer your_secret_token"
},
"external_id": "ext-123456"
}
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({
client_transaction_id: 'txn-12345',
limit_amount: 500,
description: 'Monthly utility payment',
payment_agreement_type: 'UTILITY',
agreement_details: {variable_agreement_details_obj: {start_date: '15/07/24', frequency: 'MONTHLY'}},
payer_details: {
name: 'John Doe',
bank_account_details: {bsb: '123456', account_number: '987654321'},
pay_id_details: {pay_id: 'payer@example.com', pay_id_type: 'EMAIL'}
},
payment_agreement_notification: {
endpoint_url: 'https://merchant.example.com/payment_status_callback',
authorization_header: 'Bearer your_secret_token'
},
external_id: 'ext-123456'
})
};
fetch('https://api.cleverhub.co/api/v1/pay_to/payment_agreement', 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",
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([
'client_transaction_id' => 'txn-12345',
'limit_amount' => 500,
'description' => 'Monthly utility payment',
'payment_agreement_type' => 'UTILITY',
'agreement_details' => [
'variable_agreement_details_obj' => [
'start_date' => '15/07/24',
'frequency' => 'MONTHLY'
]
],
'payer_details' => [
'name' => 'John Doe',
'bank_account_details' => [
'bsb' => '123456',
'account_number' => '987654321'
],
'pay_id_details' => [
'pay_id' => 'payer@example.com',
'pay_id_type' => 'EMAIL'
]
],
'payment_agreement_notification' => [
'endpoint_url' => 'https://merchant.example.com/payment_status_callback',
'authorization_header' => 'Bearer your_secret_token'
],
'external_id' => 'ext-123456'
]),
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"
payload := strings.NewReader("{\n \"client_transaction_id\": \"txn-12345\",\n \"limit_amount\": 500,\n \"description\": \"Monthly utility payment\",\n \"payment_agreement_type\": \"UTILITY\",\n \"agreement_details\": {\n \"variable_agreement_details_obj\": {\n \"start_date\": \"15/07/24\",\n \"frequency\": \"MONTHLY\"\n }\n },\n \"payer_details\": {\n \"name\": \"John Doe\",\n \"bank_account_details\": {\n \"bsb\": \"123456\",\n \"account_number\": \"987654321\"\n },\n \"pay_id_details\": {\n \"pay_id\": \"payer@example.com\",\n \"pay_id_type\": \"EMAIL\"\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 \"external_id\": \"ext-123456\"\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")
.header("app-id", "<api-key>")
.header("secret-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"client_transaction_id\": \"txn-12345\",\n \"limit_amount\": 500,\n \"description\": \"Monthly utility payment\",\n \"payment_agreement_type\": \"UTILITY\",\n \"agreement_details\": {\n \"variable_agreement_details_obj\": {\n \"start_date\": \"15/07/24\",\n \"frequency\": \"MONTHLY\"\n }\n },\n \"payer_details\": {\n \"name\": \"John Doe\",\n \"bank_account_details\": {\n \"bsb\": \"123456\",\n \"account_number\": \"987654321\"\n },\n \"pay_id_details\": {\n \"pay_id\": \"payer@example.com\",\n \"pay_id_type\": \"EMAIL\"\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 \"external_id\": \"ext-123456\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cleverhub.co/api/v1/pay_to/payment_agreement")
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 \"client_transaction_id\": \"txn-12345\",\n \"limit_amount\": 500,\n \"description\": \"Monthly utility payment\",\n \"payment_agreement_type\": \"UTILITY\",\n \"agreement_details\": {\n \"variable_agreement_details_obj\": {\n \"start_date\": \"15/07/24\",\n \"frequency\": \"MONTHLY\"\n }\n },\n \"payer_details\": {\n \"name\": \"John Doe\",\n \"bank_account_details\": {\n \"bsb\": \"123456\",\n \"account_number\": \"987654321\"\n },\n \"pay_id_details\": {\n \"pay_id\": \"payer@example.com\",\n \"pay_id_type\": \"EMAIL\"\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 \"external_id\": \"ext-123456\"\n}"
response = http.request(request)
puts response.read_body{
"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"
}
}Authorizations
A unique identifier assigned to each application.
A secure token associated with the app-id.
Body
application/json
Unique identifier for the transaction created by the merchant’s system.
Required string length:
1 - 90Example:
"txn-12345"
Maximum payment amount allowed for each transaction under this agreement. If using a fixed agreement, this amount should match the intended charge.
Example:
500
Brief description of the payment agreement.
Required string length:
5 - 140Example:
"Monthly utility payment"
Type of the payment agreement.
Available options:
MORTGAGE, UTILITY, LOAN, DEPENDANT_SUPPORT, GAMBLING, RETAIL, SALARY, PERSONAL, GOVERNMENT, PENSION, TAX, OTHER_SERVICE Example:
"UTILITY"
- Option 1
- Option 2
- Option 3
- Option 4
Show child attributes
Show child attributes
Payer details, with either bank_account_details or pay_id_details required.
Show child attributes
Show child attributes
Callback configuration for receiving payment agreement status updates.
Show child attributes
Show child attributes
Custom identifier provided by the merchant for tracking purposes.
Maximum string length:
255Example:
"ext-123456"
Callbacks
POST{$request.body#/payment_agreement_notification/endpoint_url}PaymentAgreementStatus
Body
application/json
A unique identifier for the payment agreement, used for tracking and management.
Example:
12345
The unique identifier for the payment agreement, providing a reference to the specific agreement being handled.
Example:
"agreement-12345"
A unique ID for the transaction as provided by the merchant, used to ensure transactions can be uniquely tracked.
Required string length:
1 - 90Example:
"client-trans-001"
The maximum allowable amount for each payment under this agreement, helping to manage the scope of transactions.
Example:
5000
A description of the payment agreement, providing context and information for the payer and merchant.
Required string length:
5 - 140Example:
"Monthly utility bill payment agreement."
A custom identifier assigned to the payment agreement, typically used for tracking and reference purposes.
Maximum string length:
255Example:
"custom-agreement-id-7890"
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"
The timestamp indicating when the payment agreement was created, in UTC.
Example:
"2024-01-01T00:00:00Z"
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"
- Option 1
- Option 2
- Option 3
- Option 4
Show child attributes
Show child attributes
Details about the payer, including either bank account information or PayID details.
Show child attributes
Show child attributes
Details for the merchant callback, including endpoint URL and authorization header for receiving status updates on the payment agreement.
Show child attributes
Show child attributes
Response
Callback received successfully.
Response
Payment agreement created successfully.
A unique identifier for the payment agreement, used for tracking and management.
Example:
12345
The unique identifier for the payment agreement, providing a reference to the specific agreement being handled.
Example:
"agreement-12345"
A unique ID for the transaction as provided by the merchant, used to ensure transactions can be uniquely tracked.
Required string length:
1 - 90Example:
"client-trans-001"
The maximum allowable amount for each payment under this agreement, helping to manage the scope of transactions.
Example:
5000
A description of the payment agreement, providing context and information for the payer and merchant.
Required string length:
5 - 140Example:
"Monthly utility bill payment agreement."
A custom identifier assigned to the payment agreement, typically used for tracking and reference purposes.
Maximum string length:
255Example:
"custom-agreement-id-7890"
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"
The timestamp indicating when the payment agreement was created, in UTC.
Example:
"2024-01-01T00:00:00Z"
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"
- Option 1
- Option 2
- Option 3
- Option 4
Show child attributes
Show child attributes
Details about the payer, including either bank account information or PayID details.
Show child attributes
Show child attributes
Details for the merchant callback, including endpoint URL and authorization header for receiving status updates on the payment agreement.
Show child attributes
Show child attributes
Create Payment Agreement
curl --request POST \
--url https://api.cleverhub.co/api/v1/pay_to/payment_agreement \
--header 'Content-Type: application/json' \
--header 'app-id: <api-key>' \
--header 'secret-key: <api-key>' \
--data '
{
"client_transaction_id": "txn-12345",
"limit_amount": 500,
"description": "Monthly utility payment",
"payment_agreement_type": "UTILITY",
"agreement_details": {
"variable_agreement_details_obj": {
"start_date": "15/07/24",
"frequency": "MONTHLY"
}
},
"payer_details": {
"name": "John Doe",
"bank_account_details": {
"bsb": "123456",
"account_number": "987654321"
},
"pay_id_details": {
"pay_id": "payer@example.com",
"pay_id_type": "EMAIL"
}
},
"payment_agreement_notification": {
"endpoint_url": "https://merchant.example.com/payment_status_callback",
"authorization_header": "Bearer your_secret_token"
},
"external_id": "ext-123456"
}
'import requests
url = "https://api.cleverhub.co/api/v1/pay_to/payment_agreement"
payload = {
"client_transaction_id": "txn-12345",
"limit_amount": 500,
"description": "Monthly utility payment",
"payment_agreement_type": "UTILITY",
"agreement_details": { "variable_agreement_details_obj": {
"start_date": "15/07/24",
"frequency": "MONTHLY"
} },
"payer_details": {
"name": "John Doe",
"bank_account_details": {
"bsb": "123456",
"account_number": "987654321"
},
"pay_id_details": {
"pay_id": "payer@example.com",
"pay_id_type": "EMAIL"
}
},
"payment_agreement_notification": {
"endpoint_url": "https://merchant.example.com/payment_status_callback",
"authorization_header": "Bearer your_secret_token"
},
"external_id": "ext-123456"
}
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({
client_transaction_id: 'txn-12345',
limit_amount: 500,
description: 'Monthly utility payment',
payment_agreement_type: 'UTILITY',
agreement_details: {variable_agreement_details_obj: {start_date: '15/07/24', frequency: 'MONTHLY'}},
payer_details: {
name: 'John Doe',
bank_account_details: {bsb: '123456', account_number: '987654321'},
pay_id_details: {pay_id: 'payer@example.com', pay_id_type: 'EMAIL'}
},
payment_agreement_notification: {
endpoint_url: 'https://merchant.example.com/payment_status_callback',
authorization_header: 'Bearer your_secret_token'
},
external_id: 'ext-123456'
})
};
fetch('https://api.cleverhub.co/api/v1/pay_to/payment_agreement', 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",
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([
'client_transaction_id' => 'txn-12345',
'limit_amount' => 500,
'description' => 'Monthly utility payment',
'payment_agreement_type' => 'UTILITY',
'agreement_details' => [
'variable_agreement_details_obj' => [
'start_date' => '15/07/24',
'frequency' => 'MONTHLY'
]
],
'payer_details' => [
'name' => 'John Doe',
'bank_account_details' => [
'bsb' => '123456',
'account_number' => '987654321'
],
'pay_id_details' => [
'pay_id' => 'payer@example.com',
'pay_id_type' => 'EMAIL'
]
],
'payment_agreement_notification' => [
'endpoint_url' => 'https://merchant.example.com/payment_status_callback',
'authorization_header' => 'Bearer your_secret_token'
],
'external_id' => 'ext-123456'
]),
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"
payload := strings.NewReader("{\n \"client_transaction_id\": \"txn-12345\",\n \"limit_amount\": 500,\n \"description\": \"Monthly utility payment\",\n \"payment_agreement_type\": \"UTILITY\",\n \"agreement_details\": {\n \"variable_agreement_details_obj\": {\n \"start_date\": \"15/07/24\",\n \"frequency\": \"MONTHLY\"\n }\n },\n \"payer_details\": {\n \"name\": \"John Doe\",\n \"bank_account_details\": {\n \"bsb\": \"123456\",\n \"account_number\": \"987654321\"\n },\n \"pay_id_details\": {\n \"pay_id\": \"payer@example.com\",\n \"pay_id_type\": \"EMAIL\"\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 \"external_id\": \"ext-123456\"\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")
.header("app-id", "<api-key>")
.header("secret-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"client_transaction_id\": \"txn-12345\",\n \"limit_amount\": 500,\n \"description\": \"Monthly utility payment\",\n \"payment_agreement_type\": \"UTILITY\",\n \"agreement_details\": {\n \"variable_agreement_details_obj\": {\n \"start_date\": \"15/07/24\",\n \"frequency\": \"MONTHLY\"\n }\n },\n \"payer_details\": {\n \"name\": \"John Doe\",\n \"bank_account_details\": {\n \"bsb\": \"123456\",\n \"account_number\": \"987654321\"\n },\n \"pay_id_details\": {\n \"pay_id\": \"payer@example.com\",\n \"pay_id_type\": \"EMAIL\"\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 \"external_id\": \"ext-123456\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cleverhub.co/api/v1/pay_to/payment_agreement")
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 \"client_transaction_id\": \"txn-12345\",\n \"limit_amount\": 500,\n \"description\": \"Monthly utility payment\",\n \"payment_agreement_type\": \"UTILITY\",\n \"agreement_details\": {\n \"variable_agreement_details_obj\": {\n \"start_date\": \"15/07/24\",\n \"frequency\": \"MONTHLY\"\n }\n },\n \"payer_details\": {\n \"name\": \"John Doe\",\n \"bank_account_details\": {\n \"bsb\": \"123456\",\n \"account_number\": \"987654321\"\n },\n \"pay_id_details\": {\n \"pay_id\": \"payer@example.com\",\n \"pay_id_type\": \"EMAIL\"\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 \"external_id\": \"ext-123456\"\n}"
response = http.request(request)
puts response.read_body{
"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"
}
}