API Overview
Introduction
Ezidebit’s API provides a fully PCI compliant payment solution to clients/partners in Australia and New Zealand.
The API provides the ability to process payments via a range of payment types (direct debit, real time, BPAY) via a powerful suite of widgets, Javascript methods and SOAP web services.
Payments can be processed from bank accounts, Visa Card, MasterCard and American Express, depending on the payment type.
API Components
Ezidebit’s API has the following core components.
Widgets
Ezidebit’s hosted widgets are powerful application components that can be “plugged” into your software, immediately offering rich features with a minimum development on your part.
The added benefit of using our widgets is that when used as specified, they ensure that your software design is fully PCI level 1 compliant.
Widgets include:
Javascript API Methods
Our Javascript API allows you to have control over the page. Your forms’ details can be sent directly to Ezidebit, and not via your server.
Web Services
We have SOAP web services that enable your customer management system to interface directly with Ezidebit’s payment processing cloud
With over 25 web services to choose from, they are designed to be platform and programming language agnostic to allow integration with Ezidebit, regardless of the language that your system is developed in. They are delivered securely over the internet using SOAP as standard XML based specifications designed for exchanging structured information over computer networks.
A number of web services exist for use by businesses/software that are already PCI compliant. Use of these methods must be approved by Ezidebit and evidence of existing PCI compliance must be provided (Certificate of Attestation or Self Assessment Questionnaire D). Specific web services that require this approval are indicated in the relevant sections below.
Sandbox
You will receive a unique Sandbox Digital Key and Public Key, which give you access to our test environment. You will also receive your login credentials for the sandbox Ezidebit Online portal (access will be read only).
Some settings may differ on your sandbox account to your live account, e.g. payment products available, fees and who is paying the fees.
Approach to Integration
Ezidebit has a dedicated Integration Services team who can work with you on the design and validation of your planned integration to ensure it meets all PCI and banking requirements. It is recommended that you contact the Integration Services team by emailing partner@ezidebit.com.au before commencing your development so that they can assist you with identifying the most appropriate API components to deliver your requirements.
Prior to go live of a new integration, the Integration Services team will complete a certification of the developed solution. This will include a review of the API components being used and a walkthrough of key functions, such as new payer sign up, processing of credit cards payments. Where PCI or banking requirements have not been met, certification will not be able to be provided until issues have been addressed.
An annual certification review will be completed by the Integration Services team.
Support can be requested at any time by emailing partner@ezidebit.com.au.
Testing information
When testing and debugging it is important to remember that typically SOAP Exceptions result from malformed or bad data presented in the XML. When you are debugging you should check both your program logic and the XML that it is producing as the request data. When you are communicating with Ezidebit about these Exceptions, it is important that you include the XML that was sent as the request to the web service with your enquiry; this will assist Ezidebit’s support staff in identifying any issue.
Testing of the integration using Ezidebit’s APIs must include not only testing relating to sending and receiving of data using the web services, but also that data received in responses is correctly dealt with in the client management system. For example, where retrieving payment data, the system must be able to correctly treat both successful and failed payments.
The following points should also be noted in relation to testing:
- Real-Time (Visa/MasterCard Only): Using our test set up via the test URLs allows you to test failed and successful payments for Visa and MasterCard depending on what number you enter for the number of cents in the payment amount. Zero cents (e.g. 100 or 100.00) will be successful. Any other number of cents will always fail with the failed reason corresponding to the number of cents (e.g. 100.51 as the payment amount will fail with error code 51, meaning insufficient funds). A list of the response codes is contained in Transaction Response Codes.
- Real-Time (American Express Only): Using our test set up via the test URLs allows you to test failed and successful payments for American Express depending on what expiry date is used. More details about this can be found in Transaction Response Codes.
- Direct Debit (Credit Card & Bank Account): In the Sandbox Environment, customers whose bank account or credit card number ends in a ‘2’ will have their test payment(s) dishonoured as “Insufficient Funds” and the customer will stay at a processing status. Customers whose bank account or credit card number ends in a ‘3’ will have their test payment(s) dishonoured as “Incorrect Bank Account/Credit Card Number” (Fatal Dishonour) and the customer record will be moved to a non-processing status. All other payments will be marked as successful. A list of response codes can be found in Bank Account Response Codes.
When testing in our Sandbox environment, processing is done at the following times:
Country | Direct Debit Processing Time | Settlement Time |
---|---|---|
Australia | 2:30 am and 6:00 pm AEST | 10am AEST |
New Zealand | 5:30am AEST | 8am AEST |
Payment Processing Times
Direct debit payments in the live environment are processed at the following times on each business day:
Country | Direct Debit Processing Time | Settlement Time |
---|---|---|
Australia | 12:30 am, 6:30am and 3:00 pm AEST | By 8:30 am AEST |
New Zealand | 1:30 am and 3:00 pm AEST | By 8:30 am AEST |
Payment Types
Ezidebit supports the following payment types:
- Direct debit from bank account, credit card and debit card – these payments are processed as Recurring payments. Direct debit payments are processed against customer records that are set up within Ezidebit’s system;
- Real time credit card and debit card payments – these payments are processed in real time as web payments or phone payments. Real time payments are considered as ‘unknown payer’ transactions within Ezidebit’s system. The payment reference supplied with the payment is typically used by the client to identify the payer;
- BPAY – customers are able to initiate a BPAY payment to billers via their internet banking facility. BPAY payments are considered as ‘unknown payer’ transactions within Ezidebit’s system. The CRN provided for the transaction is used by the client to identify the payer.
Creating Customers
Customers are created in Ezidebit’s system to facilitate direct debit payments from a bank account, credit card or debit card. In addition, a real time credit card payment can be processed as a tokenised payment using stored credit card details.
Customers added for direct debit payments must complete an approved Direct Debit Request in one of the following formats:
- Electronic Direct Debit Request (eDDR)
- Paper Direct Debit Request (provided by Ezidebit with live account set up)
- Customised online sign up page, subject to approval by Ezidebit prior to go live
Customers can be added to Ezidebit’s system via the following mechanisms:
- eDDR;
- Web service (requires use of embeddable widget or a client side method for capture of bank account/credit card details)
- Javascript API method.
These options are outlined in the sections below.
eDDR
Description
The Electronic Direct Debit Request (eDDR) form is a single web based form designed to capture Direct Debit Request authorisations and create the payer, and (optionally) their payment schedule, in Ezidebit’s system. The eDDR provides an authorisation for Ezidebit clients that deal with their own customers remotely, rather than in a face-to-face manner. It also reduces the management and handling of paperwork, improving security, and assisting in removing PCI-DSS obligations from Ezidebit’s clients.
Appearance
Through Ezidebit Online, you can customise the look and feel of the eDDR page so that it is more aligned to your own branding with elements such as brand colours and logos. This can be done through the Web Page Configuration option in the Admin menu.
The following page displays how the default standard Scheduled Payment (eDDR) page may look.
Use Cases
Payment templates can be set up in Ezidebit Online, which can provide a convenient eDDR URL and will direct to your customers to the prepared payment plan. They only need to fill in their particulars and payment details - one-off amount and/or recurring debits as well as frequency of payments are pre-filled into the submission form. The following are examples of generated URLs when set up by the template.
Scenario 1 - Customer signs up to become a member for a fitness centre for a membership fee of AU$100 and a monthly fee of AU$50:
If you do not need to collect any information of your own, a standard hyperlink can be prepared to give out to your customers to sign-up online and become a member. This hyperlink can be provided from your website, or within an email. A sign-up page displays to capture relevant customer information. They will enter their name, address, phone number, bank account or credit card details, etc., review the terms and conditions, and submit the form. This creates the customer within Ezidebit’s system.
Where you want to capture some preliminary data on your website, for example a customer browses to your web site and decides to sign-up online to become a member for a membership fee of AU$100 and a monthly fee of AU$50, additional parameters can be passed into the eDDR URL:
A sign-up page on your website displays to capture relevant customer information. (name, address, phone number, etc.). The details that have already been entered by the customer can be passed in to the eDDR form so that the customer is not required to re-type them. The customer is then directed to the eDDR form to enter their bank account or credit card details, review the terms and conditions and select submit, which creates the customer within Ezidebit’s system. The web site user can then be redirected back to your website with additional data about the debit.
Scenario 2 - Pay an invoice over a number of instalments
A customer is paying you an invoice amount of AU$1,000. He signs up to pay this invoice over 10 monthly instalments of AU$100.
Scenario 3 - Make a regular donation to a charity
A donor browses to your web site and decides to donate AU$50. Further, the donor wants to continue donating AU$10 on a fortnightly basis.
Structure
The eDDR form is available at the following URLs. Your account specific URL is available from Ezidebit Online in Web Page Configuration under the Admin menu.
The URL of the LIVE (Production Environment) eDDR is:
https://secure.ezidebit.com.au/webddr/
The URL of the TEST (Sandbox Environment) eDDR is:
https://demo.ezidebit.com.au/webddr/
The form allows data to be provided to it through GET and POST methods. Examples of each are outlined below.
GET METHOD
As demonstrated in the scenario links above, if you do not need to collect any information of your own, a standard hyperlink can be prepared to give out to your customers. This hyperlink can be provided from your website, or within an email.
<form action="https://secure.ezidebit.com.au/webddr/Request.aspx?a=51172E35-1B77-41DF-2007-0EE14CB27262" method="post">
<input type="hidden" name="urefLabel" value="Invoice Number" />
<label for="uref">Invoice Number</label>
<input type="text" name="uref" />
<label for="<td colspan="3" style="background-color:#F8F8F8; font-style:italic;">">First Name</label>
<input type="text" name="<td colspan="3" style="background-color:#F8F8F8; font-style:italic;">" />
<label for="lname">Last Name</label>
<input type="text" name="lname" />
<label for="email">Email</label>
<input type="text" name="email" />
<input type="hidden" name="debits" value="2" />
<input type="hidden" name="tamount" value="400.00" />
<input type="submit" value="Go!!!!" />
</form>
POST METHOD
A form can be used to collect some preliminary information and then submit that data to the eDDR form. The following scenario covers a customer filling out some information on your own website, and then forwarding them to Ezidebit’s eDDR to finish entering bank details, etc.
General Guidelines
Below are a number of important points that you should keep in mind when using the Electronic Direct Debit Request:
- For security purposes no bank account or credit card information can be passed into, nor will be passed back from the eDDR form;
- When parameters are passed to the form, the field that they are passed into is disabled and not editable by the customer. This is based on the assumption that if a client is supplying data for a field, there is a specific reason for the value and it is not desirable to have a customer override the data. If you do want to allow customers to override the pre-filled values that are passed to the form you can pass the ed=1 parameter to the form and it will enable all fields on the form and simply use data passed to it as a default;
- The eDDR cannot be used to modify existing payment details (e.g. change bank account details);
- When the query string is incorrect or the client record is not active, “Direct Debit Request Error” page will be displayed when the URL is used;
- When the Client is not set up to accept either Bank Account or Credit Cards, the corresponding payment method will not be displayed on the eDDR;
- When the Client is not set up for SMS reminders, the SMS tick box will be unavailable on the eDDR.
Input Values
Below is a list of all of the possible query string parameters that can be used with the eDDR URL to initialise the form.
Parameter | Form Control | Format | Example |
---|---|---|---|
uRefLabel |
“Your Reference” Label value. * Note that not providing this parameter will show the default label of “Your Reference” |
String
(80 Char maximum) |
Invoice Number |
uRef |
Your Reference field value. This value must be unique across all customers associated with the client account Where a value is passed in to the eDDR form for the ‘Your Reference’ field (uRef parameter), a check will be done to see if the value already exists for a customer record in the client account with Ezidebit. Where the value already exists, the value will not be populated and the field will become editable. |
String
(50 Char maximum) |
LWB:12029 |
nouRef |
This will hide the reference field and produce a generic reference upon submission |
Numeric
(Number 1 only) |
1 |
businessOrPerson |
Specifying this parameter will display data entry fields of First Name and Last Name for a Person, or Company Name for a Company. |
Number |
1 - Person 2 - Business *Note that not providing this parameter will show a drop-down menu for the user to select Person or Business options by default. |
fName |
First Name |
String
(30 Char maximum) |
Joe |
lName |
Last Name |
String
(60 Char maximum) |
Bloggs |
String
(255 Char maximum) |
example@example.com |
||
noClientEmail |
Copy of the agreement will not be emailed to Client |
Numeric
(Number 1 only) |
1 |
mobile |
Mobile No |
Numeric
(10 digits beginning with '04’) |
0400 000 000 |
nosms |
This will hide the SMS notification option if set to 1 |
Numeric |
1 |
sms |
This enables the SMS notification option to be set to Yes by default. The customer then can untick it if required |
Numeric |
1 |
addr | Address line 1
* Note required if Address line 2 is present |
String
(30 Char maximum) |
123 Fake St |
addr2 | Address line 2 |
String
(30 Char maximum) |
Apartment 03-05 |
suburb | Suburb |
String
(20 Char maximum) |
Milton |
state | State |
String
(3 Char maximum) |
QLD |
pCode | Postcode |
Numeric
(4 digits exactly) |
4064 |
debits |
This determines which options are available in the Debit Arrangement area: 1 - Show only “Once Off Debit” 2 - Show only “Regular Debits” 4 - Show only “Triggered Debit Authorization” * Note that not providing this parameter will show Once Off Debits AND Regular Debits by default |
Numeric
(Numbers 1 - 4) |
2 |
oAmount |
This will set the value of the Debit Amount for the Once Off Debit option * Note you can include this parameter with different values more than once in the query string, or alternately provide a comma separated list as the value. By providing more than one value for this parameter it will change the amount field to a drop-down list of values for the customer to select. For example: |
Numeric or Comma separated list of numeric values. (Decimal number of ddd.cc) |
oAmount=200.00 |
oDate |
This will set the value of the Date field for the Once Off Debit option. If a valid date is passed then the debit date will be set to that date (or the next business day if the date falls on a weekend). If a day of week value is passed then the debit date will be calculated to be the next possible occurrence of that particular day of the week, e.g. submitting WED on a Wednesday sets the debit date as that day, submitting MON on a Wednesday sets the debit date as the following Monday. If an integer value is passed then the debit date will be calculated as the current date plus the integer value number of days - e.g. passing 0 sets the debit date to today , passing 1 sets the debit date to tomorrow, etc. * Note that a valid parameter will always shift the debit date to a Monday if the supplied or calculated date falls on a weekend. |
Date (dd/mm/YYYY)
OR Day of week (MON - FRI) OR In x days (Numbers 0-30) |
27/08/2010
OR FRIOR 14 (will be two weeks from today) |
rAmount |
This will set the value of the Debit Amount for the Regular Debits option. * Note you can include this parameter with different values more than once in the query string, or alternately provide a comma-separated list as the value. By providing more than one value for this parameter it will change the amount field to a drop-down list of values for the customer to select. For example: |
Numeric or Comma separated list of numeric values. (Decimal number of ddd.cc) |
rAmount=200.00 |
rDate |
This will set the value of the Date field for the Regular Debits option. If a valid date is passed then the debit date will be set to that date (or the next business day if the date falls on a weekend). If a day of week value is passed then the debit date will be calculated to be the next possible occurrence of that particular day of the week, e.g. submitting WED on a Wednesday sets the debit date as that day, submitting MON on a Wednesday sets the debit date as the following Monday. If an integer value is passed then the debit date will be calculated as the current date plus the integer value number of days, e.g. passing 0 sets the debit date to today , passing 1 sets the debit date to tomorrow, etc. * Note that a valid parameter will always shift the debit date to a Monday if the supplied or calculated date falls on a weekend. |
Date (dd/mm/YYYY)
OR Day of week (MON - FRI) OR In x days (Numbers 0-30) |
27/08/2010
OR FRIOR 14 (will be two weeks from today) |
aFreq |
This allows you to choose which debit frequencies are available within the Frequency select list in the Regular Debits Area. Multiple frequencies can be selected by adding the values of the frequencies that you want to display from the list below: 1 - Weekly 2 - Fortnightly 4 - Monthly 8 - Every four weeks 16 - Quarterly 32 - Half Yearly 64 - Yearly E.g. To show either weekly or monthly the value of this parameter would be determined by: Weekly (1) + Monthly (4) = 5 * Note that not providing this parameter will show only Weekly , Fortnightly or Monthly frequencies by default. |
Number |
7 This would display Weekly, Fortnightly |
freq |
This will set the value of the Frequency field in the Regular Debits area. 1 - Select Weekly 2 - Select Fortnightly 4 - Select Monthly 8 - Select Every four weeks 16 - Select Quarterly 32 - Select Half Yearly 64 - Select Yearly |
Number |
4 This would set Monthly as the frequency |
aDur |
This allows you to choose which duration options are available within the Duration select list in the Regular Debits area. Multiple options can be selected by adding the values of the durations that you want to display from the list below: 1 - Ongoing 2 - Total Amount 4 - Total Payments E.g. To show either Total Amount or Total Payments the value of this parameter would be determined by: Total Amount (2)+Total Payments (4)= 6 * Note that not providing this parameter will show all three options by default. |
5 |
|
dur |
This will set the value of the Duration field in the Regular Debits area 1 - Ongoing 2 - Total Amount 4 - Total Payments |
Number |
4 This would set Total Payments as the Duration |
tAmount |
This will set the value of the Total Payment Amount for the Regular Debits option * Note you can include this parameter with different values more than once in the query string, or alternately provide a comma separated list as the value. By providing more than one value for this parameter it will change the amount field to a drop-down list of values for the customer to select. For example: |
Numeric or Comma separated list of numeric values. (Decimal number of ddd.cc) |
tAmount=200.00 |
tPay |
This will set the value of the Total Payments field in the Regular Debits area |
Number |
10 |
method |
This will show only the selected payment method. 1 - Bank Account Only 2 - Credit Card Only * Note that not providing this parameter will show both payment options by default |
Number |
2 |
ed |
This affects any fields set by passing values into them through query string or form parameters. By passing in a value for ed it will make any field where the value has been set editable by your customer. This is typically used where you want to provide defaults, but still allow the customer to change anything of their choosing. |
Number |
1 |
a |
The client public key or identifier compound (DGR Hash) |
GUID or Hex String |
1C1C7315-ECD8-47C1-59C9-EC5D04EEDCBF or 0x3231313021504BF347454E |
callback |
Specifying this parameter forces the eDDR form to redirect the user to the URL specified in this parameter after the form submission is completed. The redirection will include the fields that contain the customer’s information as described in section below of this document. * Note that the redirection will use the HTTP Method specified in the cMethod parameter. If the cMethod parameter is not included, it will default to GET. ** See section below, Return Values & Response Code, for specific details about the function of this parameter. |
String
(255 Char maximum) |
http://example.com/formcompleted.htm |
cMethod |
The HTTP method you would like Ezidebit to use when it submits the customer data to the callback URL specified in the callback parameter. * Note that by default this parameter is set to GET. If no value is provided for the callback parameter then this parameter will be ignored ** See section below, Return Values & Response Code, for specific details about the function of this parameter. |
String
(4 char maximum) |
GET
OR POST |
dishonAction |
Presets the dishonour action for the contract on submission. DISHONOUR - No attempt is made to recover failed payment. Remainder of contract defined schedule continues unchanged (default). |
String | RESCHEDULE_NEXT |
CALLBACK METHOD:
If you would like to receive the information we collect from the customer after they have filled out our form, you can request a callback using either of the following methods.
<input type="hidden" name="callback" value="http://example.com/complete.htm" />
<input type="hidden" name="cmethod" value="get" />
Callback using GET
This will allow you to collect all fields in the “Customer Details” section including our reference. Just add the callback and cMethod parameters to the link or form:
https://demo.ezidebit.com.au/webddr/Request.aspx?a=51172E35-1B77-41DF-2007-0EE14CB27262&debits=3&method=2&callback=http://example.com/complete.htm&cmethod=get
<input type="hidden" name="callback" value="http://example.com/complete.htm" />
<input type="hidden" name="cmethod" value="post" />
Callback using POST
This will allow you to collect all fields in the “Customer Details” section including our reference. Just add the callback and cMethod parameters to the link or form:https://demo.ezidebit.com.au/webddr/Request.aspx?a=51172E35-1B77-41DF-2007-0EE14CB27262&debits=3&method=2&callback=http://example.com/complete.htm&cmethod=post
Return Values & Response Codes
The following is a list of values that will be returned to you via either of the callback methods.
Value | Description |
---|---|
uref | Your Customer Reference (YourSystemReference) |
cref | Ezidebit's Customer Reference (EzidebitCustomerID) |
fname | First Name (if the customer is a Person and not a Business) |
lname | Last Name (or company name when a Business) |
Email address | |
mobile | Mobile number |
addr | Address line 1 |
addr2 | Address line 2 |
suburb | Suburb |
state | State |
pcode | Postcode |
rdate | The date of the first recurring payment |
ramount | The regular debit amount |
freq | The frequency that debits will occur on (values in parameters table) |
odate | The date of any one-off payment |
oamount | The amount of a one-off payment |
numpayments | The number of payments a schedule is restricted to |
totalamount | The total amount that a schedule is restricted to |
method | The method of payment chosen by the Customer |
Note: Only customers that were successfully added to the Ezidebit system will be returned via the callback.
The successfully created Payer details can be found in the Client’s Ezidebit Online Portal.
AddCustomer
URL
URL of Web Services | |
Production (LIVE) | https://api.ezidebit.com.au/v3-5/nonpci |
Sandbox (TEST) | https://api.demo.ezidebit.com.au/v3-5/nonpci |
Description
This method creates a new customer record in the Ezidebit database from which you will be able to schedule direct debit payments or use a stored credit card for tokenised real time payments. It is important to note the following when creating customers:
- This method will create the customer record and it will set the new customer record to a non-processing status. Credit Card or Bank Account details will need to be provided (typically through the Account Widget) before debits can be taken from the customer;
- Each customer may have only one payment method recorded against them. This payment method will be either a bank account or a credit card. When a scheduled payment becomes due, it will be debited from the payment method recorded against that customer at that point in time. Each time the payment method is updated, it will override any existing payment method that the customer has;
- Customers have a single payment schedule associated with them. It is possible to insert additional “manual” payments into an existing schedule;
- If a customer has a status that does not allow processing of payments (Hold or Cancelled Status) at the time that a scheduled payment becomes due, then the payment will be removed from their schedule, but will not be debited from their payment method.
When using this method to save a customer as part of an online sign up, you MUST adhere to the requirements set out in the BECS Compliance section.
Request Parameters
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:px="https://px.ezidebit.com.au/">
<soapenv:Header />
<soapenv:Body>
<px:AddCustomer>
<px:DigitalKey>00000000-0000-0000-0000-000000000000</px:DigitalKey>
<px:YourSystemReference>102</px:YourSystemReference>
<px:YourGeneralReference>102</px:YourGeneralReference>
<px:LastName>Stevens</px:LastName>
<px:FirstName>John</px:FirstName>
<px:AddressLine1>123 Smith St</px:AddressLine1>
<px:AddressLine2>Level 2</px:AddressLine2>
<px:AddressSuburb>Wilston</px:AddressSuburb>
<px:AddressState>QLD</px:AddressState>
<px:AddressPostCode>4051</px:AddressPostCode>
<px:EmailAddress>jstevens@example.com</px:EmailAddress>
<px:MobilePhoneNumber>0400123456</px:MobilePhoneNumber>
<px:ContractStartDate>2011-03-01</px:ContractStartDate>
<px:SmsPaymentReminder>NO</px:SmsPaymentReminder>
<px:SmsFailedNotification>NO</px:SmsFailedNotification>
<px:SmsExpiredCard>NO</px:SmsExpiredCard>
<px:Username>WebServiceUser</px:Username>
</px:AddCustomer>
</soapenv:Body>
</soapenv:Envelope>
Parameter Name | Description | Format | Example |
---|---|---|---|
DigitalKey (Required) |
The 36 character Digital Key supplied to you by Ezidebit to identify your business |
String | 8591BFD4-E7C8-4284-84F7-E6C419114FA8 |
YourSystemReference |
A unique system identifier for the customer (e.g. GUID or your primary key). This is typically a unique identifier for the account/member/contract in your application and is used in a system-to-system manner. The purpose of this reference is to allow you to access your Customer’s details via Ezidebit’s web services using your own reference numbers, without the need to record an Ezidebit reference in your system. |
String
(Max 50 char) |
563445878985432x76 |
YourGeneralReference |
A secondary unique reference for the customer. Where system based identifiers (YourSystemReference) can be complex numbers, this is designed to be a simpler, human-friendly number. You may use a GUID to create the system-to-system link with YourSystemReference, and choose to include a membership ID, or such in this field. If no value is supplied for this field it will default to 'LastnameFirstnameYYYYmmDDhhMM’. |
String
(Max 50 char) |
101 |
LastName (Required) |
Where the customer is an individual, the Customer’s surname should be supplied. Where the customer is a business or organisation, the name of the entity should be supplied. |
String
(Max 60 char) |
Smith |
FirstName |
Customer’s first name (for individuals) If this is left blank, the customer will be flagged in Ezidebit’s system as a business. |
String
(Max 30 char) |
Joe |
AddressLine1 |
The first line of the Customer’s physical address. * Note required if customerAddress2 is present |
String
(Max 30 char) |
123 Smith St |
AddressLine2 |
The second line of the Customer’s physical address |
String
(Max 30 char) |
Level 4 |
AddressSuburb |
The Suburb of the Customer’s physical address. |
String
(Max 20 char) |
Wilston |
AddressState |
The State of the Customer’s physical address. |
String
(Max 3 char) |
QLD |
AddressPostCode |
The Postcode of the Customer’s physical address. |
String
(Max 4 digits) |
4051 |
EmailAddress |
Customer’s email address |
String
(Max 255 char) |
joesmith@example.com |
MobilePhoneNumber |
Customer’s mobile telephone number. NB - for Australian Customers the mobile phone number must be 10 digits long and begin with '04’. For New Zealand Customers the mobile phone number must be up to 12 digits long and begin with '02’ |
String
(Max 12 char) |
0400123456 |
ContractStartDate (Required) |
The date that the customer signed the Direct Debit Request Service Agreement. Must be formatted as yyyy-MM-dd |
String yyyy-MM-dd | 2010-12-22 |
SmsPaymentReminder (Required) |
Optionally send an SMS to the customer reminding them of their upcoming scheduled debits. |
String
YES or NO |
YES |
SmsFailedNotification (Required) |
Send an SMS to the customer notifying them if their debit fails. For a valid mobile number an SMS is sent regardless of the parameter |
String
YES or NO |
YES |
SmsExpiredCard (Required) |
Optionally send an SMS to the customer notifying them if their recorded credit card is due to expire. |
String
YES or NO |
YES |
Username |
Optionally record the user in your system that is executing this action |
String
(Max 50 char) |
Webuser |
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<AddCustomerResponse xmlns="https://px.ezidebit.com.au/">
<AddCustomerResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Data xmlns:a="http://schemas.datacontract.org/2004/07/Ezidebit.PaymentExchange.V3_3.DataContracts ">
<a:CustomerRef>123456</a:CustomerRef>
</Data>
<Error>0</Error>
<ErrorMessage i:nil="true" />
</AddCustomerResult>
</AddCustomerResponse>
</s:Body>
</s:Envelope>
Response
- The <Data> field in the AddCustomer response will be either:
- A CustomerRef value containing positive non-zero integer that is the value of the EziDebitCustomerID that has been allocated to the successfully created Customer;
- Empty - When the Data field is empty, it indicates that the update was not successful. You should check the value of the Error field. If an error has occurred, it will be indicated by a non-zero value in the Error field, with a text descriptor in the ErrorMessage field.
SaveCustomer
URL
Endpoint | |
Production (LIVE) | https://api.ezidebit.com.au/V3-5/public-rest |
Sandbox (TEST) | https://api.demo.ezidebit.com.au/V3-5/public-rest |
Javascript File | https://static.ezidebit.com.au/javascriptapi/js/ezidebit_2_0_0.min.js |
Description
The SaveCustomer Javascript method will add a customer record to the Ezidebit database. This request is used when credit card details are being collected from the customer and stored by Ezidebit for later processing of a 'batched’ transaction using direct debit, or a tokenised real time payment. When submitting the customer with credit card details, there are two scenarios that can occur:
- If the customer details and card information are passed but with no payment amount then the customer is stored with the credit card information and but no charge to the credit card is processed;
- If the customer details, card information and payment amount are passed then the customer is charged in real-time and the customer and payment information are stored for later use.
When using this method, credit card details are securely transmitted to Ezidebit – they are never sent to your own servers or database. This ensures the card details are handled in a PCI compliant manner.
When credit card deatils are being entered using this method, you must display the relevant card scheme logo as the card is being entered. For more information please see the Displaying Credit Card Logos section.
When using this method to save a customer as part of an online sign up, you MUST adhere to the requirements set out in the BECS Compliance section.
$(document).ready(function () {
eziDebit.init("YOUR_PUBLIC_KEY", {
submitAction: "SaveCustomer",
submitButton: "btnSubmit",
submitCallback: displaySubmitCallback,
submitError: displaySubmitError,
customerFirstName: "txtFirstName",
customerLastName: "txtLastName",
customerReference: "hidReference",
customerAddress1: "txtAddress1",
customerAddress2: "txtAddress2",
customerSuburb: "txtSuburb",
customerState: "txtState",
customerPostcode: "txtPostcode",
customerEmail: "txtEmail",
customerMobile: "txtMobile",
nameOnCard: "txtNameOnCard",
cardExpiryMonth: "txtExpiryMonth",
cardExpiryYear: "txtExpiryYear",
CardCCV: "txtCCV",
paymentAmount: "hdnAmount",
paymentReference: "hdnPaymentRef",
}, endpoint);
Requests
Parameter Name | Description | Format | Example |
---|---|---|---|
submitAction (required) |
This should always be SaveCustomer for this function |
String | SaveCustomer |
submitButton (required) |
The client side element name of the button to submit the form (usually an input of type submit or button) |
String | btnSubmit.ClientID |
submitCallback (required) |
The method name of some client side code to execute when the operation completes successfully. A useful action would be to store the Ezidebit customer ID into a hidden field and then to submit the form to your server |
Function | SubmitCallback |
submitError (required) |
The method name of some client side code to execute when the operation failed, or the form failed validation. Generally, this should be an action that takes an error message and displays it on the page |
Function | ErrorCallback |
customerFirstName |
The client side element name that is capturing the customer first name (usually an input of type text) |
String
(Max 30 char) |
txtFirstName |
customerLastName (required) |
The client side element name that is capturing the customer last name (usually an input of type text) |
String
(Max 60 char) |
txtLastName |
customerReference |
The client side element name that is capturing your unique customer reference (usually an input of type hidden). This is optional |
String
(Max 50 char) |
hidReference |
customerAddress1 |
The client side element name that is capturing the customer address line 1 (usually an input of type text). This is optional * * Note required if customerAddress2 is present |
String
(Max 30 char) |
txtAddress1 |
customerAddress2 |
The client side element name that is capturing the customer address line 2 (usually an input of type text). This is optional |
String
(Max 30 char) |
txtAddress2 |
customerSuburb |
The client side element name that is capturing the customer suburb (usually an input of type text). This is optional |
String
(Max 20 char) |
txtSuburb |
customerState |
The client side element name that is capturing the customer state (usually an input of type text). This is optional |
String
(Max 3 char) |
txtState |
customerPostcode |
The client side element name that is capturing the customer postcode (usually an input of type text). This is optional |
String
(Max 4 digits) |
txtPostcode |
customerEmail |
The client side element name that is capturing the customer email address (usually an input of type text) |
String
(Max 255 char) |
txtEmail |
customerMobile |
The client side element name that is capturing the customer mobile number (usually an input of type text). This is optional. NB - for Australian Customers the mobile phone number must be 10 digits long and begin with '04’. |
String
(Max 12 char) |
txtMobile |
nameOnCard
(required if storing credit card) |
The client side element name that is capturing the customer’s name as it appears on their card (usually an input of type text) |
String
(Max. 100 char) |
txtNameOnCard |
cardNumber
(required if storing credit card) |
The client side element name that is capturing the customer’s card number (usually an input of type text) |
String
(Numeric Max 16 digits) |
txtCardNumber |
cardExpiryMonth
(required if storing credit card) |
The client side element name that is capturing the customer’s card month expiry date (usually an input of type text) |
Numeric
(2 digits) |
txtExpiryMonth |
cardExpiryYear
(required if storing credit card) |
The client side element name that is capturing the customer’s card year expiry date (must be 4 digits, usually an input of type text) |
Numeric
(4 digits) |
txtExpiryYear |
CardCCV
(Required for real-time processing only) |
The client side element name that is capturing the CCV number of the card (usually an input of type text) |
Numeric
(4 digits) |
txtCCV |
paymentAmount |
The client side element name that is capturing the amount. Usually, this would be a hidden field that your server has already generated. 0 must be passed for this element if you do not want to perform a realtime payment from the card. If a non-0 integer is passed for this element, the customers credit card will be charged that amount |
Numeric | hdnAmount |
paymentReference
(Required for real-time processing only) |
The client side element name that is capturing a payment reference number. This may be a hidden field that your server has already generated. |
String
(Max 50 char) |
hdnPaymentRef.ClientID |
Response
If the transaction and storing of the customer is unsuccessful, the standard error message is reported back and the error handler is called as normal. If the transaction is successful, the data object is returned containing the following parameters:
Parameter Name | Description | Format | Example |
---|---|---|---|
Data.BankReceiptId |
The receipt ID generated by the bank. You can use this ID to confirm a payment has been approved |
Integer | 237817 |
Data.CustomerRef |
The unique reference number stored in the Ezidebit database that corresponds to the customer. |
Integer | 327873 |
Error |
The error response code. This will be 0 for a successful API call. |
Numeric | 0 |
ErrorMessage |
A short description of the Payment Result code that you may choose to display to the user. |
String | null |
Complete Examples
We have a sample pack of HTML pages that you can download or check out a few implementations:
View the source or download the files to see how they work.
Please note: If you enter something into the Payment Reference field and a Payment Amount is anything other than $0, a charge will be attempted on the card and then customer saved. If the Payment Reference and Amount is left blank, no attempt will be made to charge the card but the customer and the entered card details will be saved. CCV is not a mandatory field in this form because it is not needed to save the card details, but if the card is to be charged, CCV becomes mandatory.
Real-time Credit Card Transaction Response Codes
Please refer to Credit Card Response Codes for a list of Transaction Response Codes
Error Response Code
Please refer to Error Codes for a list of Error Codes.
SaveCustomerAccount
URL
Endpoint | |
Production (LIVE) | https://api.ezidebit.com.au/V3-5/public-rest |
Sandbox (TEST) | https://api.demo.ezidebit.com.au/V3-5/public-rest |
Javascript File | https://static.ezidebit.com.au/javascriptapi/js/ezidebit_2_0_0.min.js |
Description
The SaveCustomerAccount method will store customer information and it will accept customer bank account information including the account name, BSB and account number.
Note that the customer is not charged. Instead, their account details are stored on file for later use.
When using this method to save a customer as part of an online sign up, you MUST adhere to the requirements set out in the BECS Compliance section.
Requests
The SaveCustomerAccount method can be called using the init method by using the public key and the following parameters:
Parameter Name | Description | Format | Example |
---|---|---|---|
submitAction (required) |
This should always be SaveCustomerAccount for this function |
String | SaveCustomerAccount |
submitButton (required) |
The client side element name of the button to submit the form (usually an input of type submit or button) |
String | btnSubmit.ClientID |
submitCallback (required) |
The method name of some client side code to execute when the operation completes successfully. A useful action would be to store the Ezidebit customer ID into a hidden field and then to submit the form to your server |
Function | SubmitCallback |
submitError (required) |
The method name of some client side code to execute when the operation failed, or the form failed validation. Generally, this should be an action that takes an error message and displays it on the page |
Function | ErrorCallback |
customerFirstName |
The client side element name that is capturing the customer first name (usually an input of type text) |
String
(Max 30 char) |
txtFirstName |
customerLastName (required) |
The client side element name that is capturing the customer last name (usually an input of type text) |
String
(Max 60 char) |
txtLastName |
customerReference |
The client side element name that is capturing your unique customer reference (usually an input of type hidden). This is optional |
String
(Max 50 char) |
hidReference |
customerAddress1 |
The client side element name that is capturing the customer address line 1 (usually an input of type text). This is optional * * Note required if customerAddress2 is present |
String
(Max 30 char) |
txtAddress1 |
customerAddress2 |
The client side element name that is capturing the customer address line 2 (usually an input of type text). This is optional |
String
(Max 30 char) |
txtAddress2 |
customerSuburb |
The client side element name that is capturing the customer suburb (usually an input of type text). This is optional |
String
(Max 20 char) |
txtSuburb |
customerState |
The client side element name that is capturing the customer state (usually an input of type text). This is optional |
String
(Max 3 char) |
txtState |
customerPostcode |
The client side element name that is capturing the customer postcode (usually an input of type text). This is optional |
String
(Max 4 digits) |
txtPostcode |
customerEmail |
The client side element name that is capturing the customer email address (usually an input of type text) |
String
(Max 255 char) |
txtEmail |
customerMobile |
The client side element name that is capturing the customer mobile number (usually an input of type text). This is optional. NB - for Australian Customers the mobile phone number must be 10 digits long and begin with '04’. |
String
(Max 12 char) |
txtMobile |
accountName (required) |
The client side element name that is capturing the customer bank account name (usually an input of type text). |
String | txtAccountName |
accountBSB (required) |
The client side element name that is capturing the customer BSB number (usually an input of type text) |
String
(Numeric max 6 characters, do not include the dash) |
txtAccountBSB |
accountNumber (required) |
The client side element name that is capturing the customer account number (usually an input of type text) |
String
(Numeric max 9 characters) |
txtAccountNumber |
Response
If the transaction and storing of the customer is unsuccessful, the standard error message is reported back and the error handler is called as normal. If the transaction is successful, the data object is returned containing the following parameters:
Parameter Name | Description | Format | Example |
---|---|---|---|
CustomerRef |
The unique reference number stored in the Ezidebit database that corresponds to the customer. |
Integer | 327873 |
Complete Examples
We have a sample pack of HTML pages that you can download or check out the SaveCustomerBankAccount.htm one on its own. View the source or download the files to see how they work.
Maintaining Account Details
Embeddable Widget
The Account Widget should be used for maintenance of bank account/credit card details for existing customers. It is possible to create customers in the Ezidebit Management Systems without Bank Account or Credit Card Details recorded against them, and they will be set to a non-processing Hold Status until the appropriate payment source is provided. This allows businesses to create new customers through integrated methods, without the need for their system to handle sensitive data, instead using Ezidebit’s widget to handle that data directly.
Description
The Account Widget is delivered over a Secure Sockets Layer (SSL) HyperText Transfer Protocol (HTTP) connection, otherwise known as HTTPS. This ensures that communication between your application or web browser is secure and encrypted.
When the Account Widget is included in a web-based application, as described in this document, the communications occur directly between the user’s browser and the Ezidebit web servers, and there is no communication between your application or database server and the Ezidebit web servers.
When the Account Widget is included in a standalone application that is installed on the user’s computer, the user’s computer will need to communicate with the Ezidebit web servers via https, and as such you will need to ensure that you include the appropriate Secure Sockets Libraries in your application to facilitate this.
Ezidebit’s SSL Certificates are signed by the DigiCert High Assurance CA-3 Intermediate Certificate, which is a commonly embedded root certificate on most platforms. If your library or program does not recognise the Certification Authority, you may also need to install the Root Certificate with your application. You can obtain the appropriate root certificate and instructions on how to install it directly from DigiCert (https://www.digicert.com/digicert-root- certificates.htm)
Use Cases
The Ezidebit Management Systems maintain only one payment source (bank account or credit card) for each Customer (payer). When you change the Bank Account or Credit Card on record, it will record this change at the Customer level and apply the new credentials for all future payments from that Payer until such a point as they are changed again.
Structure
The Account Widget is a web-based form. You can access the form through either GET or POST methods, via a secured HTTPS call. The live and test widgets are located at the following addresses.
The URL of the LIVE widget is:
https://widget.ezidebit.com.au/account/
The URL of the TEST widget is:
https://widget.demo.ezidebit.com.au/account/
The base URL without any actions will return an Error 404. You will need to provide the actions with the widget. The widget currently has two actions available, view and edit. These actions are appended to the URL before the query string parameters. For example:
To view account details:
https://widget.demo.ezidebit.com.au/account/view?dk=49A67D1B-DF3F-4013-B13A-A5E9E41E8873&cr=99999
To edit account details:
https://widget.demo.ezidebit.com.au/account/edit?dk=49A67D1B-DF3F-4013-B13A-A5E9E41E8873&cr=99999
CALLBACK METHOD
If you would like to redirect customer after they have filled out our form and successfully submitted, you can request a callback by providing link in the callback
parameter.
Embed Using iFrame
To use the account widget within your application or website it must be rendered in its own container. Typically, you will achieve this in a website by providing an iframe to position the widget where you wish.
The source URL for the iframe should be dynamically generated by your application to ensure that the correct customer is
loaded through the query string parameters, as well as any visual component you wish to control. As a minimum, you must
supply your digital key and either of the customer reference identification parameters (er=
or cr=
).
Input Values
Below is a list of all of the possible query string or POST parameters that can be passed to the widget to initialise the state of the form. Note that the parameters in bold may be required.
Parameter | Description | Format | Example |
---|---|---|---|
dk (required) |
Digital Key The integration Digital Key supplied to the client by Ezidebit. |
String
(36 chars) |
49A67D1B-DF3F-4013-B13A-A5E9E41E8874 |
er
(*required if cr parameter is not provided) |
Ezidebit Reference Number The number provided by Ezidebit for the customer. This Ezidebit ID can be used to allow the client system to communicate with Ezidebit using the Ezidebit ID in the case that the client system does not have its own identifier. This value is the same as the EziDebitCustomerID value that is used through other Ezidebit APIs |
Number
(typically 5 to 7 digits long) |
678124 |
cr
(*required if er parameter is not provided) |
Client’s Reference Number A unique identifier for this customer that is generated by the client management application. This might be a member ID, order number, GUID or some other identifier. This reference ID can be used in place of the Ezidebit Customer ID to allow the client system to communicate with Ezidebit using its own payer/customer references. This value is the same as the YourSystemReference value used through other Ezidebit APIs |
String
(max 50 chars) |
5363-XXs |
E |
Editable
Setting this parameter to 1 will enable users to edit the account details. Providing an e=1 parameter enables an “Edit” button to be displayed at the bottom of the view action. |
Number
(1 char) 0 - View Only 1 - Editable |
0 or 1 |
callback |
Callback URL Specifying this parameter forces widget to redirect the user to the URL specified in this parameter after the form submission is completed. |
String | http://www.ezidebit.com/ |
F |
Font
Sets the font for all text on the widget. |
String
(max 50 chars) |
Trebuchet MS |
h1c |
Header Colour Sets the colour of the header. Must be a hex code - RRGGBB |
String
(6 chars) |
FF5595 |
h1s |
Header Size Sets the size of the header. Must be in pixels. |
Number
(in pixels) |
20 |
lblc |
Label Colour Sets the colour of the labels. Must be a hex code - RRGGBB |
String
(6 chars) |
EB7636 |
lbls |
Label Size Sets the size of the labels. Must be in pixels. |
Number
(in pixels) |
14 |
bgc |
Background Colour Sets the background colour of the widget. Must be a hex code - RRGGBB |
String
(6 chars) |
FFFFFF |
hgl |
Highlight Colour Sets the highlight colour of the widget. This is the predominant colour of the widget. Must be a hex code - RRGGBB |
String
(6 chars) |
1892CD |
txtc |
Text Colour Sets the colour of all other text on the widget. Must be a hex code - RRGGBB |
String
(6 chars) |
333333 |
txtbgc |
Textbox Background Colour Sets the background colour of the textboxes. Must be a hex code - RRGGBB |
String
(6 chars) |
FFFFFF |
txtbc |
Textbox Focus Border Colour Sets the colour of the textbox borders for the currently selected (focus) textbox. Must be a hex code - RRGGBB |
String
(6 chars) |
EB7636 |
Error Codes
The table below outlines the possible error codes that may be returned by the widget.
Code | Description |
Possible Cause |
101 |
Not all required parameters were supplied |
The widget requires at least the digital key (dk) parameter and either the Ezidebit ID (er) or your ID (cr) parameters. |
201 |
Could not find a customer with the provided details |
The value of the reference ID parameter (er or cr) does not relate to a customer in the Ezidebit Management System. Check that the customer has been created. |
202 |
Invalid Digital Key |
The value of the Digital Key parameter (dk) does not identify a client record in the Ezidebit Management System. Check that the Digital Key that you are using is active and you are calling the correct URL, i.e. you are using a Test digital key for the test widget or a live digital key for the live widget. |
ChangeCustomerPaymentInfo
URL
Endpoint | |
Production (LIVE) | https://api.ezidebit.com.au/V3-5/public-rest |
Sandbox (TEST) | https://api.demo.ezidebit.com.au/V3-5/public-rest |
Javascript File | https://static.ezidebit.com.au/javascriptapi/js/ezidebit_2_0_0.min.js |
The ChangeCustomerPaymentInfo is a Javascript method that enables you to collect updated bank account or credit card details from customers via your web site. We recommend that you have a secure log in for the customer to access any of their existing information before allowing update of details.
Description
This method allows you to update the billing account details currently held on file by Ezidebit for a customer. This requires an identifier to be passed in to identify the correct customer to be updated.
Note that the customer is not charged. Instead, their account details are stored on file for later use.
This method by default reactivates a customer if on hold status.
Requests
You can call the ChangeCustomerPaymentInfo method by passing the init method a public key followed by an array of arguments. The array parameters include:
Parameter Name | Description | Format | Example |
---|---|---|---|
submitAction (required) |
This should always be ChangeCustomerPaymentInfo for this function |
String | ChangeCustomerPaymentInfo |
submitButton (required) |
The client side element name of the button to submit the form (usually an input of type submit or button) |
String | btnSubmit.ClientID |
submitCallback (required) |
The method name of some client side code to execute when the operation completes successfully. A useful action would be to store the Ezidebit customer ID into a hidden field and then to submit the form to your server |
Function | SubmitCallback |
submitError |
The method name of some client side code to execute when the transaction failed, or the form validation failed. Generally this should be an action that takes an error message and displays it on the page |
Function | ErrorCallback |
customerRef |
The Ezidebit Customer Ref used to identify the customer in Ezidebit’s system |
Numeric | 5432102 |
customerReference |
The Client side method name that is used to identify the customer. |
String | Customer1001 |
cardNumber |
The client side element name that is capturing the customer’s card number (usually an input of type text). This is the card number that will be used for future direct debit payments. Do not supply a value if updating to use a bank account |
Numeric
(max 16 digits) |
4434123456789351 |
cardExpiryMonth |
The client side element name that is capturing the customer’s card month expiry date (usually an input of type text) Mandatory where cardNumber is provided |
Numeric
(two digits) |
12 |
cardExpiryYear |
The client side element name that is capturing the customer’s card year expiry date (must be 4 digits, usually an input of type text). Mandatory where cardNumber is provided |
Numeric
(four digits) |
2016 |
nameOnCard |
The client side element name that is capturing the customer’s name as it appears on their card (usually an input of type text). Mandatory where cardNumber is provided |
String
(max 100 char) |
John Smith |
accountName |
The client side element name that is capturing the customer’s bank account name (usually an input type of text). Do not supply a value if updating to use a credit card |
String
(max 100 char) |
John Smith |
accountBSB |
The client side element name that is capturing the customer’s BSB number (usually an input type of text). Mandatory where accountName is provided |
Numeric
(six digits) |
124001 |
accountNumber |
The client side element name that is capturing the customer’s account number number (usually an input type of text). Mandatory where accountName is provided |
Numeric
(max nine digits) |
789654123 |
Response
If the values entered by the customer are invalid, the submitError callback is invoked and will pass an error message together with the element that contains the problem value. An example of a submitError callback is shown below, in which the handler displays the error message and highlights the problem element with a red background and border.
If the call to the server was successful, but the server returned an error message then the same callback given to SubmitCallback is called and passes an errorMessage but no element.
Complete Examples
We have a sample pack of HTML pages that you can download or check out a few implementations:
View the source or download the files to see how they work.
Real-time Credit Card Transaction Response Codes
Please refer to Transaction Return Codes for a list of Transaction Return Codes.
Please refer to Transaction Return Codes for a list of Transaction Return Codes.
Error Response Code
Please refer to Error Codes for a list of Error Codes.
EditCustomerBankAccount
URL
URL of Web Services | |
Production (LIVE) | https://api.ezidebit.com.au/v3-5/pci |
Sandbox (TEST) | https://api.demo.ezidebit.com.au/v3-5/pci |
Description
This method will Add or Edit the Bank Account detail on record for a Customer (Payer).
It is important to note the following when using EditCustomerBankAccount:
- If you are using this method to ADD bank account details to a newly created Customer, you must provide a value of YES in the Reactivate parameter if you want the Customer to be activated so that debits will be taken from them. Newly created Customers are created on a Hold (HB) status until Bank Account or Credit Card details are provided;
- If the Customer currently has Credit Card details on record as the Payment Source, then this function will change the Payment Source for all future payments to the bank account details supplied.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:px="https://px.ezidebit.com.au/">
<soapenv:Header />
<soapenv:Body>
<px:EditCustomerBankAccount>
<px:DigitalKey>00000000-0000-0000-0000-000000000000</px:DigitalKey>
<px:EziDebitCustomerID>351328</px:EziDebitCustomerID>
<px:YourSystemReference />
<px:BankAccountName>Joe Smith</px:BankAccountName>
<px:BankAccountBSB>064001</px:BankAccountBSB>
<px:BankAccountNumber>1234</px:BankAccountNumber>
<px:Reactivate>YES</px:Reactivate>
<px:Username>WebServiceUser</px:Username>
</px:EditCustomerBankAccount>
</soapenv:Body>
</soapenv:Envelope>
Request Parameters
Parameter Name | Description | Format | Example |
---|---|---|---|
DigitalKey (Required) |
The 36 character Digital Key supplied to you by Ezidebit to identify your business |
String | 8591BFD4-E7C8-4284-84F7-E6C419114FA8 |
EziDebitCustomerID |
The unique number assigned to the Customer by Ezidebit. |
Integer | 351328 |
YourSystemReference |
A unique system identifier for the customer (e.g. GUID or your primary key). You can use this value to identify your Customer in the Ezidebit system if you supplied a value in this field in the AddCustomer method. NB - You must provide a value for either EziDebitCustomerID or YourSystemReference to identify your Customer, but not both. |
String (Max 50 char) | 563445878985432x76 |
BankAccountName (Required) |
Customer’s bank account name |
String (Max 32 char) | Joe Smith |
BankAccountBSB (Required) |
Customer’s BSB number |
String (Numeric 6 digits) | 064001 |
BankAccountNumber (Required) |
Customer’s bank account number |
String (Numeric max 9 digit AU/9-10 digit NZ) | 12345678 |
Reactivate (Required) |
This field allows you to set the Customer status as Active. NB - If the Customer is already active, passing a value of YES will have no impact. If the Customer is not Active, passing a value of YES will move the Customer to an Active Status. Passing a value of NO will not alter the Customer status. |
String YES or NO |
YES |
Username |
Optionally record the user in your system that is executing this action |
String (Max 50 char) | Webuser |
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<EditCustomerBankAccountResponse xmlns="https://px.ezidebit.com.au/">
<EditCustomerBankAccountResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Data>S</Data>
<Error>0</Error>
<ErrorMessage />
</EditCustomerBankAccountResult>
</EditCustomerBankAccountResponse>
</s:Body>
</s:Envelope>
Response
The <Data>field in the EditCustomerBankAccount response will be either:
- ’S’ - indicates that the Bank Account details were successfully added to the Customer record;
- Empty - When the Data field is empty, it indicates that the update was not successful.You should check the value of the Error field. If an error has occurred, it will be indicated by a non-zero value in the Error field, with a text descriptor in the ErrorMessage field.
EditCustomerCreditCard
URL
URL of Web Services | |
Production (LIVE) | https://api.ezidebit.com.au/v3-5/pci |
Sandbox (TEST) | https://api.demo.ezidebit.com.au/v3-5/pci |
Description
This method will Add or Edit the Credit Card detail on record for a Customer (Payer).
It is important to note the following when using EditCustomerCreditCard:
- If you are using this method to ADD Credit Card details to a newly created Customer, you must provide a value of YES in the Reactivate parameter if you want the Customer to be activated so that debits will be taken from them. Newly created Customers are created on a Hold (HB) status until Bank Account or Credit Card details are provided;
- If the Customer currently has Bank Account details on record as the Payment Source, then this function will change the Payment Source for all future payments to the credit card details supplied.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:px="https://px.ezidebit.com.au/">
<soapenv:Header />
<soapenv:Body>
<px:EditCustomerCreditCard>
<px:DigitalKey>00000000-0000-0000-0000-000000000000</px:DigitalKey>
<px:EziDebitCustomerID>351328</px:EziDebitCustomerID>
<px:YourSystemReference />
<px:NameOnCreditCard>Joe Smith</px:NameOnCreditCard>
<px:CreditCardNumber>4242424242424242</px:CreditCardNumber>
<px:CreditCardExpiryYear>2012</px:CreditCardExpiryYear>
<px:CreditCardExpiryMonth>12</px:CreditCardExpiryMonth>
<px:Reactivate>YES</px:Reactivate>
<px:Username>WebServiceUser</px:Username>
</px:EditCustomerCreditCard>
</soapenv:Body>
</soapenv:Envelope>
Request Parameters
Parameter Name | Description | Format | Example |
---|---|---|---|
DigitalKey (Required) |
The 36 character Digital Key supplied to you by Ezidebit to identify your business |
String | 8591BFD4-E7C8-4284-84F7-E6C419114FA8 |
EziDebitCustomerID |
The unique number assigned to the Customer by Ezidebit. |
Integer | 351328 |
YourSystemReference |
A unique system identifier for the customer (e.g. GUID or your primary key). You can use this value to identify your Customer in the Ezidebit system if you supplied a value in this field in the AddCustomer method. NB - You must provide a value for either EziDebitCustomerID or YourSystemReference to identify your Customer, but not both. |
String (Max 50 char) | 563445878985432x76 |
NameOnCreditCard (Required) |
The name on the customer’s credit card |
String (Max 100) | Joe Smith |
CreditCardNumber (Required) |
Customer’s credit card number |
String (Numeric Max 16 digits) | 4242000042420000 |
CreditCardExpiryYear (Required) |
Customer’s credit card expiry year |
Numeric (4 digits) | 2012 |
CreditCardExpiryMonth (Required) |
Customer’s credit card expiry month |
Numeric (2 digits) | 12 |
Reactivate (Required) |
This field allows you to set the Customer status as Active. NB - If the Customer is already active, passing a value of YES will have no impact. If the Customer is not Active, passing a value of YES will move the Customer to an Active Status. Passing a value of NO will not alter the Customer status. |
String
YES or NO |
YES |
Username |
Optionally record the user in your system that is executing this action |
String (Max 50 char) | Webuser |
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<EditCustomerCreditCardResponse xmlns="https://px.ezidebit.com.au/">
<EditCustomerCreditCardResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Data>S</Data>
<Error>0</Error>
<ErrorMessage />
</EditCustomerCreditCardResult>
</EditCustomerCreditCardResponse>
</s:Body>
</s:Envelope>
Response
The <Data> field in the EditCustomerCreditCard response will be either:
- ’S’ - indicates that the Credit Card details were successfully added to the Customer record;
- Empty - When the Data field is empty, it indicates that the update was not successful. You should check the value of the Error field. If an error has occurred, it will be indicated by a non-zero value in the Error field, with a text descriptor in the ErrorMessage field.
GetCustomerAccountDetails
URL
URL of Web Services | |
Production (LIVE) | https://api.ezidebit.com.au/v3-5/pci |
Sandbox (TEST) | https://api.demo.ezidebit.com.au/v3-5/pci |
Description
This method allows you to retrieve the current Bank Account or Credit Card details recorded for the customer.
It is important to note the following when using GetCustomerAccountDetails:
- Credit Card details that are returned will be masked to show only the last four (4) digits;
- Bank Account details that are returned will be masked to show the full BSB number and only the last 50% of the Bank Account digits;
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:px="https://px.ezidebit.com.au/">
<soapenv:Header />
<soapenv:Body>
<px:GetCustomerAccountDetails>
<px:DigitalKey>00000000-0000-0000-0000-000000000000</px:DigitalKey>
<px:EzidebitCustomerID>351328</px:EzidebitCustomerID>
<px:YourSystemReference />
</px:GetCustomerAccountDetails>
</soapenv:Body>
</soapenv:Envelope>
Parameters
Parameter Name | Description | Format | Example |
---|---|---|---|
DigitalKey (Required) |
The 36 character Digital Key supplied to you by Ezidebit to identify your business |
String | 8591BFD4-E7C8-4284-84F7-E6C419114FA8 |
EzidebitCustomerID |
The unique number assigned to the Customer by Ezidebit. |
Integer | 351328 |
YourSystemReference |
A unique system identifier for the customer (e.g. GUID or your primary key). You can use this value to identify your Customer in the Ezidebit system if you supplied a value in this field in the AddCustomer method. NB - You must provide a value for either EziDebitCustomerID or YourSystemReference to identify your Customer, but not both. |
String (Max 50 char) |
563445878985432x76 |
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetCustomerAccountDetailsResponse xmlns="https://px.ezidebit.com.au/">
<GetCustomerAccountDetailsResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Data>
<AccountHolderName>JOE SMITH</AccountHolderName>
<AccountNumber>XX34</AccountNumber>
<BSB>064-001</BSB>
<CardHolderName>JOE SMITH</CardHolderName>
<CreditCardNumber>xxxxxxxxxxxx4242</CreditCardNumber>
<ExpiryMonth>12</ExpiryMonth>
<ExpiryYear>2023</ExpiryYear>
<PaymentMethod>CR</PaymentMethod>
</Data>
<Error>0</Error>
<ErrorMessage />
</GetCustomerAccountDetailsResult>
</GetCustomerAccountDetailsResponse>
</s:Body>
</s:Envelope>
Response
The <Data>
field in the GetCustomerAccountDetails
response will be either:
- A data set enclosed within the
<Data>
tags for both Bank Account and Credit Card Details. Where details do not exist in the Ezidebit system, an empty parameter will be returned; - Empty - When the Data field is empty, it indicates that the request was not successful.
You should check the value of the Error field. If an error has occurred, it will be indicated by a
non-zero value in the
Error
field, with a text descriptor in theErrorMessage
field.
Parameter Name | Description | Format | Example |
---|---|---|---|
AccountHolderName | Customer’s bank account name | String | John Smith |
AccountNumber | Customer’s bank account number | String | 123456 |
BSB | Customer’s bank account BSB | String | 123-456 |
CardHolderName | The name on the customer's credit card | String | John Smith |
CreditCardNumber | The customer’s masked credit card number. | String | xxxxxxxxxxxx2346 |
ExpiryMonth | The customers credit card expiry month. | Integer | 05 |
ExpiryYear | The customers credit card expiry year. | Integer | 2017 |
PaymentMethod | The payment method which will be used to debit the customer (DR for Bank Accounts OR CR for Credit Cards) | String | CR |
Processing Instant Payments
Ezidebit provides the ability to process a real time credit card payment, either as a once off payment or as a tokenised recurring payment. The following mechanisms are available for processing real time payments:
- Hosted payment page;
- Javascript method;
- Web services.
Hosted payment page
Ezidebit’s hosted payment page provides an out of the box payment page that is fully PCI compliant. The look and feel of the page can be customised via the Ezidebit Online portal to more closely align to a client’s own branding.
Each client’s unique hosted payment page URL is available from the Ezidebit Online portal under Web Page Configuration in the Admin menu.
The submission page simply requires a HTML form with the action parameter set to your unique URL, for example:
https://simple-business-tech.pay.demo.ezidebit.com.au/
During testing, use the URL available from your sandbox account by logging in to Ezidebit Online and selecting Web Page Configuration from the Admin menu.
The payment submission page can pre-load parameters in the payment page by HTML 'GET’ or 'POST’. Both methods are supported and it is your choice if you wish to hide the entry parameters or not. Which method you use will depend on the level of complexity you wish to implement in your website’s encoding to pass data into the hosted payment page for payment processing.
The URL below is an example of using GET Parameters:
https://simple-business-tech.pay.demo.ezidebit.com.au/?FirstName=Test&LastName=Customer&PaymentReference=Payment123
Input Values
The following form fields are submitted by you to our hosted payments page when your customer is sent to our website to make the payment.
Input Field Name | Description | Required | Format |
---|---|---|---|
Type |
Only valid values (I, B) - I = Individual B = Business |
Yes |
String
(Max 1 Char) |
PaymentReference |
This is a reference number or string (usually an order number or invoice number) that is created on your website to identify the order that the payment is for. This value will be passed back to your website when the customer is returned so you can match the order with the results of the payment |
Yes |
String
(Max 20 chars) |
FirstName |
First name of the person making the payment |
Yes |
String
(Max 150 chars) |
LastName |
Last name of the person making the payment |
Yes |
String
(Max 150 chars) |
CompanyName |
Company Name |
No |
String
(Max 150 chars) |
PaymentAmount |
The amount of money in dollars/cents that your customer must pay. Supported currencies only. |
Yes |
Numeric
(Max 2 decimal places allowed) |
countryCode |
Values accepted format [Country Code]_[Dailing Code], eg; (AU_61 , NZ_64) |
Yes |
String
(Max 5 Chars) |
MobilePhoneNumber |
Optional |
No |
String
(Max 255 Chars) |
EmailAddress |
Optional |
No |
String
(Max 255 Chars) |
RedirectURL |
The absolute URL address of the client’s web page that the customer is to be returned to after they make the payment. |
Yes |
String
(Max 500 Chars) |
RedirectMethod |
The method that will be used to pass return paramters back to the return page. Accepted values are GET or POST |
No |
String
(Max 4 Chars) |
ShowDisabledInputs |
When enabled, this will display pre-filled values as text instead of displaying in an editable box. Accepted values are 0 for enabled and 1 for disabled |
Optional |
Numeric
(0 or 1) |
The WebPay instant payment page can host up to 5 unique customised values to better describe your transaction. Contact partner@ezidebit.com.au and our Integration Services Team will assist you to set this up.
Response
Your customer will be sent to this page when they have completed their payment. There are no requirements for this page as far as our gateway is concerned because by this stage all our processing has been completed, however you will likely want to update your order records based on whether the payment was successful or not. To do this you will need to set up your return page to check and store a number of query string variables that contain the results of the payment that will be included on the URL link to your return page (see the Return Values below for details of these variables).
Value Name | Description | Format |
---|---|---|
PaymentReference | The payment reference value that you originally sent through the submission page. | String (Max 20 chars) |
ScheduledAmount | The payment amount value that you originallysent through the submission page. | Decimal |
TransactionFeeCustomer | Transaction fees paid by the payer on this transaction. | Decimal |
ResultText | A short description of the reason for the payment result (value is 'Approved' for successful transactions). | String |
ResultCode | A code that identifies the reason for the payment result (value is '00' or '000' for successful transactions) | Numeric |
NameOnCard | Name entered in the name on card field. | String (Max 100 chars) |
BankReceiptID | Payment receipt ID issued bythe bank if the payment was able to reach the bank for processing. | Numeric |
PayerName | Name entered for the payer in the submission page. | String (Max 100 Chars) |
MobilePhoneNumber | Mobile phone number entered in the submission page. | String (Max 14 Chars) |
EmailAddress | Email Address entered in the submission page. | String (Max 255 Chars) |
BillerID | Biller's Identification | String |
TransactionID | The transaction record | String |
PaymentAmount | The payment amount value that you originally sent through the submission page + any fees paid by the payer. | Decimal |
CompanyName | The company name entered in the submission page. | String (Max 100 Chars) |
ChargeCard
URL
Endpoint | |
Production (LIVE) | https://api.ezidebit.com.au/V3-5/public-rest |
Sandbox (TEST) | https://api.demo.ezidebit.com.au/V3-5/public-rest |
Javascript File | https://static.ezidebit.com.au/javascriptapi/js/ezidebit_2_0_0.min.js |
Description
ChargeCard will process a real-time credit card payment through Ezidebit’s payment gateway. No customer details are stored by Ezidebit.
$(document).ready(function () {
eziDebit.init("YOUR_PUBLIC_KEY", {
submitAction: "ChargeCard",
submitButton: "payNowButton",
submitCallback: displaySubmitCallback,
submitError: displaySubmitError,
nameOnCard: "nameOnCard",
cardNumber: "cardNumber",
cardExpiryMonth: "expiryMonth",
cardExpiryYear: "expiryYear",
cardCCV: "ccv",
paymentAmount: "amount",
paymentReference: "paymentReference"
}, endpoint);
Requests
You can call the ChargeCard method by passing the init method a public key followed by an array of arguments.The array parameters include:
Parameter Name | Description | Format | Example |
---|---|---|---|
submitAction (required) |
This should always be ChargeCard for this function |
String | ChargeCard |
submitButton (required) |
The id of the element to submit the form (usually an input of type submit or button) |
String | btnSubmit |
submitCallback (required) |
The method name of some client side code to execute when the transaction is successful. A useful action would be to store the bank receipt ID in a hidden field and then submit the form to your server. No sensitive data will be submitted. |
Function | SubmitCallback |
submitError (required) |
The method name of some client side code to execute when the transaction failed, or the form failed validation. Generally, this should be an action that takes an error message and displays it on the page. |
Function | ErrorCallback |
nameOnCard (required) |
The client side element name that is capturing the customer’s name as it appears on their card (usually an input of type text) |
String
(Max. 100 char) |
txtNameOnCard |
cardNumber (required) |
The client side element name that is capturing the customer’s card number (usually an input of type text) |
String
(Numeric Max 16 digits) |
txtCardNumber |
cardExpiryMonth (required) |
The client side element name that is capturing the customer’s card month expiry date (usually an input of type text) |
Numeric
(2 digits) |
txtExpiryMonth |
cardExpiryYear (required) |
The client side element name that is capturing the customer’s card year expiry date (must be 4 digits, usually an input of type text) |
Numeric
(4 digits) |
txtExpiryYear |
CardCCV (required) |
The client side element name that is capturing the CCV number of the card (usually an input of type text) |
Numeric
(4 digits) |
txtCCV |
paymentAmount (required) |
The client side element name that is capturing the payment amount (usually either a label field if the customer should not change the value or an input of type text) |
Numeric | lblAmount |
paymentReference (required) |
The client side element name that is capturing a payment reference number. This may be a hidden field that your server has already generated. |
String
(Max 50 char) |
hdnPaymentRef |
function ErrorCallback(errorMessage, element) {
document.getElementById("results").innerHTML = errorMessage;
document.getElementById(element).style.border = "1px solid red";
document.getElementById(element).style.background = "\#F5E4E6";
}
Response
If the values entered by the customer are invalid, the submitError callback is invoked and will pass an error message together with the element that contains the problem value. An example of a submitError callback is shown below, in which the handler displays the error message and highlights the problem element with a red background and border.
If the call to the server was successful, but the server returned an error message then the same callback given to submitError is called and passes an errorMessage but no element.
If the transaction is successful, submitCallback callback is invoked and is passed a data object containing a BankReceiptID and PaymentResult property. The parameters returned are shown below.
Parameter Name | Description | Format | Example |
---|---|---|---|
BankReceiptID |
The receipt ID generated by the bank. You can use this ID to confirm a payment has been approved |
Integer | 237817 |
PaymentResult |
The payment response code from the bank |
String |
A to indicate “approved”. Any other code means the transaction failed. |
Complete Examples
We have a sample pack of HTML pages that you can download or check out the ChargeCard.htm one on its own. View the source or download the files to see how they work.
SaveCustomer
URL
Endpoint | |
Production (LIVE) | https://api.ezidebit.com.au/V3-5/public-rest |
Sandbox (TEST) | https://api.demo.ezidebit.com.au/V3-5/public-rest |
Javascript File | https://static.ezidebit.com.au/javascriptapi/js/ezidebit_2_0_0.min.js |
Description
The SaveCustomer method will add a customer record and associated credit card details to the Ezidebit database, after first optionally processing a real time transaction. The saved customer can be used for later direct debit payments or for a tokenised real time payment.
When submitting the customer with credit card details, there are two scenarios that can occur:
- If the customer details and card information are passed but with no payment amount or payment reference, the customer is stored with the credit card information and no charge to the credit card is processed;
- If the customer details, card information and a payment amount and payment reference are passed, the customer is charged in real-time and the customer and credit card information are stored for later use.
Note that the CCV is not a mandatory field in this form because it is not needed to save the card details, but if the card is to be charged the CCV becomes mandatory.
Requests
Parameter Name | Description | Format | Example |
---|---|---|---|
submitAction (required) |
This should always be SaveCustomer for this function |
String | SaveCustomer |
submitButton (required) |
The client side element name of the button to submit the form (usually an input of type submit or button) |
String | btnSubmit.ClientID |
submitCallback (required) |
The method name of some client side code to execute when the operation completes successfully. A useful action would be to store the Ezidebit customer ID into a hidden field and then to submit the form to your server |
Function | SubmitCallback |
submitError (required) |
The method name of some client side code to execute when the operation failed, or the form failed validation. Generally, this should be an action that takes an error message and displays it on the page |
Function | ErrorCallback |
customerFirstName |
The client side element name that is capturing the customer first name (usually an input of type text) |
String
(Max 30 char) |
txtFirstName |
customerLastName (required) |
The client side element name that is capturing the customer last name (usually an input of type text) |
String
(Max 60 char) |
txtLastName |
customerReference |
The client side element name that is capturing your unique customer reference (usually an input of type hidden). This is optional |
String
(Max 50 char) |
hidReference |
customerAddress1 |
The client side element name that is capturing the customer address line 1 (usually an input of type text). This is optional * * Note required if customerAddress2 is present |
String
(Max 30 char) |
txtAddress1 |
customerAddress2 |
The client side element name that is capturing the customer address line 2 (usually an input of type text). This is optional |
String
(Max 30 char) |
txtAddress2 |
customerSuburb |
The client side element name that is capturing the customer suburb (usually an input of type text). This is optional |
String
(Max 20 char) |
txtSuburb |
customerState |
The client side element name that is capturing the customer state (usually an input of type text). This is optional |
String
(Max 3 char) |
txtState |
customerPostcode |
The client side element name that is capturing the customer postcode (usually an input of type text). This is optional |
String
(Max 4 digits) |
txtPostcode |
customerEmail |
The client side element name that is capturing the customer email address (usually an input of type text) |
String
(Max 255 char) |
txtEmail |
customerMobile |
The client side element name that is capturing the customer mobile number (usually an input of type text). This is optional. NB - for Australian Customers the mobile phone number must be 10 digits long and begin with '04’. |
String
(Max 12 char) |
txtMobile |
nameOnCard
(required if storing credit card) |
The client side element name that is capturing the customer’s name as it appears on their card (usually an input of type text) |
String
(Max. 100 char) |
txtNameOnCard |
cardNumber
(required if storing credit card) |
The client side element name that is capturing the customer’s card number (usually an input of type text) |
String
(Numeric Max 16 digits) |
txtCardNumber |
cardExpiryMonth
(required if storing credit card) |
The client side element name that is capturing the customer’s card month expiry date (usually an input of type text) |
Numeric
(2 digits) |
txtExpiryMonth |
cardExpiryYear
(required if storing credit card) |
The client side element name that is capturing the customer’s card year expiry date (must be 4 digits, usually an input of type text) |
Numeric
(4 digits) |
txtExpiryYear |
CardCCV
(required for real-time processing) |
The client side element name that is capturing the CCV number of the card (usually an input of type text) |
Numeric
(4 digits) |
txtCCV |
paymentAmount |
The client side element name that is capturing the amount. Usually, this would be a hidden field that your server has already generated. If this parameter is not included, the customer and card details are saved. If this parameter is included then the customer credit card is charged then the customer and card details saved. |
Numeric | hdnAmount |
paymentReference |
The client side element name that is capturing a payment reference number. This may be a hidden field that your server has already generated. |
String
(Max 50 char) |
hdnPaymentRef.ClientID |
Response
If the transaction and storing of the customer is unsuccessful, the standard error message is reported back and the error handler is called as normal. If the transaction is successful, the data object is returned containing the following parameters:
Parameter Name | Description | Format | Example |
---|---|---|---|
Data.BankReceiptId |
The receipt ID generated by the bank. You can use this ID to confirm a payment has been approved |
Integer | 237817 |
Data.CustomerRef |
The unique reference number stored in the Ezidebit database that corresponds to the customer. |
Integer | 327873 |
Error |
The error response code. This will be 0 for a successful API call. |
Numeric | 0 |
ErrorMessage |
A short description of the Payment Result code that you may choose to display to the user. |
String | null |
Complete Examples
We have a sample pack of HTML pages that you can download or check out a few implementations:
SaveCustomerCreditCard.htm View the source or download the files to see how they work.
Real-time Credit Card Transaction Response Codes
Please refer to Credit Card Response Codes for a list of Transaction Response Codes.
Error Response Code
Please refer to Error Codes for a list of Error Codes.
ProcessRealTimeTokenPayment
URL
URL of Web Services | |
Production (LIVE) | https://api.ezidebit.com.au/v3-5/pci |
Sandbox (TEST) | https://api.demo.ezidebit.com.au/v3-5/pci |
Description
This method allows you to process a credit card payment in real time using a customer’s credit card number previously stored with Ezidebit.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:px="https://px.ezidebit.com.au/">
<soapenv:Header />
<soapenv:Body>
<px:ProcessRealtimeTokenPayment>
<px:digitalKey>00000000‐0000‐0000‐0000‐000000000000</px:digitalKey>
<px:token>9999999</px:token>
<px:paymentAmountInCents>1600</px:paymentAmountInCents>
<px:customerName>J Smith</px:customerName>
<px:paymentReference>123456789</px:paymentReference>
</px:ProcessRealtimeTokenPayment>
</soapenv:Body>
</soapenv:Envelope>
Request Parameters
Parameter Name | Description | Format | Example |
---|---|---|---|
digitalKey (Required) | The 36 character Digital Key supplied to you by Ezidebit to identify your business | String | 8591BFD4-E7C8-4284-84F7-E6C419114FA8 |
token (Required) | The token used to identify the customer whose credit card is to be used for this payment. Usually this is the EziDebitCustomerID (The unique number assigned to the Customer by Ezidebit.) The second match will be YourSystemRef – your unique system identifier for the customer (eg. GUID or your primary key). Note: YourSystemRef values should not be numeric. | String | 55555555 |
paymentAmountInCents (Required) |
The amount to debit from your payer in cents. The system will verify your minimum allowed amount. The maximum amount is $10000.00 E.g. $20.00 = 2000 |
Numeric | 2000 |
customerName (Required) |
The name of your Customer NB - This is included for reporting purposes. |
String (Max. 80 char) |
Joe Smith |
paymentReference (Required) | Your unique identifier for the transaction | String
(Max 50 char) |
512458557 |
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<ProcessRealtimeTokenPaymentResponse xmlns="https://px.ezidebit.com.au/">
<ProcessRealtimeTokenPaymentResult xmlns:i="http://www.w3.org/2001/XMLSchemainstance">
<Data>
<BankReceiptID>1083550</BankReceiptID>
<ExchangePaymentID>930837</ExchangePaymentID>
<PaymentResult>A</PaymentResult>
<PaymentResultCode>00</PaymentResultCode>
<PaymentResultText>APPROVED</PaymentResultText>
</Data>
<Error>0</Error>
<ErrorMessage i:nil="true" />
</ProcessRealtimeTokenPaymentResult>
</ProcessRealtimeTokenPaymentResponse>
</s:Body>
</s:Envelope>
Response
The <Data> field in the ProcessRealtimeTokenPayment response will be either:
- A data set enclosed within the
<Data>
tags containing payment result details; - Empty - When the Data field is empty, it indicates that the request was not successful. You should check the value of the Error field. If an error has occurred, it will be indicated by a non-zero value in the Error field, with a text descriptor in the ErrorMessage Field.
The following table describes the data contained within Result data set of a response for ProcessRealtimeTokenPayment.
Parameter Name | Description | Format | Example |
---|---|---|---|
BankReceiptID |
The Original Receipt Number issued by the Merchant Acquirer (bank) for this payment. NB - All Payments where the system has been able to communicate with the bank will receive a Receipt ID, regardless of the outcome of the transaction. This field will contain a value for both SUCCESSFUL and UNSUCCESSFUL transactions |
Numeric | 351328 |
ExchangePaymentID | An identifier for the payment within Ezidebit’s own payment systems. | Numeric | 496557 |
PaymentResult |
A single character that identifies the result of the payment. Possible values are: A - Approved. Payment was successfully processed at the bank. F - Failed. Payment was rejected by the bank. Check the PaymentResult Fields for further details about why the payment was unsuccessful. U - Unable to process. A communication or other issue has occurred that means that the Payment cannot be submitted to the bank at this point. You will need to reattempt this payment at a later time. |
String (Max 1 char) | A |
PaymentResultCode | A standard two or three digit code that provides detail on the outcome of a payment. See Credit Card Response Codes for a complete list of values. | Numeric | 00 |
PaymentResultText | A short description of the Payment Result code that you may choose to display to the user. See Credit Card Response Codes for a complete list of values. | String | Approved |
ProcessRealTimeCreditCardPayment
URL
URL of Web Services | |
Production (LIVE) | https://api.ezidebit.com.au/v3-5/pci |
Sandbox (TEST) | https://api.demo.ezidebit.com.au/v3-5/pci |
Description
This method allows you to process a credit card payment in real time.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:px="https://px.ezidebit.com.au/">
<soapenv:Header />
<soapenv:Body>
<px:ProcessRealtimeCreditCardPayment>
<px:DigitalKey>00000000-0000-0000-0000-000000000000</px:DigitalKey>
<px:CreditCardNumber>4242424242424242</px:CreditCardNumber>
<px:CreditCardExpiryMonth>12</px:CreditCardExpiryMonth>
<px:CreditCardExpiryYear>2012</px:CreditCardExpiryYear>
<px:CreditCardCCV>454</px:CreditCardCCV>
<px:NameOnCreditCard>J.P. Smith</px:NameOnCreditCard>
<px:PaymentAmountInCents>2000</px:PaymentAmountInCents>
<px:CustomerName>Joe Smith</px:CustomerName>
<px:PaymentReference>512458557</px:PaymentReference>
</px:ProcessRealtimeCreditCardPayment>
</soapenv:Body>
</soapenv:Envelope>
Request Parameters
Parameter Name | Description | Format | Example |
---|---|---|---|
DigitalKey (Required) |
The 36 character Digital Key supplied to you by Ezidebit to identify your business |
String | 8591BFD4-E7C8-4284-84F7-E6C419114FA8 |
CreditCardNumber (Required) |
Customer’s credit card number |
String
(Numeric Max 16 digits) |
4242000042420000 |
CreditCardExpiryMonth (Required) |
Customer’s credit card expiry month |
Numeric
(2 digits) |
12 |
CreditCardExpiryYear (Required) |
Customer’s credit card expiry year |
Numeric
(4 digits) |
2012 |
CreditCardCCV (Required) |
The three or four digit Credit Card Security Number that is located on the signature panel (Visa/Mastercard) or front of the card. |
Numeric
(4 digits) |
454 |
NameOnCreditCard (Required) |
The name as it appears on the customer’s credit card |
String
(Max. 100 char) |
J.P. Smith |
PaymentAmountInCents (Required) |
The amount to debit from your payer in cents. The system has a $2.00 minimum debit amount. If you would like to process smaller amounts please email partner@ezidebit.com.au E.g. $20.00 = 2000 |
Numeric | 2000 |
CustomerName |
The name of your Customer NB - This is included for reporting purposes. |
String
(Max. 255 char) |
Joe Smith |
PaymentReference (Required) |
Your unique identifier for the transaction |
String
(Max 50 char) |
512458557 |
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<ProcessRealtimeCreditCardPaymentResponse xmlns="https://px.ezidebit.com.au/">
<ProcessRealtimeCreditCardPaymentResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Data>
<BankReceiptID>933369</BankReceiptID>
<ExchangePaymentID>49476</ExchangePaymentID>
<PaymentResult>A</PaymentResult>
<PaymentResultCode>00</PaymentResultCode>
<PaymentResultText>Approved</PaymentResultText>
</Data>
<Error>0</Error>
<ErrorMessage i:nil="true" />
</ProcessRealtimeCreditCardPaymentResult>
</ProcessRealtimeCreditCardPaymentResponse>
</s:Body>
</s:Envelope>
Response
The <Data> field in the ProcessRealtimeCreditCardPayment response will be either:
- A data set enclosed within the <Data> tags containing payment result details;
- Empty - When the Data field is empty, it indicates that the request was not successful. You should check the value of the Error field. If an error has occurred, it will be indicated by a non-zero value in the Error field, with a text descriptor in the ErrorMessage field.
The following table describes the data contained within Result data set of a response for ProcessRealtimeCreditCardPayment.
Parameter Name | Description | Format | Example |
---|---|---|---|
BankReceiptID |
The Original Receipt Number issued by the Merchant Acquirer (bank) for this payment. NB - All Payments where the system has been able to communicate with the bank will receive a Receipt ID, regardless of the outcome of the transaction. This field will contain a value for both SUCCESSFUL and UNSUCCESSFUL transactions |
Numeric | 351328 |
ExchangePaymentID |
An identifier for the payment within Ezidebit’s own payment systems. |
Numeric | 496557 |
PaymentResult |
A single character that identifies the result of the payment. Possible values are: A - Approved. Payment was successfully processed at the bank. F - Failed. Payment was rejected by the bank. Check the PaymentResult Fields for further details about why the payment was unsuccessful. U - Unable to process. A communication or other issue has occurred that means that the Payment cannot be submitted to the bank at this point. You will need to reattempt this payment at a later time. |
String
(Max 1 char) |
A |
PaymentResultCode |
A standard two or three digit code that provides detail on the outcome of a payment. See Credit Card Response Codes for a complete list of values. |
Numeric |
00 |
PaymentResultText |
A short description of the Payment Result code that you may choose to display to the user. See Credit Card Response Codes for a complete list of values. |
String | Approved |
Creating Batch Payments
AddPayment
URL
URL of Web Services | |
Production (LIVE) | https://api.ezidebit.com.au/v3-5/nonpci |
Sandbox (TEST) | https://api.demo.ezidebit.com.au/v3-5/nonpci |
Description
This method is used to add a single payment to the Customer’s payment schedule to be debited on the date provided in the DebitDate field.
The existing payment schedule may or may not already have payments that have been added individually or as part of a created schedule. This method will simply create a new payment for the identified customer on the date provided.
A PaymentReference may be included in the data. The PaymentReference can then be used later to retrieve the status or full transaction details of the payment. The payment reference is maintained within Ezidebit’s systems and is included in some reporting to the client, however the PaymentReference value will not appear on a customer’s bank account or credit card statement.
It is also important to note the following when adding Payments:
- Not more than two (2) payments may be added for an individual customer on any given day;
- A DebitDate of up to thirty-one (31) days in the past can be used. Any payment that is scheduled with a DebitDate in the past will be processed and transmitted to the bank during the next processing run;
- You can use either EziDebitCustomerID or YourSystemReference to identify your customer in the Ezidebit System when adding payments.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:px="https://px.ezidebit.com.au/">
<soapenv:Header />
<soapenv:Body>
<px:AddPayment>
<px:DigitalKey>00000000-0000-0000-0000-000000000000</px:DigitalKey>
<px:EziDebitCustomerID />
<px:YourSystemReference>563445878985432x76</px:YourSystemReference>
<px:DebitDate>2011-03-02</px:DebitDate>
<px:PaymentAmountInCents>2000</px:PaymentAmountInCents>
<px:PaymentReference>test</px:PaymentReference>
<px:Username>WebServiceUser</px:Username>
</px:AddPayment>
</soapenv:Body>
</soapenv:Envelope>
Request Parameters
Parameter Name | Description | Format | Example |
---|---|---|---|
DigitalKey (Required) |
The 36 character Digital Key supplied to you by Ezidebit to identify your business |
String | 8591BFD4-E7C8-4284-84F7-E6C419114FA8 |
EziDebitCustomerID |
The unique number assigned to the Customer by Ezidebit. |
String | 351328 |
YourSystemReference |
A unique system identifier for the customer (e.g. GUID or your primary key). You can use this value to identify your Customer in the Ezidebit system if you supplied a value in this field in the AddCustomer method. NB - You must provide a value for either EziDebitCustomerID or YourSystemReference to identify your Customer, but not both. |
String
(Max 50 char) |
563445878985432x76 |
DebitDate (Required) |
The date that you wish for this payment to be deducted from your Customer’s bank account or credit card. |
String yyyy-MM-dd | 2010-12-22 |
PaymentAmountInCents (Required) |
The amount to debit from your payer in cents. The system has a $2.00 minimum debit amount. If you would like to process smaller amounts please email partner@ezidebit.com.au Eg. $20.00 = 2000 |
Integer | 2000 |
PaymentReference |
An optional ID that you can use to later identify this payment in the Ezidebit systems. This ID might be a specific Invoice or Order number within your system relating to an individual payment. The PaymentReference can also be searched for using a wildcard in other methods. You might choose to provide delimited references that identify the batch or customer and payment or any other additional data that you might wish to search on later. |
String
(Max 50 char) |
TS004 |
Username |
Optionally record the user in your system that is executing this action |
String
(Max 50 char) |
Webuser |
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<AddPaymentResponse xmlns="https://px.ezidebit.com.au/">
<AddPaymentResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Data>S</Data>
<Error>0</Error>
<ErrorMessage i:nil="true" />
</AddPaymentResult>
</AddPaymentResponse>
</s:Body>
</s:Envelope>
Response
The <Data> field in the AddPayment response will be either:
- ’S’ - indicates that the Payment was successfully added to the Customer’s Schedule to be debited at a later date. This does not indicate that the payment was successfully received from the Customer’s payment method;*
- Empty - When the Data field is empty, it indicates that the update was not successful. You should check the value of the Error field. If an error has occurred, it will be indicated by a non-zero value in the Error field, with a text descriptor in the ErrorMessage Field.
AddPaymentUnique
URL
URL of Web Services | |
Production (LIVE) | https://api.ezidebit.com.au/v3-5/nonpci |
Sandbox (TEST) | https://api.demo.ezidebit.com.au/v3-5/nonpci |
Description
This method is used to add a single payment to the Customer’s payment schedule to be debited on the date provided in the DebitDate field.
This method is identical to the AddPayment method except that PaymentReference must be included in the data and uniqueness check is performed on PaymentReference before adding payment to schedule.
AddBankDebit
URL
URL of Web Services | |
Production (LIVE) | https://api.ezidebit.com.au/v3-5/pci |
Sandbox (TEST) | https://api.demo.ezidebit.com.au/v3-5/pci |
Description
This method is designed to accept requests that include both Customer (Payer) and Payment details in a single call. It will create, update or maintain a Customer and schedule the payment to be debited from the account. A system utilising this method will provide a unique Payer Reference from the integrating system as well as a unique Payment Reference for each payment.
It is important to note the following when using AddBankDebit:
- Ezidebit Customer References cannot be used with this method;
- If the Customer cannot be identified in the Ezidebit system using the YourSystemReference parameter, a new Customer will be created and the payment added to the Customer’s schedule;
- If the Customer can be identified in the Ezidebit system by the YourSystemReference Parameter but the Bank Account details differ to those on record or the Customer is currently using a Credit Card for payments, the Customer’s account with Ezidebit will be updated using the new details and the payment will be scheduled;
- If the Customer can be identified in the Ezidebit system by the YourSystemReference Parameter and the Bank Account details do not differ to those on record, then payment will simply be scheduled;
- If new Bank Account details are provided for a Customer that is not on an Active status in the Ezidebit system, the Customer details will be updated and the Customer status will be changed to Active;
- A DebitDate of up to thirty-one (31) days in the past can be used. Any payment that is scheduled with a DebitDate in the past will be processed and transmitted to the bank during the next processing run.
When using this method to save a customer as part of an online sign up, you MUST adhere to the requirements set out in the BECS Compliance section.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:px="https://px.ezidebit.com.au/">
<soapenv:Header />
<soapenv:Body>
<px:AddBankDebit>
<px:DigitalKey>00000000-0000-0000-0000-000000000000</px:DigitalKey>
<px:YourSystemReference>101</px:YourSystemReference>
<px:YourGeneralReference>101</px:YourGeneralReference>
<px:LastName>Smith</px:LastName>
<px:FirstName>Joe</px:FirstName>
<px:EmailAddress>test@ezidebit.com.au</px:EmailAddress>
<px:MobilePhoneNumber>0400000000</px:MobilePhoneNumber>
<px:PaymentReference>1</px:PaymentReference>
<px:BankAccountName>Joe Smith</px:BankAccountName>
<px:BankAccountBSB>064001</px:BankAccountBSB>
<px:BankAccountNumber>1234</px:BankAccountNumber>
<px:PaymentAmountInCents>500</px:PaymentAmountInCents>
<px:DebitDate>2010-12-24</px:DebitDate>
<px:SmsPaymentReminder>NO</px:SmsPaymentReminder>
<px:SmsFailedNotification>NO</px:SmsFailedNotification>
<px:SmsExpiredCard>NO</px:SmsExpiredCard>
<px:Username>WebServiceUser</px:Username>
</px:AddBankDebit>
</soapenv:Body>
</soapenv:Envelope>
Request Parameters
Parameter Name | Description | Format | Example |
---|---|---|---|
DigitalKey (Required) | The 36 character Digital Key supplied to you by Ezidebit to identify your business | String | 8591BFD4-E7C8-4284-84F7-E6C419114FA8 |
YourSystemReference (Required) | A unique system identifier for the customer (e.g. GUID or your primary key). You can use this value to identify your Customer in the Ezidebit system. | String (Max 50 char) | 563445878985432x76 |
YourGeneralReference |
A secondary unique reference for the customer. Where system based identifiers (YourSystemReference) can be complex numbers, this is designed to be a simpler, human-friendly number. You may use a GUID to create the system-to-system link with YourSystemReference, and choose to include a membership ID, or such in this field. If no value is supplied for this field it will default to 'LastnameFirstnameYYYYmmDDhhMM’. |
String (Max 50 char) | 101 |
LastName (Required) | Where the customer is an individual, the Customer’s surname should be supplied. Where the customer is a business or organisation, the name of the entity should be supplied. | String (Max 60 char) | Smith |
FirstName | Customer’s first name (for individuals) | String (Max 30 char) | Joe |
EmailAddress | Customer’s email address | String (Max 255 char) | joesmith@example.com |
MobilePhoneNumber |
Customer’s mobile telephone number. NB - for Australian Customers the mobile phone number must be 10
digits long and begin with '04’. For New Zealand
Customers the mobile phone number must be 10 digits long
and begin with '02’. |
String (Max 12 char) | 0400123456 |
PaymentReference (Required) |
An ID that you can use to later identify this payment in the Ezidebit systems. This ID might be a specific Invoice or Order number within your system relating to an individual payment. The PaymentReference can also be searched for using a wildcard in other methods. You might choose to provide delimited references that identify the batch or customer and payment or any other additional data that you might wish to search on later. |
String (Max 50 char) | TS004 |
BankAccountName (Required) | Customer’s bank account name | String (Max 32 char) | Joe Smith |
BankAccountBSB (Required) | Customer’s BSB number | String (Numeric 6 digits) | 064001 |
BankAccountNumber (Required) | Customer’s bank account number | String (Numeric max 9 digit AU/9-10 digit NZ) | 12345678 |
PaymentAmountInCents (Required) | The amount to debit from your payer in cents. The system has a $2.00 minimum debit amount. If you would like to debit smaller amounts please amil partner@ezidebit.com.au. E.g. $20.00 = 2000 | Numeric | 2000 |
DebitDate (Required) | The date that you wish for this payment to be deducted from your Customer’s bank account or credit card. | String yyyy-MM-dd | 2010-12-22 |
SmsPaymentReminder (Required) | Optionally send an SMS to the customer reminding them of their upcoming scheduled debits. | String YES or NO | YES |
SmsFailedNotification (Required) |
Send an SMS to the customer notifying them if their debit fails. For a valid mobile number an SMS is sent regardless of the parameter |
String YES or NO | YES |
SmsExpiredCard (Required) | Optionally send an SMS to the customer notifying them if their recorded credit card is due to expire. Should always set to NO where bank account is being submitted. | String YES or NO | YES |
Username | Optionally record the user in your system that is executing this action | String (Max 50 char) | Webuser |
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<AddBankDebitResponse xmlns="https://px.ezidebit.com.au/">
<AddBankDebitResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Data xmlns:a="http://schemas.datacontract.org/2004/07/Ezidebit.PaymentExchange.V3_3.DataContracts ">
<a:CustomerRef>123456</a:CustomerRef>
</Data>
<Error>0</Error>
<ErrorMessage i:nil="true" />
</AddBankDebitResult>
</AddBankDebitResponse>
</s:Body>
</s:Envelope>
Response
The <Data> field in the AddBankDebit response will be either:
- A CustomerRef value containing positive non-zero integer that is the value of the EziDebitCustomerID of the Customer that has been created, updated or had the payment scheduled against. This does not indicate that the payment was successfully received from the Customer’s payment method;
- Empty - When the Data field is empty, it indicates that the update was not successful. You should check the value of the Error field. If an error has occurred, it will be indicated by a non-zero value in the Error field, with a text descriptor in the ErrorMessage field.
AddCardDebit
URL
URL of Web Services* | |
Production (LIVE) | https://api.ezidebit.com.au/v3-5/pci |
Sandbox (TEST) | https://api.demo.ezidebit.com.au/v3-5/pci |
Description
This method is designed to accept requests that include both Customer (Payer) and Payment details in a single call. It will either create, update or maintain a Customer and schedule the payment to be debited from the account. A system utilising this method will provide a unique Payer Reference from the integrating system as well as a unique Payment Reference for each payment.
It is important to note the following when using AddCardDebit:
- Ezidebit Customer References cannot be used with this method;
- If the Customer cannot be identified in the Ezidebit system using the YourSystemReference parameter, a new Customer will be created and the payment added to the Customer’s schedule;
- If the Customer can be identified in the Ezidebit system by the YourSystemReference Parameter but the Credit Card details differ to those on record or the Customer is currently using a Bank Account for payments, the Customer’s account with Ezidebit will be updated using the new details and the payment will be scheduled;
- If the Customer can be identified in the Ezidebit system by the YourSystemReference Parameter and the Credit Card details do not differ to those on record, then payment will simply be scheduled;
- If new Credit Card details are provided for a Customer that is not on an Active status in the Ezidebit system, the Customer details will be updated and the Customer status will be changed to Active;
- A DebitDate of up to thirty-one (31) days in the past can be used. Any payment that is scheduled with a DebitDate in the past will be processed and transmitted to the bank during the next processing run.
When using this method to save a customer as part of an online sign up, you MUST adhere to the requirements set out in the BECS Compliance section.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:px="https://px.ezidebit.com.au/">
<soapenv:Header />
<soapenv:Body>
<px:AddCardDebit>
<px:DigitalKey>00000000-0000-0000-0000-000000000000</px:DigitalKey>
<px:YourSystemReference>101</px:YourSystemReference>
<px:YourGeneralReference>101</px:YourGeneralReference>
<px:LastName>Smith</px:LastName>
<px:FirstName>Joe</px:FirstName>
<px:EmailAddress>test@ezidebit.com.au</px:EmailAddress>
<px:MobilePhoneNumber>0400000000</px:MobilePhoneNumber>
<px:PaymentReference>3</px:PaymentReference>
<px:NameOnCreditCard>Joe Smith</px:NameOnCreditCard>
<px:CreditCardNumber>4242424242424242</px:CreditCardNumber>
<px:CreditCardExpiryYear>2012</px:CreditCardExpiryYear>
<px:CreditCardExpiryMonth>12</px:CreditCardExpiryMonth>
<px:PaymentAmountInCents>2000</px:PaymentAmountInCents>
<px:DebitDate>2010-12-21</px:DebitDate>
<px:SmsPaymentReminder>NO</px:SmsPaymentReminder>
<px:SmsFailedNotification>NO</px:SmsFailedNotification>
<px:SmsExpiredCard>NO</px:SmsExpiredCard>
<px:Username>WebServiceUser</px:Username>
</px:AddCardDebit>
</soapenv:Body>
</soapenv:Envelope>
Request Parameters
Parameter Name | Description | Format | Example |
---|---|---|---|
DigitalKey (Required) | The 36 character Digital Key supplied to you by Ezidebit to identify your business | String | 8591BFD4-E7C8-4284-84F7-E6C419114FA8 |
YourSystemReference (Required) | A unique system identifier for the customer (e.g. GUID or your primary key). You can use this value to identify your Customer in the Ezidebit system. | String (Max 50 char) | 563445878985432x76 |
YourGeneralReference | A secondary unique reference for the customer. Where system based identifiers (YourSystemReference) can be complex numbers, this is designed to be a simpler, human-friendly number. You may use a GUID to create the system-to-system link with YourSystemReference, and choose to include a membership ID, or such in this field. If no value is supplied for this field it will default to 'LastnameFirstnameYYYYmmDDhhMM’. |
String (Max 50 char) | 101 |
LastName (Required) | Where the customer is an individual, the Customer’s surname should be supplied. Where the customer is a business or organisation, the name of the entity should be supplied. | String (Max 60 char) | Smith |
FirstName | Customer’s first name (for individuals) | String (Max 30 char) | Joe |
EmailAddress | Customer’s email address | String (Max 255 char) | joesmith@example.com |
MobilePhoneNumber | Customer’s mobile telephone number. NB - for Australian Customers the mobile phone number must be 10 digits long and begin with '04’. For New Zealand Customers the mobile phone can be up to be 12 digits long and begin with '02’ |
String (Max 12 char) | 0400123456 |
PaymentReference (Required) | An ID that you can use to later identify this payment in the Ezidebit systems. This ID might be a specific Invoice or Order number within your system relating to an individual payment. The PaymentReference can also be searched for using a wildcard in other methods. You might choose to provide delimited references that identify the batch or customer and payment or any other additional data that you might wish to search on later. |
String (Max 50 char) | TS004 |
NameOnCreditCard (Required) | The name on the customer’s credit card | String (Max 100) | Smith |
CreditCardNumber (Required) | Customer’s credit card number | String (Numeric Max 16 digits) | 4242000042420000 |
CreditCardExpiryYear (Required) | Customer’s credit card expiry year | Numeric (4 digits) | 2012 |
CreditCardExpiryMonth (Required) | Customer’s credit card expiry month | Numeric (2 digits) | 12 |
PaymentAmountInCents (Required) | The amount to debit from your payer in cents. The system has a $2.00 minimum debit amount. If you would like to debit smaller amounts please amil partner@ezidebit.com.au. E.g. $20.00 = 2000 | Numeric | 2000 |
DebitDate (Required) | The date that you wish for this payment to be deducted from your Customer’s bank account or credit card. | String yyyy-MM-dd | 2010-12-22 |
SmsPaymentReminder (Required) | Optionally send an SMS to the customer reminding them of their upcoming scheduled debits. | String YES or NO | YES |
SmsFailedNotification (Required) |
Send an SMS to the customer notifying them if their debit fails. For a valid mobile number an SMS is sent regardless of the parameter |
String YES or NO | YES |
SmsExpiredCard (Required) | Optionally send an SMS to the customer notifying them if their recorded credit card is due to expire. | String YES or NO | YES |
Username | Optionally record the user in your system that is executing this action | String (Max 50 char) | Webuser |
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<AddCardDebitResponse xmlns="https://px.ezidebit.com.au/">
<AddCardDebitResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Data xmlns:a="http://schemas.datacontract.org/2004/07/Ezidebit.PaymentExchange.V3_3.DataContracts">
<a:CustomerRef>123456</a:CustomerRef>
</Data>
<Error>0</Error>
<ErrorMessage i:nil="true" />
</AddCardDebitResult>
</AddCardDebitResponse>
</s:Body>
</s:Envelope>
Response
The <Data> field in the AddCardDebit response will be either:
- A CustomerRef value containing positive non-zero integer that is the value of the EziDebitCustomerID of the Customer that has been created, updated or had the payment scheduled against. This does not indicate that the payment was successfully received from the Customer’s payment method;
- Empty - When the Data field is empty, it indicates that the update was not successful. You should check the value of the Error field. If an error has occurred, it will be indicated by a non-zero value in the Error field, with a text descriptor in the ErrorMessage field.
CreateSchedule
URL
URL of Web Services | |
Production (LIVE) | https://api.ezidebit.com.au/v3-5/nonpci |
Sandbox (TEST) | https://api.demo.ezidebit.com.au/v3-5/nonpci |
Description
This method allows you to create a new schedule for the given Customer. It will create a schedule for on-going debits (up to 20 payments will exist at a point in time), or will calculate a schedule to fulfil a required total payment amount, or number of payments.
It is important to note the following when creating a payment schedule:
- This function will first remove an existing payment schedule and then create a new payment schedule in accordance with your parameters;
- When creating a new schedule for a fixed amount or fixed number of payments, the calculation will not consider any payments already made by the Customer;
- When a schedule is created, a series of individual payment records are created in the Ezidebit system, which can be altered independently of each other;
- For customers with an ongoing payment schedule, payments will be scheduled for up to one year in advance. As each payment is processed (or removed from the schedule where the customer is in a non-processing status) an additional debit will be added to the end of the schedule at the required frequency;
- For Customers on a fixed number of payments, or total amount owing, if a payment is unsuccessful, it will cause a new debit to be scheduled at the end of the existing schedule for the correct amount, at the frequency specified when the schedule was created;
- Where a payment is scheduled for a non-processing day (i.e. weekend or national public holiday) it will be processed on the next business day.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:px="https://px.ezidebit.com.au/">
<soapenv:Header />
<soapenv:Body>
<px:CreateSchedule>
<px:DigitalKey>49A67D1B-DF3F-4013-B13A-A5E9E41E8873</px:DigitalKey>
<px:EziDebitCustomerID />
<px:YourSystemReference>102</px:YourSystemReference>
<px:ScheduleStartDate>2011-03-05</px:ScheduleStartDate>
<px:SchedulePeriodType>W</px:SchedulePeriodType>
<px:DayOfWeek>MON</px:DayOfWeek>
<px:DayOfMonth>5</px:DayOfMonth>
<px:FirstWeekOfMonth>Y</px:FirstWeekOfMonth>
<px:SecondWeekOfMonth>Y</px:SecondWeekOfMonth>
<px:ThirdWeekOfMonth>Y</px:ThirdWeekOfMonth>
<px:FourthWeekOfMonth>Y</px:FourthWeekOfMonth>
<px:PaymentAmountInCents>4000</px:PaymentAmountInCents>
<px:LimitToNumberOfPayments>4</px:LimitToNumberOfPayments>
<px:LimitToTotalAmountInCents>0</px:LimitToTotalAmountInCents>
<px:KeepManualPayments>NO</px:KeepManualPayments>
<px:Username>WebServiceUser</px:Username>
</px:CreateSchedule>
</soapenv:Body>
</soapenv:Envelope>
Request Parameters
Parameter Name | Description | Format | Example |
---|---|---|---|
DigitalKey (Required) |
The 36 character Digital Key supplied to you by Ezidebit to identify your business |
String | 8591BFD4-E7C8-4284-84F7-E6C419114FA8 |
EziDebitCustomerID |
The unique number assigned to the Customer by Ezidebit. |
String | 122456 |
YourSystemReference |
A unique system identifier for the customer (e.g. GUID or your primary key). You can use this value to identify your Customer in the Ezidebit system if you supplied a value in this field in the AddCustomer method. NB - You must provide a value for either EziDebitCustomerID or YourSystemReference to identify your Customer, but not both. |
String | 563445878985432x76 |
ScheduleStartDate (Required) |
The date that you wish for the first payment in the schedule to be deducted from your Customer’s bank account or credit card. |
String (yyyy-MM-dd) | 2011-05-03 |
SchedulePeriodType (Required) |
The frequency with which you want payments deducted from your Customer Possible values are: 'W’ - Weekly 'F’ - Fortnightly ’M’ - Monthly '4’ - 4 Weekly 'N’ - Weekday in month (e.g. Monday in the third week of every month) 'Q’ - Quarterly 'H’ - Half Yearly (6 Monthly) 'Y’ - Yearly The frequency is applied to the payment scheduled beginning from the date defined in ScheduledStartDate |
String (Max 1 char)
(Must be a character from defined list of possible values) |
W |
DayOfWeek |
If appropriate, the day of the week on which the Customer will be debited. Possible values are: MON, TUE, WED, THU, FRI NB - A value must be provided for this parameter when the SchedulePeriodType is in 'W’,'F’,'4’,'N’. |
String
(Must be a value from defined list of possible values) |
MON |
DayOfMonth (Required) |
If appropriate, the day of the month on which the Customer will be debited. NB - A value must be provided for this parameter. When not used a value of 0 should be specified. When the SchedulePeriodType is ’M&rsquo a non-zero integer must be supplied. The debit schedule is then created to debit on DayOfMonth each month starting from the next instance of it after ScheduleStartDate. |
Integer
(Must be between 0 and 31) |
15 |
FirstWeekOfMonth |
If appropriate, specifies if debits will occur on the day of the week specified by DayOfWeek in the first week of each month. NB - Required and effective only if SchedulePeriodType is 'N’. |
String
YES or NO |
YES |
SecondWeekOfMonth |
If appropriate, specifies if debits will occur on the day of the week specified by DayOfWeek in the second week of each month. NB - Required and effective only if SchedulePeriodType is 'N’. |
String
YES or NO |
YES |
ThirdWeekOfMonth |
If appropriate, specifies if debits will occur on the day of the week specified by DayOfWeek in the third week of each month. NB - Required and effective only if SchedulePeriodType is 'N’. |
String
YES or NO |
YES |
FourthWeekOfMonth |
If appropriate, specifies if debits will occur on the day of the week specified by DayOfWeek in the fourth week of each month. NB - Required and effective only if SchedulePeriodType is 'N’. |
String
YES or NO |
YES |
PaymentAmountInCents (Required) |
The amount to debit from your payer in cents. The system has a $2.00 minimum debit amount. If you would like to debit smaller amounts please amil partner@ezidebit.com.au. Eg. $20.00 = 2000 |
Integer | 4000 |
LimitToNumberOfPayments (Required) |
This parameter gives you the ability to specify whether the schedule should be limited to a fixed number of successful debits. If a non-zero value is supplied, the payment schedule will consist of LimitToNumberOfPayments payments of PaymentAmountInCents each. NB - If you do not wish to limit the payment schedule to a specific number of payments you must provide a value of 0 (zero) for this parameter. |
Integer |
5 |
LimitToTotalAmountInCents (Required) |
This optional parameter gives you the ability to specify whether the schedule should be limited to a total sum of LimitToTotalAmountInCents. If a non-zero value is supplied, the payment schedule will consist of a set number of scheduled debits of PaymentAmountInCents each, with the final payment being less than or equal to that amount to make a correct total. NB - If you do not wish to limit the payment schedule to a specific total value you must provide a value of 0 (zero) for this parameter. |
Integer | 12000 |
KeepManualPayments (Required) |
This will ensure that any individual ad-hoc payments that have been added will not be deleted when the new schedule is created. |
String - YES or NO | NO |
Username |
Optionally record the user in your system that is executing this action |
String
(Max 50 char) |
Webuser |
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<CreateScheduleResponse xmlns="https://px.ezidebit.com.au/">
<CreateScheduleResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Data>S</Data>
<Error>0</Error>
<ErrorMessage i:nil="true" />
</CreateScheduleResult>
</CreateScheduleResponse>
</s:Body>
</s:Envelope>
Response
The <Data> field in the CreateSchedule response will be either:
- ’S’ - indicates that the payment scheduled has been created;
- Empty - When the Data field is empty, it indicates that the update was not successful. You should check the value of the Error field. If an error has occurred, it will be indicated by a non-zero value in the Error field, with a text descriptor in the ErrorMessage field.
Maintaining Batch Payments
ClearSchedule
URL
URL of Web Services | |
Production (LIVE) | https://api.ezidebit.com.au/v3-5/nonpci |
Sandbox (TEST) | https://api.demo.ezidebit.com.au/v3-5/nonpci |
Description
Payment schedule is a concept used for managing recurring payments for the costs of goods or services. There are two methods which a payment schedule can be utilised, payment to a specified total amount for cost of goods or ongoing schedule for a subscription or service.
In some situations, cancelling the payment schedule is required but within the Ezidebit system cancelling a schedule doesn’t mean the party is cancelled from the system, only that payments will not be drawn. The party is still active in the system but will not be debited.
Cancelled schedules will move a party to an ongoing and on-demand status. The payer is not removed because they and their payment methods are still valid, only inactive and not being debited. In this status, the payer can be billed again without needing the AddPayer process to occur. One-off payments can be triggered manually or a new payment schedule can be created.
The ClearSchedule method will remove payments that exist in the payment schedule for the given customer. You can control whether all payments are deleted, or if you wish to preserve any manually added payments, and delete an ongoing cyclic schedule. The customer will continue to exist, the future payments will have been cleared and ongoing payments will be manually triggered.
Parameters
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:px="https://px.ezidebit.com.au/">
<soapenv:Header />
<soapenv:Body>
<px:ClearSchedule>
<px:DigitalKey>49A67D1B-DF3F-4013-B13A-A5E9E41E8873</px:DigitalKey>
<px:EziDebitCustomerID />
<px:YourSystemReference>102</px:YourSystemReference>
<px:KeepManualPayments>YES</px:KeepManualPayments>
<px:Username>WebServiceUser</px:Username>
</px:ClearSchedule>
</soapenv:Body>
</soapenv:Envelope>
Parameter Name | Description | Format | Example |
---|---|---|---|
DigitalKey (Required) |
The 36 character Digital Key supplied to you by Ezidebit to identify your business |
String | 8591BFD4-E7C8-4284-84F7-E6C419114FA8 |
EziDebitCustomerID |
The unique number assigned to the Customer by Ezidebit. |
String | 122456 |
YourSystemReference |
A unique system identifier for the customer (e.g. GUID or your primary key). You can use this value to identify your Customer in the Ezidebit system if you supplied a value in this field in the AddCustomer method. NB - You must provide a value for either EziDebitCustomerID or YourSystemReference to identify your Customer, but not both. |
String | 563445878985432x76 |
KeepManualPayments (Required) |
This will ensure that any individual ad-hoc payments that have been added will not be deleted when the schedule is cleared. |
String - YES or NO | NO |
Username |
Optionally record the user in your system that is executing this action |
String
(Max 50 char) |
Webuser |
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<ClearScheduleResponse xmlns="https://px.ezidebit.com.au/">
<ClearScheduleResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Data>S</Data>
<Error>0</Error>
<ErrorMessage i:nil="true" />
</ClearScheduleResult>
</ClearScheduleResponse>
</s:Body>
</s:Envelope>
Response
The <Data>
field in the ClearSchedule
response will be either:
- ’S’ - indicates that the scheduled payments have been deleted;
- Empty - When the Data field is empty, it indicates that the delete was not successful.
You should check the value of the Error field. If an error has occurred, it will be indicated by a
non-zero value in the
Error
field, with a text descriptor in theErrorMessage
field.
ChangeScheduledAmount
URL
URL of Web Services | |
Production (LIVE) | https://api.ezidebit.com.au/v3-5/nonpci |
Sandbox (TEST) | https://api.demo.ezidebit.com.au/v3-5/nonpci |
Description
This method allows you to change the debit amount for one or more payments that exist in the Customer’s payment schedule.
It is also important to note the following when changing a Scheduled Amount:
- Only scheduled payments with a status of 'W’ can have their scheduled debit amounts changed;
- This method will only change the debit amounts of scheduled payments - the debit dates will still remain the same.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:px="https://px.ezidebit.com.au/">
<soapenv:Header />
<soapenv:Body>
<px:ChangeScheduledAmount>
<px:DigitalKey>49A67D1B-DF3F-4013-B13A-A5E9E41E8873</px:DigitalKey>
<px:EziDebitCustomerID />
<px:YourSystemReference>102</px:YourSystemReference>
<px:ChangeFromPaymentNumber>0</px:ChangeFromPaymentNumber>
<px:ChangeFromDate>2011-01-01</px:ChangeFromDate>
<px:NewPaymentAmountInCents>4000</px:NewPaymentAmountInCents>
<px:ApplyToAllFuturePayments>YES</px:ApplyToAllFuturePayments>
<px:KeepManualPayments>YES</px:KeepManualPayments>
<px:Username>WebServiceUser</px:Username>
</px:ChangeScheduledAmount>
</soapenv:Body>
</soapenv:Envelope>
Parameters
Parameter Name | Description | Format | Example |
---|---|---|---|
DigitalKey (Required) | The 36 character Digital Key supplied to you by Ezidebit to identify your business | String | 8591BFD4-E7C8-4284-84F7-E6C419114FA8 |
EziDebitCustomerID | The unique number assigned to the Customer by Ezidebit. | String | 122456 |
YourSystemReference |
A unique system identifier for the customer (e.g. GUID or your primary key). You can use this value to identify your Customer in the Ezidebit system if you supplied a value in this field in the AddCustomer method. NB - You must provide a value for either EziDebitCustomerID or YourSystemReference to identify your Customer, but not both. |
String (Max 50 char) | 563445878985432x76 |
ChangeFromPaymentNumber (Required) |
The payment number of the earliest payment that you want to change the debit amount of. For example, the second payment in the Payer’s schedule will be payment number 2 (two). NB - You must provide a value for either ChangeFromPaymentNumber or ChangeFromDate to identify the starting point for the change, but not both. To indicate that the ChangeFromDate value should be used you will need to pass a value of 0 (zero) for this parameter |
Integer | 1 |
ChangeFromDate |
A date that is the earliest that you want to change the debit amount from. This date does not have to exactly match a scheduled debit date, it will match the first (or any) payment that falls on or after the provided date. NB - You must provide a value for either ChangeFromPaymentNumber or ChangeFromDate to identify the starting point for the change, but not both. |
String (yyyy-MM-dd) | 2011-01-01 |
NewPaymentAmountInCents (Required) |
The amount to change the existing payer’s debits to in cents. The system has a $2.00 minimum debit amount. If you would like to debit smaller amounts please amil partner@ezidebit.com.au. Eg. $20.00 = 2000 |
Integer | 4000 |
ApplyToAllFuturePayments (Required) |
Indicate whether you wish to have the NewPaymentAmountInCents applied to all (YES) payments that occur on or after the position identified by the ChangeFromPaymentNumber or ChangeFromPaymentDate, or just the earliest payment (NO). |
String - YES or NO | YES |
KeepManualPayments (Required) |
This will ensure any individual payments that have been added to the schedule using the AddPayment Method are not updated by this call. This allows you to make a change to an ongoing scheduled commitment from your Customer, whilst maintaining the amount of any one-off or ad-hoc payments that may be required. |
String - YES or NO | YES |
Username |
Optionally record the user in your system that is executing this action |
String (Max 50 char) | Webuser |
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<ChangeScheduledAmountResponse xmlns="https://px.ezidebit.com.au/">
<ChangeScheduledAmountResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Data>S</Data>
<Error>0</Error>
<ErrorMessage i:nil="true" />
</ChangeScheduledAmountResult>
</ChangeScheduledAmountResponse>
</s:Body>
</s:Envelope>
Response
The <Data>
field in the ChangeScheduledAmount
response will be either:
- ’S’ - indicates that the update of the Debit Amount for the applicable payments has been successful;
- Empty - When the Data field is empty, it indicates that the update was not successful.
You should check the value of the Error field. If an error has occurred, it will be indicated by a
non-zero value in the
Error
field, with a text descriptor in theErrorMessage
field.
ChangeScheduledDate
URL
URL of Web Services | |
Production (LIVE) | https://api.ezidebit.com.au/v3-5/nonpci |
Sandbox (TEST) | https://api.demo.ezidebit.com.au/v3-5/nonpci |
Description
This method allows you to change the debit date for a single payment in a Customer’s payment schedule.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:px="https://px.ezidebit.com.au/">
<soapenv:Header />
<soapenv:Body>
<px:ChangeScheduledDate>
<px:DigitalKey>49A67D1B-DF3F-4013-B13A-A5E9E41E8873</px:DigitalKey>
<px:EziDebitCustomerID />
<px:YourSystemReference>102</px:YourSystemReference>
<px:ChangeFromDate />
<px:PaymentReference>test</px:PaymentReference>
<px:ChangeToDate>2011-03-05</px:ChangeToDate>
<px:KeepManualPayments>YES</px:KeepManualPayments>
<px:Username>WebServiceUser</px:Username>
</px:ChangeScheduledDate>
</soapenv:Body>
</soapenv:Envelope>
Parameters
Parameter Name | Description | Format | Example |
---|---|---|---|
DigitalKey (Required) |
The 36 character Digital Key supplied to you by Ezidebit to identify your business |
String | 8591BFD4-E7C8-4284-84F7-E6C419114FA8 |
EziDebitCustomerID |
The unique number assigned to the Customer by Ezidebit. |
String | 122456 |
YourSystemReference |
A unique system identifier for the customer (e.g. GUID or your primary key). You can use this value to identify your Customer in the Ezidebit system if you supplied a value in this field in the AddCustomer method. NB - You must provide a value for either EziDebitCustomerID or YourSystemReference to identify your Customer, but not both. |
String
(Max 50 char) |
563445878985432x76 |
ChangeFromDate |
The exact date on which the payment that you wish to move is scheduled to be deducted from your Customer’s bank account or credit card. NB - You must provide a value for either ChangeFromDate or PaymentReference to identify the payment. |
String (yyyy-MM-dd) | 2011-01-01 |
PaymentReference |
If you used a specific PaymentReference when adding a payment using the AddPayment Method, then you can use that value here to exactly identify that payment within the Customer’s schedule. |
String
(max 50 char) |
TS2004 |
ChangeToDate (Required) |
The new date that you wish for this payment to be deducted from your Customer’s bank account or credit card. This must be a future date. |
String (yyyy-MM-dd) | 2011-04-02 |
KeepManualPayments (Required) |
This parameter is not currently used. The first payment found matching the criteria will be updated to the ChangeToDate |
String
YES or NO |
YES |
Username |
Optionally record the user in your system that is executing this action |
String
(Max 50 char) |
Webuser |
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<ChangeScheduledDateResponse xmlns="https://px.ezidebit.com.au/">
<ChangeScheduledDateResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Data>S</Data>
<Error>0</Error>
<ErrorMessage i:nil="true" />
</ChangeScheduledDateResult>
</ChangeScheduledDateResponse>
</s:Body>
</s:Envelope>
Response
The <Data>
field in the ChangeScheduledDate
response will be either:
- ’S’ - indicates that the update of the Debit Date for the applicable payment has been successful;
- Empty - When the Data field is empty, it indicates that the update was not successful.
You should check the value of the Error field. If an error has occurred, it will be indicated by a
non-zero value in the
Error
field, with a text descriptor in theErrorMessage
field.
DeletePayment
URL
URL of Web Services | |
Production (LIVE) | https://api.ezidebit.com.au/v3-5/nonpci |
Sandbox (TEST) | https://api.demo.ezidebit.com.au/v3-5/nonpci |
Description
This method will allow for either the deletion of an entire payment schedule or the deletion of one specific scheduled payment.
It is important to note the following when deleting a payment:
- Only unprocessed scheduled payments (
PaymentStatus
of 'W’) can be deleted. Any payment that has already been processed can not be deleted. - If you provide values for DebitDate and PaymentAmountInCents and there is more than one payment for
PaymentAmountInCents
scheduled onDebitDate
, then only one of the payments will be deleted.
The following combinations of PaymentReference
, PaymentAmountInCents
and DebitDate
are supported:
Parameters Provided | Behaviour |
---|---|
PaymentReference;PaymentAmountInCents; |
All future dated unprocessed payments matching the criteria will be deleted. |
PaymentReference;PaymentAmountInCents;DebitDate; |
Looks for a single payment.
|
PaymentAmountInCents;DebitDate; |
Looks for a single payment.
|
In all cases if no payments, processed or unprocessed can be found to match with the search criteria then a response message of the payments could not be found will be returned.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:px="https://px.ezidebit.com.au/">
<soapenv:Header />
<soapenv:Body>
<px:DeletePayment>
<px:DigitalKey>49A67D1B-DF3F-4013-B13A-A5E9E41E8873</px:DigitalKey>
<px:EziDebitCustomerID />
<px:YourSystemReference>102</px:YourSystemReference>
<px:PaymentReference />
<px:DebitDate>2011-03-07</px:DebitDate>
<px:PaymentAmountInCents>4000</px:PaymentAmountInCents>
<px:Username>WebServiceUser</px:Username>
</px:DeletePayment>
</soapenv:Body>
</soapenv:Envelope>
Parameters
Parameter Name | Description | Format | Example |
---|---|---|---|
DigitalKey (Required) |
The 36 character Digital Key supplied to you by Ezidebit to identify your business |
String | 8591BFD4-E7C8-4284-84F7-E6C419114FA8 |
EziDebitCustomerID |
The unique number assigned to the Customer by Ezidebit. |
String | 122456 |
YourSystemReference |
A unique system identifier for the customer (e.g. GUID or your primary key). You can use this value to identify your Customer in the Ezidebit system if you supplied a value in this field in the AddCustomer method. NB - You must provide a value for either EziDebitCustomerID or YourSystemReference to identify your Customer, but not both. |
String
(Max 50 char) |
563445878985432x76 |
PaymentReference |
If you used a specific PaymentReference when adding a payment using the AddPayment Method, then you can use that value here to exactly identify that payment within the Customer’s schedule. |
String
(Max 50 char) |
TS2004 |
DebitDate |
The date that the payment you wish to delete is scheduled to be deducted from your Customer’s bank account or credit card. |
String (yyyy-MM-dd) | 2011-05-03 |
PaymentAmountInCents (Required) |
The amount in cents that the payment you wish to delete is scheduled to be deducted from your payer Customer’s bank account or credit card. NB - If you are using the PaymentReference to identify the payment then you must pass a value of 0 in this field. |
Integer | 4000 |
Username |
Optionally record the user in your system that is executing this action |
String
(Max 50 char) |
Webuser |
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<DeletePaymentResponse xmlns="https://px.ezidebit.com.au/">
<DeletePaymentResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Data>S</Data>
<Error>0</Error>
<ErrorMessage i:nil="true" />
</DeletePaymentResult>
</DeletePaymentResponse>
</s:Body>
</s:Envelope>
Response
The <Data>
field in the DeletePayment response will be either:
- ’S’ - indicates that a single payment has been deleted from your Customer’s payment schedule;
- Empty - When the Data field is empty, it indicates that the delete was not successful. You should check the value of the Error field. If an error has occurred, it will be indicated by a non-zero value in the
Error
field, with a text descriptor in theErrorMessage
field.
Retrieving Payment Details
GetPayments
URL
URL of Web Services | |
Production (LIVE) | https://api.ezidebit.com.au/v3-5/nonpci |
Sandbox (TEST) | https://api.demo.ezidebit.com.au/v3-5/nonpci |
Description
This method allows you to retrieve payment information from across Ezidebit’s various payment systems. It provides you with access to scheduled, pending and completed payments made through all payment channels.
It is important to note the following when querying Payment details:
- This method can be used to retrieve information about payments that have been made by your Customer through any means;
- This is the recommended method for retrieving a set of payment results in a single call as most other methods are designed to provide detail about a single transaction. This method will return a full set of transactions matching the supplied criteria;
- The flexibility of using a wildcard in the PaymentReference search value means that if you are adding payments with the AddPayment method as they become due, you can provide structured PaymentReferences that will allow you to group or batch payments in a way that you see fit
- Ezidebit only processes settlement deposits to clients once a day. Since the “SUCCESS” criteria for a scheduled direct debit payment is set when the payment is deposited to the client, the combination of PaymentType=ALL DateField=SETTLEMENT DateFrom={LastSuccessfulPaymentDate + 1} DateTo={currentDate} will provide you with all payments that have been made to the client since the last time your system received payment information.
- Refunds will only appear in the response if the functionality has been enabled in the Ezidebit account
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:px="https://px.ezidebit.com.au/">
<soapenv:Header />
<soapenv:Body>
<px:GetPayments>
<px:DigitalKey>49A67D1B-DF3F-4013-B13A-A5E9E41E8873</px:DigitalKey>
<px:PaymentType>ALL</px:PaymentType>
<px:PaymentMethod>ALL</px:PaymentMethod>
<px:PaymentSource>ALL</px:PaymentSource>
<px:PaymentReference />
<px:DateFrom>2011-01-01</px:DateFrom>
<px:DateTo>2011-02-01</px:DateTo>
<px:DateField>SETTLEMENT</px:DateField>
<px:EziDebitCustomerID />
<px:YourSystemReference>201102%</px:YourSystemReference>
</px:GetPayments>
</soapenv:Body>
</soapenv:Envelope>
Request Parameters
Parameter Name | Description | Format | Example |
---|---|---|---|
DigitalKey (Required) |
The 36 character Digital Key supplied to you by Ezidebit to identify your business |
String | 8591BFD4-E7C8-4284-84F7-E6C419114FA8 |
PaymentType (Required) |
Choose the type of transaction to search for in conjunction with the other search criteria specified. Possible values are: ALL - return details for all payments regardless of the payment status. PENDING - return details for all payments that have a pending status. This means that the payment has been processed from the payment schedule and sent to the financial institutions for processing and Ezidebit is currently awaiting a final result. FAILED - return details only for payments that have dishonoured (been unsuccessful) SUCCESSFUL - return details only for payments that have been marked as successful. This occurs once the payment has been deposited to the client settlement account. |
String
(Must be a value listed in the Possible values) |
ALL |
PaymentMethod (Required) |
The payment method from which the payment was taken. Possible values are: ALL - return details for payments regardless of the method from which they were paid CR - return details only for payments that have been made to Ezidebit from a Credit Card DR - return values for payments that have been made to Ezidebit from a Bank Account |
String
(Must be a value listed in the Possible values) |
CR |
PaymentSource (Required) |
The source channel by which the payment was made. Possible values are: ALL - return details for payments regardless of the channel through which they were made. SCHEDULED - return details on for payments that were made by Direct Debit. WEB - return details only for payments that were made to Ezidebit through a web-based real-time credit card processing system. PHONE - return details only for payments that were made to Ezidebit through the real-time Interactive Voice Recording (IVR) phone credit card system. BPAY - return details only for payments that were made to Ezidebit through the BPAY system. ADJ - return details only for adjustments to previously debited payments. |
String
(Must be a value listed in the Possible values) |
ALL |
PaymentReference |
Provides the search with data to match against any PaymentReference that was supplied for the transaction. This will include the Customer Reference Number (CRN) or Bill Reference Number used in the BPAY and real-time credit card processing systems respectively. If you have been adding payments to Customer payment schedules using the AddPayment method, and including a structured or delimited Payment Reference, you can search on part of the reference field by using the percentage wildcard ’%’. NB - If a value is supplied to this parameter without the wildcard character, the system will only return details of payments where the payment reference matches exactly to the value supplied. The wildcard ’%’ symbol can be used to match to part of the reference |
String
(max 50 char) |
201102% |
DateFrom |
This is used in conjunction with the DateField parameter. When supplied, it will match payments where the appropriate date field is on or after the supplied date. NB - If you do not wish to limit payment results by date you can supply a blank value for this parameter. |
String yyyy-MM-dd | 2011-05-01 |
DateTo |
This is used in conjunction with the DateField parameter. When supplied, it will match payments where the appropriate date field is up to and including the supplied date. NB - If you do not wish to limit payment results by date you can supply a blank value for this parameter. |
String yyyy-MM-dd | 2011-07-01 |
DateField |
Choose which date to filter the DateFrom and DateTo values against. Possible values are: PAYMENT - this will cause the date parameters to match to the date that the payment was deducted from the Customer’s payment method. For scheduled direct debit transactions, this will be the date that the payment was processed and sent to the Customer’s financial institution to be deducted. For real-time or BPAY payments, this will be the date that the Customer made the payment to Ezidebit. SETTLEMENT - This will cause the date parameters to match to the date that the payment was deposited to the client’s settlement bank account. |
String
(Must be a value listed in the Possible values) |
SETTLEMENT |
EziDebitCustomerID |
The unique number assigned to the Customer by Ezidebit. NB - Wildcards cannot be used with this parameter. |
Integer | 351328 |
YourSystemReference |
A unique system identifier with your account for the customer (e.g. GUID or your primary key). You can use this value to identify your Customer in the Ezidebit system if you supplied a value in this field in the AddCustomer method. NB - Wildcards cannot be used with this parameter. NB - If you want to retreive paymets for a specific customer, you must provide a value for either EziDebitCustomerID or YourSystemReference to identify the Customer, but not both. |
String
(Max 50 char) |
563445878985432x76 |
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetPaymentsResponse xmlns="https://px.ezidebit.com.au/">
<GetPaymentsResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Data>
<Payment>
<BankFailedReason />
<BankReceiptID>430357</BankReceiptID>
<BankReturnCode>O</BankReturnCode>
<CustomerName>Test</CustomerName>
<DebitDate>2011-01-04T00:00:00</DebitDate>
<EziDebitCustomerID />
<InvoiceID>0</InvoiceID>
<PaymentAmount>20</PaymentAmount>
<PaymentID>WEB48992</PaymentID>
<PaymentMethod>CR</PaymentMethod>
<PaymentReference>45</PaymentReference>
<PaymentSource>WEB</PaymentSource>
<PaymentStatus>P</PaymentStatus>
<SettlementDate i:nil="true" />
<ScheduledAmount>19.10</ScheduledAmount>
<TransactionFeeClient>0</TransactionFeeClient>
<TransactionFeeCustomer>0.90</TransactionFeeCustomer>
<TransactionTime>2011-01-19T11:45:00</TransactionTime>
<YourGeneralReference />
<YourSystemReference />
</Payment>
<Payment>...</Payment>
</Data>
<Error>0</Error>
<ErrorMessage i:nil="true" />
</GetPaymentsResult>
</GetPaymentsResponse>
</s:Body>
</s:Envelope>
Response
The <Data> field in the GetPayments response will contain either:
- A data set enclosed within the <Payment> set for each individual payment returned;
- Empty - When the Data field is empty, it indicates that the request was not successful. You should check the value of the Error field. If an error has occurred, it will be indicated by a non-zero value in the Error field, with a text descriptor in the ErrorMessage field. If the value of the Error field is 0 but the Data field is empty then the API call was successful but there was no data that matched the criteria used.
When seeking to the data for future scheduled payments (PaymentStatus 'W’) then the request inputs have to be seeking future dated scheduled payments. Below is an example of the request parameters if the condition of current date is 30/09/2015. The date from and date to field have to be in the future of present date and the DateField is set as 'PAYMENT’.
The following table describes the data contained within Payment data set of a successful response for GetPayments.
Parameter Name | Description | Format | Example |
---|---|---|---|
BankFailedReason |
The full text description for the reason that the payment was unsuccessful (dishonoured) Where a payment is successful or still pending an outcome, this value will be blank. A list of possible values is provided in Batch Responses |
String |
Credit Card Transaction Declined |
BankReceiptID |
The original receipt number supplied by the banking system for real-time credit cards or BPAY payments NB - ALL real time credit card payments are assigned a BankReceiptID when the transaction is attempted. The presence of a BankReceiptID does NOT identify the payment as being successful. You must check the PaymentStatus to determine the outcome of the transaction. |
String | CBA201103021224565 |
BankReturnCode |
A number that identifies the reason code within Ezidebit for the reason that the payment was unsuccessful (dishonoured) Where a payment is successful or still pending an outcome, this value will be 0 (zero). A list of possible values is provided in Batch Responses. |
String |
21 |
CustomerName |
For scheduled payments, this will be the first name and surname of your Customer, as recorded in the Ezidebit System. For real-time credit cards, this will be the name supplied as the name on the credit card |
String |
Joe Smith |
DebitDate |
The date that the payment was actually debited from the Customers payment method by Ezidebit |
dateTime (yyyy-MM-ddThh:mm:ss) |
2011-05-03T15:31:29 |
EziDebitCustomerID |
The unique number assigned to the Customer by Ezidebit. |
String | 351328 |
InvoiceID |
The Ezidebit Tax Invoice number that the fees for this payment were charged on. The Invoice number is also used as a batch identifier for transactions that were settled to the client. |
String | 2856548 |
PaymentAmount |
The total amount of funds debited from your Customers payment method. NB - This will not necessarily be the same amount as the original payment schedule. In the cases where the Customer is paying the transaction fee, the fee amounts are added to the scheduled amount and the total is debited. This value represents that Total. It may be necessary for you to deduct the TransactionFeeCustomer from the PaymentAmount to determine the original requested debit amount. |
Double | 50.88 |
PaymentID |
The unique transaction ID given to the payment by Ezidebit. This value is not assigned to a payment until the scheduled payment has been processed and sent to the bank. |
String | 20116584259 |
PaymentMethod |
The payment method from which Ezidebit deducted this transaction. Possible values are: 'DR’ - Payment was debited from a bank account. 'CR’ - Payment was debited from a credit card. |
String | DR |
PaymentReference |
If you used a specific PaymentReference when adding a payment using the AddPayment Method, then you can use that value here to exactly identify that payment within the Customer’s schedule. |
String (Max 50 char) |
TS2204 |
PaymentSource |
The source channel by which the payment was made. Possible values are:
SCHEDULED - payments that were made by Direct Debit. WEB - payments that were made to Ezidebit through a web-based real-time credit card processing system. PHONE - payments that were made to Ezidebit through the real-time Interactive Voice Recording (IVR) phone credit card system. BPAY - payments that were made to Ezidebit through the BPAY system. ADJ - adjustments to previously debited payments. TERMINAL - payments that were made using a POS terminal |
String | SCHEDULED |
PaymentStatus |
A status indicating the state of the payment within the Ezidebit system. Possible values are: ’S’ (successful) - Payment has been successfully debited from the Customer and deposited to the client’s settlement bank account. 'P’ (pending) - Payment request has been sent to the bank for processing and Ezidebit is waiting on a success or fail response before completing settlement. This value will also be returned if the payment has been processed but has not been deposited into the client’s settlement bank account. ’D’ (dishonoured) - Payment has been dishonoured by the Customer’s financial institution due to insufficient funds. 'F’ (fatal dishonour) - Payment has been dishonoured by the Customer’s financial institution for a technical reason, such as incorrect details etc.
'W’
(waiting) - Future scheduled payment. As these are not yet settled, query by payment date, not settlement date. NB - Payments that are dishonoured for “fatal” reasons will cause the Customer’s record to be moved to a non-processing status until such point as the incorrect details are altered and the Customer is reactivated to a processing status. Whilst a Customer has a non-processing status, no debits will be attempted against their payment method by Ezidebit. |
String |
F |
ScheduledAmount |
The original amount that was scheduled to be deducted from the Customers payment method. NB - This figure may differ from the Payment Amount if Ezidebit has applied transaction, SMS or setup fees to the Customer. |
Double | 49.00 |
SettlementDate |
The date that the payment was settled to the client (for successful transactions) or the date that Ezidebit was notified that the payment was unsuccessful (for dishonoured transactions) This value will remain blank until such point as the payment is dishonoured in the Ezidebit system or is settled to the client’s bank account |
dateTime (yyyy-MM-ddThh:mm:ss) |
2011-03-28T00:00:00 |
TransactionFeeClient |
The total amount of fees paid to Ezidebit by the client (business) for processing this transaction. |
Double | 1.10 |
TransactionFeeCustomer |
The total amount of fees paid to Ezidebit by the Customer for processing this transaction. |
Double | 4.40 |
TransactionTime |
For real-time credit card payment (WEB or PHONE) the time (UTC+10) that the transaction was actually made by the Customer. |
dateTime (hh:mm) | 17:58 |
YourGeneralReference |
A secondary unique reference for the customer. |
String
(Max 50 char) |
101 |
YourSystemReference |
A unique system identifier for the customer (e.g. GUID or your primary key). You can use this value to identify your Customer in the Ezidebit system if you supplied a value in this field in the AddCustomer method. |
String
(Max 50 char) |
563445878985432x76 |
The following adjustment types may be returned in GetPayments:
- Refund - Refunds are where some or all of the money taken from a customer is returned to the payment instrument used.
- Claim - A payer can dispute a Bank Account transaction, resulting in a claim being raised by their financial institution.
- Claim Reversal - If a claim is unsuccessful, funds are returned to the biller resulting in a Claim Reversal.
- Chargeback - A payer can dispute a Credit Card transaction, resulting in a chargeback being raised by their financial institution.
- Chargeback Reversal - If a chargeback is unsuccessful, funds are returned to the biller resulting in a Chargeback Reversal.
GetPaymentStatus
URL
URL of Web Services | |
Production (LIVE) | https://api.ezidebit.com.au/v3-5/nonpci |
Sandbox (TEST) | https://api.demo.ezidebit.com.au/v3-5/nonpci |
Description
This method allows you to retrieve the status of a particular payment from the direct debit system where a PaymentReference has been provided.
It is important to note the following when querying Payment details:
- This method will only return the status of one payment at a time;
- To use this method, you must have provided a PaymentReference when adding the payment to the Customer’s schedule.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:px="https://px.ezidebit.com.au/">
<soapenv:Header />
<soapenv:Body>
<px:GetPaymentStatus>
<px:DigitalKey>49A67D1B-DF3F-4013-B13A-A5E9E41E8873</px:DigitalKey>
<px:PaymentReference>1</px:PaymentReference>
</px:GetPaymentStatus>
</soapenv:Body>
</soapenv:Envelope>
Request Parameters
Parameter Name | Description | Format | Example |
---|---|---|---|
Digital Key (Required) |
The 36 character Digital Key supplied to you by Ezidebit to identify your business |
String | 8591BFD4-E7C8-4284-84F7-E6C419114FA8 |
PaymentReference (Required) |
Provides the search with data to match against any PaymentReference that was supplied for the transaction. |
String (Max 50 char) | TS2204 |
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetPaymentStatusResponse xmlns="https://px.ezidebit.com.au/">
<GetPaymentStatusResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Data>W</Data>
<Error>0</Error>
<ErrorMessage i:nil="true" />
</GetPaymentStatusResult>
</GetPaymentStatusResponse>
</s:Body>
</s:Envelope>
Response
The <Data> field in the GetPaymentStatus response will contain either:
A status of which the possible values are:
'W’ (waiting) - Payment is scheduled waiting to be sent to the bank;
'P’ (pending) - Payment request has been sent to the bank for processing and Ezidebit is waiting on a success or fail response before completing settlement. This value will also be returned if the payment has been processed but has not been deposited into the client’s settlement bank account;
’S’ (successful) - Payment has been successfully debited from the Customer and deposited to the client’s settlement bank account;
’D’ (dishonoured) - Payment has been dishonoured by the Customer’s financial institution due to insufficient funds;
'F’ (fatal dishonour) - Payment has been dishonoured by the Customer’s financial institution;
Empty - When the Data field is empty, it indicates that the request was not successful. You should check the value of the Error field. If an error has occurred, it will be indicated by a non-zero value in the Error field, with a text descriptor in the ErrorMessage field.
GetPaymentDetail
URL
URL of Web Services | |
Production (LIVE) | https://api.ezidebit.com.au/v3-5/nonpci |
Sandbox (TEST) | https://api.demo.ezidebit.com.au/v3-5/nonpci |
Description
This method retrieves details about the given payment. It can only be used to retrieve information about payments where Ezidebit was provided with a PaymentReference.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:px="https://px.ezidebit.com.au/">
<soapenv:Header />
<soapenv:Body>
<px:GetPaymentDetail>
<px:DigitalKey>49A67D1B-DF3F-4013-B13A-A5E9E41E8873</px:DigitalKey>
<px:PaymentReference>1</px:PaymentReference>
</px:GetPaymentDetail>
</soapenv:Body>
</soapenv:Envelope>
Request Parameters
Parameter Name | Description | Format | Example |
---|---|---|---|
DigitalKey (Required) |
The 36 character Digital Key supplied to you by Ezidebit to identify your business |
String | 8591BFD4-E7C8-4284-84F7-E6C419114FA8 |
PaymentReference (Required) |
If you used a specific PaymentReference when adding a payment using the AddPayment Method, then you can use that value here to exactly identify that payment within the Customer’s schedule. |
String (max 50) |
TS2204 |
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetPaymentDetailResponse xmlns="https://px.ezidebit.com.au/">
<GetPaymentDetailResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Data>
<BankFailedReason />
<BankReturnCode>0</BankReturnCode>
<DebitDate>2011-03-14T00:00:00</DebitDate>
<InvoiceID />
<PaymentAmount>40</PaymentAmount>
<PaymentID>SCHEDULED12554</PaymentID>
<PaymentMethod>DR</PaymentMethod>
<PaymentReference>1</PaymentReference>
<PaymentStatus>P</PaymentStatus>
<SettlementDate i:nil="true" />
<ScheduledAmount>40.00</ScheduledAmount>
<TransactionFeeClient>0</TransactionFeeClient>
<TransactionFeeCustomer>1.35</TransactionFeeCustomer>
<YourGeneralReference>102</YourGeneralReference>
<YourSystemReference>102</YourSystemReference>
</Data>
<Error>0</Error>
<ErrorMessage i:nil="true" />
</GetPaymentDetailResult>
</GetPaymentDetailResponse>
</s:Body>
</s:Envelope>
Response
The <Data> field in the GetPaymentDetail response will contain either:
- The set of fields returned by the query, as described and outlined below, containing the data stored in the Ezidebit systems that relate to the specific Payment;
- Empty - When the Data field is empty, it indicates that the request was not successful. You should check the value of the Error field. If an error has occurred, it will be indicated by a non-zero value in the Error field, with a text descriptor in the ErrorMessage field.
The following table describes the data contained within each of the fields of a successful response for GetPaymentDetail
Parameter Name | Description | Format | Example |
---|---|---|---|
BankFailedReason |
The full text description for the reason that the payment was unsuccessful (dishonoured) Where a payment is successful or still pending an outcome, this value will be blank. A list of possible values are provided in Batch Responses. |
String |
Credit Card Transaction Declined |
BankReturnCode |
A number that identifies the reason code within Ezidebit for the reason that the payment was unsuccessful (dishonoured) Where a payment is successful or still pending an outcome, this value will be 0 (zero). A list of possible values is provided in Batch Responses. |
Integer |
21 |
DebitDate |
The date that the payment was actually debited from the Customer’s payment method by Ezidebit |
dateTime (yyyy-MM-ddThh:mm:ss) |
2011-05-03T00:00:00 |
InvoiceID |
The Ezidebit Tax Invoice number that the fees for this payment were charged on. The Invoice number is also used as a batch identifier for transactions that were settled to the client. |
String | 2856548 |
PaymentAmount |
The total amount of funds debited from your Customer’s payment method. NB - This will not necessarily be the same amount as the original payment schedule. In the cases where the Customer is paying the transaction fee, the fee amounts are added to the scheduled amount and the total is debited. This value represents that Total. It may be necessary for you to deduct the TransactionFeeCustomer from the PaymentAmount to determine the original requested debit amount. |
Double | 50.88 |
PaymentID |
The unique transaction ID given to the payment by Ezidebit. This value is not assigned to a payment until the scheduled payment has been processed and sent to the bank. |
String | 20116584259 |
PaymentMethod |
The payment method from which Ezidebit deducted this transaction. Possible values are: 'DR’ - Payment was debited from a bank account. 'CR’ - Payment was debited from a credit card. |
String |
DR |
PaymentReference |
If you used a specific PaymentReference when adding a payment using the AddPayment Method, then you can use that value here to exactly identify that payment within the Customer’s schedule. |
String (Max 50 char) |
TS2204 |
PaymentStatus |
A status indicating the state of the payment within the Ezidebit system.
'W’ (waiting) - Payment is scheduled waiting to be sent to the bank. 'P’ (pending) - Payment request has been sent to the bank for processing and Ezidebit is waiting on a success or fail response before completing settlement. This value will also be returned if the payment has been processed but has not been deposited into the client’s settlement bank account. ’S’ (successful) - Payment has been successfully debited from the Customer and deposited to the client’s settlement bank account. ’D’ (dishonoured) - Payment has been dishonoured by the Customer’s financial institution due to insufficient funds. 'F’ (fatal dishonour) - Payment has been dishonoured by the Customer’s financial institution for a technical reason, such as incorrect details etc. NB - Payments that are dishonoured for “fatal” reasons will cause the Customer’s record to be moved to a non-processing status until such point as the incorrect details are altered and the Customer is reactivated to a processing status. Whilst a Customer has a non-processing status, no debits will be attempted against their payment method by Ezidebit. |
String |
F |
ScheduledAmount |
The original amount that was scheduled to be deducted from the Customer’s payment method. NB - This figure may differ from the Payment Amount if Ezidebit has applied transaction, SMS or setup fees to the Customer. |
Decimal | 49.00 |
SettlementDate |
The date that the payment was settled to the client (for successful transactions) or the date that Ezidebit was notified that the payment was unsuccessful (for dishonoured transactions) This value will remain blank until such point as the payment is dishonoured in the Ezidebit system or is settled to the client’s bank account |
Date/Time String yyyy-MM-ddThh:mm:ss |
2011-03-28T00:00:00 |
TransactionFeeClient |
The total amount of fees paid to Ezidebit by the client (business) for processing this transaction. |
Double | 1.10 |
TransactionFeeCustomer |
The total amount of fees paid to Ezidebit by the Customer for processing this transaction. |
Double | 4.40 |
YourSystemReference |
A unique system identifier for the customer (e.g. GUID or your primary key). You can use this value to identify your Customer in the Ezidebit system if you supplied a value in this field in the AddCustomer method. |
String
(Max 50 char) |
563445878985432x76 |
YourGeneralReference |
A secondary unique reference for the customer. This is typically a human-readable reference for your Customer and is included in the reporting the Ezidebit supplies to its clients via email. |
String
(Max 50 char) |
101 |
GetScheduledPayments
URL
URL of Web Services |
|
Production (LIVE) |
|
Sandbox (TEST) |
Description
This method allows you to retrieve information about payments that are scheduled for a given Customer in the Ezidebit direct debit system.
It is important to note the following when querying Payment details:
- This method can be used to retrieve information about payments that are scheduled to be debited, but have not yet been sent to the bank for processing;
- This method provides access only to payments that have been added to a payer’s schedule through the integrated web services, Ezidebit Online website or by Ezidebit client support.
Payment information about real-time credit card or BPAY payments cannot be accessed through this method.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:px="https://px.ezidebit.com.au/">
<soapenv:Header />
<soapenv:Body>
<px:GetScheduledPayments>
<px:DigitalKey>49A67D1B-DF3F-4013-B13A-A5E9E41E8873</px:DigitalKey>
<px:DateFrom />
<px:DateTo />
<px:EziDebitCustomerID />
<px:YourSystemReference />
</px:GetScheduledPayments>
</soapenv:Body>
</soapenv:Envelope>
Request Parameters
Parameter Name | Description | Format | Example |
---|---|---|---|
Digital Key (Required) |
The 36 character Digital Key supplied to you by Ezidebit to identify your business |
String | 8591BFD4-E7C8-4284-84F7-E6C419114FA8 |
DateFrom |
When supplied, it will match payments where the scheduled debit date is on or after the supplied date. |
String (yyyy-MM-dd) | 2011-05-01 |
DateTo |
When supplied, it will match payments where the scheduled debit date is up to and including the supplied date. NB - If you do not wish to limit payment results by date you can supply a blank value for this parameter. |
String (yyyy-MM-dd) | 2011-07-01 |
EziDebitCustomerID |
The unique number assigned to the Customer by Ezidebit. |
String | 351328 |
YourSystemReference |
A unique system identifier for the customer (e.g. GUID or your primary key). You can use this value to identify your Customer in the Ezidebit system if you supplied a value in this field in the AddCustomer method. NB - You must provide a value for either EziDebitCustomerID or YourSystemReference to identify your Customer, but not both. |
String
(Max 50 char) |
563445878985432x76 |
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetScheduledPaymentsResponse xmlns="https://px.ezidebit.com.au/">
<GetScheduledPaymentsResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Data>
<ScheduledPayment>
<EziDebitCustomerID>350054</EziDebitCustomerID>
<ManuallyAddedPayment>false</ManuallyAddedPayment>
<PaymentAmount>100</PaymentAmount>
<PaymentDate>2010-12-20T00:00:00</PaymentDate>
<PaymentReference />
<YourGeneralReference>TEST TURNBULL</YourGeneralReference>
<YourSystemReference>TEST TURNBULL</YourSystemReference>
</ScheduledPayment>
<ScheduledPayment>...</ScheduledPayment>
</Data>
<Error>0</Error>
<ErrorMessage i:nil="true" />
</GetScheduledPaymentsResult>
</GetScheduledPaymentsResponse>
</s:Body>
</s:Envelope>
Response
The field in the GetScheduledPayments response will contain either:
- A data set enclosed within the
set for each individual payment returned; - Empty - When the Data field is empty, it indicates that the request was not successful. You should check the value of the Error field. If an error has occurred, it will be indicated by a non-zero value in the Error field, with a text descriptor in the ErrorMessage field.
The following table describes the data contained within each of the fields of a successful response for GetScheduledPayments
Parameter Name | Description | Format | Example |
---|---|---|---|
EzidebitCustomerID | The unique number assigned to the Customer by Ezidebit. | String | 123456 |
ManuallyAddedPayment | Whether the payment was added manually or created as part of a schedule | Boolean (True OR False) | True |
PaymentAmount | The amount of the payment in dollars. | Double | 123.56 |
PaymentDate | The date that the payment is scheduled to be taken. | DateTime (yyyy-MM-dd) | 2017-05-23 |
PaymentReference | The payment reference that was assigned when the payment was added. This will be empty for non-manual payments. | String | Payment123 |
YourGeneralReference |
A secondary unique reference for the customer. This is typically a human-readable reference for your Customer and is included in the reporting the Ezidebit supplies to its clients via email. |
String | JohnSmith1 |
YourSystemReference |
A unique system identifier for the customer (e.g. GUID or your primary key) You can use this value to identify your Customer in the Ezidebit system if you supplied a value in this field in the AddCustomer method. |
String | Customer123 |
Maintaining Customer Details
ChangeCustomerStatus
URL
URL of Web Services |
|
Production (LIVE) |
|
Sandbox (TEST) |
Description
This method allows you to change the processing status of a Customer record.
It is important to note the following when changing Customers’ Status:
- This method only allows you to change Customer Status from Active to Hold or Cancelled, or from Hold to Active or Cancelled. You cannot change the status of a Customer who is Cancelled;
- Ezidebit’s processing tasks may alter the processing status of your Customer. This will typically occur when a payment dishonours for a “Fatal” reason, such as “Invalid Bank Account Number”. Ezidebit will move these Customers to a non-processing status, as it knows that funds can no longer be drawn from that payment method. Typically these will require additional action (e.g. new Bank Account details) before the status can be changed;
- If a Customer has a status that does not allow processing of payments (Hold or Cancelled Statuses) at the time that a scheduled payment becomes due, then the payment will be removed from their schedule, but will not be debited from their payment method.
- When reactivating a customer using this method, any previously added payments that have not yet been debited will be inactivated and therefore not taken.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:px="https://px.ezidebit.com.au/">
<soapenv:Header />
<soapenv:Body>
<px:ChangeCustomerStatus>
<px:DigitalKey>00000000-0000-0000-0000-000000000000</px:DigitalKey>
<px:EziDebitCustomerID />
<px:YourSystemReference>102</px:YourSystemReference>
<px:NewStatus>C</px:NewStatus>
<px:Username>WebServiceUser</px:Username>
</px:ChangeCustomerStatus>
</soapenv:Body>
</soapenv:Envelope>
Request Parameters
Parameter Name | Description | Format | Example |
---|---|---|---|
DigitalKey (Required) |
The 36 character Digital Key supplied to you by Ezidebit to identify your business |
String | 8591BFD4-E7C8-4284-84F7-E6C419114FA8 |
EziDebitCustomerID |
The unique number assigned to the Customer by Ezidebit. |
String | 122456 |
YourSystemReference |
A unique system identifier for the customer (e.g. GUID or your primary key). You can use this value to identify your Customer in the Ezidebit system if you supplied a value in this field in the AddCustomer method. NB - You must provide a value for either EziDebitCustomerID or YourSystemReference to identify your Customer, but not both. |
String
(Max 50 char) |
563445878985432x76 |
NewStatus (Required) |
The new status to set the customer to: 'A’ (Active) - Is used to move your Customer to an active status to allow scheduled debits to be drawn from the Customer’s payment method. 'H’ (Hold) - Is used to move your Customer to a non-processing status in order to temporarily stop payments from being drawn from their payment method. You will typically use this if you intend to reactivate this Customer again in the future. 'C’ (Cancelled) - Is used to cancel the Customer record in the Ezidebit system. This is used when you have completed business with the Customer and no longer wish to manage their account. Moving a Customer to a cancelled status will delete any payments that may be scheduled, but not yet taken, from the Customer’s account. |
String
(Must be 'A’, 'H’, or 'C’) |
A |
Username |
Optionally record the user in your system that is executing this action |
String
(Max 50 char) |
Webuser |
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<ChangeCustomerStatusResponse xmlns="https://px.ezidebit.com.au/">
<ChangeCustomerStatusResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Data>S</Data>
<Error>0</Error>
<ErrorMessage i:nil="true" />
</ChangeCustomerStatusResult>
</ChangeCustomerStatusResponse>
</s:Body>
</s:Envelope>
Response
The field in the ChangeCustomerStatus response will be either:
- ‘S’ - indicates that the update of the Customer status has been successful;
- Empty - When the Data field is empty, it indicates that the update was not successful. You should check the value of the Error field. If an error has occurred, it will be indicated by a non-zero value in the Error field, with a text descriptor in the ErrorMessage field.
EditCustomerDetails
URL
URL of Web Services |
|
Production (LIVE) |
|
Sandbox (TEST) |
Description
This method allows you to update the details for an existing customer within the Ezidebit system.
It is important to note the following when editing customer details:
- If an empty string or “blank” is provided as a value for a parameter in this method, then the relating database field will be updated with the empty value, i.e. it will replace all values provided, with the exception of NewYourSystemReference;
- When a value is supplied for the NewYourSystemReference parameter, it will replace the current value of YourSystemReference with that supplied in NewYourSystemReference. This can be used to update the reference within the Ezidebit system in the event that your own Customer Reference or unique identifier has changed.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:px="https://px.ezidebit.com.au/">
<soapenv:Header />
<soapenv:Body>
<px:EditCustomerDetails>
<px:DigitalKey>49A67D1B-DF3F-4013-B13A-A5E9E41E8873</px:DigitalKey>
<px:EziDebitCustomerID />
<px:YourSystemReference>102</px:YourSystemReference>
<px:NewYourSystemReference />
<px:YourGeneralReference>102</px:YourGeneralReference>
<px:LastName>Stevens</px:LastName>
<px:FirstName>John</px:FirstName>
<px:AddressLine1>123 Jones St</px:AddressLine1>
<px:AddressLine2>Level 2</px:AddressLine2>
<px:AddressSuburb>Wilston</px:AddressSuburb>
<px:AddressState>QLD</px:AddressState>
<px:AddressPostCode>4051</px:AddressPostCode>
<px:EmailAddress>jstevens@example.com</px:EmailAddress>
<px:MobilePhoneNumber>0400000000</px:MobilePhoneNumber>
<px:SmsPaymentReminder>NO</px:SmsPaymentReminder>
<px:SmsFailedNotification>NO</px:SmsFailedNotification>
<px:SmsExpiredCard>NO</px:SmsExpiredCard>
<px:Username>WebServiceUser</px:Username>
</px:EditCustomerDetails>
</soapenv:Body>
</soapenv:Envelope>
Request Parameters
Parameter Name | Description | Format | Example |
---|---|---|---|
DigitalKey (Required) |
The 36 character Digital Key supplied to you by Ezidebit to identify your business |
String | 8591BFD4-E7C8-4284-84F7-E6C419114FA8 |
EziDebitCustomerID |
The unique number assigned to the Customer by Ezidebit. |
String | 351328 |
YourSystemReference |
A unique system identifier for the customer (e.g. GUID or your primary key). You can use this value to identify your Customer in the Ezidebit system if you supplied a value in this field in the AddCustomer method. NB - You must provide a value for either EziDebitCustomerID or YourSystemReference to identify your Customer, but not both. |
String
(Max 50 char) |
563445878985432x76 |
NewYourSystemReference |
A new unique system identifier for the customer (e.g. GUID or your primary key). |
String
(Max 50 char) |
628945878985432x0A |
YourGeneralReference |
A secondary unique reference for the customer. This is typically a human-readable reference for your Customer and is included in the reporting the Ezidebit supplies to its clients via email. Where system based identifiers (YourSystemReference) can be complex numbers, this is designed to be a simpler, human-friendly number. You may use a GUID to create the system-to-system link with YourSystemReference, and choose to include a membership ID, or such in this field. If no value is supplied for this field it will default to 'LastName FirstName’. |
String
(Max 50 char) |
101 |
LastName (Required) |
Where the customer is an individual, the Customer’s surname should be supplied. Where the customer is a business or organisation, the name of the entity should be supplied. |
String
(Max 60 char) |
Smith |
FirstName |
Customer’s first name (for individuals) |
String
(Max 30 char) |
Joe |
AddressLine1 |
The first line of the Customer’s physical address. * Note required if customerAddress2 is present |
String
(Max 30 char) |
123 Smith St |
AddressLine2 |
The second line of the Customer’s physical address |
String
(Max 30 char) |
Level 4 |
AddressSuburb |
The Suburb of the Customer’s physical address. |
String
(Max 20 char) |
Wilston |
AddressPostCode |
The Postcode of the Customer’s physical address. |
String
(Max 4 digits) |
4051 |
AddressState |
The State of the Customer’s physical address. |
String
(Max 3 char) |
QLD |
EmailAddress |
Customer’s email address |
String
(Max 255 char) |
joesmith@example.com |
MobilePhoneNumber |
Customer’s mobile telephone number. NB - for Australian Customers the mobile phone number must be 10 digits long and begin with '04’. For New Zealand Customers the mobile phone number can be up to 12 digits long and begin with '02’ |
String
(Max 12 char) |
0400123456 |
SmsPaymentReminder (Required) |
Optionally send an SMS to the customer reminding them of their upcoming scheduled debits. |
String
YES or NO |
YES |
SmsFailedNotification (Required) |
Send an SMS to the customer notifying them if their debit fails. For a valid mobile number an SMS is sent regardless of the parameter |
String
YES or NO |
YES |
SmsExpiredCard (Required) |
Optionally send an SMS to the customer notifying them if their recorded credit card is due to expire. |
String
YES or NO |
YES |
Username |
Optionally record the user in your system that is executing this action |
String
(Max 50 char) |
Webuser |
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<EditCustomerDetailsResponse xmlns="https://px.ezidebit.com.au/">
<EditCustomerDetailsResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Data>S</Data>
<Error>0</Error>
<ErrorMessage i:nil="true" />
</EditCustomerDetailsResult>
</EditCustomerDetailsResponse>
</s:Body>
</s:Envelope>
Response
The field in the EditCustomerDetails response will be either:
- ‘S’ - indicates that your Customer’s record has been successfully updated;
- Empty - When the Data field is empty, it indicates that the update was not successful. You should check the value of the Error field. If an error has occurred, it will be indicated by a non-zero value in the Error field, with a text descriptor in the ErrorMessage field.
GetCustomerDetails
URL
URL of Web Services |
|
Production (LIVE) |
|
Sandbox (TEST) |
Description
This method retrieves details about the given Customer.
It is important to note the following when querying Customer details:
- This method will effectively provide the same subset of Customer data that you can provide to Ezidebit, with the exception of some payment schedule fields, and the inclusion of some statistical values for the performance of a Customer’s payment history;
- This method does not provide any detail about the payment method (i.e. bank account or credit card detail);
- This method does not provide detailed information about each payment in the payment schedule. It only provides the same level of detail required to create the schedule.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:px="https://px.ezidebit.com.au/">
<soapenv:Header />
<soapenv:Body>
<px:GetCustomerDetails>
<px:DigitalKey>49A67D1B-DF3F-4013-B13A-A5E9E41E8873</px:DigitalKey>
<px:EziDebitCustomerID />
<px:YourSystemReference>102</px:YourSystemReference>
</px:GetCustomerDetails>
</soapenv:Body>
</soapenv:Envelope>
Request Parameters
Parameter Name | Description | Format | Example |
---|---|---|---|
DigitalKey (Required) |
The 36 character Digital Key supplied to you by Ezidebit to identify your business |
String | 8591BFD4-E7C8-4284-84F7-E6C419114FA8 |
EziDebitCustomerID |
The unique number assigned to the Customer by Ezidebit. |
String | 122456 |
YourSystemReference |
A unique system identifier for the customer (e.g. GUID or your primary key). You can use this value to identify your Customer in the Ezidebit system if you supplied a value in this field in the AddCustomer method. NB - You must provide a value for either EziDebitCustomerID or YourSystemReference to identify your Customer, but not both. |
String
(Max 50 char) |
563445878985432x76 |
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetCustomerDetailsResponse xmlns="https://px.ezidebit.com.au/">
<GetCustomerDetailsResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Data>
<AddressLine1>123 JONES ST</AddressLine1>
<AddressLine2>LEVEL 2</AddressLine2>
<AddressPostCode>4051</AddressPostCode>
<AddressState>QLD</AddressState>
<AddressSuburb>WILSTON</AddressSuburb>
<ContractStartDate>2011-03-01T00:00:00</ContractStartDate>
<CustomerFirstName>JOHN</CustomerFirstName>
<CustomerName>STEVENS</CustomerName>
<Email>jstevens@example.com</Email>
<EziDebitCustomerID>352818</EziDebitCustomerID>
<MobilePhone>0400000000</MobilePhone>
<PaymentMethod>DR</PaymentMethod>
<PaymentPeriod>W</PaymentPeriod>
<PaymentPeriodDayOfMonth>5</PaymentPeriodDayOfMonth>
<PaymentPeriodDayOfWeek>MON</PaymentPeriodDayOfWeek>
<SmsExpiredCard>NO</SmsExpiredCard>
<SmsFailedNotification>NO</SmsFailedNotification>
<SmsPaymentReminder>NO</SmsPaymentReminder>
<StatusCode>A</StatusCode>
<StatusDescription>Active</StatusDescription>
<TotalPaymentsFailed>0</TotalPaymentsFailed>
<TotalPaymentsFailedAmount>0</TotalPaymentsFailedAmount>
<TotalPaymentsSuccessful>0</TotalPaymentsSuccessful>
<TotalPaymentsSuccessfulAmount>0</TotalPaymentsSuccessfulAmount>
<YourGeneralReference>102</YourGeneralReference>
<YourSystemReference>102</YourSystemReference>
</Data>
<Error>0</Error>
<ErrorMessage i:nil="true" />
</GetCustomerDetailsResult>
</GetCustomerDetailsResponse>
</s:Body>
</s:Envelope>
Response
The field in the GetCustomerDetails response will contain either:
- The set of fields returned by the query, as outlined below, containing the data stored in the Ezidebit systems that relate to the specific Customer;
- Empty - When the Data field is empty, it indicates that the request was not successful. You should check the value of the Error field. If an error has occurred, it will be indicated by a non-zero value in the Error field, with a text descriptor in the ErrorMessage field.
Parameter Name | Description | Format | Example |
---|---|---|---|
AddressLine1 | The first line of the Customer’s physical address. |
String
(Max 30 char) |
1 Smith St |
AddressLine2 | The second line of the Customer’s physical address. |
String
(Max 30 char) |
Level 4 |
AddressPostCode | The Postcode of the Customer’s physical address. |
String
(Max 4 char) |
4006 |
AddressState | The State of the Customer’s physical address. |
String
(Max 3 char) |
QLD |
AddressSuburb | The Suburb of the Customer’s physical address. |
String
(Max 20 char) |
Fortitude Valley |
ContractStartDate | The date that the customer signed the Direct Debit Request Service Agreement. | DateTime (yyyy-MM-dd) | 2017-06-28 |
CustomerFirstName | Customer’s first name | String (Max 60 Char) | John |
CustomerName | Customer’s last name (for individuals) Where the customer is a business or organisation, this will be the name of the entity. |
String (Max 60 Char) | Smith |
Customer’s email address | String (Max 255 Char) | John | |
EzidebitCustomerID | The unique number assigned to the Customer by Ezidebit. | String | 3513284 |
MobilePhone | Customer’s mobile phone number | String | 0450123456 |
PaymentMethod | The payment method that is being used to debit the customer. (DR = Bank Account; CR = Credit Card) | String (Max 2 Char) | DR |
PaymentPeriod | The frequency of the schedule for the Customer. Possible values are: W - Weekly F - Fortnightly M - Monthly 4 - 4 Weekly N - Weekday in month (e.g. Monday in the third week of every month) Q - Quarterly H - Half Yearly (6 Monthly) Y - Yearly |
String (Max 1 Char) | M |
PaymentPeriodDayOfMonth | The Day of the month that the payments were being taken on. (For monthly schedules) | String (Max 2 Char) | 12 |
PaymentPeriodDayOfWeek | The Day of the week that the payments were being taken on. (For weekly schedules) | String (Max 3 Char) | MON |
SmsExpiredCard | Whether the customer will receive an SMS reminder when the Credit Card being used is due to expire at the end of the month. | String (Max 3 Char) | NO |
SmsFailedNotification | Whether the customer will receive an SMS reminder when a scheduled payment has dishonoured. | String (Max 3 Char) | NO |
SmsPaymentReminder | Whether the customer will receive an SMS reminder when a payment is going to be taken the same or next day. | String (Max 3 Char) | NO |
StatusCode | The status code for the status that the customer is on. | String (Max 2 Char) | A |
StatusDescription | The full description for the status code. | String (Max 2 Char) | A |
TotalPaymentsFailed | The number of payments that have failed for the customer. | Integer | 3 |
TotalPaymentsFailedAmount | The value (in dollars) of payments that have failed for the customer. | Double | 58.23 |
TotalPaymentsSuccessful | The number of payments that have been successfully debited for the customer. | Integer | 3 |
TotalPaymentsFailedAmount | The value (in dollars) of payments that have been successfully debited for the customer. | Double | 1337.12 |
YourGeneralReference | Your secondary unique reference for the customer that was added with the customer. | String | |
YourSystemReference | Your unique system identifier for the customer (e.g. GUID or your primary key) that was added with the customer. | String |
GetCustomerFees
The following table describes the data contained within Result data set of a response for CustomerFees.
Request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:px="https://px.ezidebit.com.au/">
<soapenv:Header/>
<soapenv:Body>
<px:GetCustomerFees>
<px:DigitalKey>b78e9ac3-3356-4088-9b24-12dfde0db2c0</px:DigitalKey>
<px:EziDebitCustomerID></px:EziDebitCustomerID>
<px:YourSystemReference></px:YourSystemReference>
<px:PaymentSource>ALL</px:PaymentSource>
<px:Username>Webuser</px:Username>
</px:GetCustomerFees>
</soapenv:Body>
</soapenv:Envelope>
Parameter Name | Description | Format | Example |
---|---|---|---|
Digital Key (Required) |
The 36 character Digital Key supplied to you by Ezidebit to identify your business |
String | 8591BFD4-E7C8-4284-84F7-E6C419114FA8 |
EziDebitCustomerID |
The unique number assigned to the Customer by Ezidebit. |
Integer | 351328 |
YourSystemReference |
A unique system identifier for the customer (e.g. GUID or your primary key). You can use this value to identify your Customer in the Ezidebit system if you supplied a value in this field in the AddCustomer method. NB - You must provide a value for either EziDebitCustomerID or YourSystemReference to identify your Customer, but not both. |
String
(Max 50 char) |
563445878985432x76 |
PaymentSource (Required) |
The source channel by which the payment was made. Possible values are: ALL - return details for payments regardless of the channel through which they were made. SCHEDULED - return details on for payments that were made by Direct Debit. WEB - return details only for payments that were made to Ezidebit through a web-based real-time credit card processing system. PHONE - return details only for payments that were made to Ezidebit through the real-time Interactive Voice Recording (IVR) phone credit card system. |
String
(Must be a value listed in the Possible values) |
ALL |
Username | Optionally record the user in your system that is executing this action | String | Webuser |
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetCustomerFeesResponse xmlns="https://px.ezidebit.com.au/">
<GetCustomerFeesResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Data>
<CustomerFee>
<EzidebitCustomerID/>
<FeeAmount>2.2</FeeAmount>
<FeeMaximumAmount>0</FeeMaximumAmount>
<FeeMinimumAmount>0</FeeMinimumAmount>
<FeeName>Administration Fee</FeeName>
<FeePercent>0</FeePercent>
<ProductName>Direct Debit Bank Account</ProductName>
<ProductVariant>Direct Debit Bank Account</ProductVariant>
<YourSystemReference/>
</CustomerFee>
<CustomerFee>
<EzidebitCustomerID/>
<FeeAmount>9.9</FeeAmount>
<FeeMaximumAmount>0</FeeMaximumAmount>
<FeeMinimumAmount>0</FeeMinimumAmount>
<FeeName>Payer Dishonour Fee</FeeName>
<FeePercent>0</FeePercent>
<ProductName>Direct Debit Card Account</ProductName>
<ProductVariant>Direct Debit Credit Card - Visa/MasterCard</ProductVariant>
<YourSystemReference/>
</CustomerFee>
</Data>
<Error>0</Error>
<ErrorMessage i:nil="true"/>
</GetCustomerFeesResult>
</GetCustomerFeesResponse>
</s:Body>
</s:Envelope>
Response
The field in the GetCustomerFees response will contain either:
- A dataset enclosed within the CustomerFees set for either the client or for an individual customer returned;
- Empty - When the Data field is empty, it indicates that the request was not successful. You should check the value of the Error field. If an error has occurred, it will be indicated by a non-zero value in the Error field, with a text descriptor in the ErrorMessage Field.
Parameter Name | Description | Format | Example |
---|---|---|---|
EzidebitCustomerID |
The unique number assigned to the Customer by Ezidebit. If no customer has been specified this will be an empty tag. |
Integer | 351328 |
FeeAmount |
The fee amount. |
Double | 5.00 |
FeeMaximumAmount |
Maximum fee amount that can be applied. Overrides the calculated fee amount if it is higher than the FeeMaximumAmount. Ignored if the FeeMaximumAmount = 0. |
Double | 10.00 |
FeeMinimumAmount |
Minimum fee amount that can be applied. Ignored if the FeeMinimumAmount = 0. |
Double | 2.00 |
FeeName |
The name of the payer fees. Possible values are: Administration Fee Administration Fee (Online) Direct Debit Amex MSF Direct Debit Bank Account Transaction Fee Direct Debit Credit Card Transaction Fee Direct Debit MasterCard MSF Direct Debit Visa MSF Payer Dishonour Fee Phonepay Amex MSF Phonepay Mastercard MSF Phonepay Transaction Fee Phonepay Visa MSF Redebit Dishonour Fee SMS Expired Card Notification SMS Failed Payment Notification SMS Payment Reminder Notification Transaction Fee WebPay Monthly Access Fee Webpay Amex MSF Webpay Amex Monthly Access fee Webpay Mastercard MSF Webpay Transaction Fee Webpay Visa MSF |
String | Administration Fee |
FeePercent |
The fee rate applied to the payment amount. Ignored if the FeePercent = 0. |
Double | 2.2 |
ProductName |
The payer fees are applied for this Product. Possible values are: Direct Debit Bank Account Direct Debit Card Account PhonePay WebPay |
String | Direct Debit Bank Account |
ProductVariant |
The payer fees are applied for this Product Variant. Possible values are: Direct Debit Bank Account Direct Debit Credit Card - Amex Direct Debit Credit Card - Visa/MasterCard PhonePay - Amex PhonePay - External - Visa/MasterCard PhonePay - Visa/MasterCard WebPay - Amex WebPay - External - Visa/MasterCard WebPay - Visa/MasterCard PhonePay - External - Amex WebPay - External - Amex |
String | Direct Debit Credit Card - Amex |
YourSystemReference |
A unique system identifier for the customer (e.g. GUID or your primary key). If no customer has been specified this will be an empty tag. |
String | 563445878985432x76 |
GetCustomerList
URL
URL of Web Services |
|
Production (LIVE) |
|
Sandbox (TEST) |
Description
This method allows you to retrieve customer information from Ezidebit’s direct debit payment system.
It is also important to note the following when querying Customer details:
- This is the recommended method of retrieving a set of customer results in a single call, as the GetCustomerDetails method is used to provide detail about a single customer;
- This method will allow you to retrieve data for a single customer, similar to GetCustomerDetails;
- This method will effectively provide the same subset of Customer data that you can provide to Ezidebit, with the exception of some payment schedule fields, and the inclusion of some statistical values for the performance of a Customer’s payment history for payments settled to the client;
- This method does not provide any detail about the payment method (i.e. bank account or credit card detail);
- This method does not provide detailed information about each payment in the payment schedule. It only provides the same level of detail required to create the schedule.
Up to 100 records will be returned per page.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:px="https://px.ezidebit.com.au/">
<soapenv:Header/>
<soapenv:Body>
<px:GetCustomerList>
<px:DigitalKey>2AF528C7-1A65-44D9-B546-3382F283BDDA</px:DigitalKey>
<px:EziDebitCustomerID></px:EziDebitCustomerID>
<px:YourSystemReference></px:YourSystemReference>
<px:CustomerStatus>ALL</px:CustomerStatus>
<px:OrderBy>EzidebitCustomerID</px:OrderBy>
<px:Order>ASC</px:Order>
<px:PageNumber>1</px:PageNumber>
</px:GetCustomerList>
</soapenv:Body>
</soapenv:Envelope>
Request Parameters
Parameter Name | Description | Format | Example |
---|---|---|---|
DigitalKey (Required) |
The 36 character Digital Key supplied to you by Ezidebit to identify your business |
String | 8591BFD4-E7C8-4284-84F7-E6C419114FA8 |
EziDebitCustomerID |
The unique number assigned to the Customer by Ezidebit. |
Integer | 122456 |
YourSystemReference |
A unique system identifier for the customer (e.g. GUID or your primary key). You can use this value to identify your Customer in the Ezidebit system if you supplied a value in this field in the AddCustomer method. NB - You may provide a value for either EziDebitCustomerID or YourSystemReference to identify your Customer, but not both. |
String
(Max 50 char) |
563445878985432x76 |
CustomerStatus (Required) |
The current status of the customer. Possible values are: ALL – return details for all customers regardless of the status. HOLD – returns only customers within the Hold status group. PENDING – returns only customers within the Pending status group. CANCELLED – returns only customers within the Cancelled status group. ACTIVE – returns only Active customers. |
String (Must be a value listed in the Possible values) | HOLD |
OrderBy |
This is used in conjunction with the Order parameter to specify Customer data to be sorted in the GetCustomerList response. If OrderBy and Order are left blank, the customer data will be sorted by descending Customer creation date. Possible values are: 'CustomerCreationDate’ – The date the customer was created. 'EzidebitCustomerID’ – The Ezidebit unique reference for the customer. 'YourSystemReference’ – Your unique system identifier for the customer. 'YourGeneralReference’ – Your secondary unique reference for the customer. |
String (Must be a value listed in the Possible values) | YourSystemReference |
Order |
This is used in conjunction with the OrderBy parameter to sort the Customer data in ascending or descending order. Possible values are: 'ASC’ – Ascending order. 'DESC’ – Descending order. |
String (Must be a value listed in the Possible values) | DESC |
PageNumber (required) | Used to specify page number of results. | Integer | 2 |
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetCustomerListResponse xmlns="https://px.ezidebit.com.au/">
<GetCustomerListResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Data>
<Customer>
<AddressLine1>Level 5, 12 Commercial Road</AddressLine1>
<AddressLine2>Newstead</AddressLine2>
<AddressPostCode>4006</AddressPostCode>
<AddressState>QLD</AddressState>
<AddressSuburb>Brisbane</AddressSuburb>
<ContractStartDate>2013-09-20T00:00:00</ContractStartDate>
<CustomerFirstName>AU REALTIME</CustomerFirstName>
<CustomerName>PAYER</CustomerName>
<Email/>
<EzidebitCustomerID>10728</EzidebitCustomerID>
<MobilePhone/>
<PaymentMethod/>
<PaymentPeriod>O</PaymentPeriod>
<PaymentPeriodDayOfMonth/>
<PaymentPeriodDayOfWeek/>
<SmsExpiredCard>NO</SmsExpiredCard>
<SmsFailedNotification>NO</SmsFailedNotification>
<SmsPaymentReminder>NO</SmsPaymentReminder>
<StatusCode>A</StatusCode>
<StatusDescription>Active</StatusDescription>
<TotalPaymentsFailed>7</TotalPaymentsFailed>
<TotalPaymentsFailedAmount>1257</TotalPaymentsFailedAmount>
<TotalPaymentsSuccessful>298</TotalPaymentsSuccessful>
<TotalPaymentsSuccessfulAmount>66390</TotalPaymentsSuccessfulAmount>
<YourGeneralReference/>
<YourSystemReference>PAYER10728</YourSystemReference>
<Country>AU</Country>
<MobileCountryCode/>
<PgnRowNo>1</PgnRowNo>
</Customer>
</Data>
<Error>0</Error>
<ErrorMessage i:nil="true"/>
</GetCustomerListResult>
</GetCustomerListResponse>
</s:Body>
</s:Envelope>
Response
The field in the GetCustomerFees response will contain either:
- A dataset enclosed within the Customer set for each individual customer returned;
- Empty - When the Data field is empty, it indicates that the request was not successful. You should check the value of the Error field. If an error has occurred, it will be indicated by a non-zero value in the Error field, with a text descriptor in the ErrorMessage field.
Refunds
ProcessRefund
URL
URL of Web Services |
|
Production (LIVE) |
|
Sandbox (TEST) |
Description
This method allows you to process a refund for a real-time credit card payment or a direct debit payment from a bank account/credit card. Refunds can only be processed for successful payments and must reference the PaymentIDs of the original transaction.
Where a product description was supplied for a transaction that was processed via WebPay, this cannot be used as a search criteria in performing a refund as the Product Description field is not unique. In the API submission, a unique identifier is required to identify the single transaction to match and perform the refund against.
It is important to note the following when using ProcessRefund
:
- This functionality is only available to approved Clients. Approval must be sought from Ezidebit before implementing this web service;
- Only settled payments can be refunded;
- A transaction fee may apply for refund transactions.
- A payment can only have a refund processed against it once
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:px="https://px.ezidebit.com.au/"\>
<soapenv:Header/>
<soapenv:Body>
<px:ProcessRefund>
<px:digitalKey>00000000-0000-0000-0000-000000000000</px:digitalKey>
<px:PaymentID>9999999</px:PaymentID>
<px:BankReceiptID></px:BankReceiptID>
<px:RefundAmountInCents>1600</px:RefundAmountInCents>
</px:ProcessRefund>
</soapenv:Body>
</soapenv:Envelope>
Parameters
Name |
Description |
Format |
Example |
DigitalKey (required) |
The digital key supplied by Ezidebit to identify the client account |
String |
D7C700C4-92DD-0CA2-E043-0A1017ACD099 |
PaymentID |
The unique transaction ID given to the original payment by Ezidebit. This value can be retrieved for the original payment using the GetPayments request. Either the PaymentID or BankReceiptID must be provided |
String |
612929 |
BankReceiptID |
Receipt Number issued by the Merchant Acquirer (bank) for the original payment. This value can be retrieved for the original payment using the GetPayments request. Either the PaymentID or BankReceiptID must be provided |
String |
1042479 |
RefundAmountInCents |
The amount that the refund is to be processed for. This must be less than or equal to the amount originally paid by the payer |
Integer |
1000 |
Response
The <Data>
field in the ProcessRefund
response will be either:
- A data set enclosed within the
<Data>
tags containing payment result details; - Empty - When the Data field is empty, it indicates that the request was not successful. You should check the value of the Error field. If an error has occurred, it will be indicated by a non-zero value in the Error field, with a text descriptor in the ErrorMessage Field.
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"\>
<s:Body>
<ProcessRefundResponse xmlns="https://px.ezidebit.com.au/">
<ProcessRefundResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Data>
<RefundPaymentID>888888</RefundPaymentID>
<BankReceiptID>930837</BankReceiptID>
<RefundResult>A</RefundResult>
<RefundResultCode>00</RefundResultCode>
<RefundResultText>APPROVED</RefundResultText>
</Data>
<Error>0</Error>
<ErrorMessage i:nil="true"/>
</ProcessRefundResult>
</ProcessRefundResponse>
</s:Body>
</s:Envelope>
The following table describes the data contained within Result data set of a response for ProcessRefund.
Parameter Name | Description | Format | Example |
---|---|---|---|
BankReceiptID | Receipt Number issued by the Merchant Acquirer (bank) for this refund |
Integer | 321654 |
RefundPaymentID | The unique transaction ID given to the refund transaction by Ezidebit |
Integer | 888888 |
RefundResult |
A single character that identifies the result of the payment. Possible values are: A - Approved. Payment was successfully processed at the bank. F - Failed. Refund was rejected by the bank. Check the RefundResult fields for further details about why the refund was unsuccessful. U - Unable to process. A communication or other issue has occurred that means that the refund cannot be submitted to the bank at this point. You will need to reattempt this refund at a later time. P - Pending. Refund is not yet processed. |
Text (max. 1 char) | A |
RefundResultCode | A standard two or three digit code that provides detail on the outcome of a refund. Refer to the standard list of real time transaction response codes in [Appendix A](#appendix-a) |
Numeric | 00 |
RefundResultText | A short description of the Payment Result code that you may choose to display to the user. Refer to the standard list of real time transaction response codes |
String | Approved |
BPAY
Description
Ezidebit’s BPAY solution provides customers with a convenient way to pay a bill, invoice or account anytime, anywhere. With just a phone call or via the internet, customers can make a payment from their cheque, savings or credit card account.
For general information about BPAY, see www.bpay.com.au.
Structure
A Unique BPAY biller code will be sent to Ezidebit clients who use this service. This BPAY biller code should be visible on all invoices provided to payers. Clients will also need to generate a Customer Reference Number for each payer. This number will identify which payer has made payment and will be displayed in Ezidebit’s reports.
Biller Codes
Unique Biller Code
A Unique Biller Code is used for clients that require their business name to appear on the customer’s bank or credit card statement (Statement ID) to indicate payment.
Unique Billers can customise additional features such as:
- Max/Min transaction value
- Payment options (bank/credit card)
- CRN length
- Have unique CRN generation MOD setting
Where a unique biller has a number of different outlets that they want to set up separately (e.g. a group of swim school locations), each account will be set up with the same unique biller code, but will have a sub-biller code to identify the specific account.
Generic Biller Code
A Generic Biller Code is used for smaller clients or for clients who do not require a Unique Biller Code. These are set up to cover different major industry groups.
When using a Generic Biller Code, a Sub-Biller code will also be issued which must be at the beginning of all CRNs that are generated or used.
There are a number of Generic Biller Codes that can be used by clients:
Biller Code | Name | CRN Length | Check Digit Algorithm | Min. Transaction Amount | Max. Transaction Amount | Account Types |
---|---|---|---|---|---|---|
197954 | Ezidebit BPAY | Variable - 6 to 20 Digits | $1.00 | $10000.00 | Bank Credit | |
197962 | Ezidebit Childcare | Variable - 6 to 20 Digits | $1.00 | $10000.00 | Bank Credit | |
197970 | Ezidebit Fitness | Variable - 6 to 20 Digits | $1.00 | $10000.00 | Bank Credit | |
197988 | Ezidebit Telecoms | Variable - 6 to 20 Digits | $1.00 | $10000.00 | Bank Credit | |
256834 | Ezidebit Education | Variable - 6 to 20 Digits | $1.00 | $10000.00 | Bank Credit | |
260059 | Ezidebit Finance | Variable - 6 to 20 Digits | $1.00 | $10000.00 | Bank Credit | |
256727 | Ezidebit Storage | Variable - 6 to 20 Digits | $1.00 | $100000.00 | Bank Credit | |
256859 | Ezidebit Accounting | Variable - 6 to 20 Digits | $1.00 | $100000.00 | Bank Credit | |
44925 | Handepay 'EziRentPay’ | Fixed - 10 Digits | $10.00 | $100000.00 | Bank | |
727776 | Handerent 'Ezidebit Handypay’ | Fixed - 10 Digits | $5.00 | $100000.00 | Bank Credit |
Clients using one of the Ezidebit biller codes will be set up in our system with a sub-biller code, which enables us to identify the specific client that a payment relates to. The CRN must incorporate this sub-biller code (see the section on CRNs below for further details). Depending on the biller code being used, the sub-biller code will be either two, three or four digits long.
BPAY Customer Reference Number (CRN)
To create BPAY Customer Reference Number (CRN), clients can either access their Ezidebit Online account and create BPAY CRN or use the GetBPayCRN API method.
A CRN is used to identify who a BPAY payment was made by and must meet specific requirements as follows:
Unique Biller | Generic Biller |
---|---|
|
|
GetBPayCRN
URL
URL of Web Services |
|
Production (LIVE) |
|
Sandbox (TEST) |
Description
This method allows you to generate a BPAY Customer Reference Number (CRN) based on your payer reference number. The returned CRN will be your BPAY Sub Biller Code, Payer Reference Number and the calculated check digit.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:px="https://px.ezidebit.com.au/">
<soapenv:Header/>
<soapenv:Body>
<px:GetBPayCRN>
<px:DigitalKey>8591BFD4-E7C8-4284-84F7-E6C419114FA8</px:DigitalKey>
<px:YourPayerNumber>81818181</px:YourPayerNumber>
<px:Username>Webuser</px:Username>
</px:GetBPayCRN>
</soapenv:Body>
</soapenv:Envelope>
Request Parameters
Parameter Name | Description | Format | Example |
---|---|---|---|
Digital Key (Required) |
The 36 character Digital Key supplied to you by Ezidebit to identify your business |
String | 8591BFD4-E7C8-4284-84F7-E6C419114FA8 |
YourPayerNumber (Required) |
Payer reference number - a unique number for the payer in your system. |
String (Max 15 Char)
Its value to be Positive Integer with possible zeroes padding |
123456 |
Username |
Optionally record the user in your system that is executing this action |
String | Webuser |
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetBPayCRNResponse xmlns="https://px.Ezidebit.com.au/">
<GetBPayCRNResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Data>
<BPayCRN>8760001436</BPayCRN>
<BPayBillerCode>197715</BPayBillerCode >
</Data>
<Error>0</Error>
<ErrorMessage i:nil="true"/>
</GenerateBPayCRNResult >
</GenerateBPayCRNResponse >
</s:Body>
</s:Envelope>
Response
The following table describes the data contained within Result data set of a response for GetBPayCRN.
Parameter Name | Description | Format | Example |
---|---|---|---|
BPayCRN | BPay CRN for the payer | Numeric | 8760001436 |
BPayBillerCode | BPay Biller Code for the client | Numeric | 197715 |
Miscellaneous
IsBsbValid
URL
URL of Web Services |
|
Production (LIVE) |
|
Sandbox (TEST) |
Description
This method allows you to verify if a BSB number is in our system.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:px="https://px.ezidebit.com.au/">
<soapenv:Header />
<soapenv:Body>
<px:IsBsbValid>
<px:DigitalKey>49A67D1B-DF3F-4013-B13A-A5E9E41E8873</px:DigitalKey>
<px:BankAccountBSB>064001</px:BankAccountBSB>
</px:IsBsbValid>
</soapenv:Body>
</soapenv:Envelope>
Request Parameters
Parameter Name | Description | Format | Example |
---|---|---|---|
Digital Key (Required) |
The 36 character Digital Key supplied to you by Ezidebit to identify your business |
String | 8591BFD4-E7C8-4284-84F7-E6C419114FA8 |
BankAccountBSB (Required) |
The BSB number to check |
String | 064001 |
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<IsBsbValidResponse xmlns="https://px.ezidebit.com.au/">
<IsBsbValidResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Data>YES</Data>
<Error>0</Error>
<ErrorMessage i:nil="true" />
</IsBsbValidResult>
</IsBsbValidResponse>
</s:Body>
</s:Envelope>
Response
The field in the IsBsbValid response will contain either a YES or a NO value.
- A YES value indicates that access to the BSB number provided is valid and can be accepted in the Ezidebit systems;
- A NO value indicates that the BSB number is invalid, and if provided will be rejected by the Ezidebit systems.
Software Design Considerations
General Guidelines
Below are a number of important points that you should keep in mind when using the Ezidebit Cloud Payment Web Services API:
- The Ezidebit Cloud Payment Web Services provides functions for all payment management activities. However, for Non-PCI Compliant Businesses that require sensitive payment method information (credit card details), Ezidebit supplies an embeddable Account Management widget to provide you with secure access to functions for adding or editing credit card and bank account details recorded for your Customers;
- The Ezidebit Cloud Payment Web Services can be used to manage scheduled and batch-style transaction processing, as well as reporting for all payment channels. You cannot use this API to execute real-time credit card transactions or request BPAY payments to be made;
- The methods included are designed to provide very specific functionality and can be used in conjunction with each other to form quite complex management tasks;
- Clients wishing to use the Ezidebit Cloud Payment Web Services must obtain an integrated Digital Key from Ezidebit to provide them access to the system;
- Ezidebit can issue a Digital Key to clients or software developers to access the integration test environment. This Digital Key will differ from their production (live) environment Digital Key;
- NEVER use real credit card or bank account details in the test environment. See the Test Payment Details for a list of samples;
- Web service requests must include all fields as outlined within the specifications for the relevant method. In some cases, the field can be left blank, however the field must still be included in the request otherwise a SOAP exception will be raised;
- It is important to recognise that the status returned by the web services for methods that will update a record, i.e. AddCustomer, AddPayment etc. will return a status that reflects the outcome of that particular method call, and not the status of the customer or payment itself. For example, if you call the AddPayment method and it returns a Successful response S, this indicates that the Payment was successfully added to the schedule and should not be interpreted as the payment has been successfully taken from the Customer’s payment method;
- Each response will contain the detail inside a Data tag unless there was an error, in which case the data tag will be null and instead the Error tag will have an error number, and the ErrorMessage tag will have user-friendly error message;
- Whenever possible, issues that arise because of normal processing and business logic will be returned to you as an Error in the normal method response. Other processing issues will be thrown as SOAP Exceptions;
- A common SOAP exception received during development and testing of integration is as follows: “Server was unable to process request. Your update could not be processed at this time - Please contact the Ezi Debit offices if this problem persists.” This error relates to XML messages being sent to the Ezidebit web services that are missing fields from the data packet. Should this error be received, please review the fields being included in the data packet against the relevant specification to ensure all fields have been included.
PCI Compliance
The available APIs provide the ability for clients to integrate with Ezidebit’s payment processing systems to manage payments made by direct debit, BPAY, Web Payments and Phone Payments.
The Payment Card Industry Data Security Standard (PCI-DSS) specifies requirements that merchants must adhere to when dealing with credit card details. Ezidebit is recognised as a Level 1 PCI-DSS Compliant Payment Service Provider and as such has implemented the most stringent security policies and protocols to protect this sensitive data. Ezidebit has also chosen to adopt these requirements as best practice when handling any sensitive payment data including payer and biller bank account and credit card details.
Full PCI specification can be found at https://www.pcisecuritystandards.org/security_standards/index.php
API methods for PCI Compliant Business only
The PCI-DSS specifies requirements that merchants must adhere to when dealing with credit card details. Ezidebit is recognised as a Level 1 PCI-DSS Compliant Payment Service Provider and as such has implemented the required security policies and protocols to protect sensitive data. Ezidebit has also chosen to adopt these requirements as best practice when handling any sensitive payment data, including payer and biller bank account and credit card details.
Such methods available within this documents provide the ability to do the following:
- Add/Edit credit card details;
- Process real-time credit card payments.
API methods recommended for Non PCI Compliant Business
The Ezidebit Cloud Payments API for Non-PCI Compliant Businesses provides Ezidebit’s clients and their software providers or partners the ability to integrate with Ezidebit’s core payment processing platform, allowing seamless management of their Customers’ payments and reporting from within their own software applications. This API provides integrators with a full range of functions, with the exception of functions that add or update sensitive credit card or bank account data. The Ezidebit Embeddable Account Widget provides facilities to record or modify card and account data within the Ezidebit database, without the need for an integrator or client to store or handle the data.
The goal of this API is to enable Ezidebit’s clients to undertake payment management activities for their customers in their own systems and have these changes updated directly in Ezidebit’s payment processing systems. The methods available within this API provide the ability to do the following:
- Add/edit customer details (excluding credit card details);
- Add/edit payment schedules;
- Add/edit manual or one-off payments;
- Delete payments;
- Retrieve payment schedules;
- Retrieve payment status (including payments made by BPay, Web and Phone).
BECS Compliance
The Bulk Electronic Clearing System (BECS), the banking regulatory which oversee Direct Entry payments, state very clearly “that it must be the account holder who provides the authority to take payment from their account.”
For this reason Ezidebit requires that integrations that are implementing Recurring Payments for both debit and credit card payments must adhere to following;
For Australia
- You must make a copy of the DDR Service Agreement available to the customer read and accept before signing up;
- You must be clear about the payment plan including plan name, frequency of payment, amount of payment, any once-off amounts, all inclusive fees , including the payer dishonour fee of up to $21.90;
- You must email a copy of the payment arrangement and service agreement to the customer within seven days of signup;
- You must display all fee that are being passed onto the customer on the sign-up page;
- You must provide a method for the payer to accept the agreement e.g. a tick box with the wording ‘I agree to the Terms and Conditions of the Direct Debit Request and Service Agreement’;
- You Must display the following text to the customer on the sign-up page:
Bank Accounts: I / We authorise Global Payments Australia 1 Pty Ltd ACN 601 396 543 (User ID No 342190, 342191, 428198) to debit my/our account at the Financial Institution identified above through the Bulk Electronic Clearing System (BECS) in accordance with this Direct Debit Request.
Credit Cards: By agreeing to this form, I / We authorise Ezidebit, acting on behalf of the Business, to debit payments from my specified Credit Card above, and I / we acknowledge that Ezi*<Business Name> will appear as the merchant on my credit card statement.
For New Zealand
- You must make a copy of the DDR Service Agreement available to the customer read and accept before signing up;
- You must be clear about the payment plan including plan name, frequency of payment, amount of payment, any once-off amounts, all inclusive fees , including the payer dishonour fee of up to $21.90;
- You must email a copy of the payment arrangement and service agreement to the customer within seven days of signup;
- You must display all fee that are being passed onto the customer on the sign-up page;
- You must provide a method for the payer to accept the agreement e.g. a tick box with the wording ‘I agree to the Terms and Conditions of the Direct Debit Request and Service Agreement’;
- You Must display the following text to the customer on the sign-up page:
Bank Accounts: I/We authorize you until further notice to debit my/our account with all amounts which EZIDEBIT (NZ) LIMITED, the registered initiator of Authorization Code 0227418, may initiate by Direct Debit. I/We acknowledge and accept that the bank accepts this authority upon the conditions listed in the terms of this agreement. I confirm that I can operate and have sole authority for the nominated bank account.
Credit Cards: By signing this form, I/we authorise Ezidebit (NZ) Limited, acting on behalf of the Business, to debit payments from my specified Credit Card above, and I/we acknowledge that Ezidebit will appear as the merchant on my credit card statement.
Displaying Credit Card Logos
When a customer is entering their credit card details, or when displaying masked credit card details, in your web page/application you must also display the relevant logo of the card type that is being used. To identify the card type, you are able to use the first 1 or 2 digits of the card number and then display the logo next to the card number.
Below is a list of first digits and the Card Type that they are associated with.
First Digits | Card Type |
2 | MasterCard |
4 | Visa |
5 | MasterCard |
34 | American Express |
37 | American Express |
A zip file containing all logos that need to be displayed is available for you to use.
NZ Bank Accounts
New Zealand Bank Account numbers follow a standardised format of 15-16 digits as shown below.
When using the API to add Bank Account details the following must be adhered to:
Design for Transaction Processing
When dealing with complex transaction processing systems that support different payment channels, it is important to understand the transaction lifecycle and timing of each. The diagram below outlines the different transaction types and outcomes, and the typical timing of each of these activities. These timings are indicative of a typical client process, but may vary slightly for individual clients. The diagram intends to give an idea of the point in time that the status updates to reflect its position in the lifecycle in terms of business banking days.
The most common analogy for the Direct Debit payment clearing process is that of accepting payment by cheque. If your system currently has a treatment for payments by cheque, it is recommended that the debit process adopt a similar approach. Another method for dealing with the clearing (pending) period is by marking all payments as accepted on the payment date, and reversing the receipt or payment entry if Ezidebit provides notice that the payment has failed.
There are a number of different ways to create Customers and payments in the Ezidebit systems, as well as manage and report on activity. The various integrated components that Ezidebit offer to work in conjunction with its Ezidebit Cloud Payment Web Services are demonstrated in the diagram below. This is just one example of what might be achieved with the Ezidebit Cloud Payment, Embeddable Widget and Web Payment System, and might be used as a starting point to consider the way in which you integrate your application with Ezidebit.
From the diagram, you can see that the web service methods in this document are used for adding a new Customer, adding payments to be debited from the customer and retrieving payment details for all payment methods to complete account and bank reconciliation activities within your own system.
The Ezidebit Management System maintains only one payment method (bank account or credit card) for each Customer (payer). When you change the Bank Account or Credit Card on record, it will record this change at the Customer level and apply the new credentials for all future payments from that Payer until such a point as they are changed again.
Managing Payments
Ezidebit’s web services contain methods for creating a full payment schedule that is maintained by Ezidebit using the parameters provided by you, or alternately, having your system add individual payments to the Ezidebit Customer payment schedule as and when they fall due. You can choose to use either and should consider the level of functionality your system currently has, whether your Customers have a static, recurring obligation to your business (e.g. monthly rental payment) or whether they have a varying obligation to your business (e.g. pay-by-usage internet access).
If you choose to create a schedule with Ezidebit (i.e. scheduled payments), you can alter, delete or create a new schedule at any point in the future using the methods available in this document.
If you choose to maintain the payment schedules in your system and communicate with Ezidebit when they are due (i.e. use Triggered payments), you need to consider the timing and references that you use.
Ezidebit can optionally send payment reminders via SMS in the 24 hours prior to the debit occurring. If you wish to take advantage of this service, you must ensure that Ezidebit has the Customer’s mobile telephone number recorded in the system and that the payment is added by close of business on the day prior to the debit being due.
The payment processing cycle occurs twice daily at 6am and 3pm Australian Eastern Standard Time (Brisbane Time) on business banking days. At each payment processing run, any scheduled payments with a payment date that is on or before the date of processing will be moved from the scheduled ‘W’ status to a ‘P’ status. This means that payments that are added after the 3pm processing run will be processed on the next business banking day.
Settlement deposits to the clients’ bank accounts are processed only during the morning processing run. All payments that are included in that day’s deposit will be marked as successful, and any payments that are reported as unsuccessful by the banking systems will be marked as either dishonoured or fatally dishonoured. Any payment that has been moved from a pending with bank ‘P’ status to either successful ‘S’, dishonoured ‘D’ or fatal dishonour ‘F’ during that processing run will have its status updated at that time.
Below diagram displays how all direct debit payments that are added to customer schedule will be reconciled through our web-service “GetPayments”. Following every payment processing cycle, Ezidebit will receive a bank response by 6:00 AM (AEST) for all the direct debit payments from credit cards. For majority of scheduled direct debit payments from bank accounts, Ezidebit will receive a bank response within two days of payment processing, and very rarely on third and fourth day from it.
Customer and Payment References
Payment References and System References are useful fields that can be used to achieve a number of different outcomes. The intended use for the YourSystemReference value is as a system-to-system link between a customer in your system with the corresponding Customer record in the Ezidebit system. By populating that parameter with a unique system-based identifier for your Customer, you can go forward and use that value as the reference in the Ezidebit system when accessing that particular Customer’s recorded payment method, payment schedule or other details.
If your system is a batch-processing style system where you maintain the payment schedules for your Customers, your might consider adding individual payments for the Customers as and when they fall due (AddPayment method). This will allow you to incorporate a batch identifier into your system as part of each PaymentReference, which can later be used with a wildcard to locate all payments from that specific batch in the Ezidebit system.
If you intend to issue invoices to your Customers that they can pay via real-time credit card or BPAY, you need to be aware that Ezidebit may issue “sub-biller” IDs to its clients that all Customer Reference or Bill Reference numbers for payments must begin with. You will also need to be able to calculate the appropriate check digit values. The Check Digit Routine (e.g. Mod10v01) will be determined by the facility that Ezidebit assigns client business to.
Digital Keys
It is also important to recognise that Ezidebit maintains one Client record for each business or branch that utilises the Payment Services offered by it. This means that each Client will receive a unique Digital Key to identify it within the Ezidebit Management Systems. For applications that are designed to service multiple Ezidebit Clients, the application must maintain this digital key on a per-Client or per-Branch basis. Your application configuration or data structures will need to allow for the recording of this in order to pass the correct details through to the web services.
Before you begin, you will need a Digital Key issued to you by Ezidebit. If you do not already have a digital key, you can contact partner@ezidebit.com.au (including details of your organisation as well as our client that you are developing the integration for) and request one for testing purposes. When you receive your test Digital Key, you should also receive login credentials for the Ezidebit Online test website (https://demo.ezidebit.com.au) where you can see the outcome of your actions.
File Encryption
Ezidebit does have a PGP Public Key that you can use to encrypt sensitive files before sending them.
Error Codes
Error Response Code
Code | Description |
---|---|
0 | No errors detected |
1 | You must provide a value for the ‘DigitalKey’ parameter |
2 | You must provide a value for either the ‘EziDebitCustomerID’ parameter or the ‘YourSystemReference’ parameter Unable to process update - Invalid Client Product for client ‘xxx-xxx-xxx’ and card type xxxxxxxx (WSvc) Failed.Payment already has a refund adjustment against it. Failed.Unable to process refund - Card expired on YYYY-MM-DD. Failed.Original payment is still being processed. It cannot be refunded at this stage. Failed.Client has insufficient funds to service the refund request. Unable to process update - Invalid credit card number entered (WSvc) Unable to process update - Declined (WSvc) Unable to process update - Your payment could not be processed due to a communication error. Please try again later. (WSvc) Failed.The Customer Account is Invalid (Non-existant or Inactive). Failed.Unable to process refund - Insufficient funds in trust to make the refund Failed.Unable to process refund - Original payment has not settled. |
3 | You must provide a value for the ‘YourSystemReference’ parameter |
4 | You must provide a value for the ‘YourGeneralReference’ parameter |
5 | You must provide a value for the ‘LastName’ parameter |
6 | You must provide a value for the ‘PaymentReference’ parameter |
7 | You must provide a value for the ‘DebitDate’ parameter |
60 | Null value detected, please pass through the empty string instead of null for parameters that you don’t wish to supply a value for |
61 | You must provide a valid value for the ‘MobileNumber’ parameter if you wish for the customer to receive SMS notifications |
62 | You must provide a value for the ‘DateField’ parameter when ‘DateFrom’ or ‘DateTo’ values are provided. |
63 | You must provide a value for the ‘DateFrom’ or ‘DateTo’ parameters when the ‘DateField’ value is provided. |
64 | You must provide a ‘YES’ value for at least one of the week of the month parameters when creating a Weekday In Month schedule. |
65 | You must provide a day of the week when creating a Weekly, Fortnightly, 4 Weekly or Weekday In Month schedule |
66 | You must provide a value for the ‘ChangeFromDate’ or the ‘PaymentReference’ parameter |
67 | You must provide a value for either the ‘ChangeFromDate’ or ‘ChangeFromPaymentNumber’ parameter |
100 | Invalid value provided for the ‘EzidebitCustomerID’ parameter. Valid values must be 50 characters or less |
101 | Not all required parameters were supplied |
102 | Invalid DigitalKey. Digital Key is incorrect or denied access to this function. |
103 | Invalid value provided for the ‘YourSystemReference’ parameter. Valid values must be 50 characters or less |
104 | Invalid value provided for the ‘YourGeneralReference’ parameter. Valid values must be 50 characters or less |
105 | Invalid value provided for the ‘NewYourSystemReference’ parameter. Valid values must be 50 characters or less |
106 | Invalid postcode entered |
107 | Invalid email address entered |
108 | Invalid mobile phone number entered |
109 | Invalid payment reference entered |
110 | Invalid value provided for the ‘NewStatus’ parameter. Valid values are: ‘A’, ‘H’ or ‘C’ |
111 | Invalid value provided for the ‘ApplyToAllFuturePayments’ parameter. Valid values are: ‘YES’ or ‘NO’ |
112 | Invalid value provided for the ‘ChangeFromPaymentNumber’ parameter. Valid values must be numeric and greater than or equal to one. |
113 | Invalid value provided for the ‘DateField’ parameter. Valid values are: ‘PAYMENT’ or ‘SETTLEMENT’ |
114 | Invalid value provided for the ‘LimitToNumberOfPayments’ parameter. Valid values must be numeric and greater than or equal to zero. |
115 | Invalid value provided for the ‘LimitToTotalAmountInCents’ parameter. Valid values must be numeric and greater than or equal to zero. |
116 | Invalid value provided for the ‘PaymentMethod’ parameter. Valid values are: ‘ALL’, ‘DR’ or ‘CR’. |
117 | Invalid value provided for the ‘PaymentSource’ parameter. Valid values are: ‘ALL’, ‘SCHEDULED’, ‘WEB’, ‘PHONE’ or ‘BPAY’. |
118 | Invalid value provided for the ‘PaymentType’ parameter. Valid values are: ‘ALL’, ‘PENDING’, ‘SUCCESSFUL’ or ‘FAILED’. |
119 | Invalid format provided for the ‘BankAccountBSB’ parameter. Valid values must be six digits only |
120 | Invalid value provided for the ‘DayOfWeek’ parameter. Valid values are: ‘MON’, ‘TUE’, ‘WED’, ‘THU’ or ‘FRI’. |
121 | Invalid value provided for the ‘DayOfMonth’ parameter. Valid values must be between 1 and 31. |
122 | Invalid value provided for the ‘FirstWeekOfMonth’ parameter. Valid values are: ‘YES’ or ‘NO’. |
123 | Invalid value provided for the ‘SecondWeekOfMonth’ parameter. Valid values are: ‘YES’ or ‘NO’. |
124 | Invalid value provided for the ‘ThirdWeekOfMonth’ parameter. Valid values are: ‘YES’ or ‘NO’. |
125 | Invalid value provided for the ‘FourthWeekOfMonth’ parameter. Valid values are: ‘YES’ or ‘NO’. |
126 | Invalid value provided for the ‘SchedulePeriodType’ paramater. Valid values are: ‘4’, ‘F’, ‘H’, ‘M’, ‘N’, ‘Q’, ‘W’ or ‘Y’ |
127 | Invalid value provided for the ‘PaymentAmountInCents’ parameter. Valid values must be greater than or equal to 200 ($2 dollars). |
128 | Invalid value provided for the ‘NewPaymentAmountInCents’ parameter. Valid values must be greater than or equal to 200 ($2 dollars). |
129 | Invalid value provided for the ‘KeepManualPayments’ parameter. Valid values are: ‘YES’ or ‘NO’ |
130 | Invalid value provided for the ‘DebitDate’ parameter. Valid values are any future date in the format of ‘YYYY-MM-DD’ |
131 | Invalid value provided for the ‘ScheduleStartDate’ parameter. Valid values are any future date in the format of ‘YYYY-MM-DD’ |
132 | Invalid value provided for the ‘ContractStartDate’ parameter. Valid values are any future date in the format of ‘YYYY-MM-DD’ |
133 | Invalid value provided for the ‘SmsPaymentReminder’ parameter. Valid values are: ‘Y’ or ‘N’. |
134 | Invalid value provided for the ‘SmsFailedNotification’ parameter. Valid values are: ‘Y’ or ‘N’. |
135 | Invalid value provided for the ‘SmsExpiredCard’ parameter. Valid values are: ‘Y’ or ‘N’. |
136 | Invalid value provided for the ‘ChangeFromDate’ parameter. Valid values are any future date in the format of ‘YYYY-MM-DD’ |
137 | Invalid value provided for the ‘ChangeToDate’ parameter. Valid values are any date in the format of ‘YYYY-MM-DD’ |
138 | Invalid value provided for the ‘DateFrom’ parameter. Valid values are any date in the format of ‘YYYY-MM-DD’ |
139 | Invalid value provided for the ‘DateTo’ parameter. Valid values are any date in the format of ‘YYYY-MM-DD’ |
140 | "DateFrom" can be no more than xx months prior to "DateTo" |
141 | The First Name contains non standard characters which is not permitted |
142 | The Last Name contains non standard characters which is not permitted |
143 | Invalid vlaue provided for the "PaymentAmountInCents" parameter. Valid values cannot be greater than xx |
144 | "DateFrom" cannot be greater than "DateTo". |
145 | Invalid value provided fro the "DishonourAction" parameter. Valid values are "DISHONOUR","RESCHEDULE"," |
150 | Invalid value provided for the ‘RefundAmountInCents’ parameter. Valid values are a refund amount between 100 and the amount of the original transaction |
180 | Parameter conflict. You can’t enter a value for both the ‘EziDebitCustomerID’ and ‘YourSystemReference’ parameters |
181 | Parameter conflict. You can’t provide a number greater than zero for both ‘LimitToNumberOfPayments’ and ‘LimitToTotalAmountInCents’ |
182 | You must provide a value for the ‘CustomerStatus’ parameter |
183 | Invalid value provided for the ‘CustomerStatus’ parameter. Valid values are: ‘ALL’, ‘HOLD’, ‘PENDING’, ‘CANCELLED’, ‘ACTIVE’. |
184 | Invalid value provided for the OrderBy parameter. Valid values are: ‘EzidebitCustomerId’, ‘YourSystemReference’, ‘YourGeneralReference’, ‘CustomerCreationDate’. |
185 | Invalid value provided for the Order parameter. Valid values are: ‘ASC’, ‘DESC’. |
186 | You must provide a value for the ‘Order’ parameter when the ‘OrderBy’ value is provided. |
187 | You must provide a value for the ‘OrderBy’ parameter when the ‘Order’ value is provided. |
188 | Invalid value provided for the PageNumber parameter. Valid values must be numeric and greater than zero. |
200 | There is already a customer existing with the upload reference you have provided. |
201 | Could not find a customer with the provided details. |
202 | Payment with reference ‘xxxxxxx’ could not be found. |
222 | Invalid value proided for the ‘xxxxxxx’ parameter. Valid value is between yyy and zzz cents. |
223 | Refunds are not allowed for the client |
232 | Dishonoured payments cannot be refunded. |
234 | Refund amount exceeds the total payment amount |
301 | Report data is currently unavailable as payment processing is currently being performed (PT). Please try again later… |
302 | Report data is currently unavailable as payment processing is currently being performed (SPS). Please try again later… |
303 | Report data is currently unavailable as payment processing is currently being performed. Please try again later |
304 | Add payment denied - Only active customers can have payments added to their schedule |
401 | Invalid bank account number entered |
402 | Invalid bank account BSB number entered |
403 | Invalid bank account name or account name entered |
404 | Invalid value entered for ‘Reactivate’ parameter. Valid values are ‘YES’ or ‘NO’ |
405 | Invalid credit card number entered |
406 | Invalid credit card expiry month entered |
407 | Invalid credit card expiry year entered |
408 | Invalid name on credit card entered |
409 | Invalid credit card CCV number entered - CCV number must be either 3 or 4 digits long |
410 | Invalid value provided for the ‘CustomerName’ parameter. Value must be less than 80 characters. |
411 | You must provide a value for the ‘customerName’ parameter |
414 | Unable to process update - Invalid credit card CCV number entered - CCV number must be 4 digits long for AMEX (WSvc) |
415 | Invalid Account Number length |
416 | Add payment denied - This customer is on hold due to invalid bank account details and these account details have not been changed. |
417 | Add payment denied - This customer is on hold due to invalid credit card details and these card details have not been changed. |
418 | Add payment denied - This customer's status of ‘xxxxx’ does not allow new payments to be added. |
419 | Invalid credit card number entered - Your product range does not include xxxxxxx |
420 | Invalid direct debit details entered - Your product range does not include direct debits. |
500 | You don't have an active BPay product |
501 | You don't use a shared Ezidebit BPay biller code. |
502 | You must provide a value for the ‘YourPayerNumber’ parameter |
503 | Invalid value is provided for the ‘YourPayerNumber’ parameter. Valid values are positive integers. |
504 | The length for the ‘YourPayerNumber’ parameter is greater than the maximum length. |
505 | Your status is xxxxx and it doesn't enable you to use the API. |
900 | Add payment denied - This customer's status of xx does not allow new payments to be added. Add payment denied - You already have a payment registered with ref xxxxxxxx. A payment reference must uniquely identify a single payment. Add payment denied - This customer already has x payments on this date. Add payment denied - This customer already has 6 payments on this date. Add payment denied - This customer is on hold due to invalid bank account details and these account details have not been changed. Add payment denied - This customer is on hold due to invalid credit card details and these card details have not been changed. There is already a customer existing with the upload reference you have provided. Add payment denied - You have multiple Client/Upload Ref combinations. Invalid BSB number entered. Digital key is incorrect or is denied access to this function. Invalid Account Number length. The operation has timed out |
903 | Digital key is incorrect or denied access to this function. The digital key validation has failed. Check that you are using the correct digital key |
904 | Client is NOT active. |
905 | You cannot change the status of a customer who is cancelled. |
906 | Status update denied - Only customers with a status of ‘A’,’N’ or ‘H’ may be changed using this service. |
907 | Parameter conflict. ‘ScheduleStartDate’ and ‘FirstWeekOfMonth’ are not in alignment. |
908 | Parameter conflict. ‘ScheduleStartDate’ and ‘SecondWeekOfMonth’ are not in alignment. |
909 | Parameter conflict. ‘ScheduleStartDate’ and ‘ThirdWeekOfMonth’ are not in alignment. |
910 | Parameter conflict. ‘ScheduleStartDate’ and ‘FourthWeekOfMonth’ are not in alignment. |
912 | This function is currently unavailable as Ezidebit processing is currently being performed. Please try again later... |
917 | Parameter conflict. You cannot enter a value for both the ‘ChangeFromDate’ and ‘ChangeFromPaymentNumber’ parameters |
921 | No data matched the selection parameters. |
922 | Parameter conflict. ‘ScheduleStartDate’ and ‘DayOfWeek’ are not in alignment. |
923 | Parameter conflict. ‘ScheduleStartDate’ and ‘DayOfMonth’ are not in alignment. |
924 | Add payment denied - This customer already has xx payments on this date. |
925 | Invalid value for provided for the ‘DebitDate’ parameter. Valid value is any date forward from thirty-one (31) days in the past, in the format of ‘YYYY-MM-DD’ |
927 | Add payment denied - You already have a payment registered with ref xxxxxxx. A payment reference must uniquely identify a single payment. |
928 | Credit card year/month has already expired. |
930 | Payment selected for deletion could not be found. |
935 | Payment has been processed and cannot be deleted |
936 | Bank account number cannot be blank |
1234 | Invalid Token. The token is not numeric |
1235 | System is currently unavailable. Please try again later. A connection cannot be opened to the database for some reason. Please contact partner@ezidebit.com.au for assistance |
1237 | System is currently unavailable. Please try again later. An unhandled error occurred extracting the details from the database. Please contact partner@ezidebit.com.au for assistance |
12361 | Digital key is incorrect or is denied access to this function. The digital key validation has failed. Check that you are using the correct digital key |
12362 | Unable to process update - Invalid token. |
12363 | Unable to process update - Not configured for credit card payments. |
12364 | Customer not Active (StatusCode). Customer status is not A (Active) or N (New) |
Customer Status Codes
Status Code | Description | Will Process Payments |
---|---|---|
A | Active | YES |
C | Cancelled | NO |
C4 | Cancelled - Customer Deceased | NO |
CB | Direct Debit Authority Cancelled by Bank | NO |
CC | Direct Debit Authority Cancelled by Customer | NO |
CD | Cancelled - Duplicate DDR | NO |
CP | Cancelled - Pick up Card | NO |
CS | Cancelled by System | NO |
H | Hold | NO |
H2 | Hold - Direct Debit Authority Cancelled by Customer | NO |
H3 | Hold - Bank Account Closed | NO |
H5 | Hold - Incorrect BSB or Account Number | NO |
H9 | Hold - Technically Invalid Transaction | NO |
HB | Hold - Waiting for Bank Account Details | NO |
HC | Hold - Waiting for Credit Card Details | NO |
HD | Hold - Waiting for Customer Start Date | NO |
HE | Hold - Expired Credit Card or Incorrect Expiry Date | NO |
HF | Hold - Fraud / Dispute | NO |
HI | Hold - Invalid Credit Card Number | NO |
HL | Hold - Lost Credit Card | NO |
HP | Hold - Waiting for Scheduled Payment Frequency | NO |
HQ | Hold - Cancelled Credit Card | NO |
HS | Hold - Waiting for Signature on DDR | NO |
HT | Hold - Temporarily Suspended | NO |
HU | Hold - Unsupported Card | NO |
HV | Hold - Waiting for DDR Authority Verification | NO |
HW | Hold - Unable to Process | NO |
HZ | Hold - Data integrity issues for investigation | NO |
N | New | YES |
SP | Suspend Payments | NO |
Direct Debit Response Codes
Direct Debit Bank Account Responses
The following return codes may exist for batch transactions. The Status column indicates the status that will be applied to the customer account in Ezidebit in the event that the return code exists for a payment:
Return Code | Description | Status Code |
---|---|---|
0 | Transaction Approved | A |
2 | Payment Stopped | H2 |
3 | Account Closed | H3 |
4 | Customer Deceased | C4 |
5 | No Account Number or Incorrect Account Number | H5 |
6 | Refer to Customer | A |
9 | Technically Invalid | H9 |
Direct Debit Credit Card Responses
Return Code | Description | Status Code |
---|---|---|
001 | Refer to Card Issuer | A |
002 | Refer to card issuer's special conditions | A |
003 | Invalid merchant | HU |
004 | Pickup Card | HL |
005 | Do not honour | A |
012 | Invalid transaction | A |
013 | Invalid amount | A |
014 | Invalid card number | HI |
015 | No such issuer | HI |
025 | Unable to locate record on file | HI |
030 | Format error | A |
033 | Expired card | HE |
034 | Suspected fraud | HF |
036 | Restricted card | HU |
039 | No credit account | HU |
040 | Request function not supported | A |
041 | Lost card | HL |
043 | Stolen card, pick up | HL |
051 | Not sufficient funds | A |
052 | No chequing account | HU |
054 | Expired Credit Card | HE |
057 | Transaction not permitted to cardholder | HU |
058 | Transaction not permitted to terminal | A |
061 | Exceeds withdrawal amount limits | A |
062 | Restricted card | A |
063 | Security violation | CP |
065 | Exceeds withdrawal frequency limit | A |
068 | Response received too late | A |
091 | Issuer or switch is inoperative | A |
092 | Financial institution not found | HU |
0Q3 | Payment Gateway Connection Error | A |
0QQ | Invalid Credit Card | HI |
Status codes that begin with 'H’ are hold statuses and will prevent further payments from being processed unless updated bank account/credit card details are provided.
Status codes that begin with 'C’ will cancel the member record and no further payments can be processed.
Late Returns and Refunds
Late returns (code 90) can occur when we are advised of a dishonoured transaction after funds have already been settled to the client account. This is not a frequent occurrence, however banks and other financial institutions have up to five days to dishonour a payment and Ezidebit may settled funds as early as two to three days after a transaction was processed.
Where a late return is received, Ezidebit will manually raise a reversal against the member record in Ezidebit’s system. This in turn will raise a debit against the client account and will 'short settle’ funds in the next settlement.
Ezidebit does allow refunds through the ProcessRefund method, however approval must be given before this method can be used
When a manual Late Return transaction exists, this will report back to integrated software using the GetPayments API method. In these cases, the response will include the following details:
- BankFailedReason will contain a value of 'Late Return’
- DebitDate will contain the date the reversal is processed
- PaymentAmount will contain the amount adjusted as a negative value (where transaction fees were paid by the member, these will be included in this value)
- ScheduledAmount will contain the amount of the adjustment, excluding any fees that were originally passed on to the member
- PaymentReference will contain the reference of the original payment
In both scenarios, it is expected that a debit will be applied to the member account in integrated software.
Claims and Chargebacks
Claims and chargebacks occur when the customer disputes a payment with their bank and their dispute is successful after investigation. In these cases, the transaction will be reversed against the member record in Ezidebit with return code 91 or 92. Ezidebit will raise a debit against the client account for the amount that has been returned to the customer by the bank
As with Late Returns above, the GetPayments method will include the details of the claim/chargeback. Again it is expected that a debit will be applied to the member account in integrated software
Realtime Credit Card Response Codes
Visa & Mastercard
Our sandbox environment allows you to test failed and successful payments for Visa and MasterCard depending on what number you enter for the number of cents in the payments amount. Zero cents (e.g. 100 or 100.00) will always be successful. Any other number of cents will always fail with the failed reason corresponding to the number of cents (e.g. 100.51 as the payment amount will fail with error code 51, meaning insufficient funds).
Approved Transactions
Cent Amount | Description | API Response |
---|---|---|
00 | Approved | APPROVED |
08 | Honour with ID | APPROVED |
10 | Partial Amount Approved | APPROVED |
11 | Approved VIP (not used) | APPROVED |
16 | Approved, Update Track 3 (unused) | APPROVED |
Declined Transactions
Cent Amount | Description | |
---|---|---|
01 | Refer to Issuer | REFERRED |
02 | Refer to Issuer’s Special Conditions | REFERRED |
03 | No Merchant | DECLINED |
04 | Pick Up Card | DECLINED |
05 | Do Not Honour | DECLINED |
06 | Error | UNSPECIFIED_FAILURE |
07 | Pick Up Card, Special Conditions | DECLINED |
09 | Request in Progress | DECLINED |
12 | Invalid Transaction | NOT_SUPPORTED |
13 | Invalid Amount | NOT_SUPPORTED |
14 | Invalid Card Number | NOT_SUPPORTED |
15 | No Issuer | DECLINED |
17 | 3D Secure Error | UNSPECIFIED_FAILURE |
19 | Re-enter Transaction | DECLINED |
21 | No Action Taken | UNSPECIFIED_FAILURE |
22 | Suspected Malfunction | DECLINED |
23 | Unacceptable Transaction Fee | DECLINED |
25 | Unable to Locate Record on File | DECLINED |
30 | Format Error | UNSPECIFIED_FAILURE |
31 | Bank not Supported by Switch | DECLINED |
33 | Expired Card-Pick Up | EXPIRED_CARD |
34 | Suspected Fraud-Pick Up | DECLINED |
35 | Contact Acquirer-Pick Up | DECLINED |
36 | Restricted Card-Pick Up | DECLINED |
37 | Call Acquirer Security-Pick Up | DECLINED |
38 | Allowable PIN Tries Exceeded | DECLINED |
39 | No Credit Account | DECLINED |
40 | Requested Function not Supported | DECLINED |
41 | Lost Card-Pick Up | DECLINED |
42 | No Universal Amount | DECLINED |
43 | Stolen Card-Pick Up | DECLINED |
44 | No Investment Account | DECLINED |
51 | Insufficient Funds | INSUFFICIENT_FUNDS |
52 | No Cheque Account | DECLINED |
53 | No Savings Account | DECLINED |
54 | Expired Card | EXPIRED_CARD |
55 | Incorrect PIN | DECLINED |
56 | No Card Record | DECLINED |
57 | Trans. not Permitted to Cardholder | DECLINED |
58 | Transaction not Permitted to Terminal | DECLINED |
59 | Suspected Fraud | DECLINED |
60 | Card Acceptor Contact Acquirer | DECLINED |
61 | Exceeds Withdrawal Amount Limits | DECLINED |
62 | Restricted Card | DECLINED |
63 | Security Violation | DECLINED |
64 | Original Amount Incorrect | DECLINED |
66 | Card Acceptor Call Acquirer Security | DECLINED |
67 | Hard Capture-Pick Up Card at ATM | DECLINED |
68 | Response Received Too Late | TIMED_OUT |
75 | Allowable PIN Tries Exceeded | DECLINED |
90 | Cut-off in Progress | DECLINED |
91 | Issuer or Switch is Inoperative | DECLINED |
92 | Financial Institution not Found | DECLINED |
93 | Trans Cannot be Completed | DECLINED |
94 | Duplicate Transmission | DECLINED |
95 | Reconcile Error | DECLINED |
96 | System Malfunction | DECLINED |
97 | Reconciliation Totals Reset | DECLINED |
98 | MAC Error | DECLINED |
99 | Reserved for National Use | UNSPECIFIED_FAILURE |
Amex
Our sandbox environment allows you to test failed and successful payments for American Express based on ther cents value of the payment. Only specific cents values will return valid responses. If a cents value not listed below is used the value may not be valid.
Please Note: AMEX is only available for Australian clients.
Cents Value | Response Code | Description |
---|---|---|
00 | 000 | Approved |
01 | 107 | Please call issuer |
03 | 109 | Invalid merchant |
04 | 200 | Deny - pick up card |
05 | 100 | Deny |
08 | 001 | Approve with ID |
13 | 110 | Invalid amount |
30 | 181 | Format error |
39 | 111 | Invalid account |
40 | 119 | Requested function not supported |
82 | 122 | Invalid card security code |
91 | 912 | Card Issuer Unavailable |
The following tables show all possible response codes for AMEX transactions.
Approved Transactions
Response Code | Description |
---|---|
000 | Approve |
003 | Approve VIP |
Declined Transactions
Response Code | Description |
---|---|
001 | Approve with ID |
100 | Deny |
101 | Expired card |
107 | Please call issuer |
109 | Invalid merchant |
110 | Invalid amount |
111 | Invalid account |
115 | Requested function not supported |
119 | Requested function not supported |
122 | Invalid card security code |
125 | Invalid effective date |
181 | Format error |
183 | Invalid currency code |
188 | Deny - Account cancelled |
189 | Deny - Cancelled or Closed Merchant/SE |
200 | Deny - pick up card |
912 | Card issuer unavailable |
Test Payment Details
Real Time Test Credit Cards
The table below provides a list of dummy Credit Card Numbers that can be used in testing for real time transactions.
- For Visa and MasterCard an expiry date of 05/21 must be used with these cards. An expiry month and year in the past will not be accepted as valid.
- For American Express an expiry date of 05/21 must be used to simulate a successful transaction. Some other expiry dates can be used to simulate specific responses and more information about this can be found in Credit Card Response Codes
Visa | MasterCard | American Express |
---|---|---|
4987 6543 2109 8769 | 5123 4567 8901 2346 | 3400 0000 0000 009 |
2223 0000 0000 0007 | 3411 1111 1111 111 | |
3421 3589 8797 783 | ||
3423 3764 9030 528 |
Please Note: AMEX is only available for Australian clients.
Direct Debit Test Credit Cards
In the Test Environment, customers whose credit card number ends in a '2’ will have their test payment(s) dishonoured as “Insufficient Funds” and the customer will stay on a processing status. Customers whose credit card number ends in a '3’ will have their test payment(s) dishonoured as “Incorrect Bank Account/Credit Card Number” (Fatal Dishonour) and the customer record will be moved to a non-processing status. All other payments will be marked as successful
Visa | MasterCard | American Express |
---|---|---|
4434 1234 5678 9351 | 5434 1234 5678 9051 | 3741 2345 6789 351 |
4545 4432 6654 8144 | 5545 4432 6654 8844 | 3754 4326 6548 444 |
4478 1122 3344 5475 | 5478 1122 3344 5175 | 3781 1223 3445 375 |
4488 9876 5432 1406 | 5488 9876 5432 1106 | 3789 8765 4321 506 |
4040 2121 2121 2968 | 5140 2121 2121 2568 | 3702 1212 1212 768 |
4148 5331 6619 6092 | 5148 5331 6619 6792 | 3785 3316 6196 992 |
4252 9543 8022 0462 | 5252 9543 8022 0162 | 3729 5438 0220 762 |
4371 8955 4034 4682 | 5371 8955 4034 4382 | 3718 9554 0344 482 |
4476 4763 9626 9382 | 5476 4763 9626 9082 | 3764 7639 6269 282 |
4554 5595 3119 7892 | 5554 5595 3119 7592 | 3745 5953 1197 492 |
4679 8191 4598 2653 | 5579 8191 4598 2453 | 3798 1914 5982 753 |
4782 4555 1667 1593 | 2223 5200 4356 0014 | 3724 5551 6671 993 |
4834 7344 5048 2763 | 2223 0000 4840 0011 | 3747 3445 0482 163 |
4917 1438 6621 1883 | 2223 0000 1009 6656 | 3771 4386 6211 983 |
4056 2776 8800 6393 | 2221 0000 0000 0009 | 3762 7768 8126 093 |
Please Note: AMEX is only available for Australian clients.
Test Bank Account
In the Test Environment, customers whose bank account number ends in a '2’ will have their test payment(s) dishonoured as “Insufficient Funds” and the customer will stay on a processing status. Customers whose bank account number ends in a '3’ will have their test payment(s) dishonoured as “Incorrect Bank Account/Credit Card Number” (Fatal Dishonour) and the customer record will be moved to a non-processing status. All other payments will be marked as successful.
The tables below provide a lists of valid and invalid BSB Numbers that can be used in testing.
Australia
Valid BSB | Invalid BSB |
---|---|
012-003 | 012-000 |
032-000 | 032-009 |
064-000 | 062-008 |
082-001 | 081-000 |
092-000 | 093-000 |
105-000 | 104-000 |
112-100 | 112-000 |
122-321 | 122-000 |
152-147 | 150-123 |
212-200 | 200-000 |
Any bank account number can be used in combination with the sample BSB numbers. Valid Australian bank account numbers are numeric only between two (2) and nine (9) digits in length.
New Zealand
The following table lists some valid BSB and Account Number combinations that can be used for New Zealand:
BSB | Account Number |
---|---|
010194 | 001234000 |
302902 | 012341232 |
030835 | 998877663 |
011838 | 123321876 |
Valid New Zealand bank account numbers are numeric only between nine (9) and ten (10) digits in length, and include a check digit. Only valid bank account numbers with correct check digit values can be used.