Skip to main content
API docs by Redocly

Oligo PayTo API (V1)

Download OpenAPI specification:Download

E-mail: tech-support@oligo.com.au

Documentation for the Oligo PayTo API.

Agreements

Create and query agreements

create agreement

Authorizations:
bearerAuth
Request Body schema: application/json
uid
required
string [ 1 .. 64 ] characters ^[A-Za-z0-9_~.-]{1,64}$

Supplied unique identifier for agreement, maximum 64 characters containing only unreserved characters as defined in RFC3986. This identifier ensures agreement uniqueness between integrator systems and Oligo.

purpose
required
string
Enum: "mortgage" "utility" "loan" "dependant_support" "gambling" "retail" "salary" "personal" "government" "pension" "tax" "other"

The nature of the agreement with the debtor

required
object

Who and where the payment is taken from

description
required
string [ 1 .. 140 ] characters ^[ -~]+$

The reason for the agreement, as narrative text. ASCII-printable characters only.

resolution_requested_before
string or null <date-time>

Requested resolution (accept/decline) deadline for this agreement. It will be provided in any notification sent to the debtor. This time is for informational purposes only and does not affect the expiry time. If not provided, it defaults to 5 days from agreement creation. Value must be an ISO8601 date-time in UTC timezone.

cancel_if_unresolved
boolean or null

An optional field to indicate whether or not we should auto cancel this agreement if it is not authorized by the debtor by the resolution_requested_before point in time. This field must be accompanied by the resolution_requested_before attribute and if not, will result in a 422 response and error code.

validity_start_date
string or null <date> ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

Start date for validity of agreement. If specified, the agreement will be valid from 00:00:00 Australia Sydney time on specified date. If no date specified, the current date will be populated.

validity_end_date
string or null <date> ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

End date of the validity of the agreement. If specified, the agreement will be valid until 23:59:59.999 Australia Sydney time on this date.

metadata
object or null (payto.metadata)

Use for your custom data. A place to store any miscellaneous information your system may need in regards to the record you are creating. This will be included in associated webhook payloads under the resource_metadata key. Nested values (i.e., objects and arrays) are not allowed. The maximum size of this parameter is 2kb.

required
object

Defines the terms of what payments can be initiated from agreement

object

SANDBOX ONLY: Parameter that allows you to simulate the debtor performing certain actions against the created agreement to aid integrators while testing their control flows. Defaults to debtor_accept if not given.

Responses

Callbacks

Request samples

Content type
application/json
{
  • "uid": "biz_agreement_ACBDEFGHIJKLMNOP",
  • "purpose": "loan",
  • "debtor": {
    },
  • "description": "Payment plan for loan #1234",
  • "resolution_requested_before": "2022-01-20T12:34:56Z",
  • "cancel_if_unresolved": true,
  • "validity_start_date": "2023-01-01",
  • "validity_end_date": "2023-12-31",
  • "metadata": {
    },
  • "payment_terms": {
    },
  • "sandbox": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Callback payload samples

Callback
Content type
application/json
{
  • "data": {
    },
  • "links": {
    }
}

list agreements

Authorizations:
bearerAuth
query Parameters
per_page
integer [ 1 .. 100 ]
Default: 20

Number of results per page

starting_after
string

Opaque pagination cursor value. Set by following "next" links.

state
Array of any
Items Enum: "pending" "created" "active" "suspended" "cancelled" "declined" "failed" "expired"

Filter agreements by state. Multiple values can be separated by commas. e.g 'pending,created'

min_created_date
string <date>
Example: min_created_date=2022-01-01

Filter by minimum created_at date. ISO8601 format.

max_created_date
string <date>
Example: max_created_date=2022-01-31

Filter by maximum created_at date. ISO8601 format.

Responses

Response samples

Content type
application/json
{
  • "links": { },
  • "data": [ ]
}

show agreement

Authorizations:
bearerAuth
path Parameters
agreement_uid
required
string^[A-Za-z0-9_~.-]{1,64}$
Example: Agreement_00012345

A supplied unique ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Payments

Make payments using an existing agreement

create payment

Authorizations:
bearerAuth
Request Body schema: application/json
uid
required
string [ 1 .. 64 ] characters ^[A-Za-z0-9_~.-]{1,64}$

Supplied unique identifier for payment, maximum 64 characters containing only unreserved characters as defined in RFC3986. This identifier ensures payment uniqueness between integrator systems and us.

agreement_uid
required
string^[A-Za-z0-9_~.-]{1,64}$

A supplied unique ID

amount
required
integer (payto.amount) [ 1 .. 1000000000 ]

Amount in cents.

priority
required
string
Enum: "unattended" "attended"

Execution priority of payment. attended payments will be prioritised over unattended payments.

reference
string or null <= 35 characters ^[ -~]+$

Free-form text for reconciliation purposes. Typically this field will be shown to both parties on bank statements, however, the debtor can also control this via the agreement. The reference given here takes precedence over the agreeement's reference when it has been set by the debtor.

description
string or null <= 280 characters

Free-form text for the matching/reconciliation of a transaction. Similar to the reference field, this can be shown on both parties' bank statements. The difference is that this description can be a longer string and banks can show this seperately from the reference.

last_payment
boolean or null

This is a required field with agreements that have a payment_terms.type of balloon. If true, it indicates that this payment is the last payment for the agreement, and should be validated against the last_payment_date and last_payment_amount. No further payments can be made with the agreement once the last payment has been made. This field should be set to false for all other payments against a balloon agreement, and must be unset for payments on non-balloon agreements.

metadata
object or null (payto.metadata)

Use for your custom data. A place to store any miscellaneous information your system may need in regards to the record you are creating. This will be included in associated webhook payloads under the resource_metadata key. Nested values (i.e., objects and arrays) are not allowed. The maximum size of this parameter is 2kb.

object

SANDBOX ONLY: Parameter that allows you to simulate the created payment going through certain scenarios to aid integrators while testing their control flows. Defaults to auto_settle if not given.

Responses

Callbacks

Request samples

Content type
application/json
{
  • "uid": "biz_20221231_ACBDEFGHIJKLMNOP",
  • "agreement_uid": "Agreement_00012345",
  • "amount": 2495,
  • "priority": "unattended",
  • "reference": "INVOICE #1003",
  • "description": "Payment 1 of 6 for Demo house Smart Fridge 300L",
  • "last_payment": false,
  • "metadata": {
    },
  • "sandbox": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Callback payload samples

Callback
Content type
application/json
{
  • "data": {
    },
  • "links": {
    }
}

list payments

Authorizations:
bearerAuth
query Parameters
per_page
integer [ 1 .. 100 ]
Default: 20

Number of results per page

starting_after
string

Opaque pagination cursor value. Set by following "next" links.

state
Array of any
Items Enum: "created" "submitting" "under_investigation" "failed" "settled"

Filter payments by state. Multiple values can be separated by commas. e.g 'created,submitting'

min_created_date
string <date>
Example: min_created_date=2022-01-01

Filter by minimum created_at date. ISO8601 format.

max_created_date
string <date>
Example: max_created_date=2022-01-31

Filter by maximum created_at date. ISO8601 format.

agreement_uid
string
Example: agreement_uid=biz_agreement_000123

Filter payments by agreement.

refunds
string
Enum: "included" "excluded" "only"
Example: refunds=included

Filter payments by whether or not they are facilitating a refund.

Responses

Response samples

Content type
application/json
{
  • "links": { },
  • "data": [
    ]
}

show payment

Authorizations:
bearerAuth
path Parameters
payment_uid
required
string^[A-Za-z0-9_~.-]{1,64}$
Example: Payment_00012345

A supplied unique ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

retry payment

Retry a failed payment as long as it has failed due to a retryable reason as indicated by the retryable boolean field within the payment's failure object. Payments may be retried up to 10 times while within the related agreement's validity begin and end dates. Additionally, payments can only be retried 5 times within 24 hours.

Authorizations:
bearerAuth
path Parameters
payment_uid
required
string^[A-Za-z0-9_~.-]{1,64}$
Example: Payment_00012345

A supplied unique ID

Request Body schema: application/json
object

SANDBOX ONLY: Parameter that allows you to simulate certain scenarios in regards to the payment retry to aid integrators while testing their control flows.

simulate
required
string
Enum: "auto_settle" "requires_investigation" "investigate_and_settle" "investigate_and_fail" "insufficient_funds" "debtor_account_closed" "financial_infrastructure_unavailable" "debtor_alias_not_found" "creditor_alias_not_found" "alias_resolution_service_unavailable"
delay
integer

An optional attribute that will delay the requested simulation by the given amount of seconds. If delay is not provided (default behaviour), the simulated action will happen instantly.

Responses

Callbacks

Request samples

Content type
application/json
{
  • "sandbox": {
    }
}

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Callback payload samples

Callback
Content type
application/json
{
  • "data": {
    },
  • "links": {
    }
}

Agreement modification

Modify existing agreements

cancel agreement

Authorizations:
bearerAuth
path Parameters
agreement_uid
required
string^[A-Za-z0-9_~.-]{1,64}$
Example: Agreement_00012345

A supplied unique ID

Request Body schema: application/json
reason
required
string
Enum: "invalid_debtor_account_number" "closed_account_number" "closed_debtor_account_number" "blocked_account" "invalid_debtor_account_type" "transaction_forbidden" "transaction_not_supported" "not_allowed_currency" "not_allowed_amount" "amount_exceeds_agreed_limit" "customer_deceased" "no_mandate_service_agent" "no_mandate_service_customer" "customer_requested" "initiating_party_requested" "mandate_expired" "suspected_fraudulent" "no_reason_customer" "no_reason_agent" "narrative" "regulatory" "no_service_debtor" "contract_amended" "debtor_cancellation_requested" "contract_expired" "mandate_suspended_final_collection" "mandate_suspended_one_collection" "mandate_suspended_failed_collections" "no_answer"

Reason for the agreement being cancelled

narrative
string or null [ 1 .. 256 ] characters

Free text field to store a description to accompany the given reason_code

object

SANDBOX ONLY: Parameter that allows you to simulate the certain scenarios related to the cancellation of an agreement to aid integrators while testing their control flows.

Responses

Callbacks

Request samples

Content type
application/json
{
  • "reason": "initiating_party_requested",
  • "narrative": "My custom description",
  • "sandbox": {
    }
}

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Callback payload samples

Callback
Content type
application/json
{
  • "data": {
    },
  • "links": {
    }
}

Alias Resolution

Resolve the display name associated with a PayID alias

resolve

This endpoint is used to resolve an alias to a display name. It is possible for this endpoint to return a 503 service unavailable error if the addressing service is not available.

Authorizations:
bearerAuth
Request Body schema: application/json
type
required
string
value
required
string^\+[0-9]{1,3}-[1-9]{1,1}[0-9]{1,29}$

A PayID phone alias. e.g. +61-411222333

required
object

Details of the end-user requesting this resolution.

object

SANDBOX ONLY: Parameter that allows you to simulate certain alias lookup scenarios to aid integrators while testing their control flows.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "alias_phone",
  • "value": "+61-411222333",
  • "requester": {
    },
  • "sandbox": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Reason codes

Agreement Failure Codes

Can be present on a failed agreement and give more detail about why an agreement has failed. MMS.API.xxxx failure codes are unexpected and indiciate an issue communicating with an upstream service. The detail for each of these will be prefixed with Contact Oligo for more information: and we recommend contacting us to have the issue investigated.

Code Title Description
MMS.API.xxxx Title of the MMS error Contact Oligo for more information: More detail about the MMS error
ZPUNP01 Debtor's financial institution does not support PayTo Cannot create agreement with provided debtor account
ZPUNP02 Invalid creditor account The given creditor account cannot accept funds via NPP
ZPUNP06 Error resolving alias Oligo was unable to reach the addressing service
ZPUNP07 Debtor alias not found Oligo was unable to resolve the given debtor alias
ZPUNP08 Creditor alias not found Oligo was unable to resolve the given creditor alias
UKNWN Unknown Error An unexpected error occured. Reach out to Oligo for more information

Agreement Decline Reason Codes

Can be present on a declined agreement and give more detail about why an agreement was declined.

Code Title Description
AC02 Invalid Debtor Account The Payer Customer Account does not exist within NPP
AC05 Closed Debtor Account The Payer Customer account is closed
AC06 Blocked Account The Payer Customer Account is blocked
AC13 Invalid Debtor Account Type The Payer Customer Account does not allow funds to be debited within NPP
AG01 Transaction Forbidden The Payer Customer Account is unable to be debited
AG03 Transaction Not Supported The Payer Customer Account is able to make NPP Payments, but is not able to make NPP Payments to the Payee Customer Account type
AM03 Not Allowed Currency The Payer Customer Account cannot draw funds in AUD
AM12 Invalid Amount No amount and/or no maximum amount have been specified
AM14 Amount Exceeds Agreed Limit The specified amount would exceed the allowed Transaction amount for the Payer Customer Account
BE06 Unknown End Customer The Payer Customer associated with the nominated Payer Customer Account does not exist within the Payer Participant (or applicable identified Institution) customer list
MD09 No Agreement Service On Customer The Payer Customer Account does not support the given agreement type
MD16 Requested By Customer Agreement/Amendment action requested by the Payer Customer
MD21 Agreement Cancelled Due To Fraud The Payer Participant detects fraud within the Agreement
NOAS No Answer From Customer The Payer Participant declines the Agreement on behalf of the Payer Customer because there was no response from the Payer Customer
RR04 Regulatory Reason The Agreement/Payment is rejected due to regulatory reasons
UKNWN Unknown Error An unexpected error occured. Reach out to Oligo for more information

Agreement Cancel/Suspend Reason Codes

Can be present on a cancelled or suspended agreement and give more detail about why the agreement is in that state.

Code Title Description
AC02 Invalid Debtor Account The Payer Customer Account does not exist within NPP
AC04 Closed Account Number The account has been closed and the Mandate is no longer valid
AC05 Closed Debtor Account The Payer Customer account is closed
AC06 Blocked Account The Payer Customer Account is blocked
AC13 Invalid Debtor Account Type The Payer Customer Account does not allow funds to be debited within NPP
AG01 Transaction Forbidden The Payer Customer Account is unable to be debited
AG03 Transaction Not Supported The Payer Customer Account is able to make NPP Payments, but is not able to make NPP Payments to the Payee Customer Account type
AM03 Not Allowed Currency The Payer Customer Account cannot draw funds in AUD
AM12 Invalid Amount No amount and/or no maximum amount have been specified
AM14 Amount Exceeds Agreed Limit The specified amount would exceed the allowed Transaction amount for the Payer Customer Account
MD07 End Customer Deceased End customer is deceased
MD08 No Mandate Service By Agent The Mandate Service is no longer supported by the Agent
MD09 No Agreement Service On Customer The Payer Customer Account does not support the given agreement type
MD16 Requested By Customer Agreement/Amendment action requested by the Payer Customer
MD20 Agreement Expired Contact Oligo for more information
MD21 Agreement Cancelled Due To Fraud The Payer Participant detects fraud within the Agreement
MS02 Not Specified Reason Customer Generated The payment was rejected by the Debtor Customer, but no reason was provided
MS03 Not Specified Reason Agent Generated The payment was rejected by the Responding Participant, but no reason was provided
NARR Narrative Contact Oligo for more information
RR04 Regulatory Reason The Agreement/Payment is rejected due to regulatory reasons
SL01 Specific Service offered by Debtor Agent The NPP Payment Initiation Request was rejected specifically due to a service offered by the Responding Participant
CTAM Contract Amended Mandate suspended due to amendment of the contract
CTCA Contract Cancellation Initiated By Debtor Mandate suspended due to cancellation of the contract, requested by the debtor
CTEX Contract Expired Mandate suspended due to the contract that expired
MCFC Mandate Suspended Final Collection Mandate suspended as final collection took place
MCOC Mandate Suspended Once Off Collection Mandate suspended as the once off collection took place
MSUC Mandate Suspended 7 Consecutive Unsuccessful Collections Mandate suspended after 7 consecutive unsuccessful collections
NOAS No Answer From Customer The Payer Participant declines the Agreement on behalf of the Payer Customer because there was no response from the Payer Customer

Payment Failure Codes

Can be present on a failed payment and give more detail about why the payment has failed.

Code Title Description Retryable
ZPPAY24 Participant not available One of the participants is currently not available to process the payment. False
AB01 Aborted Clearing Timeout Clearing process aborted due to timeout True
AB02 Aborted Clearing Fatal Error Clearing process aborted due to a fatal error True
AB03 Aborted Settlement Timeout Settlement aborted due to timeout True
AB04 Aborted Settlement Fatal Error Settlement process aborted due to a fatal error True
AC02 Invalid Debtor Account The Payer Customer Account does not exist within NPP False
AC05 Closed Debtor Account The Payer Customer account is closed False
AC06 Blocked Account The Payer Customer Account is blocked True
AC13 Invalid Debtor Account Type The Payer Customer Account does not allow funds to be debited within NPP False
AC15 Account Details Changed The account details for the counterparty have changed False
AG01 Transaction Forbidden The Payer Customer Account is unable to be debited False
AG03 Transaction Not Supported The Payer Customer Account is able to make NPP Payments, but is not able to make NPP Payments to the Payee Customer Account type False
AG07 Unsuccesful Direct Debit Debtor account cannot be debited for a generic reason. May indicate insufficient funds True
AGNT Incorrect Agent BSB/IIN of the account provided falls outside the range published in the NPP Reference Data False
AM01 Zero Amount Specified message amount is equal to zero False
AM02 Not Allowed Amount Specified transaction amount is greater than allowed maximum False
AM03 Not Allowed Currency The Payer Customer Account cannot draw funds in AUD False
AM04 Insufficient Funds The specified Payer Customer Account has insufficient funds True
AM06 Too Low Amount The amount requested is below the agreed minimum amount False
AM09 Wrong Amount The amount requested was not what the Payer Customer was expecting False
AM12 Invalid Amount No amount and/or no maximum amount have been specified False
AM19 Invalid Group Number Of Transactions The number of transactions in the NPP Payment Initiation Request is not 1 False
AM21 Limit Exceeded The payment amount exceeds the agreed limit between the Responding Participant and the Debtor Customer True
BE06 Unknown End Customer The Payer Customer associated with the nominated Payer Customer Account does not exist within the Payer Participant (or applicable identified Institution) customer list False
BE08 Missing Debtor Name Debtor name is missing False
CH20 Decimal Points Not Compatible With Currency The amount does not have two or zero fraction digits False
CH21 Required Element Missing One or more mandatory fields have not been provided False
CURR Incorrect Currency Currency of the payment is incorrect False
CUST Requested By Customer Debtor Customer has directed the Responding Participant to reject the payment False
DT02 Invalid Creation Date The CreationDateTime in the Group Header is not as per the required format False
DT04 Future Date Not Supported The Business Service does not support future dated NPP payments False
ED05 Settlement Failed Settlement of the transaction has failed False
ED06 Settlement System Not Available The FSS is unavailable so the Clearing Request cannot be made False
FF04 Invalid Service Level Code The Service Level code in the NPP Payment Initiation Request is not as per the specified format False
FF08 Invalid End To End Id End to End Id missing or invalid False
FF10 Bank System Processing Error Responding Participant is unable to process the payment due to back office issues or outage True
FF11 Clearing Request Aborted The Clearing Request associated to payment was aborted False
FRAD Fraudulent Origin The NPP payment was rejected due to identified fraud or due to a scam False
MD01 No Agreement The NPP Payment Initiation Request did not contain a Agreement False
MD02 Missing Mandatory Information In Agreement Contact Oligo for more information False
MD20 Agreement Expired Contact Oligo for more information True
MS02 Not Specified Reason Customer Generated The payment was rejected by the Debtor Customer, but no reason was provided False
MS03 Not Specified Reason Agent Generated The payment was rejected by the Responding Participant, but no reason was provided False
NARR Narrative Contact Oligo for more information True
NAUT Not Authorised The payment contents do not align with the Agreement terms False
RR02 Missing Debtor Name or Address Regulatory details of the Debtor were not provided in the NPP Payment Initiation Request False
RR04 Regulatory Reason The Agreement/Payment is rejected due to regulatory reasons False
RC05 Invalid BIC Identifier The BIC identifier in the Message Payload is invalid or missing False
SL01 Specific Service offered by Debtor Agent The NPP Payment Initiation Request was rejected specifically due to a service offered by the Responding Participant False
SL13 Maximum number of Direct Debit Transactions exceeded The payment was rejected because the number of transactions requested exceeds the Debtor Agent offering True
SL14 Maximum Direct Debit Transaction Amount exceeded The payment was rejected because the total value of transactions requested exceeds the Debtor Agent offering True
TD03 Incorrect File Structure The file format is incomplete or invalid True
TM01 Invalid Cut Off Time The NPP Payment Initiation Request was received by the Responding Participant after an agreed cut-off time True
AVED After Validity End Date It is after the agreement's validity end date False
BVSD Before Validity Start Date It is before the agreement's validity start date False
MCGP In Grace Period The agreement has recently been migrated and is still in its grace period False
NACT Not Active Agreement is not active False
ZPUNP01 Debtor's financial institution does not support PayTo Cannot create agreement with provided debtor account False
ZPUNP06 Error resolving alias Unable to reach the addressing service False
ZPUNP07 Debtor alias not found Unable to resolve the given debtor alias False
ZPUNP08 Creditor alias not found Unable to resolve the given creditor alias False
UKNWN Unknown Error An unexpected error occured. False

Unprocessable Entity (422) Codes

Comprehensive list of possible error codes that can be returned in a 422 response. Note that each endpoint will only return a subset of these codes. For a list of codes that can be returned by a specific endpoint, see the documentation for the 422 response within that endpoint.

Code Title Description
ZPUNP00 One or more fields violate the relevant schema {details}
ZPUNP01 Debtor's financial institution does not support PayTo Cannot create agreement with provided debtor account
ZPUNP06 Error resolving alias Unable to reach the addressing service
ZPUNP07 Debtor alias not found Unable to resolve the given debtor alias
ZPUNP08 Creditor alias not found Unable to resolve the given creditor alias
ZPUNP09 Alias resolution not enabled Account not enabled for alias resolution services
ZPAGR00 Duplicate UID An agreement with the given UID already exists
ZPAGR01 No configured ABN PayTo Merchants are required to have a configured ABN
ZPAGR02 Invalid resolution requested before Resolution requested before cannot be after {latest_time}
ZPAGR03 Invalid resolution requested before Resolution requested before cannot be in the past
ZPAGR04 Past validity start date Validity start date must not be in the past
ZPAGR05 Validity start date not amendable Validity start date cannot be amended
ZPAGR06 Validity start date after end date Validity start date must be prior to the validity end date
ZPAGR07 Validity start date after first payment date Validity start date must be prior to the first payment date
ZPAGR08 Validity end date too early Validity end date must be equal to or later than the current date and, if given, the last payment date
ZPAGR09 First payment date in past First payment date must not be in the past
ZPAGR10 Last payment date before first payment date Last payment date cannot be before the first payment date
ZPAGR11 Last payment date in the past Last payment date cannot be before the current date
ZPAGR12 Debtor account number only zeroes Debtor account number contains only zeroes
ZPAGR13 Debtor account number reserved Debtor account number is a reserved account
ZPAGR14 Debtor branch code does not exist Debtor branch code does not exist
ZPAGR15 Mandate limit reached You have reached the maximum number of mandates you can create for a debtor per 24 hours
ZPAGR16 Mandate create limit reached You have reached the maximum number of mandates your account can create per 24 hours
ZPAGR17 Auto-Cancel Needs Resolution Date 'cancel_if_unresolved' must be accompanied by 'resolution_requested_before'
ZPPAY00 Duplicate UID A payment with the given UID already exists
ZPPAY01 Over daily limit This Payment would cause you to exceed your current daily limit of {limit}
ZPPAY02 Over per-transaction limit The amount is higher than your current per-transaction limit of {limit}
ZPPAY03 Agreement not active The related agreement must be active before you can initiate a payment
ZPPAY07 After validity end date The validity end date specified in the agreement has already passed
ZPPAY08 Before validity start date The validity start date specified in the agreement has not yet passed
ZPPAY09 Last payment required for balloon The last payment parameter must be specified for a payment against a balloon type agreement
ZPPAY10 Last payment given for non-balloon The last payment parameter must only be specified for a payment against a balloon type agreement
ZPPAY12 Amount over maximum The payment amount is larger than the maximum specified in the agreement
ZPPAY13 After last payment date The last payment date specified in the agreement has already passed
ZPPAY14 First payment date mismatch The payment date does not match the first payment date specified in the agreement
ZPPAY15 Amount incorrect The payment amount does not match the amount specified in the agreement
ZPPAY16 Timing incorrect The time that this payment was initiated does not match the terms of the agreement
ZPPAY17 Too many payments The maximum number of payments has already been reached for the current frequency period, according to the terms of the agreement
ZPPAY18 First payment amount incorrect The payment amount does not match the first payment amount specified in the agreement
ZPPAY19 Last payment amount incorrect The payment amount does not match the last payment amount specified in the agreement
ZPPAY20 Last payment date mismatch The payment date does not match the last payment date specified in the agreement
ZPPAY21 Last payment made No further payments can be created for this agreement, as the last payment has been made
ZPPAY22 Agreement not found No agreement could be found for the given agreement UID
ZPPAY23 Debtor account mismatch The payment debtor does not match the agreement debtor
ZPREF00 Duplicate UID A refund with the given UID already exists
ZPREF01 Payment not found No payment could be found for the given payment UID
ZPREF02 Payment not refundable The payment is not refundable
ZPREF03 Float bank account not found No float bank account could be found for the given float_bank_account_id
ZPREF04 Float bank account not active The given float bank account is not currently active
ZPREF05 Float bank account missing services The given float bank account is not configured to support realtime payments
ZPREF06 Total refunds greater than original payment amount The sum of all refunds is greater than the original payment
ZPREF07 The provided fund source has insufficient funds The provided fund source has insufficient funds to process this refund
ZPREF08 Refunding Via PayTo Not Enabled This feature has not been enabled for your account
ZPREF09 Original Payment is a Refund The payment being refunded cannot be a payment created by a previous refund
ZPREF10 Over per-transaction limit The amount is higher than your current per-transaction limit of {limit}
ZPREF11 Over Daily Limit This Refund would cause you to exceed your current daily limit
ZPREF12 Description must start with REFUND PayTo Refunds processed via a float payment must have a description that starts with REFUND
ZPAMN00 Agreement not amendable Agreement must be active or suspended before it can be amended
ZPAMN01 Amendment already processing There is a pending amendment for this agreement
ZPAMN02 No changes No changes were specified
ZPAMN03 Mandate doesn't change The agreement already has the given changes
ZPAMN04 Validity end date not amendable Validity end date cannot be amended if it was null in original mandate
ZPAMN06 Invalid resolution requested before Resolution requested before cannot be after {latest_time}
ZPAMN07 Resolution requested before in past Resolution requested before cannot be in the past
ZPAMN08 Last payment made This agreement can no longer be amended, as the last payment has been made
ZPPRY00 Payment not retryable Payment is not in a retryable state
ZPPRY01 Too many retries Payment has reached the maximum amount of retries
ZPPRY02 After mandate validity end date The related agreement is no longer valid
ZPPRY03 Retry timeout Payment has been retried too many times recently. Cannot be retried again until {next_time}
ZPPRY04 Retry timeout after validity end Payment has been retried too many times recently and the related mandate will not be valid at the next retryable time.
ZPCAN00 Incorrect agreement state Agreement can not be cancelled while in the '{state}' state
ZPCAN01 Already processing There is a pending cancellation for this agreement
ZPREA01 Already processing There is a pending reactivation for this agreement
ZPSUS01 Already processing There is a pending suspension for this agreement
ZPARE00 Amendment not recallable Amendment is not recallable while in the '{state}' state
ZPARE01 Already processing There is already an in-progress recall for this amendment
ZPARE02 Agreement has no amendment Agreement has no in-progress amendment to recall
ZPPGN00 One or more paramaters are invalid {details}
ZPADD01 Alias not found The given alias was not able to be resolved
ZPADD02 Account lookup limit reached The account level lookup limit has been reached for the current period
ZPADD03 Remote IP lookup limit reached The remote IP level lookup limit has been reached for the current period
ZPADD04 Requester ID lookup limit reached The requester ID level lookup limit has been reached for the current period

Sandbox Guides

A guide to our Sandbox environment for simulating certain errors and behaviour.

Asynchronous Simulations

Within the API endpoints for our sandbox environment, we provide the ability to perform asynchronous simulations - such as simulating an agreement being accepted, or a payment being settled automatically. This can be done using the sandbox simulate parameter (see below).

"sandbox": {
  "simulate": "debtor_accept",
  "delay": 0
}

Please refer to the documentation / schema for each endpoint for further information.

Testing Branch Codes

In our sandbox environment, we provide certain branch codes that will emulate the given institution having or lacking certain capabilities. These can be used to receive certain validation errors (422) within the response to an API request. For example, providing 100001 as the debtor branch code will result in a 422 response with an error code when creating an Agreement.

These are described in the table below and can be provided for any party when creating an Agreement, Amendment or Payment.

BSB Simulated Behaviour
100-000 Invalid BSB
100-001 Party institution does not have PayTo debtor capabilities
100-002 Party institution is not able to receive funds via SCT