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",
    "available_balance": "100.0000"
  },
  {
    "bank_account_id": "6cd3d122-2004-4481-851e-5c44154806c4",
    "bsb": "032-000",
    "bank_name": "Squarepay",
    "account_number": "238493",
    "status": "ACTIVE",
    "title": "Float Account #2",
    "available_balance": "13.3700"
  }]
}

Returns a list of your float accounts.

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.
account_number The account number.
status The account status ACTIVE INACTIVE.
title The title of the bank account.
available_balance The account balance in dollars.

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}

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, disbursement as a Disbursement, 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.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.reactivated The agreement has been reactivated by the Customer.
payto_agreement.suspended The agreement has been cancelled by the Customer or Debtor.
payto_agreement.amended The agreement has been amended by the Debtor.
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.

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