Debit Batch Groups
For processing batch payments in the Pay Advantage API you will need to use both Debit Batches and Debit Instructions.
Batch debiting allows you to process authorised bank accounts as a batch group.
The debit batch group is used to schedule and group individual debit instructions together.
This API is useful for the management of a large number of transactions that may occur at a particular point in time.
Note that debits from bank accounts can not be done individually as there is no mechanism to receive an instant response.
Debit Batches are used to group & schedule debit instructions. You must first create a debit batch group and then append instructions for each account you want to debit. This is done using the Debit Instructions API. When the batch contains all the debit instructions you want to process, the batch is authorised and all instructed payments will be scheduled to process.
Endpoints
GET '/debit_batches/{code}'
GET '/debit_batches'
POST '/debit_batches'
PUT '/debit_batches/{code}'
DELETE '/debit_batches/{code}'
PUT '/debit_batches/{code}/authorise'This documentation is deprecated
Please refer to the updated documentation https://docs.payadvantage.com.au/reference/debit_batches_get-1
Returns details associated with a specific debit batch group. Uses the Code value of the debit batch as an identifier.
Example Request
curl -L -X GET 'https://api.payadvantage.com.au/v3/debit_batches/{code}' \
-H 'Authorization: Bearer {access_token}' \Example Responses
STATUS 200 // Successful
{
"Code": "ABC001",
"CreatedBy": {
"FirstName": "Your",
"LastName": "User",
"UserName": "youruser@email.com"
},
"DateCreated": "2020-08-20T11:50:43.235",
"DateToDebit": "2020-08-20T11:50:43.235",
"DebitInstructionAmountSum": 10000.00,
"DebitInstructionCount": 10,
"Name": "Invoicing",
"RemitterName": "Your Remitter Name",
"IsConfirmed": true,
"IsAuthorised": true,
"IsProcessed": true
}STATUS 4## // Error
{
"errorCode": "error_code",
"messages": [
"Error message."
]
}
Query Parameters
Parameter used in the GET function URL.
| code string min = 6, max = 12 |
|---|
| Unique internal identifier assigned to the debit batch by Pay Advantage. This cannot be changed. Returns a single debit batch record. |
This documentation is deprecated
Please refer to the updated documentation https://docs.payadvantage.com.au/reference/debit_batches_search-1
Returns a list of debit batch groups (most recent first by default). The list is paged and will always return the first page of records. If there are no records that match your search you will be returned an empty list.
Example Request
curl -L -X GET 'https://api.payadvantage.com.au/v3/debit_batches' \
-H 'Authorization: Bearer {access_token}' \Example Responses
STATUS 200 // Successful
{
"Records": [
{
"Code": "ABC001",
"CreatedBy": {
"FirstName": "Your",
"LastName": "User",
"UserName": "youruser@email.com"
},
"DateCreated": "2020-08-20T11:50:43.235",
"DateToDebit": "2020-08-20T11:50:43.235",
"DebitInstructionAmountSum": 10000.00,
"DebitInstructionCount": 10,
"Name": "Invoicing",
"RemitterName": "Your Remitter Name",
"IsConfirmed": true,
"IsAuthorised": true,
"IsProcessed": true
},
{
...
}
]
"Meta": {
"page": 0,
"recs_per_page": 15,
"total_recs": 75
}
}Query Parameters
Parameters used in the request URL to return filtered or sorted data in the response body. These parameters follow the same rules as any standard HTML query string parameter. The first parameter is separated by ‘?’ and subsequent parameters are separated by ‘&’.
| page integer |
|---|
| The page number you want to view using the zero-based index i.e. page=0 will return page 1 of direct debit Records. If the page index is greater than the last page, you will be returned an empty page. Negative indexes will return an error. |
| per_page integer min = 0, max = 1000 |
| Number of records to view per page. By default the value is 100. Values greater than the max value, or negative values will return an error. |
| sort string array |
| Lets you sort direct debit records by a defined set of fields. You can sort by one field e.g. sort={field1} or by many e.g. sort={field1},{field2} A minus symbol (-) in front of the field indicates the descending order for that field only e.g. sort={field1},-{field2} will sort field1 by ascending but field2 by descending. Valid Field Strings:
|
| code string min = 6, max = 12 |
| Unique internal identifier assigned to the debit batch by Pay Advantage. This cannot be changed. Returns a single debit batch record. |
| datecreated date string |
| Returns debit batch records based on date and time they were created. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datecreated={ddMMyyyy} |
| datecreatedto date string |
| Returns debit batch records that were created before or on the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datecreatedto={ddMMyyyy} |
| datecreatedfrom date string |
| Returns debit batch records that were created after or on the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datecreatedfrom={ddMMyyyy} |
| name string min = 2, max = 50 |
| The debit batch name assigned to this batch group. Used to help you easily identify debit batches from each other. |
| datetodebit date string |
| Returns debit batch records based on date and time they are scheduled to debit. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datetodebit={ddMMyyyy} |
| datetodebitto date string |
| Returns debit batch records that have been scheduled to debit before or on the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datetodebitto={ddMMyyyy} |
| datetodebitfrom date string |
| Returns debit batch records that have been scheduled to debit after or on the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datetodebitfrom={ddMMyyyy} |
| isconfirmed boolean |
| Flag indicating if the the debit batch has been confirmed. If true this debit batch can no longer edited and is scheduled to process based on the datetodebit parameter. |
| isauthorised boolean |
| Flag indicating if the the debit batch has been authorised. If true this debit batch can no longer edited and is scheduled to process based on the datetodebit parameter. |
| isprocessed boolean |
| Flag indicating if the the debit batch has been processed. If true this debit batch can no longer edited and payments have already begun/been processed. |
| debitinstructioncount integer |
| Returns debit batch records based on number of debit instructions they contain. Integer must be a whole number and can be 0. |
| debitinstructioncountto integer |
| Returns any debit groups where the number of debit instructions contained is equal to or under the integer queried. Integer must be a whole number and can be 0. |
| debitinstructioncountfrom integer |
| Returns any debit groups where the number of debit instructions contained is equal to or over the integer queried. Integer must be a whole number and can be 0. |
| debitinstructionamountsum number |
| Returns debit batch records based on the total amount to be debited of all debit instructions in the batch. Enter value as a currency amount in AUD e.g. 1500.50 |
| debitinstructionamountsumto number |
| Returns debit batch records where the total amount to be debited of all debit instructions in the batch is equal to or less than the value queried. Enter value as a currency amount in AUD e.g. 1500.50 |
| debitinstructionamountsumfrom number |
| Returns debit batch records where the total amount to be debited of all debit instructions in the batch is equal to or more than the value queried. Enter value as a currency amount in AUD e.g. 1500.50 |
| createdby Dictionary |
|
firstname string min = 2, max = 255
First name of the user account that created this batch debit.
lastname string min = 2, max = 255
Last name of the user account that created this batch debit.
username string min = 2, max = 255
Username for the user account that created this batch debit.
|
This documentation is deprecated
Please refer to the updated documentation https://docs.payadvantage.com.au/reference/debit_batches_post-1
Generates a new Debit Batch Group that debit instructions can be added to. Name and DateToDebit are always required. DateToDebit must be the day of creation or a future date (AEDT - Sydney). You can include an initial array of Debit Instructions, or send an empty Debit Instructions array and add them later. Learn more about constructing Debit Instructions in the API documentation here.
Example Request
curl -L -X POST 'https://api.payadvantage.com.au/v3/debit_batches' \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json' \
-d '{
"Name": "Invoicing Batch"
"DateToDebit": "2020-12-31",
"RemitterName": null,
"DebitInstructions": [
{
...
},
{
...
}
]
}'Example Responses
STATUS 201 // Successful
{
"Code": "ABC001",
"CreatedBy": {
"FirstName": "Your",
"LastName": "User",
"UserName": "youruser@email.com"
},
"DateCreated": "2020-08-20T11:50:43.235",
"DateToDebit": "2020-08-20T11:50:43.235",
"DebitInstructionAmountSum": 10000.00,
"DebitInstructionCount": 1,
"Name": "Invoicing",
"RemitterName": "Your Remitter Name",
"IsConfirmed": false,
"IsAuthorised": false,
"IsProcessed": false
}STATUS 4## // Error
{
"errorCode": "error_code",
"messages": [
"Error message."
]
}
Request Parameters
| Name string Requiredmin = 2, max = 50 |
|---|
| Will be appended as the name of this debit batch group. Used to help you easily identify debit batch groups from each other. |
| DateToDebit date string Required |
| Set a date for the debit batch group to process debits on. Enter your date string in this format "YYYY-MM-DD". The date must be either the day of creation, or a future date. A date in the past will return an error. |
| RemitterName string max = 16 |
| The remitter name that appears on customers bank statements to let them know why they have been debited. You can set this as null and it will use the default remitter name for your account. This is the recommended use of this field. |
| DebitInstructions array |
| This is where you can enter an array of debit instructions. You can leave this parameter empty if you wish to add instructions later. To see how to layout debit instructions read the API here. |
This documentation is deprecated
Please refer to the updated documentation https://docs.payadvantage.com.au/reference/debit_batches_put-1
Updates a debit batch group using its Code as an identifier. If a parameter is not included in the request body, it will not be updated.
Example Request
curl -L -X PUT 'https://api.payadvantage.com.au/v3/debit_batches' \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json' \
-d '{
"Name": "Invoicing Batch - August 2021",
"DateToDebit": "2020-12-31",
"RemitterName": null
}'Example Responses
STATUS 200 // Successful
{
"Code": "ABC001"
}STATUS 4## // Error
{
"errorCode": "error_code",
"messages": [
"Error message."
]
}Request Parameters
| Name string Required min = 2, max = 50 |
|---|
| Will be appended as the name of this debit batch group. Used to help you easily identify debit batch groups from each other. |
| DateToDebit date string Required |
| Set a date for the debit batch group to process debits on. Enter your date string in this format "YYYY-MM-DD". The date must be either the day of creation, or a future date. A date in the past will return an error. |
| RemitterName string max = 16 |
| The remitter name that appears on customers bank statements to let them know why they have been debited. You can set this as null and it will use the default remitter name for your account. This is the recommended use of this field. |
This documentation is deprecated
Please refer to the updated documentation https://docs.payadvantage.com.au/reference/debit_batches_delete-1
A debit batch can be deleted provided it is not in a confirmed or authorised state. This deletes all instructions within it. This is how you can cancel a debit batch any time before being processed or authorised. Use a debit batches Code in the request to specify which batch to delete.
Example Request
curl -L -X DELETE 'https://api.payadvantage.com.au/v3/debit_batches/{code}' \
-H 'Authorization: Bearer {access_token}'
Example Responses
STATUS 200 // Successful
{
}STATUS 4## // Error
{
"errorCode": "error_code",
"messages": [
"Error message."
]
}This documentation is deprecated
Please refer to the updated documentation https://docs.payadvantage.com.au/reference/debit_batches_put-1
Once a debit batch has been created and all Debit Instructions added, it must be confirmed and authorised. Once authorised the batch will be scheduled to process on the date defined by the DateToDebit parameter. Use the debit batch Code to specify which debit batch you want to authorise.
Example Request
curl -L -X PUT 'https://api.payadvantage.com.au/v3/debit_batches/{code}/authorise' \
-H 'Authorization: Bearer {access_token}'
Example Responses
STATUS 200 // Successful
{
"Code": "ABC001",
"DateExpectedToDebit": "2020-08-20T11:50:43.235"
}STATUS 4## // Error
{
"errorCode": "error_code",
"messages": [
"Error message."
]
}
Debit Batch Instructions
For processing batch payments in the Pay Advantage API you will need to use both Debit Batches and Debit Instructions.
Debit Instructions are individual instructions to debit an amount from a bank account. With debit instructions we don't manage any scheduling of the debit, we simply process a batch of payments and record the success or failure of each payment instruction and nothing more.
Debit Batches
Before creating debit instructions you must first create a debit batch group that will be used to control certain functions like the debit date etc for all of the instructions. See debit batches for more information.
On-Charging Fees
If you decide to on-charge debit fees directly to your customers then you can make use of the OnchargeFees flag and we will deal with this for you. Debit Fees will be calculated when the Debit Instruction is processed for payment (typically the DateToDebit from the DebitBatch). The fee will be added to the payment at this point for on-charged debit instructions.
Group Key Feature
Any Debit Instruction may have a Group Key assigned. As the name suggests, this field is used for grouping related instructions together. The same group key may be used across any number of batches over any period of time. A good idea is to use a customers unique code or identifier for this field.
Please be aware that, when using the Group Key and On-charge features together, any on-charged fee that dishonours will be added to the next on-charged debit instruction with a matching group key. This is by design to assist in fee management and recovery. It is only a real concern if on-charging is used and the group key is shared between different customers. One solution in this scenario is to add a unique suffix to group key for each customer in that group (for example “AB001-01”, “AB001-02”) so these can be filtered at a later date using the first number characters.
Endpoints
GET '/debit_instructions/{code}'
GET '/debit_instructions'
POST '/debit_instructions'
DELETE '/debit_instructions/{code}'
DELETE '/debit_instructions/{code},{code}'
GET '/debit_instructions_failed'
PUT '/debit_instructions/{code},{code}/ackfail'This documentation is deprecated
Please refer to the updated documentation https://docs.payadvantage.com.au/reference/debit_instructions_get-1
Returns a debit instruction record using its unique Code value as an identifier.
Example Request
curl -L -X GET 'https://api.payadvantage.com.au/v3/debit_instructions/{code}' \
-H 'Authorization: Bearer {access_token}' \Example Responses
STATUS 200 // Successful
{
"Code": "DI12345",
"Reference": "Your reference",
"GroupKey": null,
"DateCreated": "2020-10-03T16:41:06.63",
"IsProcessed": true,
"BSBNumber": "012345",
"AccountNumber": "12341234"
"AccountName": "Bob Smith",
"Amount": 87.50,
"RemitterName": "XYZ Trading",
"OnchargeFees": true,
"IsFailAcknowledged": false,
"DebitBatch": {
"Code": "DB123123",
"DateToDebit": "2020-10-05T00:00:00.00"
},
"Payment": {
"Code": "P12345",
"DatePaid": "2020-10-06T16:41:06.63",
"DateFailed": null,
"FailCode": null,
"FailReason": null,
"Amount": 88.45
}
}
STATUS 4## // Error
{
"errorCode": "error_code",
"messages": [
"Error message."
]
}
Query Parameters
Parameter used in the GET function URL.
| code string min = 6, max = 6 |
|---|
| Unique internal identifier assigned to the debit instruction by Pay Advantage. This cannot be changed. Returns a single direct debit instruction record. |
This documentation is deprecated
Please refer to the updated documentation https://docs.payadvantage.com.au/reference/debit_instructions_search-1
Returns a list of debit instruction records (most recent first by default). The list is paged and will always return the first page of records. If there are no records that match your search you will be returned an empty list.
Example Request
curl -L -X GET 'https://api.payadvantage.com.au/v3/debit_instructions' \
-H 'Authorization: Bearer {access_token}' \Example Responses
STATUS 200 // Successful
{
"Records": [
{
"Code": "DI12345",
"Reference": "Your reference",
"GroupKey": null,
"DateCreated": "2020-10-03T16:41:06.63",
"IsProcessed": true,
"BSBNumber": "012345",
"AccountNumber": "12341234"
"AccountName": "Bob Smith",
"Amount": 87.50,
"RemitterName": "XYZ Trading",
"OnchargeFees": true,
"IsFailAcknowledged": false,
"DebitBatch": {
"Code": "DB123123",
"DateToDebit": "2020-10-05T00:00:00.00"
},
"Payment": {
"Code": "P12345",
"DatePaid": "2020-10-06T16:41:06.63",
"DateFailed": null,
"FailCode": null,
"FailReason": null,
"Amount": 88.45
}
},
{
...
}
],
"Meta": {
"page": 0,
"recs_per_page": 15,
"total_recs": 1500
}
}
STATUS 4## // Error
{
"errorCode": "error_code",
"messages": [
"Error message."
]
}
Query Parameters
Parameter used in the GET function URL.
| page integer |
|---|
| The page number you want to view using the zero-based index i.e. page=0 will return page 1 of direct debit Records. If the page index is greater than the last page, you will be returned an empty page. Negative indexes will return an error. |
| per_page integer min = 0, max = 1000 |
| Number of records to view per page. By default the value is 100. Values greater than the max value, or negative values will return an error. |
| sort string array |
| Lets you sort direct debit records by a defined set of fields. You can sort by one field e.g. sort={field1} or by many e.g. sort={field1},{field2} A minus symbol (-) in front of the field indicates the descending order for that field only e.g. sort={field1},-{field2} will sort field1 by ascending but field2 by descending. Valid Field Strings:
|
| code string min = 6, max = 6 |
| Unique internal identifier assigned to the debit instruction record by Pay Advantage. This cannot be changed. Returns a single direct debit record. |
| reference string min = 2, max = 20 |
| An optional placeholder for your own system ID. |
| amount number |
| Amount to be debited (excluding fees) in AUD e.g. $100 would be amount=100.00 |
| amountfrom number |
| Returns an array of records where the amount is equal to or more than the value queried. Amount needs to be entered in AUD e.g. $100 would be amount=100.00 |
| amountto number |
| Returns an array of records where the amount is equal to or less than the value queried. Amount needs to be entered in AUD e.g. $100 would be amount=100.00 |
| payment Dictionary |
|
code string min = 6, max = 6
Unique internal identifier of the payment associated with a particular debit instruction.
amountincfees number
Total amount that was charged for the payment (inclusive of fees). Amount needs to be entered in AUD e.g. $100 would be amountincfees=100.00
amountincfeesfrom number
Returns an array of records where the total payment amount (inclusive of fees) is equal to or more than the value queried. Amount needs to be entered in AUD e.g. $100 would be amountincfeesfrom=100.00
amountincfeesto number
Returns an array of records where the total payment amount (inclusive of fees) is equal to or less than the value queried. Amount needs to be entered in AUD e.g. $100 would be amountincfeesto=100.00
datepaid date string
Returns a list of records based on date they were paid. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datepaid={ddMMyyyy}
datepaidfrom date string
Returns a list of records that were paid on or after the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datepaidfrom={ddMMyyyy}
datepaidto date string
Returns a list of records that were paid on or before the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datepaidto={ddMMyyyy}
datefailed date string
Returns a list of records based on date they were failed. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datefailed={ddMMyyyy}
datefailedfrom date string
Returns a list of records that were failed on or after the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datefailedfrom={ddMMyyyy}
datefailedto date string
Returns a list of records that were failed on or before the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datefailedto={ddMMyyyy}
dateclears date string
Returns a list of records based on date they cleared. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. dateclears={ddMMyyyy}
dateclearsfrom date string
Returns a list of records that were cleared on or after the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. dateclearsfrom={ddMMyyyy}
dateclearsto date string
Returns a list of records that were cleared on or before the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. dateclearsto={ddMMyyyy}
|
| datecreated date string |
| Returns debit instruction records based on date and time they were created. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datecreated={ddMMyyyy} |
| datecreatedto date string |
| Returns debit instruction records that were created before or on the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datecreatedto={ddMMyyyy} |
| datecreatedfrom date string |
| Returns debit instruction records that were created after or on the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datecreatedfrom={ddMMyyyy} |
| bsbnumber string min = 6, max = 6 |
| The BSB Number of the account being debited. |
| accountnumber string min = 4, max = 9 |
| Bank account Number of account being debited. |
| onchargefees boolean |
| Flag that indicates if debit fees are oncharged to the customer or not. If true, any additional service fees will be added to the amount to be debited. |
| isprocessed boolean |
| Flag that indicates if debit instruction has been processed. |
| isfailacknowledged boolean |
| If this debit instruction has failed, this flag will indicate wheter that failure has been acknowledged. If the instruction debit hasn't failed this will return false. |
| debitbatch Dictionary |
|
code string min = 6, max = 6
Unique internal identifier of the debit batch associated with a particular debit instruction.
datetodebit date string
Date to debit of the parent debit batch. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. debitbatch.datetodebit={ddMMyyyy}
datetodebitfrom date string
Returns a list of records where the date to debit of the parent batch is on or after the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. debitbatch.datetodebifrom={ddMMyyyy}
datetodebitto date string
Returns a list of records where the date to debit of the parent batch is on or before the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. debitbatch.datetodebito={ddMMyyyy}
|
This documentation is deprecated
Please refer to the updated documentation https://docs.payadvantage.com.au/reference/debit_instructions_post-1
Create a Debit Instruction and add it to an already exisiting Debit Batch. A Debit Instruction must be appended to a Debit Batch Group. Read more about creating Debit Batch Groups here.
Example Request
curl -L -X POST 'https://api.payadvantage.com.au/v3/debit_instructions' \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json' \
-d '{
"DebitBatch": {
"Code": ABC001
},
"DebitInstructions": [
{
"BSBNumber": "012345",
"AccountNumber": "12341234",
"AccountName": "Test Account",
"Amount": 123.45,
"Reference": "Your Ref",
"OnchargeFees": true,
"GroupKey": null
},
{
"BSBNumber": "012345",
"AccountNumber": "9876543",
"AccountName": "Test Account2",
"Amount": 5.50,
"Reference": "Your Ref",
"OnchargeFees": false,
"GroupKey": 123
},
{
...
}
]
}'Example Responses
STATUS 200 // Successful
[
{
"Code": "DI01234",
"Reference": "Your reference",
"GroupKey": null,
"DateCreated": "2020-08-20T11:50:43.235",
"IsProcessed": false,
"BSBNumber": "012345",
"AccountNumber": "12341234",
"AccountName": "Test Account",
"Amount": 123.45,
"RemitterName": "XYZ Trading",
"OnchargeFees": true,
"IsFailAcknowledged": false,
"DebitBatch": {
"Code": "ABC001",
"DateToDebit": "2020-08-20T11:50:43.235"
},
"Payment": null
}
]STATUS 4## // Error
{
"errorCode": "error_code",
"messages": [
"Error message."
]
}
Request Parameters
| Code string Requiredmin = 6, max = 12 |
|---|
| Unique internal identifier assigned to the debit batch by Pay Advantage. This designates the debit batch group these instructions will be added to. You must have setup a debit batch already through our Debit Batch API otherwise this method will not work. |
| BSBNumber string Required for Bank Account min = 6, max = 6 |
| The BSB Number of the account being debited as a string. Set as null if charging a card. |
| AccountNumber string Required for Bank Account min = 4, max = 9 |
| Bank account Number of account being debited. Set as null if charging a card. |
| AccountName string Required for Bank Account min = 2, max = 50 |
| Name of the account being debited. Set as null if charging a card. |
| Amount number Required |
| The payment amount to be charged by the debit instruction. Enter value as a currency amount in AUD e.g. 15.50 |
| Reference string max = 50 |
| An optional placeholder for your own system ID. |
| OnchargeFees boolean |
| Flag that indicates if debit fees are on-charged to the customer or not. If true, any additional service fees will be added to the amount to be debited. |
| GroupKey string max = 50 |
| Optional field for grouping related instructions together. The same group key may be used across any number of batches over any period of time. These are covered in more detail in the overview of our Debit Instruction API at the top of this page. |
This documentation is deprecated
Please refer to the updated documentation https://docs.payadvantage.com.au/reference/debit_instructions_delete-1
Deletes a Debit Instruction using its code as an identifier.
A debit instruction can be deleted as long as the “DebitBatch” it belongs to is not confirmed, authorised, or processed. You can delete a single instruction or multiple instructions by separating the {code} with a comma. You can delete up to a maximum of 1,000 codes per delete request e.g. v3/debit_instructions/{code},{code},{...}
Example Request
curl -L -X DELETE 'https://api.payadvantage.com.au/v3/debit_instructions/{code},{code},{...}' \
-H 'Authorization: Bearer {access_token}'Example Responses
STATUS 200 // Successful
{
}STATUS 4## // Error
{
"errorCode": "error_code",
"messages": [
"Error message."
]
}
This documentation is deprecated
Returns a list of debit instructions where the payment has failed (most recent first by default).
To simplify the management and handling of debit instructions Pay Advantage provides a helper method to quickly retrieve and “acknowledge” debit instruction failures. When a debit instructions payment fails (which can take several business days for bank accounts) we will combine these across all batches and make them available for handling in your own system.
Once a failure is acknowledged it will no longer be returned by this method. It can still be accessed later through the view debit instruction record methods
Example Request
curl -L -X GET 'https://api.payadvantage.com.au/v3/debit_instructions_failed' \
-H 'Authorization: Bearer {access_token}' \Example Responses
STATUS 200 // Successful
{
"Records": [
{
"Code": "DI12345",
"Reference": "Your reference",
"GroupKey": null,
"DateCreated": "2020-10-03T16:41:06.63",
"IsProcessed": true,
"BSBNumber": "012345",
"AccountNumber": "12341234"
"AccountName": "Bob Smith",
"Amount": 87.50,
"RemitterName": "XYZ Trading",
"OnchargeFees": true,
"IsFailAcknowledged": false,
"DebitBatch": {
"Code": "DB123123",
"DateToDebit": "2020-10-05T00:00:00.00"
},
"Payment": {
"Code": "P12345",
"DatePaid": "2020-10-06T16:41:06.63",
"DateFailed": null,
"FailCode": null,
"FailReason": null,
"Amount": 88.45
}
},
{
...
}
],
"Meta": {
"page": 0,
"recs_per_page": 15,
"total_recs": 1500
}
}
STATUS 4## // Error
{
"errorCode": "error_code",
"messages": [
"Error message."
]
}
If required you can create more complex filters using the fields available for filtering on debit instructions, for example:
# Failed debit instructions for a week that have not been acknowledged
curl -L -X GET 'https://api.payadvantage.com.au/v3/debit_instructions?isfailacknowledged=false&payment.datefailedfrom=20042014&payment.datefailedto=26042014' \
-H 'Authorization: Bearer {access_token}' \Alternatively you can also query settled payments to only retrieve payments that have cleared and settled to your bank account.
Query Parameters
Parameter used in the GET function URL.
| page integer |
|---|
| The page number you want to view using the zero-based index i.e. page=0 will return page 1 of direct debit Records. If the page index is greater than the last page, you will be returned an empty page. Negative indexes will return an error. |
| per_page integer min = 0, max = 1000 |
| Number of records to view per page. By default the value is 100. Values greater than the max value, or negative values will return an error. |
| sort string array |
| Lets you sort direct debit records by a defined set of fields. You can sort by one field e.g. sort={field1} or by many e.g. sort={field1},{field2} A minus symbol (-) in front of the field indicates the descending order for that field only e.g. sort={field1},-{field2} will sort field1 by ascending but field2 by descending. Valid Field Strings:
|
| code string min = 6, max = 6 |
| Unique internal identifier assigned to the debit instruction record by Pay Advantage. This cannot be changed. Returns a single direct debit record. |
| reference string min = 2, max = 20 |
| An optional placeholder for your own system ID. |
| amount number |
| Amount to be debited (excluding fees) in AUD e.g. $100 would be amount=100.00 |
| amountfrom number |
| Returns an array of records where the amount is equal to or more than the value queried. Amount needs to be entered in AUD e.g. $100 would be amount=100.00 |
| amountto number |
| Returns an array of records where the amount is equal to or less than the value queried. Amount needs to be entered in AUD e.g. $100 would be amount=100.00 |
| payment Dictionary |
|
code string min = 6, max = 6
Unique internal identifier of the payment associated with a particular debit instruction.
amountincfees number
Total amount that was charged for the payment (inclusive of fees). Amount needs to be entered in AUD e.g. $100 would be amountincfees=100.00
amountincfeesfrom number
Returns an array of records where the total payment amount (inclusive of fees) is equal to or more than the value queried. Amount needs to be entered in AUD e.g. $100 would be amountincfeesfrom=100.00
amountincfeesto number
Returns an array of records where the total payment amount (inclusive of fees) is equal to or less than the value queried. Amount needs to be entered in AUD e.g. $100 would be amountincfeesto=100.00
datepaid date string
Returns a list of records based on date they were paid. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datepaid={ddMMyyyy}
datepaidfrom date string
Returns a list of records that were paid on or after the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datepaidfrom={ddMMyyyy}
datepaidto date string
Returns a list of records that were paid on or before the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datepaidto={ddMMyyyy}
datefailed date string
Returns a list of records based on date they were failed. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datefailed={ddMMyyyy}
datefailedfrom date string
Returns a list of records that were failed on or after the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datefailedfrom={ddMMyyyy}
datefailedto date string
Returns a list of records that were failed on or before the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datefailedto={ddMMyyyy}
dateclears date string
Returns a list of records based on date they cleared. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. dateclears={ddMMyyyy}
dateclearsfrom date string
Returns a list of records that were cleared on or after the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. dateclearsfrom={ddMMyyyy}
dateclearsto date string
Returns a list of records that were cleared on or before the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. dateclearsto={ddMMyyyy}
|
| datecreated date string |
| Returns debit instruction records based on date and time they were created. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datecreated={ddMMyyyy} |
| datecreatedto date string |
| Returns debit instruction records that were created before or on the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datecreatedto={ddMMyyyy} |
| datecreatedfrom date string |
| Returns debit instruction records that were created after or on the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. datecreatedfrom={ddMMyyyy} |
| bsbnumber string min = 6, max = 6 |
| The BSB Number of the account being debited. |
| accountnumber string min = 4, max = 9 |
| Bank account Number of account being debited. |
| onchargefees boolean |
| Flag that indicates if debit fees are on-charged to the customer or not. If true, any additional service fees will be added to the amount to be debited. |
| isprocessed boolean |
| Flag that indicates if debit instruction has been processed. |
| isfailacknowledged boolean |
| If this debit instruction has failed, this flag will indicate whether that failure has been acknowledged. If the instruction debit hasn't failed this will return false. |
| debitbatch Dictionary |
|
code string min = 6, max = 6
Unique internal identifier of the debit batch associated with a particular debit instruction.
datetodebit date string
Date to debit of the parent debit batch. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. debitbatch.datetodebit={ddMMyyyy}
datetodebitfrom date string
Returns a list of records where the date to debit of the parent batch is on or after the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. debitbatch.datetodebifrom={ddMMyyyy}
datetodebitto date string
Returns a list of records where the date to debit of the parent batch is on or before the date queried. We accept date strings as either YYYYMMDD or DDMMYYYY however, these do not need to be declared e.g. debitbatch.datetodebito={ddMMyyyy}
|
This documentation is deprecated
Please refer to the updated documentation https://docs.payadvantage.com.au/reference/debit_instructions_acknowledge_fail_put-1
This endpoint will soon be depreciated. New merchants should implement push/pull webhooks to handle dishonours.
The API contains a feature to mark failures as acknowledged. This provides a fast method for identification of which records have been dealt with. Once acknowledged, failed debit instructions will stop appearing in the returned list of failed debit instructions.
You can acknowledge a single failure or multiple by separating the {code} with a comma. You can acknowledge up to a maximum of 1,000 codes per delete request e.g. v3/debit_instructions/{code},{code},{...}/ackfail
Example Request
curl -L -X PUT 'https://api.payadvantage.com.au/v3/debit_instructions/{code},{code},{...}/ackfail' \
-H 'Authorization: Bearer {access_token}'Example Responses
STATUS 200 // Successful
{
"Records": [
{
"Code": "DI12345",
"Reference": "Your reference",
"GroupKey": null,
"DateCreated": "2020-10-03T16:41:06.63",
"IsProcessed": true,
"BSBNumber": "012345",
"AccountNumber": "12341234"
"AccountName": "Bob Smith",
"Amount": 87.50,
"RemitterName": "XYZ Trading",
"OnchargeFees": true,
"IsFailAcknowledged": true,
"DebitBatch": {
"Code": "DB123123",
"DateToDebit": "2020-10-05T00:00:00.00"
},
"Payment": {
"Code": "P12345",
"DatePaid": "2020-10-06T16:41:06.63",
"DateFailed": null,
"FailCode": null,
"FailReason": null,
"Amount": 88.45
}
},
{
...
}
],
"Meta": {
"page": 0,
"recs_per_page": 100,
"total_recs": 2
}
}STATUS 4## // Error
{
"errorCode": "error_code",
"messages": [
"Error message."
]
}
Comments
0 comments
Please sign in to leave a comment.