Getting Started

Introduction

The eDebit Direct Debit Integration API has been developed to facilitate direct debit integration for software developers/vendors and web developers from differing industries and market segments.

The amount to be debited can vary from period to period and may be controlled by the integrated software. Where the amount does not vary then it may be useful to utilise the CreateSchedule function detailed in this API as this instructs our process to deduct a fixed amount for either a fixed period of time and then to discontinue debiting or until further notice.

The eDebit Direct Debit Service may only be used to facilitate debits in Australia and New Zealand. International rules and regulations with regards to debits from accounts and cards stipulate that the business for whom we conduct the debit (the end user of the integrated software) must be conducting their business in Australia or New Zealand. The API CANNOT be used to undertake a debit from a US issued card for a US based business, the API CAN be used to debit a US issued card for an Australian/NZ based business. Bank accounts held by Australian or New Zealand banks are the only bank accounts that may be debited.

This document has been produced to provide software vendors and developers with the required information to enable them to integrate direct debit functionality into their software/web application. It should be noted that this document supersedes all prior versions. This version of the API introduces downstream compliance with PCIDSS requirements. Please refer to the section on PCIDSS Compliance below.

The API is subject to change and amendment and development teams are advised to obtain the latest copy of the API and to discuss projected amendments with eDebit prior to commencing development.

Prerequisites

Developers and software vendors are advised of the following prerequisites;

  1. The business using the integrated application must have registered with eDebit and must have been provided with both an account number and integration key. The account number and key we provide are unique to the business and are required to be made accessible to the application when calling functions. Whether this is stored in a database or a configuration file is at the discretion of the software vendor.
  2. The integrated software must be registered with eDebit and must have been provided with a unique API key. A valid API key is required when calling functions.
  3. The integrated software must have on demand access to the web and have the capacity to send requests using SSL
  4. The development environment must provide for a 'WebBrowser control' that can display a URL that will be provided.
  5. Where paperless sign up and authorisation is required then the integrated software must store or gather information with regards to the drivers licence of the account/card holder and this must be included in the 'passed in' values to the relevant API call. There is no requirement for the integrated software to store these values.
  6. Provision for a unique account holder reference number, this may be a reference, membership or internal account number. However it must be unique and cannot be reused at any time.
  7. Provision for a unique debit reference that identifies each debit for each account holder. This may be the primary key in a table for example. This will be used by the eDebit system to provide return path information on the debit status and permit the software to access daily updates on the progress of a debit.
  8. The integrated software must be able to determine the type of account to be debited, card or bank, prior to registration of the account.
  9. Where the schedule function is not utilised then the integrated software must provide the data instructing us to debit a given client on the relevant date.
  10. Please be advised that the usage of the Schedule function is end user dependent. An end user of the integrated software may choose to use or not the Schedule function based on their settings agreed with eDebit. However this setting applies to all account holders to be debited by that end user. An end user cannot use the Schedule function for some account holders and not others. In principle eDebit advises that each software application provides an internal billing or invoicing function to create and transmit the data to eDebit. The Schedule function is best suited to business owned web sites offering a fixed price product or service directly debiting their own clients and where there is an integration/tokenisation requirement.
  11. All string values should be validated. Any control characters should be removed. Empty strings must be passed in where the value is optional and maximum length adhered to. The eDebit system will drop invalid characters and truncate strings that exceed the required length and this may lead to unexpected behaviour or data entry.
  12. Where a value is to be passed in as part of the POST then this should be appended to the URL as a query string ensuring that the key is the same as that listed. Note keys are case sensitive and you should ensure that any casing is correct.
  13. We advise that POSTing should be undertaken using dynamic/programmatic web requests rather than setting the POSTBack URL on form submission to the provided URL. The latter option will inhibit the ability of the software to capture and utilise the return values, in addition information will be displayed with no formatting or adherence to the web site CSS/styles.

PCIDSS Compliance

eDebit in conjunction with its banking partners has been able to provide a PCIDSS compliant solution that has been extended to software that is integrated using this API as a result of the tokenisation functionality.

eDebit recognises that integrated software may have conflicting requirements with regards to storage of card or account information and that end users who conduct their own debits or use alternate service providers may require this information to be stored locally and this may provide a challenge. Storage of the masked number in combination with the expiry date and name on the card is permitted under the PCI requirements where this is a requirement of the software, as a result database integrity may not be compromised.

Downstream compliance is dependent upon a number of key factors as follows;

  1. Software integrated using this API must not store credit card or bank account numbers in full. Our API provides a masked number that can be used for verification; this consists of the first 6 and last 3 digits of the card number or the last 3 digits of the bank account number.
  2. Software vendors intending to utilise our API are required to confirm in writing that when using this API that full card/account numbers are not stored or saved at any time.

First Steps

The procedure of entering a new client, adding payment details and setting up a debit cycle can be completed in 3 steps;


Important Information

PLEASE NOTE the Daily Billing Process is undertaken at approximately 2pm Sydney Time (GMT +11) every week day except public holidays. We recommend that any Edits/Updates/Additions are performed before 1:30pm or after 3pm. If you wish debits to be processed on the same day they are submitted we must recevie the request before 1:30pm.

CheckService

Quickly check the current status of the eDebit API and test your basic required information.

GET | https://api.edebit.com.au/CheckService/
curl "https://api.edebit.com.au/CheckService/?Key=123ABC456&BusKey=ABC123DEF&eDebitNumber=100100"
NameTypeMax LengthRequiredExampleDescription
KeyString----YesUnique key provided by eDebit to the software developer.
BusKeyString----YesUnique key provided by eDebit to the individual business.
eDebitNumberInt6Yes100100Account number provided to business by eDebit.

Successful Result


{
    "result": "successful",
    "message": "eDebit API Online"
}
	

NewClient

This call allows you to add a new client into the relevant account. This is the first step to getting a client into the eDebit system and processing debits.

POST | https://api.edebit.com.au/NewClient/
curl -d "eDebitNumber=100100&Key=123ABC456&BusKey=ABC123DEF&ClientReference=NewClient20&FirstName=John&LastName=Smith" -X POST https://api.edebit.com.au/NewClient/
NameTypeMax LengthRequiredExampleDescription
KeyString----YesUnique key provided by eDebit to the software developer.
BusKeyString----YesUnique key provided by eDebit to the individual business.
eDebitNumberInt6Yes100100Account number provided to business by eDebit.
ClientReferenceString11Yes123ABC456This reference must be unique and will be used in future calls to identify the client.This could be the reference you use in internal systems for this client.
FirstNameString45NoJohnClient's first name.
LastNameString45YesSmithClient's last or business name.
AddressString45No1 Address StClient's street address.
CityString45NoSydneyClient's suburb / city.
StateString3NoNSWClient's state.
PostcodeInt4No2116Client's postcode.
TelInt10No0299994455Client's telephone number, landline or mobile.
EmailString100Noemail@email.com.auClient's valid email address.

Successful Result


{
    "result": "successful",
    "message": {
        "eDebitNumber": "100100",
        "ClientReference": 123ABC456,
        "Created": "2015-05-01 13:17:30"
    }
}
	

Failed Result


{
    "result": "failed",
    "error": "Fata Error - No Data Saved"
}
	

UpdateClient

This call enables you to change the information eDebit has saved for a selected client. Please note the client must already be present in the relevant account.

Warning: All information must be passed in regardless of if it is updated or not, failure to do so will result in data being removed.

POST | https://api.edebit.com.au/UpdateClient/
curl -d "eDebitNumber=100100&Key=123ABC456&BusKey=ABC123DEF&ClientReference=NewClient20&NewClientReference=Client1&FirstName=John&LastName=Smith" -X POST https://api.edebit.com.au/UpdateClient/
NameTypeMax LengthRequiredExampleDescription
KeyString----YesUnique key provided by eDebit to the software developer.
BusKeyString----YesUnique key provided by eDebit to the individual business.
eDebitNumberInt6Yes100100Account number provided to business by eDebit.
ClientReferenceString11Yes123ABC456Client's reference number, set up during NewClient call.
NewClientReferenceString11NoNewRefNumClient's new reference if you wish to update.
FirstNameString45NoJohnClient's first name.
LastNameString45YesSmithClient's last or business name.
AddressString45No1 Address StClient's street address.
CityString45NoSydneyClient's suburb / city.
StateString3NoNSWClient's state.
PostcodeInt4No2116Client's postcode.
TelInt10No0299994455Client's telephone number, landline or mobile.
EmailString100Noemail@email.com.auClient's valid email address.

Successful Result


{
    "result": "successful",
    "message": {
        "eDebitNumber": "100100",
        "ClientReference": "123ABC224",
        "Updated": "2015-05-01 13:19:06"
    }
}
	

Failed Result


{
    "result": "failed",
    "error": <Error Message>
}
	

Possible Error Messages

MessageDescription
No Matching ReferenceThe provided client reference number cannot be found.
New Reference Already In UseThe client reference number must be unique.
Fatal Error - No Data Saved

GetClientInfo

This call enables you to get the personal information related to either a selected client or all clients that are currently entered. This call was developed to work in two ways;

  1. Creating a select list of all clients for an overall "select your client" page or drop down.
  2. Once a client was selected making the call again but with the ClientReference to populate the personal information in an editable section.
GET | https://api.edebit.com.au/GetClientInfo/
curl "https://api.edebit.com.au/GetClientInfo/?Key=123ABC456&BusKey=ABC123DEF&eDebitNumber=100100&ClientReference=JSmith1"
NameTypeMax LengthRequiredExampleDescription
KeyString----YesUnique key provided by eDebit to the software developer.
BusKeyString----YesUnique key provided by eDebit to the individual business.
eDebitNumberInt6Yes100100Account number provided to business by eDebit.
ClientReferenceString11NoJSmith1If no ClientReference is supplied all entered clients will be returned.

Successful Result


{
    "result": "successful",
    "message": [
        {
            "ClientReference": "JSmith1",
            "FirstName": "John",
            "LastName": "Smith",
            "Address": "1 Street Address",
            "City": "Sydney",
            "State": "NSW",
            "Postcode": "2777",
            "Tel": "0400123456",
            "Email": "email@email.com.au",
            "Status": <status>,
			"isUFN" : "True"
        }
    ]
}
		

Status Values

Active
Non-Active

Failed Result


{
    "result": "failed",
    "error": <Error Message>
}
	

Possible Error Messages

MessageDescription
ClientReference RequiredThe Client Reference Number must be included.
No Client FoundThere is no client matching the provied reference number.
Fatal Error - No Data Saved

CheckClientStatus

This call allows you to easily check if a client has been entered into a given account, if they have any valid payment details and if the required signed authority form has been completed.

GET | https://api.edebit.com.au/CheckClientStatus/
curl "https://api.edebit.com.au/CheckClientStatus/?Key=123ABC456&BusKey=ABC123DEF&eDebitNumber=100100&ClientReference=Client123"
NameTypeMax LengthRequiredExampleDescription
KeyString----YesUnique key provided by eDebit to the software developer.
BusKeyString----YesUnique key provided by eDebit to the individual business.
eDebitNumberInt6Yes100100Account number provided to business by eDebit.
ClientReferenceString11Yes123ABC456Client's reference number, set up during NewClient call.

Successful Result

Credit Card


{
    "result": "successful",
    "message": {
        "Valid Client": "TRUE",
        "Payment Method": "Credit Card",
        "Valid CC Details": "FALSE",
        "Valid CC Expiry": "TRUE",
        "Valid CC Name": "TRUE",
        "Authority Form Saved": "TRUE"
    }
}
	

Bank Account


{
    "result": "successful",
    "message": {
        "Valid Client": "TRUE",
        "Payment Method": "Bank Account",
        "Valid BSB": "TRUE",
        "Valid Account Number": "TRUE",
        "Valid Account Name": "TRUE",
        "Authority Form Saved": "TRUE"
    }
}
	

Failed Result


{
    "result": "failed",
    "error": "Invalid ClientReference"
}
	

AddBankInfo

This call enables you to add bank account information for a selected client. Masked details will be returned.

POST | https://api.edebit.com.au/AddBankInfo/
curl -d "eDebitNumber=100100&Key=123ABC456&BusKey=ABC123DEF&ClientReference=NewClient20&BSB=011011&AccountNumber=123456&AccountName=John Smith" -X POST https://api.edebit.com.au/AddBankInfo/
NameTypeMax LengthRequiredExampleDescription
KeyString----YesUnique key provided by eDebit to the software developer.
BusKeyString----YesUnique key provided by eDebit to the individual business.
eDebitNumberInt6Yes100100Account number provided to business by eDebit.
ClientReferenceString11Yes123ABC456Client's reference number, set up during NewClient call.
BSBInt6Yes011011Valid BSB.
AccountNumberInt9Yes123456Valid Bank account number.
AccountNameString40YesJohn SmithName on Bank account.

Successful Result


{
    "result": "successful",
    "message": {
        "eDebitNumber": "100100",
        "ClientReference": "NewClient20",
        "BSB": "011011",
        "AccountNumber": "XXX456",
        "AccountName": "JOHN SMITH",
        "Saved": "2015-10-19 11:27:30"
    }
}
	

Failed Result


{
    "result": "failed",
    "error": <Error Message>
}
	

Possible Error Messages

MessageDescription
Invalid ClientReferenceThe provided client reference number cannot be found.
Invalid BSBThe provided BSB has failed the validation check.
Invalid AccountNumberThe provided Account Number is invalid.
Invalid AccountNameThe provided Account Name is invalid.
Fatal Error

AddCCInfo

This call enables you to credit card information for a selected client. Masked details will be returned.

POST | https://api.edebit.com.au/AddCCInfo/
curl -d "eDebitNumber=100100&Key=123ABC456&BusKey=ABC123DEF&ClientReference=NewClient20&CCNumber=4916765503007018&Expiry=05/21&CCName=John Smith" -X POST https://api.edebit.com.au/AddCCInfo/
NameTypeMax LengthRequiredExampleDescription
KeyString----YesUnique key provided by eDebit to the software developer.
BusKeyString----YesUnique key provided by eDebit to the individual business.
eDebitNumberInt6Yes100100Account number provided to business by eDebit.
ClientReferenceString11Yes123ABC456Client's reference number, set up during NewClient call.
CCNumberInt16Yes4916765503007018Valid credit card number.
ExpiryString5Yes05/21Valid credit card expiry.
CCNameString40YesJohn SmithName on credit card.

Successful Result


{
    "result": "successful",
    "message": {
        "eDebitNumber": "100100",
        "ClientReference": "NewClient20",
        "CCNumber": "491676XXXXXXX018",
        "Expiry": "05/21",
        "CCName": "JOHN SMITH",
        "Saved": "2015-10-19 11:55:36"
    }
}
	

Failed Result


{
    "result": "failed",
    "error": <Error Message>
}
	

Possible Error Messages

MessageDescription
Invalid CCNumberThe provided Credit Card Number is invalid.
Invalid ExpiryThe provided Expiry Date for the card is invalid.
Invalid CCNameThe provided Card Name is invalid.
Fatal Error

CreateAuthorityForm

This call enables you to produce an authority form and display additional information such as Debit Amount, Number of Debits, Display Transaction Fees, Frequency of Debits, Date of First Debit.

Please Note: If NOT all optional parameters are sent, then the form will state "as per principal agreement."

POST | https://api.edebit.com.au/CreateAuthorityForm/

Drivers Licence Details

curl -d "eDebitNumber=100100&Key=123ABC456&BusKey=ABC123DEF&ClientReference=NewClient20&DLNumber=123ABC456&DLName=John Smith&DLState=NSW" -X POST https://api.edebit.com.au/CreateAuthorityForm/

Signature File

curl -X POST
		-F "eDebitNumber=100100"
		-F "Key=123ABC456"
		-F "BusKey=ABC123DEF"
		-F "ClientReference=NewClient20"
		-F "SigImage=signature.png"
		https://api.edebit.com.au/CreateAuthorityForm/
	
NameTypeMax LengthRequiredExampleDescription
KeyString----YesUnique key provided by eDebit to the software developer.
BusKeyString----YesUnique key provided by eDebit to the individual business.
eDebitNumberInt6Yes100100Account number provided to business by eDebit.
ClientReferenceString11Yes123ABC456Client's reference number, set up during NewClient call.

If using Drivers Licence
DLNumberString15Yes123ABC456Client's Licence number.
DLNameString45YesJohn SmithName on client's licence.
DLStateString3YesNSWState of issue

If using Signature File
SigImageFile50KBYessig.pngValid Extensions (png, jpg, jpeg)

Optional Parameters
DebitAmtDouble6No50.00Amount you wish to debit client.
DebitDateString8No20150501Date of debit. Date must be formatted YYYYMMDD.
DebitFreqString3No7DFrequency of debits. See table above.
UFNInt1No1Should the debits continue until further notice. 1=Yes, 0=No
DebitCountInt2No5Number of debits, only used if UFN is set to 0.
InitialFeeDouble6No100.00A once off intial fee (eg. joining, admin) you wish to charge in addition to DebitAmt on the first debit.

Valid Frequency Strings

FrequencyDescription
7DWeekly
14DFortnightly
28D4 Weekly
1MMonthly
3MQuarterly

Successful Result

Drivers Licence Details


{
    "result": "successful",
    "message": {
        "eDebitNumber": "100100",
        "ClientReference": "123ABC",
        "DLNumber": "123ABC",
        "DLName": "John Smith",
        "DLState": "NSW",
        "Added": "2015-10-15 12:05:40"
    }
}
	

Signature File


{
	"result":"successful",
	"message":{
		"eDebitNumber":"100100",
		"ClientReference":"123ABC",
		"SigImage":"image.png",
		"Sent":"2015-05-05 15:37:14"
	}
}

Failed Result


{
    "result": "failed",
    "error": <Error Message>
}
	

Possible Error Messages

MessageDescription
Invalid ClientReferenceThe provided client reference number cannot be found.
Invalid Client EmailThe provided client email address is invalid.
Invalid Debit Amount (<Debit Amount>)The Debit Amount must be numeric.
Invalid Frequency (<Frequency>)The Frequency must be a valid value.
Invalid Debit Date (<Debit Date>)Debit Date must be 8 characters in length.
Invalid Debit Date Format (<Debit Date>)Debit Date must be in the format yyyymmdd.
Invalid Debit Count (<Debit Count>)Debit Count must be numeric.
Invalid Initial Fee (<Initial Fee>)Initial Fee must be numeric.
Drivers Licence Number RequiredThe Drivers Licence Number is missing.
Drivers Licence Name RequiredThe Drivers Licence Name is missing.
Drivers Licence State RequiredThe Drivers Licence State is missing.
SigImage RequiredThe signature image file is missing
SigImage Size Exceeded <size imagename>The size of the uploaded image needs to be a maximum of 50k.
Invalid File Extension <imagename>Valid Extensions (png, jpg, jpeg)
Error Creating Authority (Invalid Client Email)The provided client email address is invalid.
Error Creating Authority (Invalid Business Email)The provided business email address is invalid.
Online Authorisation Type RequiredEither full Drivers Licence details need to be provided or a signature image file.
Fatal Error, No Data Saved

SignOnline

This call enables you to display a signature capture form within your application. You will need to make this call within an iframe / WebBrowser control as this call will return a data entry page. Once the signature has been successfully saved eDebit will send an email to the account holder. Valid email information for the account holder is required.

GET | https://api.edebit.com.au/SignOnline/
curl "https://api.edebit.com.au/SignOnline/?Key=123ABC456&BusKey=ABC123DEF&eDebitNumber=100100&ClientReference=Client123"
NameTypeMax LengthRequiredExampleDescription
KeyString----YesUnique key provided by eDebit to the software developer.
BusKeyString----YesUnique key provided by eDebit to the individual business.
eDebitNumberInt6Yes100100Account number provided to business by eDebit.
ClientReferenceString11Yes123ABC456Client's reference number, set up during NewClient call.

Successful Result


{
	"result":"successful",
	"message":{
		"eDebitNumber":"100100",
		"ClientReference":"123ABC",
		"Sent":"2015-05-05 15:37:14"
	}
}

Failed Result


{
    "result": "failed",
    "error": <Error Message>
}
	

Possible Error Messages

MessageDescription
Invalid Client EmailThe provided client email address is invalid.
Invalid Signature
Fatal Error, No Data Saved

AddDriversLicence

This call enables you to electronically complete our signed authority form using your clients drivers licence details as proof of identity. During this call we will attempt to email a copy of the signed authority to the account holder. Please note: You must verify the clients Photo ID.

POST | https://api.edebit.com.au/AddDriversLicence/
curl -d "eDebitNumber=100100&Key=123ABC456&BusKey=ABC123DEF&ClientReference=NewClient20&DLNumber=123ABC456&DLName=John Smith&DLState=NSW" -X POST https://api.edebit.com.au/AddDriversLicence/
NameTypeMax LengthRequiredExampleDescription
KeyString----YesUnique key provided by eDebit to the software developer.
BusKeyString----YesUnique key provided by eDebit to the individual business.
eDebitNumberInt6Yes100100Account number provided to business by eDebit.
ClientReferenceString11Yes123ABCClient's reference number, set up during NewClient call.
DLNumberString15Yes123ABC456Client's Licence number.
DLNameString45YesJohn SmithName on client's licence.
DLStateString3YesNSWState of issue

Successful Result


{
    "result": "successful",
    "message": {
        "eDebitNumber": "100100",
        "ClientReference": "123ABC",
        "DLNumber": "123ABC",
        "DLName": "John Smith",
        "DLState": "NSW",
        "Added": "2015-10-15 12:05:40"
    }
}
	

Failed Result


{
    "result": "failed",
    "error": <Error Message>
}
	

Possible Error Messages

MessageDescription
Invalid ClientReferenceThe provided client reference number cannot be found.
Drivers Licence Number RequiredThe Drivers Licence Number is missing.
Drivers Licence Name RequiredThe Drivers Licence Name is missing.
Drivers Licence State RequiredThe Drivers Licence State is missing.

AddDigitalSig

This call enables you to electronically complete our signed authority form using your clients digital signature as proof of identity. This call differs from SignOnline as you need to upload an image file of the signature which has been already captured by your software. During this call we will attempt to email a copy of the signed authority to the account holder. Please note: You must verify the signature provided.

POST | https://api.edebit.com.au/AddDigitalSig/
curl -X POST
		-F "eDebitNumber=100100"
		-F "Key=123ABC456"
		-F "BusKey=ABC123DEF"
		-F "ClientReference=NewClient20"
		-F "SigImage=signature.png"
		https://api.edebit.com.au/AddDigitalSig/
	
NameTypeMax LengthRequiredExampleDescription
KeyString----YesUnique key provided by eDebit to the software developer.
BusKeyString----YesUnique key provided by eDebit to the individual business.
eDebitNumberInt6Yes100100Account number provided to business by eDebit.
ClientReferenceString11Yes123ABCClient's reference number, set up during NewClient call.
SigImageFile50KBYessig.pngValid Extensions (png, jpg, jpeg)

Successful Result


{
    "result": "successful",
    "message": {
        "eDebitNumber": "100100",
        "ClientReference": "123ABC",
        "SigImage": "signature.png",
        "Saved": "2015-10-15 12:05:40"
    }
}
	

Failed Result


{
    "result": "failed",
    "error": <Error Message>
}
	

Possible Error Messages

MessageDescription
Invalid ClientReferenceThe provided client reference number cannot be found.
Error Uploading File
SigImage RequiredNo Image has been uploaded.
SigImage Size RequiredThe size of the uploaded image needs to be a maximum of 50k.
Invalid File ExtensionValid Extensions (png, jpg, jpeg)
Fatal Error

GetMaskedInfo

Use this call to retrieve the masked payment information entered during the AddBankInfo or AddCCInfo call. As this information is masked it may be displayed to the user.

GET | https://api.edebit.com.au/GetMaskedInfo/
curl "https://api.edebit.com.au/GetMaskedInfo/?Key=123ABC456&BusKey=ABC123DEF&eDebitNumber=100100&ClientReference=Client123"
NameTypeMax LengthRequiredExampleDescription
KeyString----YesUnique key provided by eDebit to the software developer.
BusKeyString----YesUnique key provided by eDebit to the individual business.
eDebitNumberInt6Yes100100Account number provided to business by eDebit.
ClientReferenceString11Yes123ABC456Client's reference number, set up during NewClient call.

Successful Result


{
    "result": "successful",
    "message": {
        "acc_holder": "JOHN SMITH",
        "acc_alias": "xxx456",
        "acc_info": "012-012"
    }
}
	

Failed Result


{
    "result": "failed",
    "error": <Error Message>
}
	

Possible Error Messages

MessageDescription
Invalid ClientReferenceThe provided client reference number cannot be found.
Invalid Payment TypeThe recorded payment type is not Bank Account or Credit Card.

AddDebit

This call is used to add a single transaction for the selected client on the required day. If you have an automated process or billing procedure this call will need done for each transaction you wish to process on that day.

POST | https://api.edebit.com.au/AddDebit/
curl -d "eDebitNumber=100100&Key=123ABC456&BusKey=ABC123DEF&ClientReference=NewClient20&DebitAmt=44.90&DebitDesc=PT Session&DebitReference=20152245&DebitDate=20150501&DebitFee=1&CreditCardFee=1" -X POST https://api.edebit.com.au/AddDebit/
NameTypeMax LengthRequiredExampleDescription
KeyString----YesUnique key provided by eDebit to the software developer.
BusKeyString----YesUnique key provided by eDebit to the individual business.
eDebitNumberInt6Yes100100Account number provided to business by eDebit.
ClientReferenceString11Yes123ABC456Client's reference number, set up during NewClient call.
DebitAmtDouble6Yes50.00Amount you wish to debit client.
DebitDescString45YesPT SessionDescription for debit, this does not appear on client's bank or credit card statement.
DebitReferenceString20Yes1A2B3CUnique reference for the debit, this will be used later to check the status.
DebitDateString8Yes20150501Date of debit. Date must be formatted YYYYMMDD.
DebitFeeInt1Yes0 or 1This flag will determine if we add the transaction fee onto the debit amount supplied. If you are calculating fees then this must be set to 0.
CreditCardFeeInt1Yes0 or 1This flag will determine if we add the merchant service fee onto the debit amount supplied. If you are calculating fees then this must be set to 0.

Successful Result


{
    "result": "successful",
    "message": {
        "eDebitNumber": "100100",
        "ClientReference": "123ABC456",
        "DebitReference": "1A2B3C",
        "DebitDesc": "PT Session",
        "Added": "2015-05-01 14:01:34"
    }
}
	

Failed Result


{
    "result": "failed",
    "error": <Error Message>
}
	

Possible Error Messages

MessageDescription
Invalid ClientReferenceThe provided client reference number cannot be found.
DebitReference RequiredDebit Reference is missing.
DebitReference Already UsedThe Debit Reference must be unique.

RemoveDebit

This call is used to either remove a single planned transaction or all planned transactions for the selected client.

POST | https://api.edebit.com.au/RemoveDebit/
curl -d "eDebitNumber=100100&Key=123ABC456&BusKey=ABC123DEF&ClientReference=NewClient20&DebitReference=20152245" -X POST https://api.edebit.com.au/RemoveDebit/
NameTypeMax LengthRequiredExampleDescription
KeyString----YesUnique key provided by eDebit to the software developer.
BusKeyString----YesUnique key provided by eDebit to the individual business.
eDebitNumberInt6Yes100100Account number provided to business by eDebit.
ClientReferenceString11Yes123ABC456Client's reference number, set up during NewClient call.
DebitReferenceString20Yes1A2B3CUnique reference for a single debit or ALL to cancel all planned transactions.

Successful Result


{
    "result": "successful",
    "message": {
        "eDebitNumber": "100100",
        "ClientReference": "123ABC456",
        "DebitReference": "123ABC",
        "Removed": "2015-11-15 12:00:00"
    }
}
	

Failed Result


{
    "result": "failed",
    "error": <Error Message>
}
	

Possible Error Messages

MessageDescription
Invalid DebitReferenceThe Debit Reference is either invalid or missing.
Invalid ClientReferenceThe provided client reference number cannot be found.
No Matching DebitReferenceThe provided Debit Reference cannot be found.
Debit Has Already Been Processed, Unable to Remove (Reference: [DebitReference])This debit has already been processed by our billing system so we are unable to remove due to it no longer being planned.

GetDebits

This call returns all debits relating to the client including status, description, amount and date.

GET | https://api.edebit.com.au/GetDebits/
curl "https://api.edebit.com.au/GetDebits/?Key=123ABC456&BusKey=ABC123DEF&eDebitNumber=100100&ClientReference=123ABC456&DebitStatus=&DebitDate=&Datesort=ASC"
NameTypeMax LengthRequiredExampleDescription
KeyString----YesUnique key provided by eDebit to the software developer.
BusKeyString----YesUnique key provided by eDebit to the individual business.
eDebitNumberInt6Yes100100Account number provided to business by eDebit.
ClientReferenceString11Yes/No123ABC456Client's reference number, set up during NewClient call. ClientReference is required if the DebitDate or DebitStatus parameters are not supplied.
DebitDateInt8No20170101Limit results to specific debit date. Valid format = YYYYMMDD
DebitStatusString10NoFailedLimit results to specific debit status. Valid options = Planned, Failed & Successful
DateSortString4NoDESCASC or DESC, Default is ASC

Successful Result


{
    "result": "successful",
    "message": [
        {
            "DebitAmt": "20.89",
            "DebitDesc": "Debit",
            "DebitReference": "",
            "DebitDate": "2016-07-01",
            "DebitStatus": "PLANNED"
            "DefaultDate": "",
			"DefaultFee": "",
			"DebitFee": "0.55",
			"CreditCardFee":"0.70",
			"ClientReference": "123ABC456",
			"InitialFee": "5.00"
        },
        {
            "DebitAmt": "20.89",
            "DebitDesc": "Debit",
            "DebitReference": "",
            "DebitDate": "2016-09-01",
            "DebitStatus": "PENDING"
            "DefaultDate": "",
			"DefaultFee": "",
			"DebitFee": "0.55",
			"CreditCardFee":"0.70",
			"ClientReference": "123ABC456",
			"InitialFee": "0.00"
        },
        {
            "DebitAmt": "20.89",
            "DebitDesc": "Debit",
            "DebitReference": "",
            "DebitDate": "2016-10-01",
            "DebitStatus": "SUCCESSFUL"
            "DefaultDate": "",
			"DefaultFee": "",
			"DebitFee": "0.55",
			"CreditCardFee":"0.70",
            "ClientReference": "123ABC456",
			"InitialFee": "0.00"
        },
        {
            "DebitAmt": "20.89",
            "DebitDesc": "Debit",
            "DebitReference": "",
            "DebitDate": "2016-11-01",
            "DebitStatus": "FAILED"
            "DefaultDate": "",
			"DefaultFee": "",
			"DebitFee": "0.55",
			"CreditCardFee":"0.70",
            "ClientReference": "123ABC456",
			"InitialFee": "0.00"
        }
    ]
}
		

Failed Result


{
    "result": "failed",
    "error": <Error Message>
}
	

Possible Error Messages

MessageDescription
Invalid DebitStatusThe Debit Status is not recognised.
Invalid DebitDateThe Debit Date is not a valid date.
Invalid ClientReferenceThe provided client reference number cannot be found.
Optional Params DebitStatus & DebitDate Not Supplied, ClientReference RequiredIf DebitStatus and DebitDate are not provided you must provided a Client Reference.
Invalid DateSortThe provided Date sort must be either "ASC" or "DESC".

CreateSchedule

This call is used to setup multiple future dated transactions for the selected client. This differs from AddDebit as you can make this call once for the client and have multiple transactions setup based upon your frequency, start date and amount. Use this call if you don't have an automated process, billing procedure or the debits for the client are always the same over their payment schedule.

POST | https://api.edebit.com.au/CreateSchedule/
curl -d "eDebitNumber=100100&Key=123ABC456&BusKey=ABC123DEF&ClientReference=NewClient20&DebitAmt=44.90&DebitDate=20150501&Frequency=7D&UFN=0&DebitCount=1&DebitFee=1&CreditCardFee=1" -X POST https://api.edebit.com.au/CreateSchedule/
NameTypeMax LengthRequiredExampleDescription
KeyString----YesUnique key provided by eDebit to the software developer.
BusKeyString----YesUnique key provided by eDebit to the individual business.
eDebitNumberInt6Yes100100Account number provided to business by eDebit.
ClientReferenceString11Yes123ABC456Client's reference number, set up during NewClient call.
InitialFeeDouble6No100.00A once off intial fee (eg. joining, admin) you wish to charge in addition to DebitAmt on the first debit.
DebitAmtDouble6Yes50.00Amount you wish to debit client.
DebitDateString8Yes20150501Date of debit. Date must be formatted YYYYMMDD.
FrequencyString3Yes7DFrequency of debits. See table below.
UFNInt1Yes1Should the debits continue until further notice. 1=Yes, 0=No
DebitCountInt2No5Number of debits for non-UFN payment cycle. If UFN set to "1" this value will be ignored.
DebitFeeInt1Yes0 or 1This flag will determine if we add the transaction fee onto the debit amount supplied. If you are calculating fees then this must be set to 0.
CreditCardFeeInt1Yes0 or 1This flag will determine if we add the merchant service fee onto the debit amount supplied. If you are calculating fees then this must be set to 0.

Valid Frequency Strings

FrequencyDescription
7DWeekly
14DFortnightly
28D4 Weekly
1MMonthly
3MQuarterly

Successful Result


{
    "result": "successful",
    "message": {
        "eDebitNumber": "100100",
        "ClientReference": "123ABC456",
        "InitialFee": "",
        "DebitAmt": "46",
		"DebitDate": "20180101",
		"Frequency": "14D",
		"UFN": "1",
		"DebitFee": "0",
		"CreditCardFee": "0",
		"DebitCount": "1",
        "Created": "2017-12-01 14:01:34"
    }
}
	

Failed Result


{
    "result": "failed",
    "error": <Error Message>
}
	

Possible Error Messages

MessageDescription
Invalid ClientReferenceThe provided client reference number cannot be found.
Invalid DebitDateThe Debit Date is not a valid date.
Invalid DebitAmtThe Debit Amount must be greater than 0.
Invalid FrequencyIf Frequency provided is not a valid value.
UFN RequiredThe "Until Further Notice" flag must be set.
DebitCount RequiredIf the UFN flag is set to 0, the number of debits must be set.
Invalid CycleThe UFN flag is set to 1 and DebitCount is > 0.

DebitStatus

This call is used to obtain the result of a transaction. This call can only be used if the original transaction was added using AddDebit call.

GET | https://api.edebit.com.au/DebitStatus/
curl "https://api.edebit.com.au/DebitStatus/?Key=123ABC456&BusKey=ABC123DEF&eDebitNumber=100100&TransactionRef=150824"
NameTypeMax LengthRequiredExampleDescription
KeyString----YesUnique key provided by eDebit to the software developer.
BusKeyString----YesUnique key provided by eDebit to the individual business.
eDebitNumberInt6Yes100100Account number provided to business by eDebit.
DebitReferenceString20Yes1A2B3CUnique reference supplied during AddDebit call.

Successful Result


{
    "result": "successful",
    "message": {
        "DebitDesc": "PT Session",
        "DebitStatus": <DebitStatus>
    }
}
	

What does DebitStatus mean?

StatusExplaination
PLANNEDThe debit has been successfully entered into our system however we have not processed it yet.
PENDINGThe debit has been processed but we have not received a successful or failed response from the bank or credit card issuer yet.
SUCCESSFULDebit has been successful
FAILEDDebit has failed (defaulted), the DebitDesc returned will show the default reason
UNKNOWNAn error has occurred and we can't find the debit.
UNPROCESSEDWe were unable to process the debit request due to missing/incomplete information. This status should not be handled the same as "FAILED", the returned "DebitDesc" string will indicate the issue. For further information please contact eDebit support on (02) 9999 4455 Option 2

Failed Result


{
    "result": "failed",
    "error": <Error Message>
}
	

Possible Error Messages

MessageDescription
Invalid DebitReferenceThe Debit Reference is missing.
No Matching DebitNo debit can be found for the provided DebitReference.

ClientGateway

Example Page

The ClientGateway was developed to enable you to accept new client (member, customer etc) applications via your website, during the process the new client will be able to authorise the debit using either their drivers licence details or digital signature. At the end of the process a digital authority form will be emailed to you, eDebit & the account holder.

Please Note: We highly recommend you verify the information supplied to confirm the payment information, signature or licence details are owned by the new applicant.

This process can be completed in 4 easy steps:

  1. User visits your website and clicks "Join Now"
  2. User is redirected to your application process on your site and completes the form providing personal information and which debit arrangement they wish to join (e.g. $50 weekly membership). We highly recommend this information is sent via a direct post to eDebit. Please see ClientGateway Example for an example (Valid BusKey required).
  3. User is redirected to secure ClientGateway page provided by eDebit to enter their payment information and authorise.
  4. Once information has been verified and saved by eDebit we redirect them to the ReturnURL provided. This would usually be a "Thank You" page.
POST | https://api.edebit.com.au/ClientGateway/
NameTypeMax LengthRequiredExampleDescription
BusKeyString----YesUnique key provided by eDebit to the individual business.
eDebitNumberInt6Yes100100Account number provided to business by eDebit.
ClientReferenceString11No123ABC456This reference must be unique and will be used in future calls to identify the client. If no ClientReference is supplied it will be generated automatically.
FirstNameString45NoJohnClient's first name.
LastNameString45YesSmithClient's last or business name.
AddressString45Yes1 Address StClient's street address.
CityString45YesSydneyClient's suburb / city.
StateString3YesNSWClient's state.
PostcodeInt4Yes2116Client's postcode.
TelInt10Yes0299994455Client's telephone number, landline or mobile.
EmailString100Yesemail@email.com.auClient's valid email address.
DebitDateString8Yes20150501Date of debit. Date must be formatted YYYYMMDD.
DebitAmtDouble6Yes50.00Amount you wish to debit client.
InitialFeeDouble6No100.00A once off intial fee (eg. joining, admin) you wish to charge in addition to DebitAmt on the first debit.
FrequencyString3Yes7DFrequency of debits. See table below.
UFNInt1Yes1Should the debits continue until further notice. 1=Yes, 0=No
DebitCountInt2Yes5Number of debits, if UFN set to >= 1
DebitFeeInt1Yes0 or 1This flag will determine if we add the transaction fee onto the debit amount supplied. If you are calculating fees then this must be set to 0.
CreditCardFeeInt1Yes0 or 1This flag will determine if we add the merchant service fee onto the debit amount supplied. If you are calculating fees then this must be set to 0.
DescriptionString100NoYearly MembershipA short description of the debits.
ReturnURLString---Yeshttp://www.google.com.auURL for user to be redirected to once process is complete.

ClientGatewayReturn

This call is used to retrieve the personal information and debit information that was entered during the ClientGateway process.

GET | https://api.edebit.com.au/ClientGatewayReturn/
KeyString----YesUnique key provided by eDebit to the software developer.
BusKeyString----YesUnique key provided by eDebit to the individual business.
eDebitNumberInt6Yes100100Account number provided to business by eDebit.
ClientReferenceString11Yes123ABCUnique client reference supplied during ClientGateway process, this reference can be found on the completed digital authority form.

Successful Result


{
    "result": "successful",
    "message": {
        "FirstName": "John",
        "LastName": "Smith",
        "Address": "1 Street Address",
        "City": "Sydney",
        "State": "NSW",
        "Postcode": "2000",
        "Tel": "0414112233",
        "Email": "email@email.com.au",
        "DebitAmt": "50.00",
        "DebitCount": 5,
        "DebitDate": "2015-11-30",
        "Frequency": "Weekly"
    }
}
	

Failed Result


{
    "result": "failed",
    "error": <Error Message>
}
	

Possible Error Messages

MessageDescription
Invalid ClientReferenceThe provided client reference number cannot be found.
No Matching ClientReferenceNo client can be found for the provided ClientReference.

processPayment

This function enables you to process a single real time credit / debit card payment using credit / debit card information supplied directly from the account holder. Please note: This feature is available to approved merchants only.

For a list of Credit Card numbers that can be used for testing, please see the list here.

POST | https://api.edebit.com.au/processPayment/
curl -d "eDebitNumber=100100&Key=123ABC456&BusKey=ABC123DEF&DebitAmount=44.90&Description=PT_Session&CCName=John Smith&CCNumber=4111111111111111&ExpiryMonth=10&ExpiryYear=19&CVN=888" -X POST https://api.edebit.com.au/processPayment/
NameTypeMax LengthRequiredExampleDescription
KeyString----YesUnique key provided by eDebit to the software developer.
BusKeyString----YesUnique key provided by eDebit to the individual business.
eDebitNumberInt6Yes100100Account number provided to business by eDebit.
DebitAmountDouble6Yes25.00Amount to Process
DescriptionString30YesPT_SessionDescription of debit, this does not appear on the statement.
CCNameString30YesJohn SmithName as printed on card.
CCNumberInt16Yes4111111111111111Number printed on card, no spaces or dashes.
ExpiryMonthInt2Yes10Expiry month printed on card.
ExpiryYearInt2Yes19Expiry year printed on card.
CVNInt4YesVisa/Mastercard/Diners - 888
AMEX - 8888
CVN/CVC printed on the back/front of the card.

Successful Result


{
    "result": "successful",
    "message": {
        "Result": "Successful",
        "responseCode": "08",
        "responseText": "Honour with identification",
        "orderNumber": "100100197",
        "DebitAmt": "1.25",
        "Description": "PT Sessions",
        "settlementDate": "20170830",
        "maskedCC": "411111...111"
    }
}
	

Failed Result


{
    "result": "failed",
    "error": <Error Message>
}
	

Possible Error Messages

MessageDescription
Invalid CCNumberThe provided Credit Card Number is invalid.
Invalid ExpiryThe provided Expiry Date for the card is invalid.
Invalid CCNameThe provided Card Name is invalid.
Invalid CVNThe provided card CVN is invalid.
Missing Card DetailsRequired Card Information is missing.
Processing Error, Contact eDebit Support Before Retrying
Error Processing Request, Contact eDebit Support for Futher Information
Fatal Error

paymentGateway

The paymentGateway was developed to enable approved merchants to collect real time credit / debit card via a "pay now" section on their website. Please see the example page for a rough idea of how this could be implemented.

For a list of Credit Card numbers that can be used for testing, please see the list here.

POST | https://api.edebit.com.au/paymentGateway/
curl -d "eDebitNumber=100100&Key=123ABC456&BusKey=ABC123DEF&DebitAmt=44.90&Description=PT_Session&ReturnURL=https://www.your-website.com.au" -X POST https://api.edebit.com.au/paymentGateway/
NameTypeMax LengthRequiredExampleDescription
KeyString----YesUnique key provided by eDebit to the software developer.
BusKeyString----YesUnique key provided by eDebit to the individual business.
eDebitNumberInt6Yes100100Account number provided to business by eDebit.
DebitAmtDouble6Yes25.00Amount to Process
DescriptionString30YesLarge HamperDescription of debit, this does not appear on the statement.
ReturnURLString100Yeswww.your-website.com.auURL to return card holder to after successful payment. The redirect will also pass back result information for local storage or display. Please see result box below for example return parameters.

Successful Result

ReturnURL: www.your-website.com.au?Result=Successful&responseCode=08&responseText=Honour%20with%20identification&orderNumber=100100198&DebitAmt=25.00&Description=1%20Large%20Hamper&settlementDate=20170830&maskedCC=411111...111

Failed Result


{
    "result": "failed",
    "error": <Error Message>
}
	

Possible Error Messages

MessageDescription
DebitAmt RequiredThe amount to be debited is missing.
Fatal Error, Please Contact eDebit Support on 02 9999 4455 Option 2.
[Result:<Result>|Code:<responseCode>|OrderNumber:<orderNumber>]
A Fatal Error has occurred. Please Contact eDebit Support on 02 9999 4455 Option 2.

Credit Card Testing Values

Response CodeExample Card Number
VisaMasterCardAmex 1Diners
08 - Honour with identification4242424242424242
4111111111111111
4444333322221111
516320000000000837000000020104830000000056030
01 Refer to Issuer4111111117444490
04 Pick Up Card4111111116444491
05 Do Not Honour4111111115444492516320000000079234000000006779239000000003892
91 Issuer or Switch Inoperative4111111114444493
54 Expired Card4111111113444494
42 No Universal Account4111111112444495
51 Insufficient Funds4111111111444496
62 Restricted Card4111111110444497
43 Stolen Card, Pick Up4111111119444498
01 Refer to Issuer4111111118444499
1 - Please Note: - AMEX Cards need a 4 digit CVN

Errors

Errors will return a JSON encoded string with a result of "failed" and a message detailing the failure reason(s).

Errors will return a HTTP Response Code 400.

Possible System Wide Error Messages

MessageDescription
API currently undergoing scheduled maintenance.Maintenance is being performed. Please try again later.
We are currently undertaking daily processing. To ensure data integrity we must temporarily restrict access to the API. Please try later.The Daily Billing Process is currently running. Please try again later. (More Info...)

Example: If we attempt to add a new client but omit the required parameters of ClientReference and LastName with the following call;

curl -d "eDebitNumber=100100&Key=123ABC456&BusKey=ABC123DEF&FirstName=John" -X POST https://api.edebit.com.au/NewClient/

then the below error message will be returned.


{
	"result": "failed",
	"error": [
    	"Reference Invalid",
    	"Last/Business Name Required"
    ]
}
	

Fee Information

If fees are not passed on to the account / credit card holder using the "CreditCardFee" & "DebitFee" flags then the relevant fees will be deducted from the DebitAmt on payment. Assuming the below fees are correct and we are undertaking a $50 credit card debit then the total debit amount and subsequent pay amount will vary.


DebitFeeCreditCardFeeTotal Debit AmountAmount Paid
00$50.00$48.69
10$50.48$49.17
01$50.83$49.52
11$51.31$50.00


Debit Status Information

StatusExplaination
PLANNEDThe debit has been successfully entered into our system however we have not processed it yet.
PENDINGThe debit has been processed but we have not received a successful or failed response from the bank or credit card issuer yet.
SUCCESSFULDebit has been successful
FAILEDDebit has failed (defaulted), the DebitDesc returned will show the default reason
UNKNOWNAn error has occurred and we can't find the debit.
UNPROCESSEDWe were unable to process the debit request due to missing/incomplete information. This status should not be handled the same as "FAILED", the returned "DebitDesc" string will indicate the issue. For further information please contact eDebit support on (02) 9999 4455 Option 2

Payment Life Cycle

Payment Workflow