NAV
squarepay.
HTTP

Introduction

Welcome to the Squarepay API, where we make collecting recurring payments via Direct Debits easy.

The Squarepay API is an overlay service for Direct Debit in Australia (Direct Entry). This allows collecting payments from any bank within Australia with the one integration.

Our API is built on top of HTTP standards, such as HTTP authentication and HTTP verbs. We also support cross-origin resource sharing, allowing your applications to interact securely with our API from a client-side web application (please be aware not to expose your private API key in any public website's client-side code). All API responses are returned in structured JSON.

For your ease of development we offer a sandbox environment to test your integration and explore the API features available. You will be issued with a test key and a live key along with the API endpoints. Our sandbox environment is cost free and will not interact with Direct Entry.

API Update Guidelines

The following types of changes are considered backwards compatible:

Changes we approve and introduce

Changes we avoid

Getting Started

Endpoint

All requests made to the Squarepay API must be via HTTPS. Any requests made over a non-secure channel are simply ignored.

The Squarepay live API Endpoint is:

https://api.squarepay.com.au/v1

The Squarepay sandbox API Endpoint is:

https://api-sandbox.squarepay.com.au/v1

Authentication

POST /v1/test HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Remember: Basic Auth headers are your-api-key:blank-password base64 encoded. Most HTTP libraries will handle this for you.

All requests to our API require your private API key. This key is unique to you and should be kept safe, do not use in client-side code or any place that is publicly accessible.

Squarepay API uses HTTP Basic Auth to authenticate requests. Simply provide your API key as the basic auth username value and leave the password blank.

Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Rate Limiting

Example Rate Limiting returned Headers

HTTP/1.1 200 (OK)
Content-Type: application/json
X-RateLimit-Limit: 80
X-RateLimit-Remaining: 320
X-RateLimit-Reset: 1480721108

{
  "data": {
    "message": "You have successfully authenticated!"
  }
}

To offer a high availability service we rate limit all API endpoints.

Each request made to the API will return HTTP header information in the response to indicate the current rate limit status. These rate limits reset every minute.

Exceeding the rate limit results in a rate_limit_exceeded error as detailed in the error types section.

Date and Time

All responses will have date times formatted as yyyy-mm-ddTHH:MM:SS, e.g. 2016-06-01T16:00:30.

Any Endpoints that require a timestamp as a request parameter, please use the format yyyy-mm-ddTHH:MM:SS e.g. 2016-06-02T16:45:15.

For endpoints that require a date as a request parameter, please use the format yyyy-mm-dd e.g. 2016-06-01.

Customers

The customer resource holds the personal details for a customer. Customer status, payment methods and contact information can be found on this resource.

Customer properties

Field Description
system_ref A unique system identifier for your customer. Generally the primary key or unique non-sequential identifier in your system for a customer or contract.
general_ref A human readable identifier for your customer. Ideally a member number.
customer_status Customer's current status. ACTIVE HOLD PENDING CANCELLED
last_name Customer's family name. If customer is a business entity then use this field to store entity name.
first_name Customer's given name. Leave blank if customer is a business entity.
address_line_1 The first line of the customer's address.
address_line_2 The second line of the customer's address.
address_suburb The suburb of the customer's address.
address_postcode The postcode of the customer's address.
email_address Customer's email address.
mobile_number Customer's mobile number.
payment_method The customers current payment method. Currently DR - Debit Request is only available.
account_holder_name Name of the account holder, as known by the bank. Typically this matches the name of the customer. This field will be transliterated, and truncated to 32 characters.
account_number Last two digits of account number.
bsb The account holders bank-state-branch number. BSB request format 032000, BSB presentation format 032-000.
contract_start_date The date the customer signed the Direct Debit Request Service Agreement.

Create a customer

Example request

POST /v1/customers HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "system_ref" : "MEM000001337",
  "general_ref" : "BillyBob201605012330",
  "last_name" : "Bob",
  "first_name" : "Billy",
  "address_line_1" : "Unit 33",
  "address_line_2" : "7 Brendan St",
  "address_suburb" : "Surry Hills",
  "address_state" : "NSW",
  "address_postcode" : 2010,
  "email_address" : "billybob@gmail.com",
  "mobile_number" : "0400000000",
  "account_holder_name" : "Billy Bob",
  "account_number" : "123456789",
  "bsb" : "111222",
  "contract_start_date": "2016-03-12T00:00:00"
}

Example response

HTTP/1.1 201 (Created)
Content-Type: application/json

{
  "data" : {
    "customer_id" : 1337,
    "system_ref" : "MEM000001337",
    "general_ref" : "BillyBob201605012330",
    "last_name" : "Bob",
    "first_name" : "Billy",
    "customer_status" : "ACTIVE",
    "address_line_1" : "Unit 33",
    "address_line_2" : "7 Brendan St",
    "address_suburb" : "Surry Hills",
    "address_state" : "NSW",
    "address_postcode" : 2010,
    "email_address" : "billybob@gmail.com",
    "mobile_number" : "0400000000",
    "payment_method" : "DR",
    "account_holder_name" : "Billy Bob",
    "account_number" : "XX89",
    "bsb" : "111222",
    "contract_start_date" : "2016-03-12T00:00:00"
  }
}

Creates a new customer resource.

HTTP Endpoint

POST /v1/customers

Parameters

Field Rules Notes
system_ref required max 50 chars Your unique system identifier.
general_ref optional max 50 chars If left blank will default to last_namefirst_nameyyyymmddHHMM.
last_name required max 100 chars If customer is a business enter entity name here.
first_name optional max 100 chars If customer is a business leave this field blank, otherwise required
address_line_1 optional max 50 chars
address_line_2 optional max 50 chars
address_suburb optional max 50 chars
address_state optional max 3 chars Use abreviated state
address_postcode optional 4 digits
email_address optional max 100 chars
mobile_number optional max 10 digits
account_holder_name optional max 32 digits Typically this matches the name of the customer. This field will be transliterated, and truncated to 32 characters. Required if provided with account_number or bsb.
account_number optional max 9 digits. Required if provided with account_holder_name or bsb.
bsb optional max 6 digits This field will be checked against the list of BSB's published by APCA. Required if provided with account_holder_name or account_number, BSB format 032000
contract_start_date required The date the contract was signed by the customer. Must be present or past dated. Date format yyyy-mm-dd

List customers

Example request

GET /v1/customers?page=1&order_by=created_at&order=DESC&customer_status=ACTIVE&after=2016-03-10 HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "data" : [{
    "customer_id" : 1337,
    "customer_status" : "ACTIVE",
    "system_ref" : "MEM000001337",
    "general_ref" : "BillyBob201605012330",
    "last_name" : "Bob",
    "first_name" : "Billy",
    "address_line_1" : "Unit 33",
    "address_line_2" : "7 Brendan St",
    "address_suburb" : "Surry Hills",
    "address_state" : "NSW",
    "address_postcode" : 2010,
    "email_address" : "billybob@gmail.com",
    "mobile_number" : "0400000000",
    "payment_method" : "DR",
    "account_holder_name" : "Billy Bob",
    "account_number" : "XX89",
    "bsb" : "111222",
    "contract_start_date" : "2016-03-12T00:00:00"
  }]
}

Returns a list of your customers for the given parameters.

HTTP Endpoint

GET /v1/customers

Parameters

Field Rules Notes
customer_id optional Search by Squarepay customer id returned by create a customer. Cannot be used with system_ref
system_ref optional Search by your unique system identifier for your customer. Cannot be used with customer_id
customer_status optional ALL, HOLD, PENDING, CANCELLED, ACTIVE Defaults to ALL
payment_method optional ALL, DR, NONE Defaults to ALL
date_filter optional created_at, contract_start_date Required if after, before or on provided. Can be set to created_at or contract_start_date
after optional Filter customers created after date (inclusive). Date format yyyy-mm-dd
before optional Filter customers created before date (inclusive). Date format yyyy-mm-dd
on optional Filter customers for the specified date_filter date. If on is provided then date_filter must be included in the request, Date format yyyy-mm-dd
order_by optional customer_id, created_at, system_ref, general_ref Defaults to customer_id
order optional ASC, DESC Defaults to ASC.
page optional Index pointing to the start of the desired set, first page is 1. Page defaults to 1.
limit optional Number of records to return, defaults to 100.

Get a single customer

Example request - using customer_id

GET /v1/customers/1337 HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example request - using system_ref

GET /v1/customers/MEM000001337?id_type=system_ref HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "data" : {
    "customer_id" : 1337,
    "customer_status" : "ACTIVE",
    "system_ref" : "MEM000001337",
    "general_ref" : "BillyBob201605012330",
    "last_name" : "Bob",
    "first_name" : "Billy",
    "address_line_1" : "Unit 33",
    "address_line_2" : "7 Brendan St",
    "address_suburb" : "Surry Hills",
    "address_state" : "NSW",
    "address_postcode" : 2010,
    "email_address" : "billybob@gmail.com",
    "mobile_number" : "0400000000",
    "payment_method" : "DR",
    "account_holder_name" : "Billy Bob",
    "account_number" : "XX89",
    "bsb" : "111222",
    "contract_start_date" : "2016-03-12T00:00:00"
  }
}

Returns the details of an existing customer.

HTTP Endpoint

GET /v1/customers/{id}

Parameters

Field Rules Notes
id_type optional customer_id, system_ref Defaults to customer_id returned by create a customer. However can also search by system_ref, remember to url encode system ref uri path.

Update a customer

Example request - using customer_id

PUT /v1/customers/1337 HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "new_system_ref" : "NEWSYSTEMREF00001",
  "last_name" : "Bob",
  "first_name" : "Billy",
  "email_address" : "example_updated_email@gmail.com"
}

Example request - using system_ref

PUT /v1/customers/MEM000001337?id_type=system_ref HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "new_system_ref" : "NEWSYSTEMREF00001",
  "last_name" : "Bob",
  "first_name" : "Billy",
  "email_address" : "example_updated_email@gmail.com"
}

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "data" : {
    "customer_id" : 1337,
    "customer_status" : "ACTIVE",
    "system_ref" : "NEWSYSTEMREF00001",
    "general_ref" : "BillyBob201605012330",
    "last_name" : "Bob",
    "first_name" : "Billy",
    "address_line_1" : "Unit 33",
    "address_line_2" : "7 Brendan St",
    "address_suburb" : "Surry Hills",
    "address_state" : "NSW",
    "address_postcode" : 2010,
    "email_address" : "example_updated_email@gmail.com",
    "mobile_number" : "0400000000",
    "payment_method" : "DR",
    "account_holder_name" : "Billy Bob",
    "account_number" : "XX89",
    "bsb" : "111222",
    "contract_start_date" : "2016-03-12T00:00:00"
  }
}

Updates a customer resource. Supports most of the fields available when creating a customer. We have made updating the bank account details a deliberate action, please see Update a customer bank account.

HTTP Endpoint

PUT /v1/customers/1337

Parameters

Field Rules Notes
id_type optional customer_id, system_ref Defaults to customer_id returned by create a customer. However can also update by system_ref, remember to url encode system ref uri path.
new_system_ref optional max 50 chars A new unique system identifier for your customer.
customer_status optional Customer's current status. ACTIVE HOLD PENDING CANCELLED
general_ref optional max 50 chars
last_name optional max 100 chars If customer is a business enter entity name here.
first_name optional max 100 chars If customer is a business leave this field blank, otherwise required
address_line_1 optional max 50 chars
address_line_2 optional max 50 chars
address_suburb optional max 50 chars
address_state optional max 3 chars Use abreviated state
address_postcode optional 4 digits
email_address optional max 100 chars
mobile_number optional max 10 digits

Update a customer bank account

Example request - using customer_id

PUT /v1/customers/1337/banks HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "account_holder_name" : "Billy Bob Saver",
  "account_number" : "987654321",
  "bsb" : "333444"
}

Example request - using system_ref

PUT /v1/customers/MEM000001337/banks?id_type=system_ref HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "account_holder_name" : "Billy Bob Saver",
  "account_number" : "987654321",
  "bsb" : "333444"
}

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "data" : {
    "customer_id" : 1337,
    "customer_status" : "ACTIVE",
    "system_ref" : "MEM000001337",
    "general_ref" : "BillyBob201605012330",
    "last_name" : "Bob",
    "first_name" : "Billy",
    "address_line_1" : "Unit 33",
    "address_line_2" : "7 Brendan St",
    "address_suburb" : "Surry Hills",
    "address_state" : "NSW",
    "address_postcode" : 2010,
    "email_address" : "billybob@gmail.com",
    "mobile_number" : "0400000000",
    "payment_method" : "DR",
    "account_holder_name" : "Billy Bob Saver",
    "account_number" : "XX21",
    "bsb" : "333444",
    "contract_start_date" : "2016-03-12T00:00:00"
  }
}

Updates a customer's bank account details.

The customer will be automatically set to ACTIVE when Bank Details are updated.

HTTP Endpoint

PUT /v1/customers/1337/banks

Parameters

Field Rules Notes
id_type optional customer_id, system_ref Defaults to customer_id returned by create a customer. However can also update by system_ref, remember to url encode system ref uri path.
account_holder_name required max 32 digits Typically this matches the name of the customer. This field will be transliterated, and truncated to 32 characters.
account_number required max 9 digits
bsb required max 6 digits This field will be checked against the list of BSB's published by APCA. BSB format 032000

Payments

The payment resource represent payments from a customer to the client.

Payment properties

Field Description
payment_id A unique identifier provided by Squarepay. This will appear on the customer's bank statement. This identifier is allocated upon transmission to the bank.
scheduled_payment_id A unique identifier provided by Squarepay. This is not to be confused with the payment_id, this identifier is for any scheduled payment whether it has been sent to the bank or not.
customer_id Squarepay's customer id returned by create a customer.
system_ref A unique system identifier for your customer.
general_ref Your customer's human readable identifier. Could be a member number.
last_name The customer's family name or entity name if a business.
first_name The customer's given name or empty if a business.
payment_date The date the payment should be processed. If this is not a business day the payment date will be rolled forward to the next business day. Date format yyyy-mm-dd or yyyy-mm-ddTHH:MM:SS when using a specified processing date and time.
payment_method The method of payment. DR - Debit Request, CR - Credit Request.
payment_ref A unique identifier for your payment.
remitter A human-readable description on the payment which appears in the customers bank statement narrative. This is ideally the clients business name.
payment_amount The amount requested to be debited from the customer. Displayed in dollars (decimal).
scheduled_amount The amount which was debited from the customer. This may vary from the payment amount if Squarepay has applied additional fees.
transaction_fee_client The total processing fees paid to Squarepay by you the client.
transaction_fee_customer The total processing fees paid to Squarepay by the customer.
settlement_date The date the payment was settled to the client. Date format yyyy-mm-dd.
invoice_id The identifier of the invoice that the fees for this payment were billed on.
payment_status WAITING, PENDING, SUCCESSFUL, DISHONOURED, FATAL, CANCELLED
bank_return_code The APCA defined return code detailing the reason for payment failure. See Bank Return Codes

Create a bank debit

Example request

POST /v1/bank_payments HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "system_ref" : "MEM000001337",
  "general_ref" : "BillyBob201605012330",
  "last_name" : "Bob",
  "first_name" : "Billy",
  "email_address" : "billybob@gmail.com",
  "mobile_number" : "0400000000",
  "account_holder_name" : "Billy Bob",
  "account_number" : "123456789",
  "bsb" : "111222",
  "payment_ref" : "1337-10014",
  "payment_amount" : 10000,
  "payment_date" : "2016-04-11T06:00:00"
}

Example response

HTTP/1.1 201 (Created)
Content-Type: application/json

{
  "data" : {
    "scheduled_payment_id" : "9000",
    "customer_id" : 1337,
    "system_ref" : "MEM000001337",
    "general_ref" : "BillyBob201605012330",
    "payment_date" : "2016-04-11T06:00:00",
    "payment_method" : "DR",
    "payment_ref" : "1337-10014",
    "payment_amount" : "100.0000",
    "payment_status" : "WAITING"
  }
}

Creates a new payment against an existing customer resource identified by system_ref and updates the customer with the provided parameters. If no customer resource found, a new customer will be created.

When a customer is found any new details provided will be updated.

The customer will be automatically set to ACTIVE when new Bank Details are provided.

HTTP Endpoint

POST /v1/bank_payments

Parameters

Field Rules Notes
system_ref required max 50 chars
general_ref optional max 50 chars If left blank will default to last_namefirst_nameyyyymmddHHMM.
last_name required max 100 chars If customer is a business enter entity name here.
first_name optional max 100 chars If customer is a business leave this field blank, otherwise required
email_address optional max 100 chars
mobile_number optional max 10 digits
account_holder_name required max 32 digits Typically this matches the name of the customer. This field will be transliterated, and truncated to 32 characters.
account_number required max 9 digits
bsb required max 6 digits This field will be checked against the list of BSB's published by APCA. BSB format 032000
payment_date required The date the payment should be processed. If this is not a business day the payment date will be rolled forward to the next business day. Date format yyyy-mm-dd or yyyy-mm-ddTHH:MM:SS when using a specified processing date and time.
payment_ref required max 50 chars A unique identifier for your payment.
payment_amount required integer The amount requested to be debited from the customer. Submit in cents. e.g. $100.00 = 10000

Create a payment

Example request - using system_ref

POST /v1/payments HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "system_ref" : "MEM000001337",
  "payment_ref" : "1337-10014",
  "payment_amount" : 10000,
  "payment_date" : "2016-04-11",
  "payment_method" : "DR"
}

Example request - using customer_id

POST /v1/payments HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "customer_id" : 1337,
  "payment_ref" : "1337-10014",
  "payment_amount" : 10000,
  "payment_date" : "2016-04-11",
  "payment_method" : "DR"
}

Example response

HTTP/1.1 201 (Created)
Content-Type: application/json

{
  "data" : {
    "scheduled_payment_id" : "9000",
    "customer_id" : 1337,
    "system_ref" : "MEM000001337",
    "general_ref" : "BillyBob201605012330",
    "payment_date" : "2016-04-11T00:00:00",
    "payment_method" : "DR",
    "payment_ref" : "1337-10014",
    "payment_amount" : "100.0000",
    "payment_status" : "WAITING"
  }
}

Creates a new payment against an existing customer resource identified by system_ref or customer_id.

HTTP Endpoint

POST /v1/payments

Parameters

Field Rules Notes
customer_id required Squarepay's customer id returned by create a customer. If provided then system_ref is not required.
system_ref required max 50 chars The customer's unique system identifier. If provided then customer_id is not required.
payment_date required The date the payment should be processed. If this is not a business day the payment date will be rolled forward to the next business day. Date format yyyy-mm-dd or yyyy-mm-ddTHH:MM:SS when using a specified processing date and time.
payment_ref optional max 50 chars An unique identifier for your payment.
payment_amount required integer The amount requested to be debited from the customer. Submit in cents. e.g. $100.00 = 10000 cents

List payments

Example request

GET /v1/payments?payment_method=DR&date_filter=settlement_date&on=2016-04-11 HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "data" : [{
    "payment_id" : 2002448,
    "scheduled_payment_id" : "9000",
    "customer_id" : 1337,
    "first_name" : "Billy",
    "last_name" : "Bob",
    "system_ref" : "MEM000001337",
    "general_ref" : "BillyBob201605012330",
    "payment_date" : "2016-04-11T00:00:00",
    "payment_method" : "DR",
    "payment_ref" : "1337-10014",
    "remitter" : "ABC CORP",
    "payment_amount" : "100.0000",
    "scheduled_amount" : "100.0000",
    "transaction_fee_client" : "0.0000",
    "transaction_fee_customer" : "1.1000",
    "settlement_date" : "2016-04-14T00:00:00",
    "invoice_id" : "20021",
    "payment_status" : "SUCCESSFUL",
    "bank_return_code" : 0
  }]
}

Returns a list of your payments for the given search parameters. These may be scheduled payments and payments already sent to the bank.

HTTP Endpoint

GET /v1/payments

Parameters

Field Rules Notes
payment_status optional ALL, WAITING, PENDING, FAILED, SUCCESSFUL, CANCELLED Search by payment status. Defaults to ALL
payment_method optional ALL, DR Search by payment method. DR - All Debit Requests made to a Bank Account. Defaults to ALL
date_filter optional payment_date, settlement_date Required if after, before or on provided. Can be set to payment_date or settlement_date
after optional Filter payments after a specified date_filter (inclusive). If after is provided then date_filter must be included in the request, Date format yyyy-mm-dd
before optional Filter payments before a specified date_filter (inclusive). If before is provided then date_filter must be included in the request, Date format yyyy-mm-dd
on optional Filter payments on the specified date_filter date. If on is provided then date_filter must be included in the request, Date format yyyy-mm-dd
customer_id optional Search by Squarepay customer id returned by create a customer. Cannot be used with system_ref
system_ref optional Search by your unique system identifier for your customer. Cannot be used with customer_id
payment_ref optional Search by your payment reference. You may use wildcards '%' to retrieve partial matches.
order_by optional payment_date, settlement_date, payment_id Defaults to payment_date
order optional ASC, DESC Defaults to ASC.
page optional Index pointing to the start of the desired set, first page is 1. Page defaults to 1.
limit optional Number of records to return, defaults to 1000.

Get a single payment

Example request - using payment_id

GET /v1/payments/2002448?id_type=payment_id HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example request - using payment_ref

GET /v1/payments/1337-10014?id_type=payment_ref HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example request - using scheduled_payment_id

GET /v1/payments/9000?id_type=scheduled_payment_id HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "data" : {
    "payment_id" : 2002448,
    "scheduled_payment_id" : 9000,
    "customer_id" : 1337,
    "first_name" : "Billy",
    "last_name" : "Bob",
    "system_ref" : "MEM000001337",
    "general_ref" : "BillyBob201605012330",
    "payment_date" : "2016-04-11T00:00:00",
    "payment_method" : "DR",
    "payment_ref" : "1337-10014",
    "remitter" : "ABC CORP",
    "payment_amount" : "100.0000",
    "scheduled_amount" : "100.0000",
    "transaction_fee_client" : "0.0000",
    "transaction_fee_customer" : "1.1000",
    "settlement_date" : "2016-04-14T00:00:00",
    "invoice_id" : "20021",
    "payment_status" : "SUCCESSFUL",
    "bank_return_code" : 0
  }
}

Return the details of an existing payment.

HTTP Endpoint

GET /v1/payments/{id}

Parameters

Field Rules Notes
id_type optional payment_ref, payment_id, scheduled_payment_id Defaults to payment_id. However can also search by payment_ref or scheduled_payment_id, remember to url encode payment_ref in the uri path.

Cancel a payment

Example request - using payment_ref

POST /v1/payments/1337-10014/action/cancel HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example request - using scheduled_payment_id

POST /v1/payments/9000/action/cancel?id_type=scheduled_payment_id HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "data" : {
    "scheduled_payment_id" : 9000,
    "customer_id" : 1337,
    "first_name" : "Billy",
    "last_name" : "Bob",
    "system_ref" : "MEM000001337",
    "general_ref" : "BillyBob201605012330",
    "payment_date" : "2016-04-11T00:00:00",
    "payment_method" : "DR",
    "payment_ref" : "1337-10014",
    "payment_amount" : "100.0000",
    "payment_status" : "CANCELLED"
  }
}

Cancels a payment that was initially in the WAITING status (has not been sent to bank). If a payment has progressed to PENDING this payment cannot be cancelled (already sent to bank).

HTTP Endpoint

POST /v1/payments/{id}/action/cancel

Parameters

Field Rules Notes
id_type optional payment_ref, scheduled_payment_id Defaults to payment_ref. However can also cancelled by scheduled_payment_id. Remember to url encode payment_ref in the uri path.

Bank Accounts

List accounts

Example request

GET /v1/bank_accounts HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "data" : [{
    "bank_account_id": "d333d441-d312-4076-9776-74af5cb69333",
    "bsb": "032-000",
    "bank_name": "Squarepay",
    "account_number": "238493",
    "status": "ACTIVE",
    "title": "Float Account #1",
    "payid": "billy.bob@mydomain.com.au",
    "available_balance": "100.0000"
  },
  {
    "bank_account_id": "9a0bfd89-b6db-38f0-91c5-2a89a7d592f8",
    "bsb": "923-100",
    "bank_name": "ING Bank (Australia) Limited (trading as ING)",
    "account_number": "74182003",
    "status": "ACTIVE",
    "title": "Daphney Bernhard I",
    "payid": null,
    "available_balance": null
  }],
  "page": 1
}

Returns a list of your accounts. This includes your virtual (float) accounts held by Squarepay and your approved branch bank accounts (real, externally-held accounts). Virtual accounts are listed first, followed by branch bank accounts; page/limit pagination spans the combined list.

Distinguish the two by their fields:

HTTP Endpoint

GET /v1/bank_accounts

Properties

Field Description
bank_account_id Unique account identifier.
bsb The account bank-state-branch number.
bank_name The financial institution name. Squarepay for a virtual (float) account.
account_number The account number.
status The account status ACTIVE INACTIVE.
title The account name, or the account holder name for a branch bank account.
payid The account's PayID, or null. Only virtual accounts may have a PayID.
available_balance The account balance in dollars for a virtual account, or null for a branch bank account.

Confirmation of Payee

Confirmation of Payee (CoP) enables you to validate whether a given name matches a given bank account before initiating a payment. This helps reduce misdirected payments and fraud.

CoP CX Guidelines

When integrating CoP into your application, you must present the outcomes to your end users in a clear and consistent manner. This section provides guidelines for iconography and messaging.

Iconography

Use standard iconography to represent CoP outcomes. You have flexibility to customise colours and styling to match your brand, but should maintain common, recognisable industry conventions.

Outcome Icon Colour Description
match Match Green Indicates the name matches the account holder.
close_match Close Match Orange/Amber Indicates a partial match requiring user attention.
no_match No Match Red Indicates the name does not match.
account_not_found Account Not Found Grey Indicates the account could not be found.
unavailable Unavailable Grey Indicates the check could not be completed.
not_supported Not Supported Grey Indicates CoP is not supported for this account.

Present clear, actionable messages to your users based on the outcome. You may adapt the tone to match your brand, but the essential meaning should remain the same.

Outcome Recommended Message User Action
match "The account name matches the name provided." Allow the user to proceed with the payment.
close_match "The account name is a close match to the name provided. Please verify the details are correct." Prompt the user to review and confirm before proceeding.
no_match "The account name does not match the name provided. Please check the details and try again." Warn the user and recommend they verify the account details.
account_not_found "The account provided cannot be found. Please check the BSB and account number." Prompt the user to re-enter the account details.
unavailable "We could not confirm the account name match at this time." Allow the user to proceed with caution or retry later.
not_supported "Account name verification is not available for this account." Allow the user to proceed with caution.

Risk-Based Decisions

Use the risk_score (0-100) in combination with the outcome to make informed decisions:

The risk score provides additional context beyond the simple outcome, allowing you to implement more nuanced user flows.

CoP Response properties

Field Description
confirmation_of_payee_id Unique identifier for the CoP request.
unique_ref Your unique reference provided in the request.
outcome The result of the name match. See Outcome values.
risk_score A score from 0-100 indicating the risk level. Lower scores indicate lower risk.
is_joint Whether the account is a joint account.
available_rails The payment rails available for this account (NPP, DE).

Outcome values

Outcome Description
match The provided name matches the account holder name.
close_match The provided name is a close match to the account holder name.
no_match The provided name does not match the account holder name.
account_not_found The account could not be found or does not exist.
unavailable The financial institution is unable to perform the check.
not_supported The financial institution does not support CoP.

Validate account

Example request

POST /v1/cop/account/validate HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "unique_ref": "c56dba3e-5cbc-4dae-bdcd-1e4df968930b",
  "entity_name": "John Doe",
  "type": "bban",
  "value": "062000-1111111"
}

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "data": {
    "confirmation_of_payee_id": "41e6dfdc-bf1d-4380-9701-725ed2bbaeef",
    "unique_ref": "c56dba3e-5cbc-4dae-bdcd-1e4df968930b",
    "outcome": "match",
    "risk_score": 10,
    "is_joint": false,
    "available_rails": [
      "NPP",
      "DE"
    ]
  }
}

Validates whether the provided name matches the account holder name for a given bank account.

HTTP Endpoint

POST /v1/cop/account/validate

Parameters

Field Rules Notes
unique_ref required max 255 chars Your unique reference for this request. Used for idempotency.
entity_name required max 140 chars The name to validate against the account holder name.
type required The account identifier type. Currently only bban is supported.
value required The account identifier value. For bban type, format is bsb-account_number (e.g. 062000-1111111).

Sandbox simulation

The Sandbox environment allows you to simulate different CoP outcomes by including the simulate_outcome parameter in your request.

Example request with simulation

POST /v1/cop/account/validate HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "unique_ref": "c56dba3e-5cbc-4dae-bdcd-1e4df968930b",
  "entity_name": "John Doe",
  "type": "bban",
  "value": "062000-1111111",
  "simulate_outcome": "close_match"
}

Example response for close match

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "data": {
    "confirmation_of_payee_id": "41e6dfdc-bf1d-4380-9701-725ed2bbaeef",
    "unique_ref": "c56dba3e-5cbc-4dae-bdcd-1e4df968930b",
    "outcome": "close_match",
    "risk_score": 25,
    "is_joint": true,
    "available_rails": [
      "NPP",
      "DE"
    ]
  }
}

Simulate outcome values

Simulate Outcome Description
match Simulates a successful name match.
close_match Simulates a close match to the account holder name.
individual_no_match Simulates no match for an individual account.
non_individual_no_match Simulates no match for a business/non-individual account.
account_closed Simulates an account that has been closed.
no_account_found Simulates an account that cannot be found.
bic_lookup_failed Simulates a BIC lookup failure.
account_daily_no_match_limit_exceeded Simulates the account's daily no-match limit being exceeded.
requester_daily_no_match_limit_exceeded Simulates the requester's daily no-match limit being exceeded.
account_daily_request_limit_exceeded Simulates the account's daily request limit being exceeded.
requester_daily_request_limit_exceeded Simulates the requester's daily request limit being exceeded.
unable_to_confirm Simulates the financial institution being unable to confirm.

Disbursements

The disbursements resource enables the secure transfer of funds from your Squarepay float account to your customer.

Disbursement properties

Field Description
disbursement_id Unique account identifier.
bank_account_id Your float account id.
customer_id Squarepay's customer id returned by create a customer.
system_ref A unique system identifier for your customer.
general_ref Your customer's human readable identifier. Could be a member number.
last_name The customer's family name or entity name if a business.
first_name The customer's given name or empty if a business.
description This description is visible to both the payer and recipient, with the payout recipient seeing the first 9 characters for Direct Entry transactions and the first 280 characters for NPP transactions.
amount The amount to be disbursed from your Squarepay float account. Displayed in dollars (decimal).
disbursement_date The date the disbursement should be processed. Date format yyyy-mm-dd or yyyy-mm-ddTHH:MM:SS when using a specified processing date and time.
bsb The account bank-state-branch number.
account_number The account number.
rails Specifies whether to use DE (Direct Entry) or NPP (New Payments Platform) or both. First specified rail in the list will be prioristised.
current_rails Indicates the final rails used to perform the disbursement. DE or NPP.
unique_ref Your unique reference to prevent duplicate transactions. This is a nonce.
status WAITING, PENDING, SUCCESSFUL, FAILED, CANCELLED
bank_return_code Error code on failed disbursement. 0 indicates no error. See Bank Return Codes
bank_return_detailed Error details on failed disbursement.

Create disbursement

Example request

POST /v1/disbursements HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "bank_account_id" : "d333d441-d312-4076-9776-74af5cb69333",
  "system_ref" : "MEM000001337",
  "general_ref" : "BillyBob201605012330",
  "last_name" : "Bob",
  "first_name" : "Billy",
  "email_address" : "billybob@gmail.com",
  "mobile_number" : "0400000000",
  "description" : "Loan Settlement LOAN:230213",
  "amount" : 10000,
  "disbursement_date" : "2016-04-11T06:00:00",
  "bsb" : "111222",
  "account_number" : "123456789",
  "rails" : ["NPP", "DE"],
  "unique_ref" : "4f3b4342-2d1f-47e7-aea4-f7fc47ad6042"
}

Example response

HTTP/1.1 201 (Created)
Content-Type: application/json

{
  "data" : {
    "disbursement_id" : "05b10c39-0eb0-46c8-86c0-86f4c9d69374",
    "customer_id" : 1337,
    "bank_account_id" : "d333d441-d312-4076-9776-74af5cb69333",
    "system_ref" : "MEM000001337",
    "general_ref" : "BillyBob201605012330",
    "last_name" : "Bob",
    "first_name" : "Billy",
    "email_address" : "billybob@gmail.com",
    "mobile_number" : "0400000000",
    "description" : "Loan Settlement LOAN:230213",
    "amount" : "100.0000",
    "disbursement_date" : "2016-04-11T06:00:00",
    "cleared_date" : null,
    "bsb" : "111222",
    "account_number" : "123456789",
    "rails" : ["NPP", "DE"],
    "current_rails" : "NPP",
    "unique_ref" : "4f3b4342-2d1f-47e7-aea4-f7fc47ad6042",
    "status" : "WAITING",
    "bank_return_code" : 0,
    "bank_return_detail" : null,
    "bank_return_date" : null
  }
}

Creates a new disbursement against an existing customer resource identified by system_ref and updates the customer with the provided parameters. If no customer resource found, a new customer will be created.

When a customer is found any new details provided will be updated.

The customer will be automatically set to ACTIVE when new Bank Details are provided.

HTTP Endpoint

POST /v1/disbursements

Parameters

Field Rules Notes
unique_ref required max 255 chars This is a unique reference to prevent duplicate transactions. This is a nonce.
bank_account_id required Your float account bank_account_id.
system_ref required max 50 chars
general_ref optional max 50 chars If left blank will default to last_namefirst_nameyyyymmddHHMM.
last_name required max 100 chars If customer is a business enter entity name here.
first_name optional max 100 chars If customer is a business leave this field blank, otherwise required
email_address optional max 100 chars
mobile_number optional max 11 digits eg. 61400000000
description required max 280 chars This description is visible to both the payer and recipient, with the payout recipient seeing the first 9 characters for Direct Entry transactions and the first 280 characters for NPP transactions.
amount required integer The amount to be disbursed from your Squarepay float account. Submit in cents. e.g. $100.00 = 10000
disbursement_date required The date the disbursement should be processed.
rails required The payment rails to be used, in order. (NPP, DE or both).
account_number required max 9 digits
bsb required max 6 digits This field will be checked against the list of BSB's published by APCA. BSB format 032000

List disbursements

Example request

GET /v1/disbursements?on=2016-04-11 HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "data" : [{
    "disbursement_id" : "05b10c39-0eb0-46c8-86c0-86f4c9d69374",
    "customer_id" : 1337,
    "bank_account_id" : "d333d441-d312-4076-9776-74af5cb69333",
    "system_ref" : "MEM000001337",
    "general_ref" : "BillyBob201605012330",
    "last_name" : "Bob",
    "first_name" : "Billy",
    "email_address" : "billybob@gmail.com",
    "mobile_number" : "0400000000",
    "description" : "Loan Settlement LOAN:230213",
    "amount" : "100.0000",
    "disbursement_date" : "2016-04-11T06:00:00",
    "cleared_date" : null,
    "bsb" : "111222",
    "account_number" : "123456789",
    "rails" : ["NPP", "DE"],
    "current_rails" : "NPP",
    "unique_ref" : "4f3b4342-2d1f-47e7-aea4-f7fc47ad6042",
    "status" : "WAITING",
    "bank_return_code" : 0,
    "bank_return_detail" : null,
    "bank_return_date" : null
  },
  {
    "disbursement_id" : "bef34336-2ff8-4deb-999e-e70d640649d6",
    "customer_id" : 1337,
    "bank_account_id" : "8b1e1443-3bc2-4967-aede-47af17863cdf",
    "system_ref" : "MEM000001337",
    "general_ref" : "BillyBob201605012330",
    "last_name" : "Bob",
    "first_name" : "Billy",
    "email_address" : "billybob@gmail.com",
    "mobile_number" : "0400000000",
    "description" : "Loan Settlement LOAN:230213",
    "amount" : "400.0000",
    "disbursement_date" : "2016-04-11T06:05:00",
    "cleared_date" : null,
    "bsb" : "062000",
    "account_number" : "987654321",
    "rails" : ["NPP", "DE"],
    "current_rails" : "DE",
    "unique_ref" : "106fe7c6-44f4-4251-930b-713a1195e472",
    "status" : "WAITING",
    "bank_return_code" : 0,
    "bank_return_detail" : null,
    "bank_return_date" : null
  }]
}

Returns a list of your disbursements for the given search parameters.

HTTP Endpoint

GET /v1/disbursements

Parameters

Field Rules Notes
disbursement_status optional ALL, WAITING, PENDING, FAILED, SUCCESSFUL, CANCELLED Search by disbursement status. Defaults to ALL
date_filter optional disbursement_date Required if after, before or on provided. Can be set to disbursement_date, cleared_date, bank_return_date
after optional Filter disbursements after a specified date_filter (inclusive). If after is provided then date_filter must be included in the request, Date format yyyy-mm-dd
before optional Filter disbursements before a specified date_filter (inclusive). If before is provided then date_filter must be included in the request, Date format yyyy-mm-dd
on optional Filter disbursements on the specified date_filter date. If on is provided then date_filter must be included in the request, Date format yyyy-mm-dd
customer_id optional Search by Squarepay customer id returned by create a customer. Cannot be used with system_ref
system_ref optional Search by your unique system identifier for your customer. Cannot be used with customer_id
description optional Search by your transaction reference exact match.
order_by optional disbursement_date, cleared_date, bank_return_date Defaults to disbursement_date
order optional ASC, DESC Defaults to ASC.
page optional Index pointing to the start of the desired set, first page is 1. Page defaults to 1.
limit optional Number of records to return, defaults to 100.

Get a single disbursement

Example request - using disbursement_id

GET /v1/disbursements/05b10c39-0eb0-46c8-86c0-86f4c9d69374?id_type=disbursement_id HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example request - using description

GET /v1/disbursements/Loan%20Settlement%20LOAN%3A230213?id_type=description HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example request - using unique_ref

GET /v1/disbursements/4f3b4342-2d1f-47e7-aea4-f7fc47ad6042?id_type=unique_ref HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "data" : {
    "disbursement_id" : "05b10c39-0eb0-46c8-86c0-86f4c9d69374",
    "customer_id" : 1337,
    "bank_account_id" : "d333d441-d312-4076-9776-74af5cb69333",
    "system_ref" : "MEM000001337",
    "general_ref" : "BillyBob201605012330",
    "last_name" : "Bob",
    "first_name" : "Billy",
    "email_address" : "billybob@gmail.com",
    "mobile_number" : "0400000000",
    "description" : "Loan Settlement LOAN:230213",
    "amount" : "100.0000",
    "disbursement_date" : "2016-04-11T06:00:00",
    "cleared_date" : null,
    "bsb" : "111222",
    "account_number" : "123456789",
    "rails" : ["NPP", "DE"],
    "current_rails" : "NPP",
    "unique_ref" : "4f3b4342-2d1f-47e7-aea4-f7fc47ad6042",
    "status" : "WAITING",
    "bank_return_code" : 0,
    "bank_return_detail" : null,
    "bank_return_date" : null
  }
}

Return the details of an existing disbursement.

HTTP Endpoint

GET /v1/disbursements/{id}

Parameters

Field Rules Notes
id_type optional description, disbursement_id, unique_ref Defaults to disbursement_id. However can also search by description or unique_ref, remember to url encode description in the uri path.

Cancel a disbursement

Example request - using disbursement_id

POST /v1/disbursements/05b10c39-0eb0-46c8-86c0-86f4c9d69374/action/cancel?id_type=disbursement_id HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example request - using description

POST /v1/disbursements/Loan%20Settlement%20LOAN%3A230213/action/cancel?id_type=description HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example request - using unique_ref

POST /v1/disbursements/4f3b4342-2d1f-47e7-aea4-f7fc47ad6042/action/cancel?id_type=unique_ref HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "data" : {
    "disbursement_id" : "05b10c39-0eb0-46c8-86c0-86f4c9d69374",
    "customer_id" : 1337,
    "bank_account_id" : "d333d441-d312-4076-9776-74af5cb69333",
    "system_ref" : "MEM000001337",
    "general_ref" : "BillyBob201605012330",
    "last_name" : "Bob",
    "first_name" : "Billy",
    "email_address" : "billybob@gmail.com",
    "mobile_number" : "0400000000",
    "description" : "Loan Settlement LOAN:230213",
    "amount" : "100.0000",
    "disbursement_date" : "2016-04-11T06:00:00",
    "cleared_date" : null,
    "bsb" : "111222",
    "account_number" : "123456789",
    "rails" : ["NPP", "DE"],
    "current_rails" : "NPP",
    "unique_ref" : "4f3b4342-2d1f-47e7-aea4-f7fc47ad6042",
    "status" : "CANCELLED",
    "bank_return_code" : 251,
    "bank_return_detail" : "The transaction was voided by its initiator.",
    "bank_return_date" : "2016-04-11T05:00:00"
  }
}

Cancels a disbursement that was initially in the WAITING status (has not been sent to bank). If a disbursement has progressed to PENDING this payment cannot be cancelled (already sent to bank).

HTTP Endpoint

POST /v1/disbursements/{id}/action/cancel

Parameters

Field Rules Notes
id_type optional description, disbursement_id, unique_ref Defaults to disbursement_id. However can also cancelled by description. Remember to url encode description in the uri path.

PayID

The PayID resource enables a destination for yoru business to receive funds from a customer. This allows the receipt of funds instantly and eliminates human error for the matching of payments to a customer.

PayID properties

Field Description
payid_id Unique PayID identifier.
customer_id Squarepay's customer id returned by create a customer.
bank_account_id Your float account id, where funds will deposit into.
system_ref A unique system identifier for your customer.
general_ref Your customer's human readable identifier. Could be a member number.
last_name The customer's family name or entity name if a business.
first_name The customer's given name or empty if a business.
payid_type EMAIL
payid_value The customer's unique payid destination.
payid_status PENDING, ACTIVE, FAILED, DISABLED, DEREGISTERED

Create PayID

Example request

POST /v1/payids HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "system_ref" : "MEM000001337",
  "general_ref" : "BillyBob201605012330",
  "last_name" : "Bob",
  "first_name" : "Billy",
  "payid_email" : "billy.bob@mydomain.com.au"
}

Example response

HTTP/1.1 201 (Created)
Content-Type: application/json

{
  "data" : {
    "payid_id" : "99acde49-0065-4f13-a935-67632a0bf99c",
    "customer_id" : 1337,
    "bank_account_id" : "d333d441-d312-4076-9776-74af5cb69333",
    "system_ref" : "MEM000001337",
    "general_ref" : "BillyBob201605012330",
    "last_name" : "Bob",
    "first_name" : "Billy",
    "payid_type" : "EMAIL",
    "payid_value" : "billy.bob@mydomain.com.au",
    "payid_status" : "PENDING",
    "alias_name" : "My Alias",
    "bsb" : "802918",
    "account_number" : "1820321"
  }
}

Creates a new PayID against an existing customer resource identified by system_ref and updates the customer with the provided parameters. If no customer resource found, a new customer will be created.

When a customer is found any new details provided will be updated.

HTTP Endpoint

POST /v1/payids

Parameters

Field Rules Notes
system_ref required max 50 chars
general_ref optional max 50 chars If left blank will default to last_namefirst_nameyyyymmddHHMM.
last_name required max 100 chars If customer is a business enter entity name here.
first_name optional max 100 chars If customer is a business leave this field blank, otherwise required
payid_email required max 256 chars

List PayIDs

Example request

GET /v1/payids HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "data" : [{
    "payid_id" : "99acde49-0065-4f13-a935-67632a0bf99c",
    "customer_id" : 1337,
    "bank_account_id" : "d333d441-d312-4076-9776-74af5cb69333",
    "system_ref" : "MEM000001337",
    "general_ref" : "BillyBob201605012330",
    "last_name" : "Bob",
    "first_name" : "Billy",
    "payid_type" : "EMAIL",
    "payid_value" : "billy.bob@mydomain.com.au",
    "payid_status" : "ACTIVE",
    "alias_name" : "My Alias",
    "bsb" : "802918",
    "account_number" : "1820321"
  },
  {
    "payid_id" : "2ed89979-6ee9-447d-89da-e0e5f170a3ee",
    "customer_id" : 4882,
    "bank_account_id" : "d333d441-d312-4076-9776-74af5cb69333",
    "system_ref" : "MEM000004882",
    "general_ref" : "DonaldDuck202104230730",
    "last_name" : "Duck",
    "first_name" : "Donald",
    "payid_type" : "EMAIL",
    "payid_value" : "donald.duck@mydomain.com.au",
    "payid_status" : "ACTIVE",
    "alias_name" : "My Alias",
    "bsb" : "802918",
    "account_number" : "1824245"
  }]
}

Returns a list of your PayIDs for the given search parameters.

HTTP Endpoint

GET /v1/payids

Parameters

Field Rules Notes
payid_status optional ALL, PENDING, ACTIVE, FAILED, DISABLED, DEREGISTERED Search by PayID status. Defaults to ALL
date_filter optional payid_date, status_date Required if after, before or on provided. Defaults to payid_date.
after optional Filter PayIDs after a specified date_filter (inclusive). If after is provided then date_filter must be included in the request, Date format yyyy-mm-dd
before optional Filter PayIDs before a specified date_filter (inclusive). If before is provided then date_filter must be included in the request, Date format yyyy-mm-dd
on optional Filter PayIDs on the specified date_filter date. If on is provided then date_filter must be included in the request, Date format yyyy-mm-dd
customer_id optional Search by Squarepay customer id returned by create a customer. Cannot be used with system_ref
system_ref optional Search by your unique system identifier for your customer. Cannot be used with customer_id
page optional Index pointing to the start of the desired set, first page is 1. Page defaults to 1.
limit optional Number of records to return, defaults to 100.

Get a single PayID

Example request - using payid_id

GET /v1/payids/99acde49-0065-4f13-a935-67632a0bf99c?id_type=payid_id HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example request - using payid_value

GET /v1/payids/billy.bob%40mydomain.com.au?id_type=payid_value HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "data" : {
    "payid_id" : "99acde49-0065-4f13-a935-67632a0bf99c",
    "customer_id" : 1337,
    "bank_account_id" : "d333d441-d312-4076-9776-74af5cb69333",
    "system_ref" : "MEM000001337",
    "general_ref" : "BillyBob201605012330",
    "last_name" : "Bob",
    "first_name" : "Billy",
    "payid_type" : "EMAIL",
    "payid_value" : "billy.bob@mydomain.com.au",
    "payid_status" : "ACTIVE",
    "alias_name" : "My Alias",
    "bsb" : "802918",
    "account_number" : "1820321"
  }
}

Return the details of an existing PayID.

HTTP Endpoint

GET /v1/payids/{id}

Parameters

Field Rules Notes
id_type optional payid_value, payid_id Defaults to payid_id. However can also search by payid_value, remember to url encode payid_value in the uri path.

Disable a PayID

Example request - using payid_id

POST /v1/payids/99acde49-0065-4f13-a935-67632a0bf99c/action/disable?id_type=payid_id HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example request - using payid_value

POST /v1/payids/billy.bob%40mydomain.com.au/action/disable?id_type=payid_value HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example response

HTTP/1.1 204 (OK)
Content-Type: application/json

Disables an existing PayID to automatically reject payments made to the relevant Account number or PayID and return them to your customer.

HTTP Endpoint

POST /v1/payids/{id}/action/disable

Parameters

Field Rules Notes
id_type optional payid_value, payid_id Defaults to payid_id. However can also disabled by payid_value. Remember to url encode payid_value in the uri path.

Activate a PayID

Example request - using payid_id

POST /v1/payids/99acde49-0065-4f13-a935-67632a0bf99c/action/activate?id_type=payid_id HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example request - using payid_value

POST /v1/payids/billy.bob%40mydomain.com.au/action/activate?id_type=payid_value HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example response

HTTP/1.1 204 (OK)
Content-Type: application/json

Activates an previously disabled PayID, restoring payment functionality to the relevant Account number or PayID.

HTTP Endpoint

POST /v1/payids/{id}/action/activate

Parameters

Field Rules Notes
id_type optional payid_value, payid_id Defaults to payid_id. However can also activate by payid_value. Remember to url encode payid_value in the uri path.

Receivables

A receivable is created automatically whenever a customer sends funds to a PayID of BBAN created using create PayID.

Receivable properties

Field Description
receivable_id Unique receivable identifier.
payid_id Unique PayID identifier returned by create PayID.
customer_id Squarepay's customer id returned by create a customer.
bank_account_id Your float account id, where funds will deposit into.
system_ref A unique system identifier for your customer.
general_ref Your customer's human readable identifier. Could be a member number.
last_name The customer's family name or entity name if a business.
first_name The customer's given name or empty if a business.
payid_type EMAIL
payid_value The customer's unique payid destination.
alias_name The businesses name displayed upon PayID resolution.receivable_id
to_bsb The receivers PayID bsb.
to_account_number The receivers PayID account number.
payment_date The date the payment was received. Date format yyyy-mm-ddTHH:MM:SS.
payment_amount The amount received from the customer. Displayed in dollars (decimal).
from_bsb The senders BSB.
from_account_number The senders account number.
description The description entered by the sender.
reference The reference entered by the sender.
from_name The senders name.
from_legal_name The senders legal name.
receivable_status SUCCESSFUL, REFUNDED
receivable_method NPP_PAYID - Customer paid using PayID
NPP_BBAN - Customer paid using BBAN with NPP enabled FI
DE - Customer paid via DE)

List receivables

Example request

GET /v1/receivables HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "data" : [{
    "receivable_id" : "4cda1125-e13d-4432-99d1-a0ba3832b86c",
    "payid_id" : "99acde49-0065-4f13-a935-67632a0bf99c",
    "customer_id" : 1337,
    "bank_account_id" : "d333d441-d312-4076-9776-74af5cb69333",
    "system_ref" : "MEM000001337",
    "general_ref" : "BillyBob201605012330",
    "last_name" : "Bob",
    "first_name" : "Billy",
    "payid_type" : "EMAIL",
    "payid_value" : "billy.bob@mydomain.com.au",
    "alias_name" : "My Alias",
    "to_bsb" : "802918",
    "to_account_number" : "1820321",
    "payment_date" : "2021-04-27T11:21:28",
    "payment_amount" : "99.9900",
    "from_bsb" : "062000",
    "from_account_number" : "123456789",
    "description" : "My Description",
    "reference" : "My Reference",
    "from_name" : "Billy Bob",
    "from_legal_name" : "Billy James Bob",
    "receivable_status" : "SUCCESSFUL",
    "receivable_method" : "NPP_PAYID"
  },
  {
    "receivable_id" : "3a16240a-0e9a-454c-9219-304a7cfa4e76",
    "payid_id" : "2ed89979-6ee9-447d-89da-e0e5f170a3ee",
    "customer_id" : 4882,
    "bank_account_id" : "d333d441-d312-4076-9776-74af5cb69333",
    "system_ref" : "MEM000004882",
    "general_ref" : "DonaldDuck202104230730",
    "last_name" : "Duck",
    "first_name" : "Donald",
    "payid_type" : "EMAIL",
    "payid_value" : "donald.duck@mydomain.com.au",
    "alias_name" : "My Alias",
    "bsb" : "802918",
    "account_number" : "1824245",
    "payment_date" : "2021-04-23T08:58:37",
    "payment_amount" : "3141.5900",
    "from_bsb" : "062000",
    "from_account_number" : "123456789",
    "description" : "My Description",
    "reference" : "My Reference",
    "from_name" : "Donald Duck",
    "from_legal_name" : "Donald Fauntleroy Duck",
    "receivable_status" : "SUCCESSFUL",
    "receivable_method" : "NPP_BBAN"
  }]
}

Returns a list of your payments (receivables) received via Pay ID for the given search parameters.

HTTP Endpoint

GET /v1/receivables

Parameters

Field Rules Notes
receivable_status optional ALL, SUCCESSFUL, REFUNDED Search by receivable status. Defaults to ALL.
date_filter optional payment_date Required if after, before or on provided. Can be set to payment_date.
after optional Filter receivables after a specified date_filter (inclusive). If after is provided then date_filter must be included in the request, Date format yyyy-mm-dd
before optional Filter receivables before a specified date_filter (inclusive). If before is provided then date_filter must be included in the request, Date format yyyy-mm-dd
on optional Filter receivables on the specified date_filter date. If on is provided then date_filter must be included in the request, Date format yyyy-mm-dd
customer_id optional Search by Squarepay customer id returned by create a customer. Cannot be used with system_ref
system_ref optional Search by your unique system identifier for your customer. Cannot be used with customer_id
payid_id optional Search by Squarepay PayID id returned by Create PayID. Cannot be used with system_ref
page optional Index pointing to the start of the desired set, first page is 1. Page defaults to 1.
limit optional Number of records to return, defaults to 100.

Get a single receivable

Example request

GET /v1/receivables/{receivable_id} HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "data" : {
    "receivable_id" : "4cda1125-e13d-4432-99d1-a0ba3832b86c",
    "payid_id" : "99acde49-0065-4f13-a935-67632a0bf99c",
    "customer_id" : 1337,
    "bank_account_id" : "d333d441-d312-4076-9776-74af5cb69333",
    "system_ref" : "MEM000001337",
    "general_ref" : "BillyBob201605012330",
    "last_name" : "Bob",
    "first_name" : "Billy",
    "payid_type" : "EMAIL",
    "payid_value" : "billy.bob@mydomain.com.au",
    "alias_name" : "My Alias",
    "bsb" : "802918",
    "account_number" : "1820321",
    "payment_date" : "2021-04-27T11:21:28",
    "payment_amount" : "99.9900",
    "from_bsb" : "062000",
    "from_account_number" : "123456789",
    "description" : "My Description",
    "reference" : "My Reference",
    "from_name" : "Billy Bob",
    "from_legal_name" : "Billy James Bob",
    "receivable_status" : "SUCCESSFUL",
    "receivable_method" : "NPP_PAYID"
  }
}

Returns the details of an existing receivable.

HTTP Endpoint

GET /v1/receivables/{receivable_id}

PayTo Agreements

PayTo is a digital payment agreement service built on the New Payments Platform (NPP). A PayTo Agreement (also referred to as a mandate) is an authorisation established between you and your customer that allows you to initiate real-time payments from the customer's bank account or PayID under agreed terms.

Once an agreement has been created, the customer authorises it in their own banking app. When the agreement becomes active you may create PayTo Payments against it. Agreements may later be modified, suspended, reactivated or cancelled.

Agreement properties

Field Description
uuid A unique identifier for the agreement, allocated by Squarepay.
reference Your unique reference for the agreement, supplied at creation. Used to address the agreement in suspend/reactivate/cancel/amend calls.
customer_reference Your unique identifier for the customer the agreement belongs to.
purpose The purpose of the agreement. See Agreement purpose.
description A human readable description of the agreement, shown to the customer when they authorise it.
first_name The customer's given name. Empty for a business.
last_name The customer's family name, or the entity name if a business.
status The current status of the agreement. See Agreement status.
error_code Populated when an agreement has failed; describes the failure reason.
start_date The date from which the agreement is valid. Date format yyyy-mm-dd.
end_date The date the agreement expires. null for an open-ended agreement. Date format yyyy-mm-dd.
payment_term_type Defines how payment amounts are constrained. See Payment term types.
frequency How often payments are expected. See Frequency.
amount The agreed payment amount in cents. Meaning depends on payment_term_type.
count The total number of payments expected over the life of the agreement, where applicable.
response_required_by The deadline by which the customer must authorise the agreement. Date format yyyy-mm-ddTHH:MM:SS.
first_payment_amount For balloon agreements, the amount of the first payment in cents.
last_payment_amount For balloon agreements, the amount of the final payment in cents.
max_amount For variable and usage agreements, the maximum amount that may be debited per payment in cents.
first_payment_date The date of the first scheduled payment. Date format yyyy-mm-dd.
last_payment_date The date of the final scheduled payment. Date format yyyy-mm-dd.
bsb The customer's BSB, when the agreement is against a bank account (bban).
account_number The customer's account number, when the agreement is against a bank account (bban).
account_type The payment method the agreement is established against. See Account type.
pay_id The customer's PayID, when the agreement is against a PayID alias.
created The date and time the agreement was created. Date format yyyy-mm-ddTHH:MM:SS.

Agreement status

A new agreement is proposed to your customer, who authorises it in their banking app. Until they respond it awaits authorisation; it then becomes active, or is declined (the customer rejected it) or expired (the customer did not respond in time).

Status Description
proposed The agreement has been created and is awaiting the customer's authorisation.
created The agreement has been lodged with the payment platform.
active The customer has authorised the agreement. Payments may now be created against it.
suspended The agreement has been temporarily suspended and cannot be used until reactivated.
cancelled The agreement has been cancelled and can no longer be used.
declined The customer declined to authorise the agreement.
failed The agreement could not be established. See error_code.
expired The agreement was not authorised before response_required_by, or has passed its end_date.
unsubmitted The agreement has been drafted but not yet submitted to the payment platform.

Payment term types

The payment_term_type controls which amount fields apply to the agreement:

Term type Description amount first_payment_amount last_payment_amount max_amount
fixed A fixed amount is debited each period. required — — —
variable The amount varies per payment, up to a ceiling. — — — optional
usage Usage/consumption based, up to a ceiling. — — — optional
balloon A regular amount with different first and/or final payments. required optional optional —

Frequency

Frequency Description
adhoc A payment on request or as necessary.
daily A payment daily.
weekly A payment once per week.
fortnightly A payment every 2 weeks.
monthly A payment once per month.
quarterly A payment every 3 months.
semi_annual A payment twice per year.
annual A payment once per year.

Agreement purpose

The purpose reflects the nature of the agreement — the reason it is being proposed to your customer — and is shown to the customer's bank. One of: mortgage, utility, loan, dependant_support, gambling, retail, salary, personal, government, pension, tax, other.

Account type

The account_type determines how the customer's account is addressed.

Account type Description Required identifier
bban A domestic bank account. bsb + account_number
alias_email A PayID registered against an email address. pay_id
alias_phone A PayID registered against a mobile number. pay_id
alias_abn A PayID registered against an ABN. pay_id
alias_organisation_identifier A PayID registered against an organisation identifier. pay_id

Creditor account

The creditor account is the account that receives the payments collected under an agreement. By default this is your branch's default settlement account. To route settlement to a specific account instead, set creditor_account to a bank_account_id from List accounts:

Omit creditor_account to keep the default behaviour (the branch settlement account). Existing integrations are unaffected.

Create an agreement

Example request - bank account (bban)

POST /v2/pay-to/agreements HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "reference": "AGREEMENT-2024-0001",
  "customer_reference": "CUST-000123",
  "purpose": "loan",
  "description": "Weekly loan repayment",
  "last_name": "Bob",
  "first_name": "Billy",
  "payment_term_type": "fixed",
  "frequency": "weekly",
  "amount": 10000,
  "start_date": "2024-06-01",
  "account_type": "bban",
  "bsb": "062000",
  "account_number": "123456789"
}

Example request - PayID (email alias)

POST /v2/pay-to/agreements HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "reference": "AGREEMENT-2024-0002",
  "customer_reference": "CUST-000123",
  "purpose": "utility",
  "description": "Monthly electricity bill",
  "last_name": "Bob",
  "first_name": "Billy",
  "payment_term_type": "variable",
  "frequency": "monthly",
  "max_amount": 50000,
  "account_type": "alias_email",
  "pay_id": "billy.bob@gmail.com"
}

Example response

HTTP/1.1 201 (Created)
Content-Type: application/json

{
  "uuid": "b3d5e8f1-2c4a-4e6b-9d8f-1a2b3c4d5e6f",
  "reference": "AGREEMENT-2024-0001",
  "customer_reference": "CUST-000123",
  "purpose": "loan",
  "description": "Weekly loan repayment",
  "first_name": "Billy",
  "last_name": "Bob",
  "status": "proposed",
  "error_code": null,
  "start_date": "2024-06-01T00:00:00",
  "end_date": null,
  "payment_term_type": "fixed",
  "frequency": "weekly",
  "amount": 10000,
  "count": null,
  "response_required_by": null,
  "first_payment_amount": null,
  "last_payment_amount": null,
  "max_amount": null,
  "first_payment_date": null,
  "last_payment_date": null,
  "bsb": "062000",
  "account_number": "123456789",
  "account_type": "bban",
  "pay_id": null,
  "created": "2024-05-20T09:15:00"
}

Creates a new PayTo agreement. The agreement is created in the proposed status and is sent to the customer to authorise in their banking app. Subscribe to webhooks to be notified when the customer authorises the agreement and it becomes active.

HTTP Endpoint

POST /v2/pay-to/agreements

Parameters

Field Rules Notes
reference required max 255 chars Your unique reference for this agreement. Must be unique across your agreements.
purpose required See Agreement purpose.
description required max 256 chars ASCII only. Shown to the customer when authorising the agreement.
first_name optional max 100 chars ASCII only. Leave blank for a business.
last_name required max 255 chars ASCII only. Enter the entity name here for a business.
customer_reference required max 64 chars ASCII only. Your unique identifier for the customer.
response_required_by optional The deadline for the customer to authorise the agreement. Date format yyyy-mm-ddTHH:MM:SS.
start_date optional The date the agreement becomes valid. Must be before end_date. Date format yyyy-mm-dd.
end_date optional The date the agreement expires. Must be after start_date. Date format yyyy-mm-dd.
payment_term_type required See Payment term types.
frequency required See Frequency.
amount See term types The agreed payment amount in cents (e.g. $100.00 = 10000). Minimum 1 cent, maximum your configured PayTo limit.
count optional integer min 1 The total number of payments expected.
first_payment_amount balloon only The first payment amount in cents (e.g. $100.00 = 10000). Prohibited for other term types.
last_payment_amount balloon only The final payment amount in cents (e.g. $100.00 = 10000). Prohibited for other term types.
max_amount variable, usage only The maximum amount per payment in cents (e.g. $100.00 = 10000). Prohibited for fixed and balloon.
first_payment_date optional Date of the first payment. Must be after start_date and before last_payment_date/end_date. Date format yyyy-mm-dd.
last_payment_date optional Date of the final payment. Must be after first_payment_date/start_date and before end_date. Date format yyyy-mm-dd.
account_type required See Account type.
bsb required for bban The customer's BSB. Checked against the APCA BSB list. BSB format 062000. Excluded for PayID types.
account_number required for bban max 9 digits. Excluded for PayID types.
pay_id required for PayID types The customer's PayID. Excluded for bban.
creditor_account optional The account that receives payments under this agreement — a bank_account_id from List accounts (a virtual or branch bank account). See Creditor account. Omit to use the branch's default settlement account. Errors: "The selected creditor account was not found." / "The selected creditor account has no usable bank account."

List agreements

Example request

GET /v2/pay-to/agreements?purpose=loan&frequency=weekly&per_page=50 HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "page": 1,
  "total": 1,
  "last_page": 1,
  "per_page": 100,
  "data": [{
    "uuid": "b3d5e8f1-2c4a-4e6b-9d8f-1a2b3c4d5e6f",
    "reference": "AGREEMENT-2024-0001",
    "customer_reference": "CUST-000123",
    "purpose": "loan",
    "description": "Weekly loan repayment",
    "status": "active",
    "payment_term_type": "fixed",
    "frequency": "weekly",
    "amount": 10000,
    "account_type": "bban",
    "bsb": "062000",
    "account_number": "123456789",
    "created": "2024-05-20T09:15:00"
  }]
}

Returns a paginated list of your agreements matching the supplied filters.

HTTP Endpoint

GET /v2/pay-to/agreements

Parameters

Field Rules Notes
reference optional max 255 chars Filter by your agreement reference.
purpose optional Filter by purpose.
first_name optional max 100 chars Filter by the customer's given name.
last_name optional max 255 chars Filter by the customer's family/entity name.
customer_reference optional max 64 chars Filter by your customer identifier.
payment_term_type optional Filter by payment term type.
frequency optional Filter by frequency.
created_on optional Filter by agreements created on this date. Date format yyyy-mm-dd.
created_after optional Filter by agreements created on or after this date (inclusive). Date format yyyy-mm-dd.
created_before optional Filter by agreements created on or before this date (inclusive). Date format yyyy-mm-dd.
page optional Index pointing to the start of the desired set, first page is 1. Page defaults to 1.
per_page optional Number of records to return, defaults to 100. Maximum 1000.

Get a single agreement

Example request - using uuid (default)

GET /v2/pay-to/agreements/b3d5e8f1-2c4a-4e6b-9d8f-1a2b3c4d5e6f HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example request - using your reference, including history

GET /v2/pay-to/agreements/AGREEMENT-2024-0001?id_type=unique_ref&with_history=true HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "uuid": "b3d5e8f1-2c4a-4e6b-9d8f-1a2b3c4d5e6f",
  "reference": "AGREEMENT-2024-0001",
  "customer_reference": "CUST-000123",
  "purpose": "loan",
  "description": "Weekly loan repayment",
  "status": "active",
  "payment_term_type": "fixed",
  "frequency": "weekly",
  "amount": 10000,
  "account_type": "bban",
  "bsb": "062000",
  "account_number": "123456789",
  "created": "2024-05-20T09:15:00",
  "amendments": []
}

Returns the details of a single agreement. By default the agreement is looked up by its uuid. Pass with_history=true to include the agreement's amendment history in an amendments array.

HTTP Endpoint

GET /v2/pay-to/agreements/{id}

Parameters

Field Rules Notes
id_type optional unique_ref By default the {id} in the path is treated as the agreement uuid. Set id_type=unique_ref to look up by your own reference instead.
with_history optional boolean When true, includes the agreement's amendments in the response.

Suspend an agreement

Example request

POST /v2/pay-to/agreements/AGREEMENT-2024-0001/suspend HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "reason": "customer_requested"
}

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "reference": "AGREEMENT-2024-0001",
  "status": "pending"
}

Requests suspension of an active agreement. Suspension is processed asynchronously by the payment platform; the response returns a pending status. Subscribe to webhooks to be notified when the suspension is applied.

HTTP Endpoint

POST /v2/pay-to/agreements/{reference}/suspend

Parameters

Field Rules Notes
reason required The reason for suspending the agreement. See Suspension and cancellation reasons.

Reactivate an agreement

Example request

POST /v2/pay-to/agreements/AGREEMENT-2024-0001/reactivate HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{}

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "reference": "AGREEMENT-2024-0001",
  "status": "pending"
}

Reactivates a previously suspended agreement. Reactivation is processed asynchronously; the response returns a pending status.

HTTP Endpoint

POST /v2/pay-to/agreements/{reference}/reactivate

Cancel an agreement

Example request

DELETE /v2/pay-to/agreements/AGREEMENT-2024-0001 HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "reason": "contract_expired"
}

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "reference": "AGREEMENT-2024-0001",
  "status": "pending"
}

Cancels an agreement. Cancellation is permanent and cannot be reversed. Cancellation is processed asynchronously; the response returns a pending status.

HTTP Endpoint

DELETE /v2/pay-to/agreements/{reference}

Parameters

Field Rules Notes
reason required The reason for cancelling the agreement. See Suspension and cancellation reasons.

Suspension and cancellation reasons

The reason supplied when suspending or cancelling an agreement must be one of the following:

Reason Reason Reason
invalid_debtor_account_number closed_account_number closed_debtor_account_number
blocked_account invalid_debtor_account_type transaction_forbidden
transaction_not_supported not_allowed_currency not_allowed_amount
amount_exceeds_agreed_limit customer_deceased no_mandate_service_agent
no_mandate_service_customer customer_requested initiating_party_requested
mandate_expired suspected_fraudulent no_reason_customer
no_reason_agent narrative regulatory
no_service_debtor creditor_not_whitelisted_by_debtor creditor_blacklisted_by_debtor
contract_amended debtor_cancellation_requested contract_expired
mandate_suspended_final_collection mandate_suspended_one_collection mandate_suspended_failed_collections
no_answer

PayTo Agreement Modifications

You may modify the terms of an existing active agreement by creating an amendment. An amendment proposes a new set of terms (amount, frequency, dates, etc.) which the customer must authorise in their banking app, just as they did for the original agreement.

An agreement can have only one pending amendment at a time — recall the current one before proposing another. While an amendment is awaiting authorisation you may recall it. An agreement retains a full history of its amendments, which you can retrieve via Get a single agreement with with_history=true.

Amendment properties

Field Description
uuid A unique identifier for the amendment, allocated by Squarepay.
reference The reference of the agreement being amended.
customer_reference Your unique identifier for the customer.
type The type of record. See Amendment type.
status The current status of the amendment. See Amendment status.
amended_by Who initiated the amendment. See Amended by.
description A human readable description of the amendment, shown to the customer.
end_date The proposed new expiry date. Date format yyyy-mm-dd.
payment_term_type The proposed payment term type.
frequency The proposed frequency.
amount The proposed payment amount in cents.
count The proposed total number of payments.
first_payment_amount The proposed first payment amount in cents (balloon only).
last_payment_amount The proposed final payment amount in cents (balloon only).
max_amount The proposed maximum per-payment amount in cents (variable/usage only).
first_payment_date The proposed first payment date. Date format yyyy-mm-dd.
last_payment_date The proposed final payment date. Date format yyyy-mm-dd.
response_required_by The deadline by which the customer must authorise the amendment. Date format yyyy-mm-ddTHH:MM:SS.
created_at The date and time the amendment was created. Date format yyyy-mm-ddTHH:MM:SS.

Amendment type

Type Description
original The original terms of the agreement, retained in history when an amendment is applied.
amendment A proposed change to the agreement's terms.

Amendment status

Status Description
created The amendment has been proposed and is awaiting the customer's authorisation.
amended The customer authorised the amendment and its terms are now in effect.
declined The customer declined the amendment. The original terms remain in effect.
expired The customer did not authorise the amendment before response_required_by.
recalled You recalled the amendment before it was authorised.
recall_failed A recall was requested but could not be applied.
previous A superseded set of terms retained in the agreement's history.

Amended by

Value Description
initiator The amendment was initiated by you (the initiator).
customer The amendment was initiated by the customer.
payment_processor The amendment was initiated by the payment processor.

Create an amendment

Example request

POST /v2/pay-to/agreements/AGREEMENT-2024-0001/amend HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "description": "Increase weekly repayment",
  "payment_term_type": "fixed",
  "frequency": "weekly",
  "amount": 15000,
  "end_date": "2025-06-01"
}

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "uuid": "9f2c1a7b-6d4e-4c3a-8b1f-2e5d6c7a8b90",
  "reference": "AGREEMENT-2024-0001",
  "customer_reference": "CUST-000123",
  "type": "amendment",
  "status": "created",
  "amended_by": "initiator",
  "description": "Increase weekly repayment",
  "end_date": "2025-06-01T00:00:00",
  "payment_term_type": "fixed",
  "frequency": "weekly",
  "amount": 15000,
  "count": null,
  "first_payment_amount": null,
  "last_payment_amount": null,
  "max_amount": null,
  "first_payment_date": null,
  "last_payment_date": null,
  "response_required_by": null,
  "created_at": "2024-07-01T11:30:00"
}

Proposes an amendment to an active agreement. The amendment is created in the created status and is sent to the customer to authorise. Subscribe to webhooks to be notified of the outcome.

The same amount/term-type rules described under Payment term types apply to amendments. An amendment cannot change the agreement's purpose or start date — those are fixed for the life of the agreement. The agreement must be active — amending an agreement in any other status returns a validation error ("Agreement is not active").

HTTP Endpoint

POST /v2/pay-to/agreements/{reference}/amend

Parameters

Field Rules Notes
description required max 256 chars ASCII only. Shown to the customer when authorising the amendment.
response_required_by optional The deadline for the customer to authorise the amendment. Date format yyyy-mm-ddTHH:MM:SS.
end_date optional The proposed new expiry date. Must be in the future. Date format yyyy-mm-dd.
payment_term_type required See Payment term types.
frequency required See Frequency.
amount See term types The proposed payment amount in cents (e.g. $100.00 = 10000).
count optional integer min 1 The proposed total number of payments.
first_payment_amount balloon only The proposed first payment amount in cents (e.g. $100.00 = 10000).
last_payment_amount balloon only The proposed final payment amount in cents (e.g. $100.00 = 10000).
max_amount variable, usage only The proposed maximum per-payment amount in cents (e.g. $100.00 = 10000).
first_payment_date optional The proposed first payment date. Must be in the future and before last_payment_date/end_date. Date format yyyy-mm-dd.
last_payment_date optional The proposed final payment date. Must be in the future and after first_payment_date. Date format yyyy-mm-dd.

Get an amendment

Example request

GET /v2/pay-to/agreements/amendment/9f2c1a7b-6d4e-4c3a-8b1f-2e5d6c7a8b90 HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "uuid": "9f2c1a7b-6d4e-4c3a-8b1f-2e5d6c7a8b90",
  "reference": "AGREEMENT-2024-0001",
  "customer_reference": "CUST-000123",
  "type": "amendment",
  "status": "created",
  "amended_by": "initiator",
  "description": "Increase weekly repayment",
  "end_date": "2025-06-01T00:00:00",
  "payment_term_type": "fixed",
  "frequency": "weekly",
  "amount": 15000,
  "created_at": "2024-07-01T11:30:00"
}

Returns the details of a single amendment by its uuid.

HTTP Endpoint

GET /v2/pay-to/agreements/amendment/{uuid}

Recall an amendment

Example request

DELETE /v2/pay-to/agreements/amendment/9f2c1a7b-6d4e-4c3a-8b1f-2e5d6c7a8b90/recall HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "uuid": "9f2c1a7b-6d4e-4c3a-8b1f-2e5d6c7a8b90",
  "reference": "AGREEMENT-2024-0001",
  "customer_reference": "CUST-000123",
  "type": "amendment",
  "status": "recalled",
  "amended_by": "initiator",
  "description": "Increase weekly repayment",
  "payment_term_type": "fixed",
  "frequency": "weekly",
  "amount": 15000,
  "created_at": "2024-07-01T11:30:00"
}

Recalls (withdraws) an amendment that is still awaiting the customer's authorisation. Once recalled, the original agreement terms remain in effect. Because an agreement can have only one pending amendment at a time, recall the current one before proposing a replacement.

HTTP Endpoint

DELETE /v2/pay-to/agreements/amendment/{uuid}/recall

PayTo Payments

Once a PayTo agreement is active you may initiate payments against it. A PayTo Payment debits the customer's account in near real-time over the NPP, within the terms authorised by the agreement.

Payments are processed asynchronously. The create response returns the payment in its initial status; subscribe to webhooks to track it through to a terminal status (cleared, rejected or returned).

PayTo payment properties

Field Description
uuid A unique identifier for the payment, allocated by Squarepay.
reference Your unique reference for the payment, supplied at creation.
status The current status of the payment. See Payment status.
amount The payment amount in cents.
fee The processing fee for the payment in cents.
description The statement narrative for the payment.
agreement_uuid The uuid of the agreement the payment was made against.
priority The payment priority. See Payment priority.
payment_date The date the payment is scheduled to be processed. Date format yyyy-mm-ddTHH:MM:SS.

Payment status

Status Description
scheduled The payment has been scheduled and is awaiting its processing date.
processing The payment has been submitted to the payment platform.
under_investigation The payment is being investigated by the payment platform.
cleared The payment settled successfully. Terminal.
rejected The payment was rejected (e.g. insufficient funds). Terminal.
returned The payment was returned after settlement. Terminal.

Payment priority

Priority Description
attended The customer is present and waiting — e.g. an e-commerce checkout. Prioritised for real-time execution.
unattended The customer is not present — e.g. a scheduled loan collection or recurring debit. Lower priority than attended.

Create a PayTo payment

Example request

POST /v2/pay-to/payments HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "reference": "PAYMENT-2024-0001",
  "agreement_uuid": "b3d5e8f1-2c4a-4e6b-9d8f-1a2b3c4d5e6f",
  "amount": 10000,
  "priority": "unattended",
  "statement_reference": "LOAN-0001",
  "statement_description": "Weekly loan repayment",
  "payment_date": "2024-06-08"
}

Example response

HTTP/1.1 201 (Created)
Content-Type: application/json

{
  "uuid": "c4e6f9a2-3b5c-4d7e-9f0a-1b2c3d4e5f60",
  "reference": "PAYMENT-2024-0001",
  "status": "scheduled",
  "amount": 10000,
  "fee": 200,
  "description": "Weekly loan repayment",
  "agreement_uuid": "b3d5e8f1-2c4a-4e6b-9d8f-1a2b3c4d5e6f",
  "priority": "unattended",
  "payment_date": "2024-06-08T00:00:00"
}

Creates a payment against an active agreement.

The requested amount is validated against the agreement's terms:

HTTP Endpoint

POST /v2/pay-to/payments

Parameters

Field Rules Notes
reference required max 255 chars Your unique reference for this payment. Must be unique across your payments.
agreement_uuid required max 64 chars The uuid of an existing active agreement to debit against.
amount required integer The amount to debit in cents (e.g. $100.00 = 10000). Minimum 1 cent, maximum your configured PayTo limit. Must satisfy the agreement's terms (see above).
priority required See Payment priority.
statement_reference optional max 35 chars Short reference for reconciliation; typically appears on both parties' bank statements. May be overridden by a debtor-controlled agreement reference.
statement_description optional max 280 chars Longer free-form narrative, also shown on statements.
last_payment optional boolean Indicates this is the final payment of the agreement. Required for balloon agreements' final payment.
payment_date optional The date to process the payment. Must be no earlier than 14 days ago. Defaults to now. Date format yyyy-mm-dd or yyyy-mm-ddTHH:MM:SS.

Retry a PayTo payment

Example request

POST /v2/pay-to/payments/retry HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "reference": "PAYMENT-2024-0001"
}

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "uuid": "c4e6f9a2-3b5c-4d7e-9f0a-1b2c3d4e5f60",
  "reference": "PAYMENT-2024-0001",
  "status": "processing",
  "amount": 10000,
  "fee": 200,
  "description": "Weekly loan repayment",
  "agreement_uuid": "b3d5e8f1-2c4a-4e6b-9d8f-1a2b3c4d5e6f",
  "priority": "unattended",
  "payment_date": "2024-06-08T00:00:00"
}

Retries a previously failed payment, identified by its reference. The payment is resubmitted against the same agreement.

HTTP Endpoint

POST /v2/pay-to/payments/retry

Parameters

Field Rules Notes
reference required max 255 chars The reference of an existing payment to retry.

Create a one-off payment

Example request

POST /v2/pay-to/payments/one-off HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "customer_reference": "CUST-000123",
  "payment_reference": "PAYMENT-ONEOFF-0001",
  "purpose": "retail",
  "description": "Once-off purchase",
  "last_name": "Bob",
  "first_name": "Billy",
  "amount": 4999,
  "priority": "attended",
  "account_type": "bban",
  "bsb": "062000",
  "account_number": "123456789"
}

Example response

HTTP/1.1 201 (Created)
Content-Type: application/json

{
  "uuid": "d5f70ab3-4c6d-4e8f-a012-2c3d4e5f6071",
  "reference": "PAYMENT-ONEOFF-0001",
  "status": "scheduled",
  "amount": 4999,
  "fee": 200,
  "description": "Once-off purchase",
  "agreement_uuid": "e6081bc4-5d7e-4f90-b123-3d4e5f607182",
  "priority": "attended",
  "payment_date": "2024-06-01T00:00:00"
}

Creates a single payment without first setting up a long-lived agreement. Behind the scenes this establishes a fixed, adhoc agreement for the customer and immediately creates one payment against it. The customer still authorises the underlying agreement in their banking app.

Use this for one-time charges where an ongoing agreement is not required.

HTTP Endpoint

POST /v2/pay-to/payments/one-off

Parameters

Field Rules Notes
customer_reference required max 50 chars Your unique identifier for the customer. Also used as the reference for the underlying agreement.
payment_reference required max 64 chars Your unique reference for the payment.
purpose required See Agreement purpose.
description required max 256 chars Shown to the customer when authorising. Sets the underlying agreement's description; the bank-statement narrative comes from statement_description.
first_name optional max 256 chars Leave blank for a business.
last_name required max 256 chars Enter the entity name here for a business.
amount required integer The amount to debit in cents (e.g. $100.00 = 10000). Minimum 1 cent, maximum your configured PayTo limit.
priority required See Payment priority.
response_required_by optional The deadline for the customer to authorise. Date format yyyy-mm-ddTHH:MM:SS.
account_type required See Account type.
bsb required for bban The customer's BSB. BSB format 062000. Excluded for PayID types.
account_number required for bban max 9 digits. Excluded for PayID types.
pay_id required for PayID types The customer's PayID. Excluded for bban.
statement_reference optional max 64 chars Reference text that appears on the customer's bank statement.
statement_description optional Longer-form narrative for the payment.
payment_date optional The date to process the payment. Must be no earlier than 14 days ago. Defaults to now. Date format yyyy-mm-dd.

List PayTo payments

Example request

GET /v2/pay-to/payments?agreement_uuid=b3d5e8f1-2c4a-4e6b-9d8f-1a2b3c4d5e6f&status=cleared&per_page=50 HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "page": 1,
  "total": 1,
  "last_page": 1,
  "per_page": 50,
  "data": [{
    "uuid": "c4e6f9a2-3b5c-4d7e-9f0a-1b2c3d4e5f60",
    "reference": "PAYMENT-2024-0001",
    "status": "cleared",
    "amount": 10000,
    "fee": 200,
    "description": "Weekly loan repayment",
    "agreement_uuid": "b3d5e8f1-2c4a-4e6b-9d8f-1a2b3c4d5e6f",
    "priority": "unattended",
    "payment_date": "2024-06-08T00:00:00"
  }]
}

Returns a paginated list of your PayTo payments matching the supplied filters. All filters are optional and may be combined.

HTTP Endpoint

GET /v2/pay-to/payments

Parameters

Field Rules Notes
reference optional max 255 chars Filter by a payment's reference.
agreement_uuid optional max 64 chars Only payments under the agreement with this uuid.
agreement_reference optional max 255 chars Only payments under the agreement with this reference.
customer_reference optional max 64 chars Only payments for the customer with this reference.
status optional Filter by payment status.
priority optional Filter by payment priority.
created_on optional Payments created on this date. Date format yyyy-mm-dd.
created_after optional Payments created on or after this date (inclusive). Date format yyyy-mm-dd.
created_before optional Payments created on or before this date (inclusive). Date format yyyy-mm-dd.
page optional Index pointing to the start of the desired set, first page is 1. Page defaults to 1.
per_page optional Number of records to return, defaults to 100. Maximum 1000.

Get a PayTo payment

Example request - using uuid (default)

GET /v2/pay-to/payments/c4e6f9a2-3b5c-4d7e-9f0a-1b2c3d4e5f60 HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example request - using your reference

GET /v2/pay-to/payments/PAYMENT-2024-0001?id_type=unique_ref HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "uuid": "c4e6f9a2-3b5c-4d7e-9f0a-1b2c3d4e5f60",
  "reference": "PAYMENT-2024-0001",
  "status": "cleared",
  "amount": 10000,
  "fee": 200,
  "description": "Weekly loan repayment",
  "agreement_uuid": "b3d5e8f1-2c4a-4e6b-9d8f-1a2b3c4d5e6f",
  "priority": "unattended",
  "payment_date": "2024-06-08T00:00:00"
}

Returns the details of a single PayTo payment. By default the {id} in the path is the payment uuid; pass id_type=unique_ref to look it up by your own payment reference instead. Returns 404 if no PayTo payment matches the identifier.

HTTP Endpoint

GET /v2/pay-to/payments/{id}

Parameters

Field Rules Notes
id_type optional unique_ref By default the {id} in the path is treated as the payment uuid. Set id_type=unique_ref to look up by your own payment reference.

PayTo Sandbox Simulation

In the real world, PayTo agreements and payments depend on the customer authorising them in their banking app and on the response of the customer's financial institution. In the Sandbox environment there is no real customer or bank, so Squarepay lets you simulate these outcomes directly.

Simulation is driven by adding a sandbox_outcome field to the request body of the normal create/amend/pay endpoints. There is no separate simulation endpoint — you simply include the parameter on the call you are already making.

How it works

Add sandbox_outcome to the body of any of the following requests to control what the simulated customer / bank does:

The simulated outcome is applied asynchronously and delivered via webhooks, mirroring how real outcomes are reported.

Field Rules Notes
sandbox_outcome optional The outcome to simulate. See Agreement outcomes and Payment outcomes. Sandbox only.
simulated_delay optional integer A delay in seconds before the simulated outcome is applied — supported on agreements, amendments and payments. For payments, a delay greater than 35 seconds causes the payment to transition through processing before reaching its final state. Sandbox only.

Simulating agreement outcomes

Example - simulate the customer accepting an agreement

POST /v2/pay-to/agreements HTTP/1.1
Host: api-sandbox.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "reference": "AGREEMENT-2024-0001",
  "customer_reference": "CUST-000123",
  "purpose": "loan",
  "description": "Weekly loan repayment",
  "last_name": "Bob",
  "first_name": "Billy",
  "payment_term_type": "fixed",
  "frequency": "weekly",
  "amount": 10000,
  "account_type": "bban",
  "bsb": "062000",
  "account_number": "123456789",
  "sandbox_outcome": "debtor_accept"
}

Example - simulate the customer declining, after a delay

POST /v2/pay-to/agreements HTTP/1.1
Host: api-sandbox.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "reference": "AGREEMENT-2024-0002",
  "customer_reference": "CUST-000123",
  "purpose": "loan",
  "description": "Weekly loan repayment",
  "last_name": "Bob",
  "payment_term_type": "fixed",
  "frequency": "weekly",
  "amount": 10000,
  "account_type": "bban",
  "bsb": "062000",
  "account_number": "123456789",
  "sandbox_outcome": "debtor_decline",
  "simulated_delay": 60
}

The sandbox_outcome values below may be used when creating an agreement or an amendment.

Agreement outcomes

Outcome Simulated result
debtor_accept The customer authorises the agreement/amendment. The agreement becomes active (or the amendment is amended).
debtor_decline The customer declines the agreement/amendment. The agreement becomes declined (or the amendment is declined).
expire The customer does not respond and the agreement/amendment expires.
debtor_account_type_not_supported The customer's account type is not supported for PayTo.
debtor_account_closed The customer's account is closed.
debtor_alias_not_found The customer's PayID could not be resolved.
creditor_account_type_not_supported The creditor account type is not supported for PayTo.
creditor_account_closed The creditor account is closed.
creditor_alias_not_found The creditor PayID could not be resolved.
alias_resolution_service_unavailable The PayID resolution service is unavailable.
agreement_service_unavailable The agreement service is unavailable.
financial_infrastructure_unavailable The underlying financial infrastructure is unavailable.

Simulating payment outcomes

Example - simulate a payment settling successfully

POST /v2/pay-to/payments HTTP/1.1
Host: api-sandbox.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "reference": "PAYMENT-2024-0001",
  "agreement_uuid": "b3d5e8f1-2c4a-4e6b-9d8f-1a2b3c4d5e6f",
  "amount": 10000,
  "priority": "unattended",
  "sandbox_outcome": "auto_settle"
}

Example - simulate insufficient funds after a delay

POST /v2/pay-to/payments HTTP/1.1
Host: api-sandbox.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "reference": "PAYMENT-2024-0002",
  "agreement_uuid": "b3d5e8f1-2c4a-4e6b-9d8f-1a2b3c4d5e6f",
  "amount": 10000,
  "priority": "unattended",
  "sandbox_outcome": "insufficient_funds",
  "simulated_delay": 45
}

The sandbox_outcome values below may be used when creating a payment or a one-off payment. If no outcome is supplied, a payment defaults to auto_settle.

Payment outcomes

Outcome Simulated result
auto_settle The payment settles successfully. The payment becomes cleared. (Default)
insufficient_funds The payment fails due to insufficient funds. The payment becomes rejected.
requires_investigation The payment is held for investigation. The payment becomes under_investigation.
investigate_and_settle The payment is investigated and then settles. Ends as cleared.
investigate_and_fail The payment is investigated and then fails. Ends as rejected.

Refunds

Certain rules apply to the issuance of a refund:

Refund properties

Field Description
receivable_id Unique receivable identifier found in a receivable
bank_account_id Your float account id.
amount The amount to be refunded. Displayed in dollars (decimal).
refund_date The date the refund was processed. Date format yyyy-mm-ddTHH:MM:SS.
description This description is visible to both the payer and recipient, with the payout recipient seeing the first 9 characters for Direct Entry transactions and the first 280 characters for NPP transactions.
rails Specifies whether to use DE (Direct Entry) or NPP (New Payments Platform) or both. First specified rail in the list will be prioristised.
current_rails Indicates the final rails used to perform the refund. DE or NPP.
unique_ref Your unique reference to prevent duplicate transactions and is strongly recommended. This is a nonce.

Issue a refund

Example request

POST /v1/refunds HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "receivable_id" : "4cda1125-e13d-4432-99d1-a0ba3832b86c",
  "bank_account_id" : "d333d441-d312-4076-9776-74af5cb69333",
  "amount" : 9999,
  "description" : "Unknown Sender",
  "rails" : ["NPP", "DE"],
  "unique_ref" : "52189a11-6dd2-46b7-9755-7ccc9eb5a87d"
}

Example response

HTTP/1.1 201 (Created)
Content-Type: application/json

{
  "data" : {
    "refund_id" : "b7a7bdc3-43d4-4b7b-a5bb-e64fb384e338",
    "bank_account_id" : "d333d441-d312-4076-9776-74af5cb69333",
    "amount" : "99.9900",
    "description" : "Unknown Sender",
    "rails" : ["NPP", "DE"],
    "current_rails" : "NPP",
    "refund_date" : "2021-04-28T14:32:46",
    "unique_ref" : "52189a11-6dd2-46b7-9755-7ccc9eb5a87d",
    "receivable": {
      "receivable_id" : "4cda1125-e13d-4432-99d1-a0ba3832b86c",
      "payid_id" : "99acde49-0065-4f13-a935-67632a0bf99c",
      "customer_id" : 1337,
      "bank_account_id" : "d333d441-d312-4076-9776-74af5cb69333",
      "system_ref" : "MEM000001337",
      "general_ref" : "BillyBob201605012330",
      "last_name" : "Bob",
      "first_name" : "Billy",
      "payid_type" : "EMAIL",
      "payid_value" : "billy.bob@mydomain.com.au",
      "alias_name" : "My Alias",
      "to_bsb" : "802918",
      "to_account_number" : "1820321",
      "payment_date" : "2021-04-27T11:21:28",
      "payment_amount" : "99.9900",
      "from_bsb" : "062000",
      "from_account_number" : "123456789",
      "description" : "My Description",
      "reference" : "My Reference",
      "from_name" : "Billy Bob",
      "from_legal_name" : "Billy James Bob",
      "receivable_status" : "SUCCESSFUL"
    }
  }
}

Creates a refund against an existing transaction identified by receivable_id.

HTTP Endpoint

POST /v1/refunds

Parameters

Field Rules Notes
unique_ref optional max 255 chars This is a unique reference to prevent duplicate transactions and is strongly recommended. This is a nonce.
bank_account_id optional Your float account bank_account_id. Will default to your primary account.
receivable_id required max 36 chars Unique receivable identifier of a receivable
amount required integer The amount to be refunded from your Squarepay float account. Submit in cents. e.g. $100.00 = 10000
description required max 280 chars This description is visible to both the payer and recipient, with the payout recipient seeing the first 9 characters for Direct Entry transactions and the first 280 characters for NPP transactions.
rails required array The payment rails to be used, in order. (NPP, DE or both).

List refunds

Example request

GET /v1/refunds?on=2021-04-28 HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "data" : [{
    "refund_id" : "b7a7bdc3-43d4-4b7b-a5bb-e64fb384e338",
    "bank_account_id" : "d333d441-d312-4076-9776-74af5cb69333",
    "amount" : "99.9900",
    "description" : "Unknown Sender",
    "rails" : ["NPP", "DE"],
    "current_rails" : "NPP",
    "refund_date" : "2021-04-28T14:32:46",
    "unique_ref" : "52189a11-6dd2-46b7-9755-7ccc9eb5a87d",
    "receivable": {
      "receivable_id" : "4cda1125-e13d-4432-99d1-a0ba3832b86c",
      "payid_id" : "99acde49-0065-4f13-a935-67632a0bf99c",
      "customer_id" : 1337,
      "bank_account_id" : "d333d441-d312-4076-9776-74af5cb69333",
      "system_ref" : "MEM000001337",
      "general_ref" : "BillyBob201605012330",
      "last_name" : "Bob",
      "first_name" : "Billy",
      "payid_type" : "EMAIL",
      "payid_value" : "billy.bob@mydomain.com.au",
      "alias_name" : "My Alias",
      "to_bsb" : "802918",
      "to_account_number" : "1820321",
      "payment_date" : "2021-04-27T11:21:28",
      "payment_amount" : "99.9900",
      "from_bsb" : "062000",
      "from_account_number" : "123456789",
      "description" : "My Description",
      "reference" : "My Reference",
      "from_name" : "Billy Bob",
      "from_legal_name" : "Billy James Bob",
      "receivable_status" : "REFUNDED"
    }
  },
  {
    "refund_id" : "7dfacca2-e97d-498b-94d9-18bde9b3189e",
    "bank_account_id" : "d333d441-d312-4076-9776-74af5cb69333",
    "amount" : "3141.5900",
    "description" : "Changed mind",
    "rails" : ["NPP", "DE"],
    "current_rails" : "NPP",
    "refund_date" : "2021-04-28T15:53:21",
    "unique_ref" : "361f5d5c-73c1-4c75-91a6-483c553a9d82",
    "receivable": {
      "receivable_id" : "3a16240a-0e9a-454c-9219-304a7cfa4e76",
      "payid_id" : "2ed89979-6ee9-447d-89da-e0e5f170a3ee",
      "customer_id" : 4882,
      "bank_account_id" : "d333d441-d312-4076-9776-74af5cb69333",
      "system_ref" : "MEM000004882",
      "general_ref" : "DonaldDuck202104230730",
      "last_name" : "Duck",
      "first_name" : "Donald",
      "payid_type" : "EMAIL",
      "payid_value" : "donald.duck@mydomain.com.au",
      "alias_name" : "My Alias",
      "bsb" : "802918",
      "account_number" : "1824245",
      "payment_date" : "2021-04-23T08:58:37",
      "payment_amount" : "3141.5900",
      "from_bsb" : "062000",
      "from_account_number" : "123456789",
      "description" : "My Description",
      "reference" : "My Reference",
      "from_name" : "Donald Duck",
      "from_legal_name" : "Donald Fauntleroy Duck",
      "receivable_status" : "REFUNDED"
    }
  }]
}

Returns a list of your refunds for the given search parameters.

HTTP Endpoint

GET /v1/refunds

Parameters

Field Rules Notes
date_filter optional refund_date Required if after, before or on provided. Defaults to refund_date
after optional Filter refunds after a specified date_filter (inclusive). If after is provided then date_filter must be included in the request, Date format yyyy-mm-dd
before optional Filter refunds before a specified date_filter (inclusive). If before is provided then date_filter must be included in the request, Date format yyyy-mm-dd
on optional Filter refunds on the specified date_filter date. If on is provided then date_filter must be included in the request, Date format yyyy-mm-dd
description optional Search by your transaction reference exact match.
order_by optional refund_date Defaults to refund_date
order optional ASC, DESC Defaults to ASC.
page optional Index pointing to the start of the desired set, first page is 1. Page defaults to 1.
limit optional Number of records to return, defaults to 100.

Get a single refund

Example request - using refund_id

GET /v1/refunds/b7a7bdc3-43d4-4b7b-a5bb-e64fb384e338?id_type=refund_id HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example request - using description

GET /v1/refunds/Unknown%20Sender?id_type=description HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example request - using unique_ref

GET /v1/refunds/52189a11-6dd2-46b7-9755-7ccc9eb5a87d?id_type=unique_ref HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "data" : {
    "refund_id" : "b7a7bdc3-43d4-4b7b-a5bb-e64fb384e338",
    "bank_account_id" : "d333d441-d312-4076-9776-74af5cb69333",
    "amount" : "99.9900",
    "description" : "Unknown Sender",
    "rails" : ["NPP", "DE"],
    "current_rails" : "NPP",
    "refund_date" : "2021-04-28T14:32:46",
    "unique_ref" : "52189a11-6dd2-46b7-9755-7ccc9eb5a87d",
    "receivable": {
      "receivable_id" : "4cda1125-e13d-4432-99d1-a0ba3832b86c",
      "payid_id" : "99acde49-0065-4f13-a935-67632a0bf99c",
      "customer_id" : 1337,
      "bank_account_id" : "d333d441-d312-4076-9776-74af5cb69333",
      "system_ref" : "MEM000001337",
      "general_ref" : "BillyBob201605012330",
      "last_name" : "Bob",
      "first_name" : "Billy",
      "payid_type" : "EMAIL",
      "payid_value" : "billy.bob@mydomain.com.au",
      "alias_name" : "My Alias",
      "to_bsb" : "802918",
      "to_account_number" : "1820321",
      "payment_date" : "2021-04-27T11:21:28",
      "payment_amount" : "99.9900",
      "from_bsb" : "062000",
      "from_account_number" : "123456789",
      "description" : "My Description",
      "reference" : "My Reference",
      "from_name" : "Billy Bob",
      "from_legal_name" : "Billy James Bob",
      "receivable_status" : "SUCCESSFUL"
    }
  }
}

Return the details of an existing refund.

HTTP Endpoint

GET /v1/refunds/{id}

Parameters

Field Rules Notes
id_type optional description, refund_id, unique_ref Defaults to refund_id. However can also search by description or unique_ref, remember to url encode description in the uri path.

Webhook Subscriptions

Webhooks provide a way for your application to respond to real-time data. You can subscribe to any number of webhooks made available by the Squarepay system.

If your application is not ready to receive webhooks but you wish to understand how they works. You may use https://webhook.site to forward webhooks to, alternatively you may use a tool like https://ngrok.com/ to forward webhooks to your local development machine.

Webhook subscription properties

Field Description
webhook_subscription_id Unique account identifier.
url This is the API endpoint where the webhook notification will be delivered.
signature_secret The shared secret to be used in Webhook signing
events See Webhook event types for a complete list of events.
status The status of the webhook.

Webhook event types

Webhooks are formatted as <resource>.<action>, for example disbursement.cleared. Webhook payload formatting is resource dependent, a direct_debit will be formatted as a Payment, a disbursement as a Disbursement, a payto_agreement as a PayTo Agreement, a payto_payment as a PayTo Payment, etc...

Event Type Description
direct_debit.cleared A direct debit (Payment) has settled.
direct_debit.failed A direct debit (Payment) has failed.
disbursement.cleared A disbursement has settled.
disbursement.failed A disbursement has failed.
disbursement.change_rails The initial disbursement channel has failed and the disbursement has automatically switched to attempt the payment using the next available channel.
disbursement.cancelled A disbursement has been cancelled.
payid.activated A Pay ID has been activated.
payid.failed A Pay ID has failed to be activated.
payid.disabled A Pay ID has been disabled.
payid.deregistered A Pay ID has been registered.
payto_agreement.activated Customer has accepted the agreement.
payto_agreement.declined Customer has declined the agreement.
payto_agreement.expired The agreement has expired.
payto_agreement.failed The agreement has failed (FI error).
payto_agreement.cancelled The pending agreement has been cancelled before acceptance.
payto_agreement.cancellation_failed An agreement cancellation could not be applied.
payto_agreement.reactivated The agreement has been reactivated by the Customer.
payto_agreement.reactivation_failed An agreement reactivation could not be applied.
payto_agreement.suspended The agreement has been suspended by the Customer or Debtor.
payto_agreement.suspension_failed An agreement suspension could not be applied.
payto_agreement.amended The agreement has been amended by the Debtor.
payto_agreement.amendment_recalled A pending amendment has been recalled by the initiator.
payto_agreement.amendment_recall_failed An amendment recall could not be applied.
payto_agreement.amendment_declined The customer declined the amendment; the original terms remain in effect.
payto_agreement.amendment_expired The amendment was not authorised before its deadline and has expired.
payto_payment.cleared A payto payment has settled.
payto_payment.failed A payto payment has failed.
payto_payment.under_investigation A payto payment is being manually reviewed.
receivable.cleared A receivable payment has settled to a Pay ID destination.
topup.cleared A top-up has been received to the float account.

Webhook delivery guarantees

Webhooks can fail to be sent due to a number of reasons, such as:

We will try to deliver a webhook for up to 1 hour every 5 minutes. In sandbox webhooks will only be retried once.

Webhook signing

When a webhook subscription is created a shared secret will be generated to be used to sign the webhook to verify the authenticity. It is important that the shared secret is remains a secret and stored securely. Each created webhook subscription has a unique secret.

To assist with the signature verification we provide two headers in the request, X-Signature-SHA256 and X-Signature-Timestamp. The X-Signature-Timestamp is a unix timestamp and the X-Signature-SHA256 is the result of calculating a HMAC of the raw body and timestamp concatenated using the SHA-256 hash function and secret.

A webhook may be validated following the process below:

1. Extract the signature and timestamp

Extract both the signature (X-Signature-SHA256) the base64 encoded hmac and timestamp (X-Signature-Timestamp) unix timestamp from the http request headers.

2. Extract the payload Construct the signed payload literal**

Extract the payload (raw JSON request body) from the http request.

3. Construct the signed_payload string

Concatenate the following:

For example if the timestamp was 1626226200 and the payload was {"data":{"some_key":"some_payload"}} then the resulting signed_payload string will be 1626226200.{"data":{"some_key":"some_payload"}}.

4. Compute the expected_signature

Compute a HMAC using the SHA256 hash function using your secret and the signed_payload, the resulting hash may need to be converted to a base64 encoded string.

The following inputs (secret, signed_payload) can be used to compute the expected output (expected_signature)

Input Type Value
secret input some-super-secret
signed_payload input 1626226200.{"data":{"some_key":"some_payload"}}
expected_signature output LfqR8ybCT0ZIINMMZVc2KBfei8t3JXnGzu8f+3suvSw=

5. Compare signature

Compare both the extracted signature from the headers and the calculated expected_signature. If they are a match the webhook is considered verified.

Create webhook subscription

Example request

POST /v1/webhook_subscriptions HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "url" : "https://webhook.site/some-uuid",
  "events": [
    "disbursement.cleared",
    "disbursement.failed"
  ]
}

Example response

HTTP/1.1 201 (Created)
Content-Type: application/json

{
  "data" : {
    "webhook_subscription_id" : "7e9f4299-6049-4c11-abed-dcdb27102e33",
    "url" : "https://webhook.site/some-uuid",
    "signature_secret": "YpG4przYWpXqn7Q6pw16G2D47762UhF0LcLlBjn59oMDOh7SfujaV6EcgOd6merv",
    "events": [
      "disbursement.cleared",
      "disbursement.failed"
    ],
    "status": "ACTIVE"
  }
}

Creates a new webhook subscription and returns a signature secret. The signature secret can be used for Webhook signing verification.

HTTP Endpoint

POST /v1/webhook_subscriptions

Parameters

Field Rules Notes
url required max 512 chars This is the API endpoint where the webhook notification will be delivered.
events required array See Webhook event types for a complete list of events. One or more events may be subscribed to.

List webhook subscriptions

Example request

GET /v1/webhook_subscriptions HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "data" : [{
    "webhook_subscription_id" : "7e9f4299-6049-4c11-abed-dcdb27102e33",
    "url" : "https://webhook.site/some-uuid",
    "signature_secret": "YpG4przYWpXqn7Q6pw16G2D47762UhF0LcLlBjn59oMDOh7SfujaV6EcgOd6merv",
    "events": [
      "disbursement.cleared",
      "disbursement.failed"
    ],
    "status": "ACTIVE"
  },
  {
    "webhook_subscription_id" : "7e9f4299-6049-4c11-abed-dcdb27102e33",
    "url" : "https://webhook.site/some-uuid",
    "signature_secret": "YpG4przYWpXqn7Q6pw16G2D47762UhF0LcLlBjn59oMDOh7SfujaV6EcgOd6merv",
    "events": [
      "payto_agreement.activated",
      "payto_agreement.declined",
      "payto_agreement.expired",
      "payto_agreement.failed",
      "payto_agreement.cancelled",
      "payto_agreement.reactivated",
      "payto_agreement.suspended",
      "payto_agreement.amended",
      "payto_payment.cleared",
      "payto_payment.failed",
      "payto_payment.under_investigation"
    ],
    "status": "ACTIVE"
}

Returns a list of your disbursements for the given search parameters.

HTTP Endpoint

GET /v1/webhook_subscriptions

Update webhook subscription

Example request

PUT /v1/webhook_subscriptions/7e9f4299-6049-4c11-abed-dcdb27102e33 HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "url" : "https://webhook.site/some-other-uuid",
  "events": [
    "disbursement.cleared"
  ]
}

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "data" : {
    "webhook_subscription_id" : "7e9f4299-6049-4c11-abed-dcdb27102e33",
    "url" : "https://webhook.site/some-other-uuid",
    "signature_secret": "YpG4przYWpXqn7Q6pw16G2D47762UhF0LcLlBjn59oMDOh7SfujaV6EcgOd6merv",
    "events": [
      "disbursement.cleared"
    ],
    "status": "ACTIVE"
  }
}

Update an existing webhook subscription.

HTTP Endpoint

PUT /v1/webhook_subscriptions/{id}

Parameters

Field Rules Notes
url required max 512 chars This is the API endpoint where the webhook notification will be delivered.
events required array See Webhook event types for a complete list of events. One or more events may be subscribed to.

Delete webhook subscription

Example request

DELETE /v1/webhook_subscriptions/7e9f4299-6049-4c11-abed-dcdb27102e33 HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
}

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "data" : {
    "webhook_subscription_id" : "7e9f4299-6049-4c11-abed-dcdb27102e33",
    "url" : "https://webhook.site/some-other-uuid",
    "signature_secret": "YpG4przYWpXqn7Q6pw16G2D47762UhF0LcLlBjn59oMDOh7SfujaV6EcgOd6merv",
    "events": [],
    "status": "DELETED"
  }
}

Update an existing webhook subscription.

HTTP Endpoint

DELETE /v1/webhook_subscriptions/{id}

Webhooks

Squarepay will maintain a record of up to 7 days of webhooks events.

List webhooks

Example request

GET /v1/webhooks?payment_method=DR&date_filter=settlement_date&on=2016-04-11 HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "data" : [{
    "webhook_id" : "2b4288d1-ad24-4e02-8916-0f5694a40ff7",
    "webhook_subscription_id" : "7e9f4299-6049-4c11-abed-dcdb27102e33",
    "webhook_status" : "SUCCESSFUL",
    "response_status_code" : 200,
    "event_type" : "disbursement.cleared",
    "event_ref_id" : "05b10c39-0eb0-46c8-86c0-86f4c9d69374",
    "webhook_date" : "2016-04-11T06:00:00"
  }]
}

Returns a list of your payments for the given search parameters. These may be scheduled payments and payments already sent to the bank.

HTTP Endpoint

GET /v1/webhooks

Parameters

Field Rules Notes
webhook_subscription_id optional Search by webhook subscription id.
webhook_status optional ALL, PENDING, SUCCESSFUL, RETRYING, FAILED Search by webhook status. Defaults to ALL.
event_type optional string See Webhook event types for a complete list of options
event_ref_id optional Search by event_ref_id.
after optional Filter webhooks after a specified date_filter (inclusive). If after is provided then date_filter must be included in the request, Date format yyyy-mm-dd
before optional Filter webhooks before a specified date_filter (inclusive). If before is provided then date_filter must be included in the request, Date format yyyy-mm-dd
on optional Filter webhooks on the specified date_filter date. If on is provided then date_filter must be included in the request, Date format yyyy-mm-dd
page optional Index pointing to the start of the desired set, first page is 1. Page defaults to 1.
limit optional Number of records to return, defaults to 100.

Get a single webhook

Example request

GET /v1/webhooks/2b4288d1-ad24-4e02-8916-0f5694a40ff7 HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "data" : {
    "webhook_id" : "2b4288d1-ad24-4e02-8916-0f5694a40ff7",
    "webhook_subscription_id" : "7e9f4299-6049-4c11-abed-dcdb27102e33",
    "event_type" : "disbursement.cleared",
    "event_ref_id" : "05b10c39-0eb0-46c8-86c0-86f4c9d69374",
    "webhook_date" : "2016-04-11T06:00:00",
    "payload" : {
      "disbursement_id" : "05b10c39-0eb0-46c8-86c0-86f4c9d69374",
      "customer_id" : 1337,
      "bank_account_id" : "d333d441-d312-4076-9776-74af5cb69333",
      "system_ref" : "MEM000001337",
      "general_ref" : "BillyBob201605012330",
      "last_name" : "Bob",
      "first_name" : "Billy",
      "email_address" : "billybob@gmail.com",
      "mobile_number" : "0400000000",
      "description" : "Loan Settlement LOAN:230213",
      "amount" : "100.0000",
      "disbursement_date" : "2016-04-11T06:00:00",
      "cleared_date" : null,
      "bsb" : "111222",
      "account_number" : "123456789",
      "rails" : ["NPP", "DE"],
      "current_rails" : "NPP",
      "unique_ref" : "4f3b4342-2d1f-47e7-aea4-f7fc47ad6042",
      "status" : "WAITING",
      "bank_return_code" : 0,
      "bank_return_detail" : null,
      "bank_return_date" : null
    },
    "webhook_status" : "SUCCESSFUL",
    "response_status_code" : 200,
    "webhook_request_date" : "2016-04-11T06:00:01",
    "webhook_request_body" : "{\"data\":{\"webhook_id\":\"2b4288d1-ad24-4e02-8916-0f5694a40ff7\",\"webhook_subscription_id\":\"7e9f4299-6049-4c11-abed-dcdb27102e33\",\"webhook_status\":\"PENDING\",\"response_status_code\":200,\"event_type\":\"disbursement.cleared\",\"event_ref_id\":\"05b10c39-0eb0-46c8-86c0-86f4c9d69374\",\"webhook_date\":\"2016-04-11T06:00:00\",\"payload\":{\"data\":{\"webhook_id\":\"2b4288d1-ad24-4e02-8916-0f5694a40ff7\",\"event_type\":\"disbursement.cleared\",\"event_ref_id\":\"05b10c39-0eb0-46c8-86c0-86f4c9d69374\",\"payload\":{\"disbursement_id\":\"05b10c39-0eb0-46c8-86c0-86f4c9d69374\",\"bank_account_id\":\"d333d441-d312-4076-9776-74af5cb69333\",\"customer_id\":1337,\"first_name\":\"Billy\",\"last_name\":\"Bob\",\"system_ref\":\"MEM000001337\",\"general_ref\":\"BillyBob201605012330\",\"description\":\"Loan Settlement LOAN:230213\",\"amount\":\"100.0000\",\"disbursement_date\":\"2016-04-11T06:00:00\",\"rails\":[\"NPP\",\"DE\"],\"status\":\"SUCCESSFUL\"}}}}}"
    "webhook_request_headers" : {
      "Content-Type" : "application/json",
      "X-Signature-SHA256" : "LfqR8ybCT0ZIINMMZVc2KBfei8t3JXnGzu8f+3suvSw=",
      "X-Signature-Timestamp" : "1685865753"
    },
    "webhook_response_date" : "2016-04-11T06:00:02",
    "webhook_response_body" : "{\"success\":true}",
    "webhook_response_headers" : null
  }
}

Return the details of an existing disbursement.

HTTP Endpoint

GET /v1/webhooks/{id}

Resend a webhook

Example request

POST /v1/webhooks/{id}/action/resend HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{
  "data" : {
    "webhook_id" : "2b4288d1-ad24-4e02-8916-0f5694a40ff7",
    "webhook_subscription_id" : "7e9f4299-6049-4c11-abed-dcdb27102e33",
    "event_type" : "disbursement.cleared",
    "event_ref_id" : "05b10c39-0eb0-46c8-86c0-86f4c9d69374",
    "webhook_date" : "2016-04-11T06:00:00",
    "payload" : {
      "disbursement_id" : "05b10c39-0eb0-46c8-86c0-86f4c9d69374",
      "customer_id" : 1337,
      "bank_account_id" : "d333d441-d312-4076-9776-74af5cb69333",
      "system_ref" : "MEM000001337",
      "general_ref" : "BillyBob201605012330",
      "last_name" : "Bob",
      "first_name" : "Billy",
      "email_address" : "billybob@gmail.com",
      "mobile_number" : "0400000000",
      "description" : "Loan Settlement LOAN:230213",
      "amount" : "100.0000",
      "disbursement_date" : "2016-04-11T06:00:00",
      "cleared_date" : null,
      "bsb" : "111222",
      "account_number" : "123456789",
      "rails" : ["NPP", "DE"],
      "current_rails" : "NPP",
      "unique_ref" : "4f3b4342-2d1f-47e7-aea4-f7fc47ad6042",
      "status" : "WAITING",
      "bank_return_code" : 0,
      "bank_return_detail" : null,
      "bank_return_date" : null
    },
    "webhook_status" : "RETRYING",
    "response_status_code" : null,
    "webhook_request_date" : null,
    "webhook_request_body" : null
    "webhook_request_headers" : null,
    "webhook_response_date" : null,
    "webhook_response_body" : null,
    "webhook_response_headers" : null
  }
}

Resends a webhook. If a resending webhook fails, it will not be retried.

HTTP Endpoint

POST /v1/webhooks/{id}/action/resend

Simulation

Direct debit test accounts

The Sandbox environment allows mocking the payment result. For example if the bank account_number ends in '2' the payment will fail with a status of FATAL. If the bank account_number ends in '6' the payment will fail with a status of DISHONOURED. Any other number will be treated as a SUCCESSFUL payment. You may process payments in the Sandbox environment by clicking the Process button in the Tools section. Keep in mind in the real world payments will clear on T+2 and Failed payments will be notified on T+1 onwards.

Account Suffix Description
2 Mock FATAL Payment
6 Mock DISHONOURED Payment
* Anything else will mock a SUCCESSFUL Payment

Simulate direct debit processing

Example request

POST /v1/simulate/process_direct_debits HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{}

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{}

Simulates the processing of direct debits that would occur in the real world at the interchange times.

HTTP Endpoint

POST /v1/simulate/process_direct_debits

Simulate float topup

Example request

POST /v1/simulate/bank_float_topup HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "bank_account_id" : "d333d441-d312-4076-9776-74af5cb69333",
  "amount" : 10000
}

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{}

Simulates a real world transfer from your bank into the float account.

HTTP Endpoint

POST /v1/simulate/bank_float_topup

Parameters

Field Rules Notes
bank_account_id required The unique identifier for the float account returned from list bank accounts.
amount required int The amount to be transferred to the Squarepay float account. Submit in cents. e.g. $100.00 = 10000

Simulate inbound PayID payment

Example request

POST /v1/simulate/inbound_payid_payment HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "payid_email" : "billy.bob@mydomain.com.au",
  "amount" : 10000,
  "description": "Simulated PayID description",
  "reference": "Simulated PayID reference",
  "from_bsb" : "062000",
  "from_account_number" : "123456789",
  "from_name" : "Simulated Sender Name",
  "from_legal_name" : "Simulated Legal Sender Name"
}

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{}

Simulates a real world PayID payment from a sender.

HTTP Endpoint

POST /v1/simulate/inbound_payid_payment

Parameters

Field Rules Notes
payid_email required The unique identifier for the PayID account specified in Create PayID.
amount required int The amount to be paid. Submit in cents. e.g. $100.00 = 10000
description optional string The description to be sent with the payment.
reference optional string The reference to be sent with the payment.
from_bsb optional string The senders bsb for source of funds verification. BSB format 032000
from_account_number optional string The senders account number for source of funds verification.
from_name optional string The senders alias name for source of funds verification.
from_legal_name optional string The senders legal name for source of funds verification.

Simulate inbound NPP payment

Example request

POST /v1/simulate/inbound_npp_payment HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "to_bsb" : "802918",
  "to_account_number": "1820321",
  "amount" : 10000,
  "description": "Simulated PayID description",
  "reference": "Simulated PayID reference",
  "from_bsb" : "062000",
  "from_account_number" : "123456789",
  "from_name" : "Simulated Sender Name",
  "from_legal_name" : "Simulated Legal Sender Name"
}

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{}

Simulates a real world NPP payment from a sender.

HTTP Endpoint

POST /v1/simulate/inbound_npp_bban_payment

Parameters

Field Rules Notes
to_bsb required The destination bsb return from Create PayID.
to_account_number required The destination account number return from Create PayID.
amount required int The amount to be paid. Submit in cents. e.g. $100.00 = 10000
description optional string The description to be sent with the payment.
reference optional string The reference to be sent with the payment.
from_bsb optional string The senders bsb for source of funds verification. BSB format 032000
from_account_number optional string The senders account number for source of funds verification.
from_name optional string The senders alias name for source of funds verification.
from_legal_name optional string The senders legal name for source of funds verification.

Simulate inbound DE payment

Example request

POST /v1/simulate/inbound_de_payment HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

{
  "to_bsb" : "802918",
  "to_account_number": "1820321",
  "amount" : 10000,
  "reference": "Simulated Ref,
  "from_bsb" : "062000",
  "from_account_number" : "123456789",
  "from_name" : "Simulated Sender"
}

Example response

HTTP/1.1 200 (OK)
Content-Type: application/json

{}

Simulates a real world DE payment from a sender.

HTTP Endpoint

POST /v1/simulate/inbound_de_payment

Parameters

Field Rules Notes
to_bsb required The destination bsb return from Create PayID.
to_account_number required The destination account number return from Create PayID.
amount required int The amount to be paid. Submit in cents. e.g. $100.00 = 10000
reference optional max 18 chars The reference to be sent with the payment.
from_bsb optional string The senders bsb for source of funds verification. BSB format 032000
from_account_number optional string The senders account number for source of funds verification.
from_name optional max 16 chars The senders alias name for source of funds verification.

Disbursement testing (NPP Rails)

The Sandbox environment allows mocking the disbursement result. To simulate a disbursement failure, create a Disbursement with an amount corresponding to the desired NPP disbursement bank return code:

For example:

Disbursement testing (DE Rails)

The Sandbox environment allows mocking the disbursement result. To simulate a disbursement failure, create a Disbursement with an amount corresponding to the desired DE disbursement bank return code:

For example:

Interchange Times

Squarepay has access to the following interchange times. However we advise you submit your payments at least 15 minutes prior to interchange, this will provide a buffer for submission changes before it is too late.

Code Description
06:00 The first run for the day.
10:00
12:00
13:45
15:45
17:45
19:45 The last run for the day.

Do you require more infomation on these interchange times or future dated processing? Feel free to drop us an email support@squarepay.com.au.

Feature Request

Is there a feature you require? Feel free to drop us an email support@squarepay.com.au detailing your requirements and we will investigate integration options.

Errors

HTTP response codes

Code Description
200 OK. The request has succeeded.
201 OK. The request has succeeded and created a new resource.
400 Bad Request. The server cannot process the request, usually due to malformed syntax. Additional details can be found in the response body.
401 Unauthorised. The request did not contain a valid HTTP header to authenticate the user. Authentication is achieved via HTTP Basic Auth.
404 Not Found. The resource requested was not found or not available for the authenticated user.
405 Method Not Allowed. The HTTP verb used is not supported.
409 Conflict. The request could not be completed due to a conflict with the current state of the target resource. For example adding a payment to an inactive customer will cause this.
422 Unprocessable Entity. Could not process the request because the request was invalid. Additional details can be found in the response body.
426 Upgrade Required. An insecure protocol was used please use HTTPS.
429 Too Many Requests. The user has sent too many request in a given amount of time. Please let us know if you require these limits to be increased.
5xx Server Error. The server encountered an unexpected condition that prevent it from fulfilling the request. These should be rare and should be reported to Squarepay support team.

Error Response

Example request

POST /v1/unknown-endpoint HTTP/1.1
Host: api.squarepay.com.au
Authorization: Basic c3F1YXJlcGF5LWRpcmVjdC1kZWJpdHMtbWFkZS1zaW1wbGUhOg==
Content-Type: application/json

Example response

HTTP/1.1 404 (Not Found)
Content-Type: application/json



{
  "error" : {
    "code" : 404,
    "type" : "endpoint_not_found",
    "message" : "The requested endpoint was not found."
  }
}

When a request to the Squarepay API fails an error key will be included in the response. The error object will contain a code mapping to the HTTP response code, an error type detailed in the Error Types, and a short message explaining the error that occurred.

The error object may also contain an errors key. This is generally found when the type is validation_error, and will contain a list of field and message pairs describing why the field has failed validation.

Error Types

Below is a list of the various types of errors which can occur.

Usage errors

Example response - usage error

HTTP/1.1 400 (Bad Request)
Content-Type: application/json

{
  "error": {
    "code": 400,
    "type": "two_identifiers_provided",
    "message": "A value must be entered for customer_id or system_ref, but not both."
  }
}

These types of errors require the request to be modified before resubmitting.

Code Description
bad_request 400 - The request was malformed and could not be understood by the server.
method_not_allowed 405 - The request contained a HTTP verb that is not allowed. For example we strictly do not use PATCH requests.
rate_limit_exceeded 429 - Too many requests have been made to the Squarepay API within the past minute. Please let us know if you require these limits to be increased.
resource_not_found 404 - The resource requested was not found or not available for the authenticated user.
endpoint_not_found 404 - The request was made to an endpoint that does not exist, check the URL format and spelling correctly matches the API.
two_identifiers_provided 400 - The Squarepay API allows for using a unique reference provided by Squarepay or a unique reference your system may use system_ref. When identifying a resource we require either the system_ref or the customer_id to be supplied in the request, but not both.
unauthorised 401 - The API key provided was not recognised.
missing_authorisation_header 401 - The Authorization header was not set or not included in the request.
insecure_channel 426 - The request was made over an insecure channel. The Squarepay API can only be accessed using the TLS protocol, please send requests using https instead of http.

State errors

Example response - state error

HTTP/1.1 409 (Conflict)
Content-Type: application/json

{
  "error": {
    "code": 409,
    "type": "customer_not_active",
    "message": "The customer status was not set to Active."
  }
}

These types of errors are a result of the underlying resource not being in an appropriate state to perform the action. For example you cannot add a payment to an inactive customer, the customer must first be activated.

Code Description
customer_not_active 409 - The payment could not be created as the customer is not currently active. The customer will need to be activated before the request can be retried.
no_bank_payment_method 409 - The bank payment could not be created as the customer has no active bank account details. Valid bank account details will need to be added before a bank payment created.
payment_already_processed 409 - The payment has already been processed and cannot be altered.

Validation errors

Example response - validation error

HTTP/1.1 422 (Unprocessable Entity)
Content-Type: application/json

{
  "error": {
    "code": 422,
    "type": "validation_error",
    "message": "Validation Error.",
    "errors": [
      {
        "field": "account_holder_name",
        "message": "The account holder name field is required."
      },
      {
        "field": "account_number",
        "message": "The account number field is required."
      },
      {
        "field": "bsb",
        "message": "The bsb field is required."
      }
    ]
  }
}

These types of errors are from missing required parameters or invalid data supplied to a parameter. The errors key will contain a list of field and message pairs describing the reason for the validation error.

Code Description
validation_error 422 - The errors key will need to be inspected to identify the fields that failed validation and reason for failure.

Server errors

Server errors are rare and should be reported to the Squarepay support team for further investigation.

Code Description
server_error 5xx - Something has gone terribly wrong on Squarepay's server, but should soon be rectified.

Bank Return Codes

DE Payment Bank Return Codes

Below is a list of the possible bank_return_code's and their descriptions that are associated with a Payment result (DE).

Code Description
0 Successful Payment Made.
1 Direct Debit failed, invalid BSB number provided.
2 Direct Debit stopped by the Bank.
3 Direct Debit failed, bank account is closed.
4 Direct Debit failed, bank account holder deceased.
5 Direct Debit failed, incorrect BSB or account number.
6 Direct Debit failed, insufficient funds.
7 Direct Debit failed, account deleted.
8 Direct Debit failed, invalid UserID, please contact Squarepay.
9 Direct Debit failed, technically invalid. This can occur if account is not available to Direct Debit e.g. E-Saver account.
90 Late Return. Read below for more information.
92 Direct Debit Claim.

Example Late Return

HTTP/1.1 200 (OK)
Content-Type: application/json



{
  "data" : {
    "payment_id" : 2002448,
    "scheduled_payment_id" : "",
    "customer_id" : 1337,
    "first_name" : "Billy",
    "last_name" : "Bob",
    "system_ref" : "MEM000001337",
    "general_ref" : "BillyBob201605012330",
    "payment_date" : "2016-04-12T00:00:00",
    "payment_method" : "CR",
    "payment_ref" : "1337-10014",
    "remitter" : "ABC CORP",
    "payment_amount" : "-100.0000",
    "scheduled_amount" : "-100.0000",
    "transaction_fee_client" : "0.0000",
    "transaction_fee_customer" : "1.1000",
    "settlement_date" : "2016-04-14T00:00:00",
    "invoice_id" : "20022",
    "payment_status" : "DISHONOURED",
    "bank_return_code" : 90
  }
}

Late Return

A payment will be marked as a Late Return (bank_return_code of 90), when a Financial Institution advises Squarepay that a payment has been dishonoured after funds have already been settled to the client account. Generally this is a rare occurrence as the majority of Financial Insitutions report a failed payment within 1 to 4 business days, while legally Financial Insitutions have up to 5 business days to report a failed payment.

When a Late Return occurs, Squarepay will reverse the transaction by creating another payment containing the payment_ref of the original payment. This will be reflected in the List Payments return results, see the example Late Return payment on the right.

Claims

Claims can arise when the customer disputes a payment with their bank and investigation finds their dispute to be valid. Similar to a Late Return a reversal transaction will be created, this time with a bank_return_code of 92. This will be reflected in the List Payments return results.

DE Disbursement Bank Return Codes

Below is a list of the possible bank_return_code's and their descriptions that are associated with a Disbursement result (DE).

Code Description
0 Successful Payment Made.
101 The BSB is not valid or is no longer active.
102 The target institution has blocked transactions to this account. Please refer to customer.
103 The target account is closed.
104 The target account's owner has been listed as deceased.
105 The target account number cannot be found by the financial institution.
106 Usually means that there is an issue with the account receiving a credit that only the customer and their financial institution can resolve. Please refer to customer.
107 The target account is deleted.
108 Please contact Squarepay for further information.
109 Usually means that the account is not creditable or that the reason for failure cannot be categorised within the standard BECS return codes. Please refer to customer.
150 The transaction was voided by an administrator.
151 The transaction was voided by its initiator.
152 There were insufficient funds to complete the transaction.
153 The transaction was unable to complete. Please contact Squarepay for assistance.
154 The target account is blocked and cannot receive funds.
199 An unknown DE error occurred. Please contact Squarepay for assistance.

NPP Disbursement Bank Return Codes

Below is a list of the possible bank_return_code's and their descriptions that are associated with a Disbursement result (NPP).

Code Description
0 Successful Payment Made.
301 An upstream network issue occurred. Please try again later.
302 The target BSB is not NPP enabled. Please try another channel.
303 The target account exists but cannot accept funds via the NPP. Please try another channel.
304 The target account number cannot be found.
305 The target financial institution is experiencing technical difficulties. Please try again later.
306 The target account is closed.
307 The target financial institution is undergoing maintenance or experiencing an outage. Please try again later.
308 The target account is blocked and cannot receive funds.
399 An unknown NPP error occurred. Please contact Squarepay for assistance.
HTTP