NAV Navbar
Logo

API Overview

 

Introduction

Ezidebit’s API provides a fully PCI compliant payment solution to clients/partners in Australia and New Zealand.

The API provides the ability to process payments via a range of payment types (direct debit, real time, BPAY) via a powerful suite of widgets, Javascript methods and SOAP web services.

Payments can be processed from bank accounts, Visa Card, MasterCard and American Express, depending on the payment type.

API Components

 

Ezidebit’s API has the following core components.

Widgets

Ezidebit’s hosted widgets are powerful application components that can be “plugged” into your software, immediately offering rich features with a minimum development on your part.

The added benefit of using our widgets is that when used as specified, they ensure that your software design is fully PCI level 1 compliant.

Widgets include:

Javascript API Methods

 

Our Javascript API allows you to have control over the page. Your forms’ details can be sent directly to Ezidebit, and not via your server.

Web Services

 

We have SOAP web services that enable your customer management system to interface directly with Ezidebit’s payment processing cloud

With over 25 web services to choose from, they are designed to be platform and programming language agnostic to allow integration with Ezidebit, regardless of the language that your system is developed in. They are delivered securely over the internet using SOAP as standard XML based specifications designed for exchanging structured information over computer networks.

A number of web services exist for use by businesses/software that are already PCI compliant. Use of these methods must be approved by Ezidebit and evidence of existing PCI compliance must be provided (Certificate of Attestation or Self Assessment Questionnaire D). Specific web services that require this approval are indicated in the relevant sections below.

Sandbox

 

You will receive a unique Sandbox Digital Key and Public Key, which give you access to our test environment. You will also receive your login credentials for the sandbox Ezidebit Online portal (access will be read only).

Some settings may differ on your sandbox account to your live account, e.g. payment products available, fees and who is paying the fees.

Approach to Integration

Ezidebit has a dedicated Integration Services team who can work with you on the design and validation of your planned integration to ensure it meets all PCI and banking requirements. It is recommended that you contact the Integration Services team by emailing partner@ezidebit.com.au before commencing your development so that they can assist you with identifying the most appropriate API components to deliver your requirements.

Prior to go live of a new integration, the Integration Services team will complete a certification of the developed solution. This will include a review of the API components being used and a walkthrough of key functions, such as new payer sign up, processing of credit cards payments. Where PCI or banking requirements have not been met, certification will not be able to be provided until issues have been addressed.

An annual certification review will be completed by the Integration Services team.

Support can be requested at any time by emailing partner@ezidebit.com.au.

Testing information

 

When testing and debugging it is important to remember that typically SOAP Exceptions result from malformed or bad data presented in the XML. When you are debugging you should check both your program logic and the XML that it is producing as the request data. When you are communicating with Ezidebit about these Exceptions, it is important that you include the XML that was sent as the request to the web service with your enquiry; this will assist Ezidebit’s support staff in identifying any issue.

Testing of the integration using Ezidebit’s APIs must include not only testing relating to sending and receiving of data using the web services, but also that data received in responses is correctly dealt with in the client management system. For example, where retrieving payment data, the system must be able to correctly treat both successful and failed payments.

The following points should also be noted in relation to testing:

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:

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:

Customers can be added to Ezidebit’s system via the following mechanisms:

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:

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:

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

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:

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:

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

If the transaction and storing of the customer is unsuccessful, the standard error message is reported back and the error handler is called as normal. If the transaction is successful, the data object is returned containing the following parameters:

Parameter Name Description Format Example
CustomerRef

The unique reference number stored in the Ezidebit database that corresponds to the customer.

Integer 327873

Complete Examples

We have a sample pack of HTML pages that you can download or check out the SaveCustomerBankAccount.htm one on its own. View the source or download the files to see how they work.

Maintaining Account Details

Embeddable Widget

 

The Account Widget should be used for maintenance of bank account/credit card details for existing customers. It is possible to create customers in the Ezidebit Management Systems without Bank Account or Credit Card Details recorded against them, and they will be set to a non-processing Hold Status until the appropriate payment source is provided. This allows businesses to create new customers through integrated methods, without the need for their system to handle sensitive data, instead using Ezidebit’s widget to handle that data directly.

Description

The Account Widget is delivered over a Secure Sockets Layer (SSL) HyperText Transfer Protocol (HTTP) connection, otherwise known as HTTPS. This ensures that communication between your application or web browser is secure and encrypted.

When the Account Widget is included in a web-based application, as described in this document, the communications occur directly between the user’s browser and the Ezidebit web servers, and there is no communication between your application or database server and the Ezidebit web servers.

When the Account Widget is included in a standalone application that is installed on the user’s computer, the user’s computer will need to communicate with the Ezidebit web servers via https, and as such you will need to ensure that you include the appropriate Secure Sockets Libraries in your application to facilitate this.

Ezidebit’s SSL Certificates are signed by the DigiCert High Assurance CA-3 Intermediate Certificate, which is a commonly embedded root certificate on most platforms. If your library or program does not recognise the Certification Authority, you may also need to install the Root Certificate with your application. You can obtain the appropriate root certificate and instructions on how to install it directly from DigiCert (https://www.digicert.com/digicert-root- certificates.htm)

Use Cases

The Ezidebit Management Systems maintain only one payment source (bank account or credit card) for each Customer (payer). When you change the Bank Account or Credit Card on record, it will record this change at the Customer level and apply the new credentials for all future payments from that Payer until such a point as they are changed again.

Structure

The Account Widget is a web-based form. You can access the form through either GET or POST methods, via a secured HTTPS call. The live and test widgets are located at the following addresses.

The URL of the LIVE widget is:

https://widget.ezidebit.com.au/account/

The URL of the TEST widget is:

https://widget.demo.ezidebit.com.au/account/

The base URL without any actions will return an Error 404. You will need to provide the actions with the widget. The widget currently has two actions available, view and edit. These actions are appended to the URL before the query string parameters. For example:

To view account details:

https://widget.demo.ezidebit.com.au/account/view?dk=49A67D1B-DF3F-4013-B13A-A5E9E41E8873&cr=99999

To edit account details:

https://widget.demo.ezidebit.com.au/account/edit?dk=49A67D1B-DF3F-4013-B13A-A5E9E41E8873&cr=99999

CALLBACK METHOD

If you would like to redirect customer after they have filled out our form and successfully submitted, you can request a callback by providing link in the callback parameter.

Embed Using iFrame

To use the account widget within your application or website it must be rendered in its own container. Typically, you will achieve this in a website by providing an iframe to position the widget where you wish.

The source URL for the iframe should be dynamically generated by your application to ensure that the correct customer is loaded through the query string parameters, as well as any visual component you wish to control. As a minimum, you must supply your digital key and either of the customer reference identification parameters (er= or cr=).

Input Values

Below is a list of all of the possible query string or POST parameters that can be passed to the widget to initialise the state of the form. Note that the parameters in bold may be required.

Parameter Description Format Example
dk (required)

Digital Key

The integration Digital Key supplied to the client by Ezidebit.

String

(36 chars)

49A67D1B-DF3F-4013-B13A-A5E9E41E8874
er

(*required if cr parameter is not provided)

Ezidebit Reference Number

The number provided by Ezidebit for the customer.

This Ezidebit ID can be used to allow the client system to communicate with Ezidebit using the Ezidebit ID in the case that the client system does not have its own identifier.

This value is the same as the EziDebitCustomerID value that is used through other Ezidebit APIs

Number

(typically 5 to 7 digits long)

678124
cr

(*required if er parameter is not provided)

Client’s Reference Number

A unique identifier for this customer that is generated by the client management application. This might be a member ID, order number, GUID or some other identifier.

This reference ID can be used in place of the Ezidebit Customer ID to allow the client system to communicate with Ezidebit using its own payer/customer references.

This value is the same as the YourSystemReference value used through other Ezidebit APIs

String

(max 50 chars)

5363-XXs

E

Editable

Setting this parameter to 1 will enable users to edit the account details. Providing an e=1 parameter enables an “Edit” button to be displayed at the bottom of the view action.

Number

(1 char)

0 - View Only

1 - Editable

0 or 1

callback

Callback URL Specifying this parameter forces widget to redirect the user to the URL specified in this parameter after the form submission is completed.

String http://www.ezidebit.com/

F

Font

Sets the font for all text on the widget.

String

(max 50 chars)

Trebuchet MS

h1c

Header Colour

Sets the colour of the header. Must be a hex code - RRGGBB

String

(6 chars)

FF5595
h1s

Header Size

Sets the size of the header. Must be in pixels.

Number

(in pixels)

20

lblc

Label Colour

Sets the colour of the labels. Must be a hex code - RRGGBB

String

(6 chars)

EB7636
lbls

Label Size

Sets the size of the labels. Must be in pixels.

Number

(in pixels)

14

bgc

Background Colour

Sets the background colour of the widget. Must be a hex code - RRGGBB

String

(6 chars)

FFFFFF
hgl

Highlight Colour

Sets the highlight colour of the widget. This is the predominant colour of the widget. Must be a hex code - RRGGBB

String

(6 chars)

1892CD
txtc

Text Colour

Sets the colour of all other text on the widget. Must be a hex code - RRGGBB

String

(6 chars)

333333
txtbgc

Textbox Background Colour

Sets the background colour of the textboxes. Must be a hex code - RRGGBB

String

(6 chars)

FFFFFF
txtbc

Textbox Focus Border Colour

Sets the colour of the textbox borders for the currently selected (focus) textbox. Must be a hex code - RRGGBB

String

(6 chars)

EB7636

Error Codes

The table below outlines the possible error codes that may be returned by the widget.

Code Description

Possible Cause

101

Not all required parameters were supplied

The widget requires at least the digital key (dk) parameter and either the Ezidebit ID (er) or your ID (cr) parameters.

201

Could not find a customer with the provided details

The value of the reference ID parameter (er or cr) does not relate to a customer in the Ezidebit Management System. Check that the customer has been created.

202

Invalid Digital Key

The value of the Digital Key parameter (dk) does not identify a client record in the Ezidebit Management System. Check that the Digital Key that you are using is active and you are calling the correct URL, i.e. you are using a Test digital key for the test widget or a live digital key for the live widget.

ChangeCustomerPaymentInfo

 

 

URL

  Endpoint
Production (LIVE) https://api.ezidebit.com.au/V3-5/public-rest
Sandbox (TEST) https://api.demo.ezidebit.com.au/V3-5/public-rest
Javascript File https://static.ezidebit.com.au/javascriptapi/js/ezidebit_2_0_0.min.js

The ChangeCustomerPaymentInfo is a Javascript method that enables you to collect updated bank account or credit card details from customers via your web site. We recommend that you have a secure log in for the customer to access any of their existing information before allowing update of details.

Description

This method allows you to update the billing account details currently held on file by Ezidebit for a customer. This requires an identifier to be passed in to identify the correct customer to be updated.

Note that the customer is not charged. Instead, their account details are stored on file for later use.

This method by default reactivates a customer if on hold status.

Requests

You can call the ChangeCustomerPaymentInfo method by passing the init method a public key followed by an array of arguments. The array parameters include:

Parameter Name Description Format Example
submitAction (required)

This should always be ChangeCustomerPaymentInfo for this function

String ChangeCustomerPaymentInfo
submitButton (required)

The client side element name of the button to submit the form (usually an input of type submit or button)

String btnSubmit.ClientID
submitCallback (required)

The method name of some client side code to execute when the operation completes successfully. A useful action would be to store the Ezidebit customer ID into a hidden field and then to submit the form to your server

Function SubmitCallback
submitError

The method name of some client side code to execute when the transaction failed, or the form validation failed. Generally this should be an action that takes an error message and displays it on the page

Function ErrorCallback
customerRef

The Ezidebit Customer Ref used to

identify the customer in Ezidebit’s

system
Numeric 5432102
customerReference

The Client side method name that is used to

identify the customer.

String Customer1001
cardNumber

The client side element name that is capturing the customer’s card number (usually an input of type text). This is the card number that will be used for future direct debit payments.

Do not supply a value if updating to use a bank account

Numeric

(max 16

digits)
4434123456789351
cardExpiryMonth

The client side element name that is capturing the customer’s card month expiry date (usually an input of type text)

Mandatory where cardNumber is provided

Numeric

(two digits)

12
cardExpiryYear

The client side element name that is capturing the customer’s card year expiry date (must be 4 digits, usually an input of type text).

Mandatory where cardNumber is

provided
Numeric

(four digits)

2016
nameOnCard

The client side element name that is capturing the customer’s name as it appears on their card (usually an input of type text).

Mandatory where cardNumber is provided

String

(max 100

char)

John Smith

accountName

The client side element name that is capturing the customer’s bank account name (usually an input type of text).

Do not supply a value if updating to use a credit card

String

(max 100

char)

John Smith

accountBSB

The client side element name that is capturing the customer’s BSB number (usually an input type of text).

Mandatory where accountName is provided

Numeric

(six digits)

124001
accountNumber

The client side element name that is capturing the customer’s account number number (usually an input type of text).

Mandatory where accountName is provided

Numeric

(max nine

digits)
789654123

Response

If the values entered by the customer are invalid, the submitError callback is invoked and will pass an error message together with the element that contains the problem value. An example of a submitError callback is shown below, in which the handler displays the error message and highlights the problem element with a red background and border.

If the call to the server was successful, but the server returned an error message then the same callback given to SubmitCallback is called and passes an errorMessage but no element.

Complete Examples

We have a sample pack of HTML pages that you can download or check out a few implementations:

View the source or download the files to see how they work.

Real-time Credit Card Transaction Response Codes

Please refer to Transaction Return Codes for a list of Transaction Return Codes.

Please refer to Transaction Return Codes for a list of Transaction Return Codes.

Error Response Code

Please refer to Error Codes for a list of Error Codes.

EditCustomerBankAccount

 

URL

  URL of Web Services
Production (LIVE) https://api.ezidebit.com.au/v3-5/pci
Sandbox (TEST) https://api.demo.ezidebit.com.au/v3-5/pci

Description

This method will Add or Edit the Bank Account detail on record for a Customer (Payer).

It is important to note the following when using EditCustomerBankAccount:


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

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:


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

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:

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

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

 

Ezidebit’s hosted payment page provides an out of the box payment page that is fully PCI compliant. The look and feel of the page can be customised via the Ezidebit Online portal to more closely align to a client’s own branding.

Each client’s unique hosted payment page URL is available from the Ezidebit Online portal under Web Page Configuration in the Admin menu.

The submission page simply requires a HTML form with the action parameter set to your unique URL, for example:
https://simple-business-tech.pay.demo.ezidebit.com.au/

During testing, use the URL available from your sandbox account by logging in to Ezidebit Online and selecting Web Page Configuration from the Admin menu.

The payment submission page can pre-load parameters in the payment page by HTML 'GET’ or 'POST’. Both methods are supported and it is your choice if you wish to hide the entry parameters or not. Which method you use will depend on the level of complexity you wish to implement in your website’s encoding to pass data into the hosted payment page for payment processing.

The URL below is an example of using GET Parameters:
https://simple-business-tech.pay.demo.ezidebit.com.au/?FirstName=Test&LastName=Customer&PaymentReference=Payment123

Input Values

 

The following form fields are submitted by you to our hosted payments page when your customer is sent to our website to make the payment.

Input Field Name Description Required Format
Type

Only valid values (I, B) - I = Individual B = Business

Yes String

(Max 1 Char)

PaymentReference

This is a reference number or string (usually an order number or invoice number) that is created on your website to identify the order that the payment is for. This value will be passed back to your website when the customer is returned so you can match the order with the results of the payment

Yes String

(Max 20 chars)

FirstName

First name of the person making the payment

Yes String

(Max 150 chars)

LastName

Last name of the person making the payment

Yes String

(Max 150 chars)

CompanyName

Company Name

No String

(Max 150 chars)

PaymentAmount

The amount of money in dollars/cents that your customer must pay. Supported currencies only.

Yes Numeric

(Max 2 decimal places allowed)

countryCode

Values accepted format [Country Code]_[Dailing Code], eg; (AU_61 , NZ_64)

Yes String

(Max 5 Chars)

MobilePhoneNumber

Optional

No String

(Max 255 Chars)

EmailAddress

Optional

No String

(Max 255 Chars)

RedirectURL

The absolute URL address of the client’s web page that the customer is to be returned to after they make the payment.

Yes String

(Max 500 Chars)

RedirectMethod

The method that will be used to pass return paramters back to the return page.

Accepted values are GET or POST

No String

(Max 4 Chars)

ShowDisabledInputs

When enabled, this will display pre-filled values as text instead of displaying in an editable box.

Accepted values are 0 for enabled and 1 for disabled

Optional Numeric

(0 or 1)

The WebPay instant payment page can host up to 5 unique customised values to better describe your transaction. Contact partner@ezidebit.com.au and our Integration Services Team will assist you to set this up.

Response

Your customer will be sent to this page when they have completed their payment. There are no requirements for this page as far as our gateway is concerned because by this stage all our processing has been completed, however you will likely want to update your order records based on whether the payment was successful or not. To do this you will need to set up your return page to check and store a number of query string variables that contain the results of the payment that will be included on the URL link to your return page (see the Return Values below for details of these variables).

Value Name Description Format
PaymentReference The payment reference value that you originally sent through the submission page. String (Max 20 chars)
ScheduledAmount The payment amount value that you originallysent through the submission page. Decimal
TransactionFeeCustomer Transaction fees paid by the payer on this transaction. Decimal
ResultText A short description of the reason for the payment result (value is 'Approved' for successful transactions). String
ResultCode A code that identifies the reason for the payment result (value is '00' or '000' for successful transactions) Numeric
NameOnCard Name entered in the name on card field. String (Max 100 chars)
BankReceiptID Payment receipt ID issued bythe bank if the payment was able to reach the bank for processing. Numeric
PayerName Name entered for the payer in the submission page. String (Max 100 Chars)
MobilePhoneNumber Mobile phone number entered in the submission page. String (Max 14 Chars)
EmailAddress Email Address entered in the submission page. String (Max 255 Chars)
BillerID Biller's Identification String
TransactionID The transaction record String
PaymentAmount The payment amount value that you originally sent through the submission page + any fees paid by the payer. Decimal
CompanyName The company name entered in the submission page. String (Max 100 Chars)

ChargeCard

 

URL

  Endpoint
Production (LIVE) https://api.ezidebit.com.au/V3-5/public-rest
Sandbox (TEST) https://api.demo.ezidebit.com.au/V3-5/public-rest
Javascript File https://static.ezidebit.com.au/javascriptapi/js/ezidebit_2_0_0.min.js

Description

ChargeCard will process a real-time credit card payment through Ezidebit’s payment gateway. No customer details are stored by Ezidebit.

$(document).ready(function () {
      eziDebit.init("YOUR_PUBLIC_KEY", {
            submitAction: "ChargeCard",
            submitButton: "payNowButton",
            submitCallback: displaySubmitCallback,
            submitError: displaySubmitError,
            nameOnCard: "nameOnCard",
            cardNumber: "cardNumber",
            cardExpiryMonth: "expiryMonth",
            cardExpiryYear: "expiryYear",
            cardCCV: "ccv",
            paymentAmount: "amount",
            paymentReference: "paymentReference"
          }, endpoint);

Requests

You can call the ChargeCard method by passing the init method a public key followed by an array of arguments.The array parameters include:

Parameter Name Description Format Example
submitAction (required)

This should always be ChargeCard for this function

String ChargeCard
submitButton (required)

The id of the element to submit the form (usually an input of type submit or button)

String btnSubmit
submitCallback (required)

The method name of some client side code to execute when the transaction is successful. A useful action would be to store the bank receipt ID in a hidden field and then submit the form to your server. No sensitive data will be submitted.

Function SubmitCallback
submitError (required)

The method name of some client side code to execute when the transaction failed, or the form failed validation. Generally, this should be an action that takes an error message and displays it on the page.

Function ErrorCallback
nameOnCard (required)

The client side element name that is capturing the customer’s name as it appears on their card (usually an input of type text)

String

(Max. 100 char)

txtNameOnCard
cardNumber (required)

The client side element name that is capturing the customer’s card number (usually an input of type text)

String

(Numeric Max 16 digits)

txtCardNumber
cardExpiryMonth (required)

The client side element name that is capturing the customer’s card month expiry date (usually an input of type text)

Numeric

(2 digits)

txtExpiryMonth
cardExpiryYear (required)

The client side element name that is capturing the customer’s card year expiry date (must be 4 digits, usually an input of type text)

Numeric

(4 digits)

txtExpiryYear
CardCCV (required)

The client side element name that is capturing the CCV number of the card (usually an input of type text)

Numeric

(4 digits)

txtCCV
paymentAmount (required)

The client side element name that is capturing the payment amount (usually either a label field if the customer should not change the value or an input of type text)

Numeric lblAmount
paymentReference (required)

The client side element name that is capturing a payment reference number. This may be a hidden field that your server has already generated.

String

(Max 50 char)

hdnPaymentRef

function ErrorCallback(errorMessage, element) {
  document.getElementById("results").innerHTML = errorMessage;
  document.getElementById(element).style.border = "1px solid red";
  document.getElementById(element).style.background = "\#F5E4E6";
}

Response

If the values entered by the customer are invalid, the submitError callback is invoked and will pass an error message together with the element that contains the problem value. An example of a submitError callback is shown below, in which the handler displays the error message and highlights the problem element with a red background and border.

If the call to the server was successful, but the server returned an error message then the same callback given to submitError is called and passes an errorMessage but no element.

If the transaction is successful, submitCallback callback is invoked and is passed a data object containing a BankReceiptID and PaymentResult property. The parameters returned are shown below.

Parameter Name Description Format Example
BankReceiptID

The receipt ID generated by the bank. You can use this ID to confirm a payment has been approved

Integer 237817
PaymentResult

The payment response code from the bank

String

A to indicate “approved”. Any other code means the transaction failed.

Complete Examples

We have a sample pack of HTML pages that you can download or check out the ChargeCard.htm one on its own. View the source or download the files to see how they work.

SaveCustomer

 

URL

  Endpoint
Production (LIVE) https://api.ezidebit.com.au/V3-5/public-rest
Sandbox (TEST) https://api.demo.ezidebit.com.au/V3-5/public-rest
Javascript File https://static.ezidebit.com.au/javascriptapi/js/ezidebit_2_0_0.min.js

Description

The SaveCustomer method will add a customer record and associated credit card details to the Ezidebit database, after first optionally processing a real time transaction. The saved customer can be used for later direct debit payments or for a tokenised real time payment.

When submitting the customer with credit card details, there are two scenarios that can occur:

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

If the transaction and storing of the customer is unsuccessful, the standard error message is reported back and the error handler is called as normal. If the transaction is successful, the data object is returned containing the following parameters:

Parameter Name Description Format Example
Data.BankReceiptId

The receipt ID generated by the bank. You can use this ID to confirm a payment has been approved

Integer 237817
Data.CustomerRef

The unique reference number stored in the Ezidebit database that corresponds to the customer.

Integer 327873
Error

The error response code. This will be 0 for a successful API call.

Numeric 0
ErrorMessage

A short description of the Payment Result code that you may choose to display to the user.

String null

Complete Examples

We have a sample pack of HTML pages that you can download or check out a few implementations:

SaveCustomerCreditCard.htm View the source or download the files to see how they work.

Real-time Credit Card Transaction Response Codes

Please refer to Credit Card Response Codes for a list of Transaction Response Codes.

Error Response Code

Please refer to Error Codes for a list of Error Codes.

ProcessRealTimeTokenPayment

 

URL

  URL of Web Services
Production (LIVE) https://api.ezidebit.com.au/v3-5/pci
Sandbox (TEST) https://api.demo.ezidebit.com.au/v3-5/pci

Description

This method allows you to process a credit card payment in real time using a customer’s credit card number previously stored with Ezidebit.


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:px="https://px.ezidebit.com.au/">
  <soapenv:Header />
  <soapenv:Body>
    <px:ProcessRealtimeTokenPayment>
      <px:digitalKey>00000000‐0000‐0000‐0000‐000000000000</px:digitalKey>
      <px:token>9999999</px:token>
      <px:paymentAmountInCents>1600</px:paymentAmountInCents>
      <px:customerName>J Smith</px:customerName>
      <px:paymentReference>123456789</px:paymentReference>
    </px:ProcessRealtimeTokenPayment>
  </soapenv:Body>
</soapenv:Envelope>

Request Parameters

Parameter Name Description Format Example
digitalKey (Required) The 36 character Digital Key supplied to you by Ezidebit to identify your business String 8591BFD4-E7C8-4284-84F7-E6C419114FA8
token (Required) The token used to identify the customer whose credit card is to be used for this payment. Usually this is the EziDebitCustomerID (The unique number assigned to the Customer by Ezidebit.) The second match will be YourSystemRef – your unique system identifier for the customer (eg. GUID or your primary key). Note: YourSystemRef values should not be numeric. String 55555555
paymentAmountInCents (Required)

The amount to debit from your payer in cents. The system will verify your minimum allowed amount. The maximum amount is $10000.00

E.g. $20.00 = 2000

Numeric 2000
customerName (Required)

The name of your Customer

NB - This is included for reporting purposes.

String

(Max. 80 char)

Joe Smith
paymentReference (Required) Your unique identifier for the transaction String

(Max 50 char)

512458557

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <ProcessRealtimeTokenPaymentResponse xmlns="https://px.ezidebit.com.au/">
      <ProcessRealtimeTokenPaymentResult xmlns:i="http://www.w3.org/2001/XMLSchemainstance">
        <Data>
          <BankReceiptID>1083550</BankReceiptID>
          <ExchangePaymentID>930837</ExchangePaymentID>
          <PaymentResult>A</PaymentResult>
          <PaymentResultCode>00</PaymentResultCode>
          <PaymentResultText>APPROVED</PaymentResultText>
        </Data>
        <Error>0</Error>
        <ErrorMessage i:nil="true" />
      </ProcessRealtimeTokenPaymentResult>
    </ProcessRealtimeTokenPaymentResponse>
  </s:Body>
</s:Envelope>

Response

The <Data> field in the ProcessRealtimeTokenPayment response will be either:

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:

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:


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

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:

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:

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:

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:

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:


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

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:

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:


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

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:

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:

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.
  1. Will find the first unprocessed payment matching the criteria and delete that payment
  2. If no unprocessed payments exist that match the criteria then nothing wil be deleted.

PaymentAmountInCents;
DebitDate;


Looks for a single payment.
  1. Will find the first unprocessed payment matching the criteria and delete that payment
  2. 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:

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:


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

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:

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:


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

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

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:

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:


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

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:


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

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:


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

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:

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:

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:

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:

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

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

Where a unique biller has a number of different outlets that they want to set up separately (e.g. a group of swim school locations), each account will be set up with the same unique biller code, but will have a sub-biller code to identify the specific account.

Generic Biller Code

A Generic Biller Code is used for smaller clients or for clients who do not require a Unique Biller Code. These are set up to cover different major industry groups.

When using a Generic Biller Code, a Sub-Biller code will also be issued which must be at the beginning of all CRNs that are generated or used.

There are a number of Generic Biller Codes that can be used by clients:

Biller Code Name CRN Length Check Digit Algorithm Min. Transaction Amount Max. Transaction Amount Account Types
197954 Ezidebit BPAY Variable - 6 to 20 Digits $1.00 $10000.00 Bank
Credit
197962 Ezidebit Childcare Variable - 6 to 20 Digits $1.00 $10000.00 Bank
Credit
197970 Ezidebit Fitness Variable - 6 to 20 Digits $1.00 $10000.00 Bank
Credit
197988 Ezidebit Telecoms Variable - 6 to 20 Digits $1.00 $10000.00 Bank
Credit
256834 Ezidebit Education Variable - 6 to 20 Digits $1.00 $10000.00 Bank
Credit
260059 Ezidebit Finance Variable - 6 to 20 Digits $1.00 $10000.00 Bank
Credit
256727 Ezidebit Storage Variable - 6 to 20 Digits $1.00 $100000.00 Bank
Credit
256859 Ezidebit Accounting Variable - 6 to 20 Digits $1.00 $100000.00 Bank
Credit
44925 Handepay
'EziRentPay’
Fixed - 10 Digits $10.00 $100000.00 Bank
727776 Handerent
'Ezidebit Handypay’
Fixed - 10 Digits $5.00 $100000.00 Bank
Credit

Clients using one of the Ezidebit biller codes will be set up in our system with a sub-biller code, which enables us to identify the specific client that a payment relates to. The CRN must incorporate this sub-biller code (see the section on CRNs below for further details). Depending on the biller code being used, the sub-biller code will be either two, three or four digits long.

BPAY Customer Reference Number (CRN)

To create BPAY Customer Reference Number (CRN), clients can either access their Ezidebit Online account and create BPAY CRN or use the GetBPayCRN API method.

A CRN is used to identify who a BPAY payment was made by and must meet specific requirements as follows:

Unique Biller Generic Biller
  • 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.

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:

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:

 

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:

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

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

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:

    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.

    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.