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:

Instant Payment Page (Pay Now)
Electronic Direct Debit Request (eDDR)
Embeddable Account Widget

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:

https://demo.ezidebit.com.au/webDDR/Request.aspx?a=51172E35-1B77-41DF-2007-0EE14CB27262 &oAmount=100&oDate=0&rAmount=50&rDate=0&Freq=4&dur=1&businessOrPerson=1

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:

https://demo.ezidebit.com.au/webDDR/Request.aspx?a=51172E35-1B77-41DF-2007-0EE14CB27262&oAmount=100&oDate=0&rAmount=50&rDate=0&Freq=4&dur=1&businessOrPerson=1&nouRef=1&fName=John&lName=Smith&email=John.Smith@ezidebit.com.au&mobile=0400%20000%20000&sms=1&addr=Queens%20St&suburb=City&state=QLD&pCode=4000

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.

https://demo.ezidebit.com.au/webddr/Request.aspx?a=51172E35-1B77-41DF-2007-0EE14CB27262&debits=2&uRefLabel=Invoice%20Number&uRef=INV0005&freq=4&rAmount=100&dur=1&businessOrPerson=1&tAmount=1000&rDate=0

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.

https://demo.ezidebit.com.au/webddr/Request.aspx?a=51172E35-1B77-41DF-2007-0EE14CB27262&oAmount=50.00&oDate=0&nosms=1&freq=2&rDate=0&rAmount=10&dur=1&businessOrPerson=1

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
email	Email	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’) *For NZ, this can be up to 12 digits beginning with 02	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: 200.00 OR oAmount=200.00&oAmount=250.00&oAmount=300.00 OR 200.00,250.00,300.00	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 FRI OR 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: 200.00 OR rAmount=200.00&rAmount=250.00&rAmount=300.00 OR 200.00,250.00,300.00	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 FRI OR 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 and Monthly (1 + 2 + 4)
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: 200.00 OR tAmount=200.00&toAmount=250.00&tAmount=300.00 OR 200.00,250.00,300.00	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). RESCHEDULE - A new scheduled debit attempt is set for three (3) days time. RESCHEDULE_NEXT - The failed payment will be re-attempted along with the next payment attempt (2 debits will be taken). APPEND - The contract is extended by one payment with the same frequency window to make up for the missed payment.	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	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’. For NZ Customers the mobile phone number can be up to 12 digits long and begin with 02	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:

SaveCustomerCreditCard.htm

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’. For NZ Customers the mobile number can be up to 12 digits long and begin with 02	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

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

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.

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 the ErrorMessage 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 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’. For NZ Customers the mobile number can be up to 12 digits long and begin with 02	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

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’. For NZ Customers the mobile number can be up to 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
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 the ErrorMessage 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 the ErrorMessage 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 the ErrorMessage 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 on DebitDate, 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. Will find the first unprocessed payment matching the criteria and delete that payment If no unprocessed payments exist that match the criteria then nothing wil be deleted.
PaymentAmountInCents; DebitDate;	Looks for a single payment. Will find the first unprocessed payment matching the criteria and delete that payment If no unprocessed payments exist that match the criteria then nothing wil be deleted.

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 the ErrorMessage 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. *See sample submission below 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. 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 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)

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 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)

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 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)

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 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)

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 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
Email	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)

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 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)

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 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
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

CRN length must be in line with the specific biller code, as outlined in the table above;
The first two/three/four digits of the CRN must contain the sub-biller code;
The last digit of the CRN must contain the check digit;
The check digit must be calculated using a standard algorithm called MOD10v01;
The CRN can be generated in Ezidebit Online if the client doesn’t have the ability to do so through other mechanisms;
The sub-biller code for the client’s account must be used at the start of the CRN.

CRN length must be in line with the details provided to the bank when the biller code was established;
The last digit of the CRN must contain the check digit;
CRN lenth is inclusive of sub biller code and the check digit;
The check digit must be calculated using the algorithm specified when the biller code was established with the bank;
Clients can use their existing reference numbers. They will need to ensure this includes the appropriate check digit.

GetBPayCRN

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 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)

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 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:

Bank and Branch Code is entered as the BSB.

The Account Number and Suffix (with no hyphen) is entered as the Account Number and be no longer than 10 digits in length.

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","RESCHEDULE_NEXT","APPEND"
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.