Squarepay API
  1. Agreements
Squarepay API
  • Authentication
    • Test Authentication
      POST
  • PayTo
    • Agreements
      • Create Agreement
        POST
      • List Agreements
        GET
      • Show Agreement
        GET
      • Show Agreement History
        GET
    • Agreement Actions
      • Cancel Agreement
    • Payments
      • Create Payment
      • List Payments
      • Show Payment
      • Retry Payment
  • Webhook Subscriptions
    • Create Webhook Subscription
      POST
    • List Webhook Subscriptions
      GET
    • Update Webhook Subscription
      PUT
    • Delete Webhook Subscription
      DELETE
  • Webhooks
    • List Webhooks
      GET
    • Show Webhook
      GET
    • Resend Webhook
      POST
  1. Agreements

Create Agreement

POST
/pay-to/agreements
payto

Request

Authorization
Send your HTTP requests with an
Authorization
header that contains the word Basic followed by a space and a base64-encoded string username:password
Example:
Authorization: Basic *****************
Header Params
Accept
string 
optional
Example:
application/json
Body Params application/json
reference
string 
required
This is a unique reference to prevent duplicate transactions. This is a nonce.
>= 1 characters<= 255 characters
purpose
enum<string> 
required
The reason for the agreement with the debtor.
Allowed values:
mortgageutilityloandependant_supportgamblingretailsalarypersonalgovernmentpensiontaxother
description
string 
required
The human readable reason for the agreement. Valid ASCII characters only.
>= 1 characters<= 256 characters
last_name
string 
required
If customer is a business enter legal entity name here.
<= 255 characters
first_name
string  | null 
optional
If customer is a business leave this field blank.
<= 100 characters
customer_reference
string 
required
A unique system identifier for your customer.
<= 50 characters
response_required_by
string  | null 
optional
An optional information requested resolution (accept/decline) deadline for this agreement. It will be displayed in any notifications send to the debtor. Format: yyyy-mm-ddTHH:MM:SS Sydney time (AEST).
start_date
string  | null 
optional
Start date for validity of agreement, will default to todays date if not provided. Format: YYYY-MM-DD timezone assumed to be Sydney time (AEST).
end_date
string  | null 
optional
End date for validity of agreement, if provided the agreement will be valid up till 23:59:59. Format: YYYY-MM-DD timezone assumed to be Sydney time (AEST).
payment_term_type
enum<string> 
required
The pattern the payments will follow.
Allowed values:
fixedusagevariableballoon
frequency
enum<string> 
required
The frequency at which payments may be made.
Allowed values:
adhocdailyweeklyfortnightlymonthlyquarterlysemi_annualannual
amount
integer  | null 
optional
The amount to be debitted based on the schedule. To be submitted in cents
count
integer  | null 
optional
Number of payments allowed per frequency period. If count is not provided it will be assumed one payment per period is allowed. If frequency is adhoc and count is not given, unlimited payments will be allowed.
first_payment_date
string  | null 
optional
The date the first payment will be initiated for the agreement. Format: YYYY-MM-DD timezone assumed to be Sydney time (AEST).
last_payment_date
string  | null 
optional
The date the last payment will be initiated for the agreement. Format: YYYY-MM-DD timezone assumed to be Sydney time (AEST).
max_amount
integer  | null 
optional
The maximum allowed payment amount. To be submitted in cents.
first_payment_amount
integer  | null 
optional
Applicable to balloon payments. To be submitted in cents.
last_payment_amount
integer  | null 
optional
Applicable to balloon payments. To be submitted in cents.
account_type
string 
required
bsb
string  | null 
optional
This field is required when account_type is bban. BSB format 032000
account_number
string  | null 
optional
This field is required when account_type is bban.
pay_id
string  | null 
optional
This field is required when account_type is not bban. This must be a valid PayID address.
Example
{
  "reference": "Loan1337",
  "purpose": "loan",
  "description": "Loan Payout 1337",
  "last_name": "Bob",
  "first_name": "Billy",
  "customer_reference": "MEM000001337",
  "response_required_by": "2024-02-25T16:45:15",
  "start_date": "2024-02-01",
  "end_date": "2025-01-31",
  "payment_term_type": "fixed",
  "frequency": "weekly",
  "amount": 10000,
  "count": 10,
  "first_payment_date": "2024-02-01",
  "last_payment_date": "2024-04-11",
  "account_type": "bban",
  "bsb": "062000",
  "account_number": "123456789"
}

Request samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://api-sandbox.squarepay.com.au/v2/pay-to/agreements' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Og==' \
--data-raw '{
    "reference": "Loan1337",
    "purpose": "loan",
    "description": "Loan Payout 1337",
    "last_name": "Bob",
    "first_name": "Billy",
    "customer_reference": "MEM000001337",
    "response_required_by": "2024-02-25T16:45:15",
    "start_date": "2024-02-01",
    "end_date": "2025-01-31",
    "payment_term_type": "fixed",
    "frequency": "weekly",
    "amount": 10000,
    "count": 10,
    "first_payment_date": "2024-02-01",
    "last_payment_date": "2024-04-11",
    "account_type": "bban",
    "bsb": "062000",
    "account_number": "123456789"
}'

Responses

🟢201OK
application/json
Body
data
object (Agreement) 
required
uuid
string 
required
UUID 36 characters
<= 36 characters
status
enum<string> 
required
The agreement status.
Allowed values:
proposedcreatedactivesuspendedcancelleddeclinedfailedexpiredunsubmitted
error_code
string  | null 
optional
A reason code for an Agreement error.
reference
string 
required
This is a unique reference to prevent duplicate transactions. This is a nonce.
>= 1 characters<= 255 characters
purpose
enum<string> 
required
The reason for the agreement with the debtor.
Allowed values:
mortgageutilityloandependant_supportgamblingretailsalarypersonalgovernmentpensiontaxother
description
string 
required
The human readable reason for the agreement.
>= 1 characters<= 256 characters
last_name
string 
required
The debtor's last name.
<= 255 characters
first_name
string  | null 
optional
The debtor's first name.
<= 100 characters
customer_reference
string 
required
A unique system identifier for your customer.
<= 50 characters
response_required_by
string  | null 
optional
An optional information requested resolution (accept/decline) deadline for this agreement. It will be displayed in any notifications send to the debtor. Format: yyyy-mm-ddTHH:MM:SS Sydney time (AEST).
start_date
string  | null 
optional
Start date for validity of agreement. Format: YYYY-MM-DD timezone assumed to be Sydney time (AEST).
end_date
string  | null 
optional
End date for validity of agreement. Format: YYYY-MM-DD timezone assumed to be Sydney time (AEST).
payment_term_type
enum<string> 
required
The pattern the payments will follow.
Allowed values:
fixedusagevariableballoon
frequency
enum<string> 
required
The frequency at which payments may be made.
Allowed values:
adhocdailyweeklyfortnightlymonthlyquarterlysemi_annualannual
amount
string  | null 
optional
Displayed in cents.
count
integer  | null 
optional
Number of payments allowed per frequency period. When the frequency is adhoc the payments will be unlimited.
first_payment_date
string  | null 
optional
The date the first payment will be initiated for the agreement. Format: YYYY-MM-DD timezone assumed to be Sydney time (AEST).
last_payment_date
string  | null 
optional
The date the last payment will be initiated for the agreement. Format: YYYY-MM-DD timezone assumed to be Sydney time (AEST).
max_amount
string  | null 
optional
The maximum allowed payment amount. Displayed in cents.
first_payment_amount
string  | null 
optional
Applicable to balloon payments. Displayed in cents.
last_payment_amount
string  | null 
optional
Applicable to balloon payments. Displayed in cents.
account_type
string 
required
bsb
string  | null 
optional
This field is nullable when account_type is not bban. BSB format 032000
account_number
string  | null 
optional
This field is nullable when account_type is not bban
pay_id
string  | null 
optional
This field is nullable when account_type is bban otherwise a valid PayID address.
Example
{
  "data": {
    "uuid": "2e9d9df0-5c70-4bdf-b031-1caa64121602",
    "status": "created",
    "error_code": "non Lorem cupidatat nostrud esse",
    "reference": "Loan1337",
    "purpose": "loan",
    "description": "Loan Payout 1337",
    "last_name": "Bob",
    "first_name": "Billy",
    "customer_reference": "MEM000001337",
    "response_required_by": "2024-02-25T16:45:15",
    "start_date": "2024-02-01",
    "end_date": "2025-01-31",
    "payment_term_type": "fixed",
    "frequency": "weekly",
    "amount": "100.00",
    "count": 10,
    "first_payment_date": "2024-02-01",
    "last_payment_date": "2024-04-11",
    "max_amount": null,
    "first_payment_amount": null,
    "last_payment_amount": null,
    "account_type": "bban",
    "bsb": "062000",
    "account_number": "123456789",
    "pay_id": null
  }
}
🟠401Unauthorised
🟠422Unprocessable Entity
🔴500Server Error
Previous
Test Authentication
Next
List Agreements
Built with