Our Direct Debit API lets you generate a link to share with your customers so they can authorise recurring payments online. You can also get a direct debit record, or a set of direct debit records that show details such as frequency, amount, date created etc.
This API doesn't handle the uploading of paper forms for direct debits and is not used to manage Active & Draft direct debits. This will need to be done through our web-app interface.
Endpoints
GET '/direct_debits'
GET '/direct_debits/{code}'
POST '/direct_debits'
DELETE '/direct_debits/{code}'This documentation is deprecated
Please refer to the updated documentation https://docs.payadvantage.com.au/reference/direct_debits_get-1
Returns a direct debit record using the Code value as an identifier.
Example Request
curl -L -X GET 'https://api.payadvantage.com.au/v3/direct_debits/{code}' \
-H 'Authorization: Bearer {access_token}' \Example Responses
STATUS 200 // Successful
{
"Code": "ABC123",
"AuthorisationLinks": [
{
"Link": "https://payadvantage.com.au/Authorise/DDAuthorise.aspx?code=1234abcd",
"Expiry": "2020-11-02T00:00:00.00"
}
],
"DateCreated": "2020-10-03T16:41:06.63",
"Status": "Draft",
"Customer": {
"Code": "C12345",
"Name": "Bob Smith",
"CustomRef": null
},
"Description": "Weekly Membership",
"ExternalID": null,
"UpfrontAmount": 45.00,
"UpfrontDate": "2020-11-09T00:00:00",
"RecurringAmount": 25.00,
"RecurringStartDate": "2020-11-09T00:00:00",
"Frequency": "weekly",
"EndConditionAmount": 5000.00,
"FailureOption": "3days",
"OnchargedFees": [
"dishonour"
]
}
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 direct debit by Pay Advantage. This cannot be changed. Returns a single direct debit record. |
This documentation is deprecated
Please refer to the updated documentation https://docs.payadvantage.com.au/reference/direct_debits_search-1
Returns a list of direct debit records arranged by creation date (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. As this endpoint is only designed to assist in creating direct debits only draft and rejected items will be returned. To see the status of an individual direct debit you will need to store the code for the direct debit and access using direct_debits/{code}.
Example Request
curl -L -X GET 'https://api.payadvantage.com.au/v3/direct_debits' \
-H 'Authorization: Bearer {access_token}' \Example Responses
STATUS 200 // Successful
{
"Records": [
{
"Code": "ABC123",
"AuthorisationLinks": [
{
"Link": "https://payadvantage.com.au/Authorise/DDAuthorise.aspx?code=1234abcd",
"Expiry": "2020-11-02T00:00:00.00"
}
],
"DateCreated": "2020-10-03T16:41:06.63",
"Status": "Draft",
"Customer": {
"Code": "C12345",
"Name": "Bob Smith",
"CustomRef": null
},
"Description": "Weekly Membership",
"ExternalID": null,
"UpfrontAmount": 45.00,
"UpfrontDate": "2020-11-09T00:00:00"
"RecurringAmount": 25.00,
"RecurringDateStart": "2020-11-21T00:00:00",
"Frequency": "weekly",
"EndConditionAmount": 5000.00,
"FailureOption": "3days",
"OnchargedFees": [
"dishonour"
]
},
{
...
}
],
"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 = 6 |
| Unique internal identifier assigned to the direct debit by Pay Advantage. This cannot be changed. Returns a single direct debit record. |
| customer Dictionary |
|
code string min = 6, max = 6
Unique internal identifier of the customer making the direct debit payment.
|
| datecreated date string |
| Returns direct debit 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 direct debit 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 direct debit 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} |
| recurringamount number |
| Returns direct debit records based on a specific recurring amount. Best practice is to enter number as if writing a currency in dollars and cents e.g. $15 AUD would be ongoingamount={15.00} |
| recurringamountto number |
| Returns direct debit records with a recurring amount less than or equal too the value queried. Best practice is to enter number as if writing acurrency in dollars and cents e.g. $15 AUD would be ongoingamount={15.00} |
| recurringamountfrom number |
| Returns direct debit records with a recurring amount more than or equal too the value queried. Best practice is to enter number as if writing acurrency in dollars and cents e.g. $15 AUD would be ongoingamount={15.00} |
| externalid string min = 1, max = 50 |
| Optional identifier from an external system that can be recorded as an attribute against this customer. Returns any customer with this id. |
This documentation is deprecated
Please refer to the updated documentation https://docs.payadvantage.com.au/reference/direct_debits_post-1
Generates a direct debit request link that can be sent to, or shared with a customer digitally. Signing this request will create an active direct debit using parameter attributes sent in the request body.
If your customer doesn't have a valid email and mobile number, your request will fail an appropriate error will be returned. You will need to update your customers details to include an email and mobile number. This method is covered in the customer API here.
Example Request
curl -L -X POST 'https://api.payadvantage.com.au/v3/direct_debits' \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json' \
-d '{
"Customer": {
"Code": "C12345"
},
"Description": "Membership Fees",
"ExternalID": "ABC001",
"UpfrontAmount": 45.00,
"UpfrontDate": "2020-11-09T00:00:00",
"RecurringAmount": 20.00,
"RecurringDateStart": "2020-11-21T00:00:00",
"Frequency": "weekly",
"EndConditionAmount": null,
"FailureOption": "3days",
"ReminderDays": 1,
"OnchargedFees": [
"dishonour"
]
}'Example Responses
STATUS 201 // Successful
{
"Code": "ABC123",
"AuthorisationLinks": [
{
"Link": "https://payadvantage.com.au/Authorise/DDAuthorise.aspx?code=1234abcd",
"Expiry": "2020-11-09T00:00:00.00"
}
],
"DateCreated": "2020-11-07T16:41:06.63",
"Status": "Draft",
"Customer": {
"Code": "C12345",
"Name": "Bob Smith",
"CustomRef": null
},
"Description": "Weekly Membership",
"ExternalID": null,
"UpfrontAmount": 45.00,
"UpfrontDate": "2020-11-09T00:00:00",
"RecurringAmount": 20.00,
"RecurringDateStart": "2020-11-21T00:00:00",
"Frequency": "weekly",
"EndConditionAmount": null,
"FailureOption": "3days",
"ReminderDays": 1,
"OnchargedFees": [
"dishonour"
]
}STATUS 4## // Error
{
"errorCode": "error_code",
"messages": [
"Error message."
]
}Request Parameters
| Customer dictionary Required |
|---|
|
Code string Required
Unique internal identifier assigned to the customer by Pay Advantage. This cannot be changed. Used to identify the customer this direct debit request will be sent to.
|
| ExternalID string min = 1, max = 50 |
| Identifier from an external system that can be appended to a direct debit request. |
| Description string Required |
| A description of the direct debit that will be visible to their merchant and the customer. Write something that tells both the customer and the merchant what this payment is for e.g. "Membership Fees". |
| UpfrontAmount number |
| The total amount that will be charged for a one-off upfront payment e.g. "UpfrontAmount=25.50". Use this if you want the first amount to have a discount, or bundle any setup costs into the first payment. If you want the first amount to be the same as the recurring amount, set this value as null. |
| UpfrontDate date string |
| The date on which the upfront amount is to be charged. Enter your date string in this format "YYYY-MM-DD". If the request hasn't been signed or approved before the declared date, instalments will not be processed and the request link will become invalid. |
| ReminderDays number |
| The number of days before a debit is due to send a debit reminder to the customer. Must be a value between 0 and 3 (0 = no reminder is sent). |
| OnChargedFees string array |
| Choose what fees you want to on-charge for this direct debit. If this isn't posted in the request these will default based on your customer setting in our portal interface. Learn more about what these fees represent in our documentation here.
Valid Field Strings:
|
| RecurringAmount number Required |
| This is the recurring amount that will be charged every instalment. If there is a first amount set, the first instalment will not use this amount. Enter value as a currency amount in AUD e.g. 15.50 |
| RecurringDateStart date string Required |
| The date on which recurring payments will begin. Enter your date string in this format "YYYY-MM-DD". If the request hasn't been signed or approved before the declared date, instalments will not be processed and the request link will become invalid. |
| Frequency string list Required |
| Specifies the frequency instalments will occur from the start date.
Valid Field Strings:
|
| EndConditionAmount number Required |
| Lets you set a total amount to be paid at which point the direct debit will complete e.g. 1200.00 would process instalments until $1,200 is paid. This value can be set to null. If set to null the direct debit will only end when it is manually cancelled by you. |
| FailureOption string list |
| What action is automatically taken when a direct debit instalment fails. Learn more about what these values represent in our documentation here. If no value is set these will default based on your failures and fees defaults that can be set through our user interface.
Valid Field Strings:
|
This documentation is deprecated
Please refer to the updated documentation https://docs.payadvantage.com.au/reference/direct_debits_delete-1
Use this endpoint to delete a direct debit request that is still using a draft status. This endpoint will not delete Direct Debits that have been successfully authorised.
Once a Direct Debit has been authorised and begun you cannot delete it, the only way it can no longer be active is by completing or being manually cancelled through our web-app interface.
Example Request
curl -L -X DELETE 'https://api.payadvantage.com.au/v3/direct_debits/{code}' \
-H 'Authorization: Bearer {access_token}' \Example Responses
STATUS 200 // Successful
{}STATUS 4## // Error
{
"errorCode": "error_code",
"messages": [
"Error message."
]
}Query Parameters
Parameters used in the DELETE functions URL.
| code string min = 6, max = 6 |
|---|
| Unique internal identifier assigned to the direct debit by Pay Advantage. This cannot be changed. Returns a single direct debit record. |
Comments
0 comments
Please sign in to leave a comment.