TranslatorDEFT API Integration Guide - v1.7 PDF

MACQUARIE BANK LIMITED
DEFT API

INTEGRATION GUIDE FOR DEFT BILLERS AND WEB

DEVELOPERS
Version 1.7
Date published 24 January 2013
Date effective 24 January 2013
Author Rob Gates
Page 1 of 49
Page 2 of 49
Table of Contents
1 DISCLAIMER 4
2 PURPOSE OF THE DOCUMENT 4
3 OVERVIEW OF THE DEFT API 5
4 SECURITY 6
5 SYSTEM ACCESS 6
6 ABOUT IP PAYMENTS 6
7 FUNCTIONALITY 7
7.1 SINGLE (ONE-OFF) PAYMENT 7

7.2 PRE-AUTH 7
7.3 SCHEDULED (RECURRING OR FUTURE) PAYMENTS 7
7.4 QUERY PAYMENT SCHEDULE 7
7.5 DELETE PAYMENT SCHEDULE 7
7.6 SURCHARGE 7
7.7 QUERY TRANSACTION 7
8 HIGH-LEVEL SOFTWARE REQUIREMENTS 8
8.1 TECHNICAL REQUIREMENTS 8

8.1.1Generating and Validating DRNs 8
8.1.2Request and response XML message formats 9
8.1.3Receipt and Reconciliation of Payments 9
8.2 PAGE DESIGN, CONTENT AND FLOW 11
8.3 PAYMENTS CARD INDUSTRY – DATA SECURITY STANDARD (PCI-DSS) COMPLIANCE AND E-COMMERCE BEST PRACTICE 12
9 THE INTEGRATION PROCESS 13
9.1 DISCOVERY PHASE 13

9.2 INITIATION PHASE 13
9.3 PLANNING AND DEVELOPMENT PHASE 13
9.4 TESTING PHASE 13
9.4.1Test environment 13
9.4.2Test cases 13
9.4.3Test data 14
9.5 REVIEW PHASE 14
9.5.1Transaction validation and processing 14
9.5.2Page design, content and flow 15
9.5.3PCI-DSS compliance checks 15
9.6 SIGN OFF PHASE 15
9.7 IMPLEMENTATION PHASE 15
10 CONTACT DETAILS 16
11 APPENDICES 17
11.1 APPENDIX 1 - DRN VALIDATION 17

11.1.1 Mod 10 – Check Digit validation 17
Page 3 of 49
11.1.2 Mod 9 – Check digit validation 18
11.2 APPENDIX 2 – DEFT API REQUEST AND RESPONSE MESSAGE FORMATS AND SAMPLES 20
11.2.1 Submit Single (One off) payment 20
Example XML for Single (One off) Credit Card Payment 21
Example XML for Single (One off) Credit Card Payment (Non .Net) 21
11.2.2 Submit Single (One off) Payment XML Response 22
Example SubmitSinglePayment XML Response 22
11.2.3 Submit Pre-Auth 23
Example XML for Pre-Auth 24
11.2.4 Submit Pre-Auth XML Response 24
Example Pre-Auth Response 25
11.2.5 Submit Payment Schedule 26
Example XML for Credit Card Payment Schedule – Single payment 27
Example XML for Credit Card Payment Schedule – Fortnightly with 24 payments 28
Example XML for Credit Card Payment Schedule – Monthly, ending after a specific date 28
Example XML for Credit Card Payment Schedule – Monthly, with 12 payments and changing amount after 6 months 29
11.2.6 Submit Payment Schedule XML Response 29
Example SubmitPaymentSchedule XML Response 30
Example SubmitPaymentSchedule XML Response – invalid data 30
11.2.7 Query Payment Schedules 31
Example XML for QueryPaymentSchedules 31
11.2.8 Query Payment Schedules XML Response 31
Example QueryPaymentSchedules XML Response with two returned schedules 32
Example QueryPaymentSchedules XML Response with error 33
11.2.9 Delete Payment Schedule 34
Example XML to Delete Payment Schedule 34
11.2.10 Delete Payment Schedule XML Response 34
Example Delete Payment Schedule XML Response 35
11.2.11 Query Surcharge 35
Example XML to Query Surcharge 36
11.2.12 Query Surcharge XML Response 36
Example Query Surcharge XML Response – with surcharge 37
Example Query Surcharge XML Response – without surcharge 37
11.2.13 Query Transaction 37
Example XML Query Transaction 38
11.2.14 Query Transaction XML Response 38
Example Query Transaction XML Response 39
11.3 APPENDIX 3 – DECLINED CODES 40
11.4 APPENDIX 4 - MAPPING BETWEEN THE PREVIOUS VERSION OF THE DEFT API (HOSTED BY SECUREPAY) AND THE NEW DEFT API
(HOSTED BY IP PAYMENTS) ERROR CODES 41
11.5 APPENDIX 5 – BANK RESPONSE CODES 42
11.5.1 Responses based on payment amount 42
11.5.2 Decline codes base on credit card number 43
11.6 APPENDIX 6 - LOCATION OF CARD VERIFICATION NUMBER (CVN) 44
11.7 APPENDIX 7 - DEFT E-COMMERCE CHECKLIST 45
11.8 APPENDIX 8 - ABBREVIATIONS, ACRONYMS AND DEFINITIONS 46
Page 4 of 49
Disclaimer
This information has been prepared by Macquarie Bank Limited ABN 46 008 583 542 (“Macquarie”). The
information provided has been prepared based on material from third party providers. This information is current as
at 25 November 2011. The information provided is not intended to replace or serve as a substitute for any
professional advice. Whilst we have taken reasonable care in producing this information, subsequent changes in
circumstances may occur at any time and may impact the accuracy of the information.
Notice of non-liability:
Macquarie provides the information “as is” with all faults. Macquarie makes no warranties of any kind (whether
express, implied or statutory) with respect to the information provided. Macquarie assumes no liability for damages
(whether direct or indirect), caused by errors or omissions, or resulting from the use of this document or the
information contained in this document or resulting from the application or use of the product or service described
herein. Macquarie reserves the right to make changes to any information herein without further notice.
© Copyright is reserved throughout. No part of this information can be reproduced in whole or part without the
express permission of Macquarie.
2 Purpose of the document

This document is intended for DEFT Billers and web developers wanting to develop their own interface to the DEFT
online payment gateway, via the DEFT API. The DEFT API offers Macquarie clients (Billers) the ability to securely
and efficiently process online, real-time credit card transactions to their Macquarie account. It also allows them to
customise their own front-end interface to the payment gateway and to integrate it with their Business Management
Software
This document details the system requirements for integration with the DEFT API and provides a step-by-step guide
to the integration process.
Page 5 of 49
Overview of the DEFT API
The DEFT API offers Billers the ability to receive DEFT payments by credit card via their own website. Payments
submitted to Macquarie through the DEFT API will be processed by Macquarie’s payment provider, IP Payments,
and will be credited to the Biller’s Macquarie account overnight. The diagram below shows this process at a
high-level. In this example the DEFT Reference number (DRN) is generated by the Biller’s website (alternatively
the DRN could appear on an invoice or remittance and the Payer would enter this reference number with their credit
card details).
Customers (Payers) enter their credit card details into the Biller website against the account due. The payment
details are validated by Macquarie’s payment provider/credit card schemes and if the payment is approved it will be
Page 6 of 49
submitted for processing. A unique reference number (DRN) is also passed through to the payment provider, which
is used to identify the Biller and the Payer involved in the transaction.
Payments made prior to the business day cut-off time will be received by the Biller the next business day. Any
payments made after this time will be processed within two business days.
Business day cut-off times:
● American Express and Diners Club 7.00pm (AEST)
● Mastercard and Visa 9.30pm (AEST)
Payments can be receipted in the Biller’s database (Business Management Software) either directly from the API’s
successful response message, or from a daily transaction file provided by Macquarie.
4 Security
Transactions are processed via an industry standard secure https connection. This means the Biller can be
assured:
1. Sensitive data such as credit card numbers will remain confidential because all information is 128bit
encrypted; and
2. The server the Biller is connecting to is authenticated as belonging to IP Payments through PKI certificates
issued by a root Certificate Authority.
In addition to the above security, each transaction request received by IP Payments is authenticated via a
pre-allocated User Id and Password. The User Id and Password are also 128bit encrypted.
5 System access
Macquarie supports a test web service and live web service, each of which can be found at the following locations:
The test web service URI is located at:

https://demo.ippayments.com.au/interface/api/dts.asmx
The live web service URI is located at:
https://www.deft.com.au/interface/api/dts.asmx
6 About IP Payments
Macquarie’s payment provider is IP Payments. They are a specialist provider of customised corporate payment
solutions, processing over $10 billion of payments per year for over 2750 clients. They are level 1 Payment and
Card Industry –Data Security Standard (PCI-DSS) compliant and Bulk Electronic Clearing System (BECS)
compliant.
Page 7 of 49
Functionality
The DEFT API offers the following functionality
7.1 Single (one-off) Payment

Requests the financial institution to debit funds from the customer’s credit card and credit them to the Biller’s
account. A valid credit card payment is authorised by the bank immediately, and a real-time response is returned in
the response XML message. A payment will return a receipt number and response code as a reference to the
payment.
7.2 Pre-Auth
A pre-auth transaction allows the Biller to verify that credit card details are valid (and that sufficient funds are
available to cover the cost of the transaction. The payment amount will be ‘held’ and deducted from the customer’s
credit limit, but the funds will not be transferred to the Biller. The hold will ‘fall off’ after approximately 5 days and
the available funds will be returned to the card. Pre-auths can be used to verify card details before accepting a
scheduled payment, by submitting a small nominal value (eg $1.00).
7.3 Scheduled (recurring or future) Payments

A Schedule action allows payment details to be stored by DEFT for future processing. This may either be a single
future dated payment, or multiple recurring payments with a set frequency. On the due date, the payments will be
compiled in a batch by DEFT and sent to the financial institution for processing. Results of scheduled payments are
available after the due date by using the Query Transaction request function, described in 7.7 below.
7.4 Query Payment Schedule

A Query Payment Schedule request allows a Biller to retrieve any scheduled payment details for a particular
customer.
7.5 Delete Payment Schedule

A Delete Payment Schedule request allows a Biller to delete any scheduled payment for a particular customer.
7.6 Surcharge
DEFT may store an issuer-dependant surcharge rate for credit card payments made by a Biller. To retrieve this
stored rate and display to a customer, or to calculate the value that DEFT will surcharge on the payment, you can
send a Surcharge request, detailing the customer’s credit card number, and the amount to be charged. DEFT will
return the surcharge rate as a percentage, and the calculated value of the surcharge on the given amount.
7.7 Query Transaction

A query transaction request allows a Biller to retrieve any previous payment details for a particular customer.
Historical transaction data is available for up to 12 months.
Page 8 of 49
High-level software requirements
The requirements for client websites to be compatible with the DEFT API can be divided into three areas:
1. Technical requirements
2. Page design, content and flow
3. PCI DSS compliance
8.1 Technical requirements

There are three components to the technical requirements of the client’s website. Firstly, it must be capable of
generating and/or validating a DRN to submit as part of the API request. Secondly, it must be able to create and
transmit a message to the payment provider in XML and to receive and interpret the XML response. And finally, it
must be capable of facilitating the receipt and reconciliation of the approved payments, as appropriate for the
reconciliation model being used.
8.1.1 Generating and Validating DRNs
A DRN is made up of two components: an account number and a customer reference number. These enable the
Biller and Payer involved in a transaction to be identified. Both components must be included in the API request
messages.
Account numbers
The first part of the DRN is a Macquarie account number. This is used by Macquarie to identify the Biller in order to
credit the payment amount to their account.
Account numbers have different lengths depending on the industry sector, as shown below. The last digit of the
account number is a modulus 10 check digit (see Appendix 1 for validation rules).
Insurance Broker clients– 6 digits.

All other clients – 9 digits
Account numbers are provided by Macquarie to the Biller.
Customer reference numbers
The second part of the DRN is the customer reference number. This is used by the Biller to identify the Payer
making the payment or invoice/remittance being paid.
Customer reference numbers are a minimum of three and a maximum of ten digits long. The number can be
zero-filled to meet the minimum length if required, eg 024. This number will be passed through to the BMS in an
overnight transaction file provided by Macquarie. The BMS may have its own specification for this number (eg,
required prefix’s) in order for the software to receipt and reconcile it. The software provider should be therefore be
consulted to ensure the customer reference generated by the website is compliant with their specification.
If it is intended that the Payer will be keying in their DRN, a check digit should be present on the end of the
customer reference number, depending on the industry sector, as shown below (see Appendix 1 for validation
rules). Note that the check digit is only required to validate key strokes, and is not to be passed to the payment
provider in the XML message. Therefore the website should validate the DRN and remove the check digit prior to
submitting the reference number in the XML message.
Insurance Broking clients– Modulus 10.

All other clients – Modulus 9
Page 9 of 49
Customer reference numbers are generated by the client’s Business Management Software (BMS).
There are two methods for generating DRNs, which will affect the validation required by the website.
DRNs generated at time of payment
In this instance the DRN is generated by the Biller’s BMS at the time of payment, (e.g., when an insurance policy is
accepted, or a donation to a charity is made). The Payer will not have to enter the DRN themselves (or even be
aware of it) and therefore there is no need for a check digit to be added to the customer reference number part of
the DRN.
DRNs generated before payment (ie, on a Biller’s invoice)
In this instance the DRN is generated by the Biller’s business management software before payment and will
typically appear on an invoice or remittance slip. The Payer will be required to enter the DRN into the website when
making the payment, and therefore the website should validate the check digits of the account number and
customer reference numbers, in order to minimise keying errors. The check digit should also be removed from the
reference number only (not the account number) prior to submitting the reference number in the XML script.
8.1.2 Request and response XML message formats
The request and response message formats and message samples can be found in Appendix 2.
Payments that are declined will include a specific declined code in the response message. A table of potential
declined codes can be found in Appendix 3.
For Billers who previously used the DEFT API hosted by Securepay, a mapping table of decline codes showing
Securepay’s code and IP Payments equivalent can be found in Appendix 4.
8.1.3 Receipt and Reconciliation of Payments
There are a number of ways in which payments made via the DEFT API can be receipted and reconciled in the
client’s BMS. The three most common methods are represented in the diagram below.
Page 10 of 49
Page 11 of 49
Model 1
In this model there is typically a single client database hosted on the clients’ web server. Payments can therefore
be receipted from the API approved payment response message. The payment is recorded as paid as soon as the
payment is approved. Alternatively an electronic file provided by Macquarie (the TXN or PAY file) on the day after
payment can be used to perform receipting. The files can also be used separately to the Accounts Receivable
process for bank reconciliation purposes.
Model 2
In this model the client would typically have BMS separate to the website. The Payer would have an invoice with a
DRN that was generated from the BMS and the Payer would go to the client’s website to make their credit card
payment. Where the client is also using Macquarie’s DEFT billing product, it is often more efficient to process all
payments using a single file interface. In this case it is done by importing an electronic file provided by Macquarie
(the TXN or PAY file) on the day after the payment was made. The file contains details of the processed credit card
payments, as well as all other DEFT transactions (e.g. BPAY, Australia Post, etc) on the Biller’s account for that
day. The payment will only be recorded as paid against a particular invoice after the file has been imported into the
client’s BMS on the day after payment. Therefore the website plays no part in the receipting process.
Model 3
In this model the client would again operate a separate BMS from the website, and so the BMS needs to receive
and potentially send details relating to the payments (for accounts receivable processing purposes). In this case it
is done through a link between the website and the BMS database (i.e. potentially via an API or interface that could
be a one or two way feed). The payment will therefore be recorded as paid in real time on the day of payment.
Note that the software may also import the electronic file provided by Macquarie (the TXN or PAY file) on the day
after the payment was made, in order to receipt other non-credit card DEFT transactions and potentially perform the
bank reconciliation. The TXN/PAY files from Macquarie will also contain the credit card transactions already
receipted via the website-database link, and so these payments should not be receipted again. The BMS could be
programmed to ignore this transaction type. Alternatively credit card transactions made via the API can be settled to
a separate facility (bank account) and the TXN/PAY file would not be downloaded on this account to avoid
duplicated receipts.
Further information on DEFT reconciliation and the file formats for the TXN and PAY file can be found in the DEFT
File Format Specifications document.
8.2 Page Design, Content and Flow

There are certain requirements in terms of the page design, flow and content that need to be considered, as
detailed below
Payment details capture page

A page is required with fields to capture the credit card information, which should include the following fields
● Credit card type
● Credit card number
● Expiry date
● Card Verification Number (CVN) – to include information on what a CVN is and how to find it (see
Appendix 6)
● Payment amount
● Notification of credit card surcharges if applicable
Confirmation page
It is recommended to display the above credit card information back to the Payer on a confirmation page, so that
they can check the information before confirming the payment. Note that the full credit card number should not be
displayed (first 6 and last 3 digits is recommended).
Page 12 of 49
It is also recommended to display the charge, the surcharge and the final grand total as separate fields.
A PAY or Confirm Payment button should appear on the screen for the Payer to confirm their payment. Text to the
effect of ‘Please click the button only once’ should appear with the button, to prevent the Payer from clicking it
multiple times, and generating duplicate payments. It is also recommended that the payment button is temporarily
disabled after the first click, to minimise the potential for unintended payments.
Receipt or declined page

Following the payment submission, a receipt or declined page should appear as appropriate, which the Payer can
print for their own records.
This page should display the following information

● Amount
● Surcharge (if applicable)
● Payment amount
● Partial credit card number (e.g., first 6 and last 3 digits)
● Expiry date
● Receipt number
● Submit date
● Submit time
The page should include text explaining that the transaction will be processed by DEFT Payment Systems a service
of Macquarie Bank. It should also display the DEFT and Macquarie Bank Logos, which will be supplied by
Macquarie along with guidelines for their use.
The receipt page should also include text explaining that the payment description on the Payer’s credit card
statement will appear as "DEFT Payments". Alternatively, this may be a Biller specific description, if they are using
a customised DEFT Merchant. The purpose of this is to ensure the cardholder recognises the payment on their
card statement, and therefore reduce the likelihood of chargebacks.
8.3 Payments Card Industry – Data Security Standard (PCI-DSS) compliance

and e-commerce best practice
The PCI-DSS is a multifaceted security standard that includes requirements for security management, policies and
procedures, network architecture, software design and other protective measures. This comprehensive framework
is intended to help organisations proactively protect customer account data. In simple terms, these standards are
meant to reduce credit card fraud. All businesses accepting payments via credit cards and debit cards are required
to comply with the PCI DSS requirements.
The Biller’s e-commerce environment should comply with industry best practice principles in order to effectively
manage e-commerce risk. A link to the best practices guide for merchant’s, provided by VISA, can be found here:
http://usa.visa.com/download/merchants/visa_risk_management_guide_ecommerce.pdf
The client will be required to complete an e-commerce checklist (Appendix 7) to confirm the website is compliant
with the key elements of e-commerce best practice. This checklist must be signed and returned to Macquarie
before the DEFT API is enabled in production.
Page 13 of 49
The Integration Process
A step-by-step guide to the integration process is set out below.
9.1 Discovery phase

Clients interested in integrating with the DEFT API should contact their Macquarie Bank Relationship Manager in
the first instance. Macquarie will organise a meeting to discuss the requirements and appropriate solutions. This
Discovery phase will typically involve Macquarie’s business diagnostics and integration teams, the client, their
web-developer and their software provider, as appropriate. If the DEFT API is found to be an appropriate solution
to the client’s requirements, the initiation phase will commence.
9.2 Initiation phase

The client will be sent the following documents by their Relationship Manager
● Indicative Offer
● DEFT Terms and Conditions
● DEFT Payment Systems E-Commerce checklist.
By agreeing to the Terms and Conditions, the client is agreeing that their website will be PCI-DSS compliant and
that they will complete and return the e-commerce best practice checklist to Macquarie before the website goes live.
The web-developer of the client will be sent the following document
● DEFT API Integration Guide (this document)
Macquarie will commence the client on-boarding and account setup during this phase, as appropriate.
9.3 Planning and development phase

Macquarie’s business diagnostics and integration teams will be available during the web-developers planning and
development phase to provide technical support as required. All questions should be referred to
softwareintegrations@macquarie.com in the first instance.
9.4 Testing phase

Macquarie will facilitate full testing of the DEFT API to satisfy both parties that the interface is working as required.
9.4.1 Test environment
The test web service URI is located at:

https://demo.ippayments.com.au/interface/api/dts.asmx
Sample SOAP requests and responses, and the WSDL, are also available at this location.
9.4.2 Test cases
Test cases should cover the following as a minimum requirement
1. Approved payments - payments should be made on all card types available on the client website
2. Declined payments - to ensure that declined payments are not misinterpreted and treated as approved by
the website
Page 14 of 49
Additional test cases will be required depending on the functionality being used. For example, surcharge requests,
scheduled payments, querying scheduled payments, deleting schedules and history queries.
Macquarie will have the ability to monitor transactions via an Admin portal, and will be able to provide feedback on
transactions if required. The Admin portal can also be used to assess whether sufficient testing has been
conducted.
9.4.3 Test data
Username and password
Macquarie will supply a username and password to be embedded in all API request messages for a particular Biller
(see Appendix 2). The password will only be applicable to the test environment. A production specific password
will be issued before the service goes live.
Account number and surcharging
Macquarie will add the Biller’s account number into the test environment and apply surcharge rates as appropriate.
Card data
The following card numbers can be used to generate test transactions. The amount entered should be over $2.00
(including surcharge) to simulate an approved response.
Card Type Card Number Expiry Date CVN (security Code)

Visa 4005 5500 0000 0001 Any future date Any 3 digit number
MasterCard 5123 4567 8901 2346 Any future date Any 3 digit number
Amex 3412 3456 7890 127 Any future date Any 4 digit number
Diners Club 3687 6543 2101 25 Any future date Any 3 digit number
Declined responses
In order to facilitate the testing of the various declined Bank Response Codes possible in production, the payment
amount submitted will trigger a particular response code to be returned. The response code returned will be based
on the payment amount plus any applicable surcharge (for amounts between $1.01 and $1.99).
A complete list of payment amounts and response codes can be found in Appendix 5. The appendix also includes
a list of credit card numbers that will generate specific declined Bank Response Codes regardless of the payment
amount entered.
9.5 Review phase

Following successful testing by the web-developer, Macquarie will conduct an accreditation process before the
DEFT API can be enabled in production for the Biller.
The web-developer will be requested to provide Macquarie with a link to their test site, including login details, where
possible. Alternatively, screen shots of all the payment pages can be supplied for review.
The following aspects of the website will be reviewed.
9.5.1 Transaction validation and processing

The ability of the website to validate and process transactions successfully will be reviewed, with particular attention
paid to the following areas
● DRN validation will be tested (where DRNs are entered directly by the user)
● approved payments
Page 15 of 49
● declined payments
● other payment functionality as appropriate (eg, surcharge request, scheduled payments, etc)
● appropriate error messages for failed validation and declined payments
9.5.2 Page design, content and flow

The website will be reviewed against the page design, content and flow requirements outlined in section 8.2.
Particular attention will be paid to the following aspects:
● use of the Macquarie and DEFT Logos

● notification of any surcharge amounts applicable, before and after payment confirmation
● ability of website to produce a receipt for Payer to keep for their own records
● text explaining what payment description will appear on the Payer’s credit card statement
9.5.3 PCI-DSS compliance checks

The website will be reviewed against aspects of e-commerce best practice, where possible, including the following
areas
● credit card numbers are not displayed in full anywhere on the website, including on confirmation and receipt
pages.
● payment screen details are cleared when refreshed, timed-out or when the transaction is approved or
declined.
Macquarie will provide feedback to the web-developer following the review. If changes are required, the review
phase will need to be repeated until accreditation is achieved.
9.6 Sign off phase

The following conditions must have been met in order for Macquarie to approve the DEFT API integration and
enable the service in production:
● successful completion of the Macquarie review phase

● DEFT E-Commerce checklist to be signed by the client and returned to Macquarie by mail or fax
9.7 Implementation phase

Macquarie will enable the DEFT API service in production and issue a production username and password to be
imbedded in all API request messages for the Biller.
The live web service URI is located at:
https://www.deft.com.au/interface/api/dts.asmx
Following implementation by the web developer it is strongly recommended that a low value test transaction is
conducted using the Biller’s account number. Macquarie can refund the transaction back to the cardholder on
request.
10
Page 16 of 49
Contact Details
For all issues related to integration with the DEFT API, please contact Macquarie Bank at
Email – softwareintegrations@macquarie.com
Page 17 of 49
11 Appendices
11.1 Appendix 1 - DRN validation
11.1.1 Mod 10 – Check Digit validation
Used for account number validation (9 digit and 6 digit) and customer reference number (insurance only)
validation
Example 1 – account number validation
The following example illustrates how the account number 300567898 should be validated using the modulus 10
version 1 check digit routine.
● Weights follow a 1, 2, 1, 2 ,1, 2, 1, 2 pattern.
● Weights are to be assigned from right to left.
● If a digit multiplied by its weighting produces a value greater than 9, sum the digits (or subtract 9).
● The modulus is 10.
● If the check digit verification routine results in a two digit number (namely 10), only the second digit (zero)
will be returned.
Step 1 Step 2
Digit x Weight Values Sum of digits
3 x 1 3 3
0 x 2 0 0
0 x 1 0 0
5 x 2 10 1
6 x 1 6 6
7 x 2 14 5
8 x 1 8 8
9 x 2 18 9
32
Step 3 Calculate the remainder when divided by 10
32 ÷ 10 = 3 with remainder of 2
Step 4 Subtract remainder from 10 to obtain the check digit
10 - 2 = 8
Therefore, the account number 300567898 is valid.
Example 2 – DEFT Biller Code validation

The following example illustrates how the DEFT Biller Code 400424 should be validated using the modulus 10
version 1 check digit routine.
● Weights follow a 1, 2, 1, 2 ,1, 2, 1, 2 pattern.
Page 18 of 49
● If a digit multiplied by its weighting produces a value greater than nine, sum the digits (or subtract nine).
● If the check digit verification routine results in a two digit number (namely 10), only the second digit (zero)
will be returned.
Step 1 Step 2
Digit x Weight Values Sum of digits
4 x 2 8 8
0 x 1 0 0
0 x 2 0 0
4 x 1 4 4
2 x 2 4 4
16
Step 3 Calculate the remainder when divided by 10
10 - 6 = 4
Therefore, the DEFT Biller Code 400424 is valid.
11.1.2 Mod 9 – Check digit validation

Used for customer reference number (sectors other than Insurance Broking) validation
Reference numbers can contain up to 11 digits including the check digit.

The following illustrates how the check digit for the reference number 67421 should be calculated.
● Weights follow a 5, 3, 2, 1, 13, 11, 7, 5, 3, 2 pattern.
● The check digit will be a number from 1 to 9 inclusive. A check digit of 0 is not possible.
Step 1 Calculate the sum of the products of the weights and digits.
Weights 11 7 5 3 2
x x x x x
Digits 6 7 4 2 1
66 49 20 6 2
Sum of products 143
Page 19 of 49
Step 2 Calculate the remainder when divided by 9.
9 - 8 = 1
Therefore, the reference number including the check digit is 674211.
11.2
Page 20 of 49
Appendix 2 – DEFT API request and response message formats
and samples
The Secure Remote API web service employs the following business logic for the processing of online transactions:
● A remote application connects and authenticates with the IP Payments’ server
● The transaction data is parsed to the API with a number of parameters
● The API responds with result data to the remote application
● Transactional data is logged to the IP Payments database
The above process occurs within the single API call.
Please allow up to 35 seconds for the transaction result before timing out.
Using another API call, it is possible to query the status of a transaction at any time. It is recommended that the
transaction status is queried before resubmitting a request that timed out before the result was received.
Note that XML tags within each API parameter are case sensitive.
11.2.1 Submit Single (One off) payment

The following list provides an overview of available transaction elements, all of which are logged to the database:
SubmitSinglePayment – XML Element Description

MAX MANDATORY
XML ELEMENT FORMAT SAMPLE DESCRIPTION
SIZE / OPTIONAL
Biller identifier (account number).
Transaction/AccountNumber 9 Numeric 123456789 M 6 digits for Insurance Broking
clients, 9 digits for all others
Biller assigned unique customer
reference number. Minimum
length 3 digits, maximum 10
digits. A check digit should NOT
be added to this.
Transaction/CustNumber 10 Numeric 12345678 M
The receipting software may also
have specifications for this
number, so it is advised that they
are consulted over their
requirements.
Transactional reference. This
reference can be used to identify
a transaction by a reference
Alpha Invoice123 assigned by the Payer. If this
Transaction/CustRef 32 M
Numeric 4 information is not captured by the
website, a generic reference (eg,
the Biller’s name) can be added
when the message is created.
Payment amount entered as an
Transaction/Amount 10 Numeric 5500 M
integer eg. $55.00 = 5500
The transaction type. Should be
Transaction/TrnType 2 Numeric 1 O set to ‘1’ for credit card
transactions (Default)
XML Node Only. This node has one attribute, ‘Registered’ which should be set to
Transaction/CreditCard
‘False’.
Page 21 of 49
Transaction/CreditCard/Card 400555000000
16 Numeric M Customer credit card number
Number 0001
Expiry month of customer credit
Transaction/CreditCard/ExpM 2 Numeric 05 M
card
Expiry year of customer credit
Transaction/CreditCard/ExpY 4 Numeric 2013 M
card
Transaction/CreditCard/Card Alpha
32 John Smith O Name as it appears on credit card
HolderName Numeric
CVN (Security Code) of the
customer credit card.
Note this field should be
converted to a string numeric (ie,
not an integer numeric) to ensure
that leading zeros and not
omitted from the number.
Transaction/CreditCard/CVN 4 Numeric 123 O This field should only be Optional
for MOTO transactions, such as
where the credit card details have
been entered onto a payment
form and are being entered by a
3rd party. If the payment is being
entered directly by the Payer, the
CVN field should be entered.
Transaction/Security/UserNa Alpha Pre-allocated Merchant API user
32 Username M
me Numeric name
Transaction/Security/Passwor Alpha Pre-allocated Merchant API
16 Password M
d Numeric password
Example XML for Single (One off) Credit Card Payment
<Transaction>
<AccountNumber>123456789</AccountNumber>
<CustNumber>12345678</CustNumber>
<CustRef>123456</CustRef>
<Amount>5500</Amount>
<TrnType>1</TrnType>
<CreditCard Registered=”False”>
<CardNumber>4005550000000001</CardNumber>
<ExpM>05</ExpM>
<ExpY>2013</ExpY>
<CVN>123</CVN>
<CardHolderName>John Smith</CardHolderName>
</CreditCard>
<Security>
<UserName>username</UserName>
<Password>password</Password> </Security>
</Transaction>

Example XML for Single (One off) Credit Card Payment (Non .Net)
If you are not using the .Net web service proxy method of sending the transaction
request to IP Payments, then you may need to instruct the server not to parse the
transaction XML.
Page 22 of 49
This is achieved through use of the CDATA tag as shown in the below example – the
entries are highlighted in bold red text.
Please note that the above will be valid for all other API functions throughout this
document.
<![CDATA[
<Transaction>
<ExpM>05</ExpM>
<ExpY>2013</ExpY>
<CVN>123</CVN>
</CreditCard>
<Security>
<Password>password</Password>
</Security>
</Transaction>
]]>
11.2.2 Submit Single (One off) Payment XML Response
The following list provides an overview of available response elements.
SubmitSinglePayment Response – XML Element Description

0 = Approved
Response/ResponseCode Numeric 0
1 = Not Approved
23-Sep-20 Timestamp is the date and time that IP Payments
Alpha
Response/Timestamp 11 has received the transaction request. The format is
Numeric
15:33:25 dd-MMM-yyyyhh:mm:ss
Alpha Invoice123 Receipt is a unique reference for this transaction
Response/Receipt
Numeric 4 issued by IP Payments
SettlementDate is the date on which approved funds
Alpha 23-Sep-20
Response/SettlementDate are settled by the acquiring bank/financial institution.
Numeric 11
The format is dd-MMM-yyyy
DeclinedCode value is present only when
ResponseCode is 1. Please see the declined code
Response/DeclinedCode Numeric 5
list for all possible values.
DeclinedMessage value is present only when

Alpha Do Not ResponseCode is 1. This contains a textual
Response/DeclinedMessage
Numeric Honour description of the declined code.
Example SubmitSinglePayment XML Response
Page 23 of 49
<Response>
<ResponseCode>0</ResponseCode>
<Timestamp>2005-02-24 21:18:47</Timestamp>
<Receipt>10001197</Receipt>
<SettlementDate>2005-02-23</SettlementDate>
<DeclinedCode></DeclinedCode>
<DeclinedMessage></DeclinedMessage>
</Response>
11.2.3
Page 24 of 49
Submit Pre-Auth
It is recommended that a pre-auth transaction is used in conjunction with accepting scheduled payments. Without a
pre-auth, the credit card used in a scheduled payment will not be verified until the payment is due. Pre-auths allow
the card to be verified at the time of entry, which in turn enables the Payer to adjust the card details if the pre-auth is
rejected. It is recommended that a low value pre-auth (eg $1.00) is conducted only on the first time a particular card
is used for a scheduled payment. The pre-auth payment amount will be ‘held’ and deducted from the Payer’s credit
limit but the funds will not be transferred to the Biller. The hold will ‘fall off’ after approximately 5 days (depending
on the issuing bank) and the available funds will be returned to the card.
The following list provides an overview of available transaction elements, all of which are logged to the database:
SubmitSinglePayment – XML Element Description

MAX MANDATORY
SIZE / OPTIONAL
Biller identifier (account number).
Transaction/AccountNumber 9 Numeric 123456789 M 6 digits for Insurance Broking
Transaction/CustNumber 10 Numeric 12345678 M length 3 digits, maximum 10
digits. A check digit should NOT
be added to this.
Transactional reference. This
reference can be used to identify
a transaction by a reference
Alpha Invoice123 assigned by the Payer. If this
Transaction/CustRef 32 M
Numeric 4 information is not captured by the
website, a generic reference (eg,
the Biller’s name) can be added
when the message is created.
Payment amount entered as an
integer eg. $55.00 = 5500
Transaction/TrnType 2 Numeric 2 M set to ‘2’ for credit card Pre-Auth
transaction.
Transaction/CreditCard
‘False’.
Transaction/CreditCard/Card 400555000000
16 Numeric M Customer credit card number
Number 0001
Expiry month of customer credit
Transaction/CreditCard/ExpM 2 Numeric 05 M
card
Expiry year of customer credit
Transaction/CreditCard/ExpY 4 Numeric 2013 M
card
Transaction/CreditCard/Card Alpha
32 John Smith O Name as it appears on credit card
HolderName Numeric
converted to a string numeric (ie,
not an integer numeric) to ensure
Transaction/CreditCard/CVN 4 Numeric 123 O
that leading zeros and not
omitted from the number.
This field should only be Optional
for MOTO transactions, such as
where the credit card details have
Page 25 of 49
been entered onto a payment
form and are being entered by a
3rd party. If the payment is being
entered directly by the Payer, the
CVN field should be entered.
Transaction/Security/UserNa Alpha Pre-allocated Merchant API user
32 Username M
me Numeric name
Transaction/Security/Passwor Alpha Pre-allocated Merchant API
16 Password M
d Numeric password
Example XML for Pre-Auth
<Transaction>
<ExpM>05</ExpM>
<ExpY>2013</ExpY>
<CVN>123</CVN>
</CreditCard>
<Security>
<Password>password</Password> </Security>
</Transaction>
11.2.4 Submit Pre-Auth XML Response
SubmitSinglePayment Response – XML Element Description

0 = Approved
1 = Not Approved
23-Sep-20 Timestamp is the date and time that IP Payments
Alpha
Response/Timestamp 11 has received the transaction request. The format is
Numeric
15:33:25 dd-MMM-yyyyhh:mm:ss
Alpha Invoice123 Receipt is a unique reference for this transaction
Response/Receipt
Numeric 4 issued by IP Payments
SettlementDate is the date on which approved funds
Alpha 23-Sep-20
Response/SettlementDate are settled by the acquiring bank/financial institution.
Numeric 11
The format is dd-MMM-yyyy
ResponseCode is 1. Please see the declined code
list for all possible values.

Alpha Do Not
Response/DeclinedMessage ResponseCode is 1. This contains a textual
Numeric Honour
description of the declined code.
Page 26 of 49
Example Pre-Auth Response
<Response>
</Response>
Page 27 of 49
11.2.5 Submit Payment Schedule
The below list provides an overview of available transaction elements to submit a payment schedule, all of which
are logged to the IP Payments database.
* Note that the Card Expiry Month and Year fields are optional. If these details are not included in the API
message, the payment schedule will continue to process beyond the expiry date of the card. However, this is
currently only the case for payments on Visa and Mastercard. Amex and Diners club require the expiry date on all
transactions and therefore scheduled payments using these schemes will be rejected if the expiry date is not
submitted. It is recommended that the front-end interface validates this accordingly.
SubmitPaymentSchedule – XML Element Description

MAX MANDATORY
SIZE / OPTIONAL
Biller identifier (account
Schedule/AccountNu 1234567 number).
9 Numeric M
mber 89 6 digits for Insurance Broking
Schedule/CustNumbe 1234567
10 Numeric M length 3 digits, maximum 10
r 8
digits. A check digit should
NOT be added to this.
Amount entered as an integer
Schedule/Amount 10 Numeric 5500 M
eg. $55.00 = 5500
Schedule/TrnType 2 Numeric 1 M set to ‘1’ for credit card
transactions
Schedule/CreditCard
‘False’.
4005550
Schedule/CreditCard/
16 Numeric 0000000 M Customer credit card number
CardNumber
01
Schedule/CreditCard/ Expiry month of customer credit
2 Numeric 05 O*
ExpM card
Schedule/CreditCard/ Expiry year of customer credit
4 Numeric 2013 O*
ExpY card
Schedule/CreditCard/ Alpha John Name as it appears on credit
32 O
CardHolderName Numeric Smith card
converted to a string numeric
(ie, not an integer numeric) to
ensure that leading zeros and
not omitted from the number.
Schedule/CreditCard/
4 Numeric 123 O This field should only be
CVN
Optional for MOTO
transactions, such as where the
credit card details have been
entered onto a payment form
and are being entered by a 3rd
party. If the payment is being
entered directly by the Payer,
Page 28 of 49
the CVN field should be
entered.
The frequency of the schedule.
One of:
S - Single Payment
Alpha W - Weekly
Schedule/Frequency 1 S M
Numeric F – Fortnightly
M – Monthly
Q – Quarterly
A – Annually
The start date of the schedule.
The first payment will be
Alpha 2011-09- processed on this date. For
Schedule/StartDate 10 M
Numeric 23 single payments this is the date
of the single payment. Format
yyyy-MM-dd
If present, no payments will be
made on or after this date.
Format yyyy-MM-dd
Alpha 2011-09-
Schedule/EndDate 10 O Not applicable for Single
Numeric 23
payments. (If this field is left
blank the payment will continue
until cancelled)
If this parameter is present, no
payments will be made once
the number of payments
Schedule/EndPayme submitted (inclusive of declined
6 Numeric 12 O
ntCount payments) is superior to the
parameter value.
For a single payment, this value
should be set to ‘1’
If the recurring amount is to
change in the future, then any
recurring payments processed
on or after this date will use the
NewAmount. If this value is
Schedule/NewAmoun Alpha 2012-01- present then NewAmount is
10 O
tDate Numeric 23 mandatory. If
Schedule/NewAmount is
non-zero,
Schedule/NewAmountDate
needs to be populated. Format
yyyy-MM-dd
If the recurring amount is to
change in the future, then any
recurring payments processed
on or after the NewAmountDate
Schedule/NewAmoun
10 Numeric 5800 O will use this NewAmount. If this
t
value is present then
NewAmountDate is mandatory.
Amount entered as an integer
eg. $55.00 = 5500
Schedule/Security/Us Alpha Usernam Pre-allocated Merchant API
32 M
erName Numeric e user name
Schedule/Security/Pa Alpha Passwor Pre-allocated Merchant API
16 M
ssword Numeric d password
:
Page 29 of 49
Example XML for Credit Card Payment Schedule – Single payment
<Schedule>
<ExpM>05</ExpM>
<ExpY>2013</ExpY>
<CVN>123</CVN>
</CreditCard>
<Schedule>
<Frequency>S</Frequency>
<StartDate>2011-12-01</StartDate>
</Schedule>
<Security>
</Security>
</Schedule>
Example XML for Credit Card Payment Schedule – Fortnightly with 24 payments
<Schedule>
<ExpM>05</ExpM>
<ExpY>2013</ExpY>
<CVN>123</CVN>
</CreditCard>
<Schedule>
<Frequency>F</Frequency>
<EndPaymentCount>24</EndPaymentCount>
</Schedule>
<Security>
</Security>
</Schedule>
Example XML for Credit Card Payment Schedule – Monthly, ending after a
specific date
<Schedule>
Page 30 of 49
<ExpM>05</ExpM>
<ExpY>2013</ExpY>
<CVN>123</CVN>
</CreditCard>
<Schedule>
<Frequency>M</Frequency>
<EndPaymentDate>2013-12-01</EndPaymentDate>
</Schedule>
<Security>
</Security>
</Schedule>
Example XML for Credit Card Payment Schedule – Monthly, with 12 payments
and changing amount after 6 months
<Schedule>
<ExpM>05</ExpM>
<ExpY>2013</ExpY>
<CVN>123</CVN>
</CreditCard>
<Schedule>
<EndPaymentCount>12</EndPaymentCount>
<NewAmountDate>2012-05-01</NewAmountDate>
<NewAmount>6500</NewAmount>
</Schedule>
<Security>
</Security>
</Schedule>
11.2.6 Submit Payment Schedule XML Response
SubmitPaymentSchedule Response – XML Element Description
Page 31 of 49
0 = Accepted
1 = Not Accepted
Alpha This uniquely identifies the schedule within IPP. Will
Response/ScheduleIdentifier 00005689
Numeric only be present if ResponseCode is 0
ResponseCode is 1.
Possible values are:

1 - Invalid username/password
2 - Invalid schedule data
99 - Exception encountered
Invalid DeclinedMessage value is present only when

Alpha
Response/DeclinedMessage schedule ResponseCode is 1. This contains a textual
Numeric
data description of the declined code.
Example SubmitPaymentSchedule XML Response
<Response>
<ScheduleIdentifier>00005689</ScheduleIdentifier>
</Response>
Example SubmitPaymentSchedule XML Response – invalid data
<Response>
<ScheduleIdentifier></ScheduleIdentifier>
<DeclinedCode>2</DeclinedCode>
<DeclinedMessage>Invalid Schedule data</DeclinedMessage>
</Response>
11.2.7
Page 32 of 49
Query Payment Schedules
The following list provides an overview of available elements to query payment schedules.
QueryPaymentSchedules – XML Element Description

MAX MANDATORY
SIZE / OPTIONAL
Biller identifier
(account number).
QuerySchedules/Account 6 digits for
9 Numeric 123456789 M
Number Insurance Broking
clients, 9 digits for
all others
Biller assigned
unique customer
reference number.
QuerySchedules/CustNu Minimum length 3
10 Numeric 12345678 M
mber digits, maximum
10 digits. A check
digit should NOT
be added to this.
Pre-allocated
QuerySchedules/Security/
32 Alpha Numeric Username M Merchant API user
UserName
name
Pre-allocated
QuerySchedules/Security/
16 Alpha Numeric Password M Merchant API
Password
password
Example XML for QueryPaymentSchedules

<QuerySchedules>
<Security>
</Security>
</QuerySchedules>
11.2.8 Query Payment Schedules XML Response

QueryPaymentSchedules Response – XML Element Description

XML Root Node Only. This node has two attributes:
‘MatchingCount’ - the number of active payment schedules found.

This count will determine how many ‘QueryResponse/Schedule’
elements there are – one for each active schedule.
QueryResponse
‘Error’ – will contain one of the following values:
0 - Schedules retrieved successfully

Page 33 of 49
This uniquely identifies the schedule

QueryResponse/Schedule/Identifier Alpha Numeric 00004568
within IPP.
2011-10-2
QueryResponse/Schedule/DateAdded Alpha Numeric
3
The frequency of the schedule. One
of:
S - Single Payment
W - Weekly
QueryResponse/Schedule/Frequency Alpha Numeric F
F – Fortnightly
M – Monthly
Q – Quarterly
A - Annually
2012-01-1 The start date of the schedule
QueryResponse/Schedule/StartDate Alpha Numeric
2 Format yyyy-MM-dd
End date of schedule. Format
2012-12-1 yyyy-MM-dd
QueryResponse/Schedule/EndDate Alpha Numeric
2 Not applicable for Single payments.
Can be blank.
The maximum number of payments
QueryResponse/Schedule/EndPaymentCo that will be processed for this
Numeric 12
unt schedule. Not applicable for Single
payments. Can be blank.
If the recurring amount is to change
in the future, then any recurring
QueryResponse/Schedule/NewAmountDat 2012-06-1 payments processed on or after this
Alpha Numeric
e 2 date will use the NewAmount. If this
value is present then NewAmount will
be present. Format yyyy-MM-dd
If the recurring amount is to change
in the future, then any recurring
payments processed on or after the
NewAmountDate will use this
QueryResponse//Schedule/NewAmount Numeric 6500
NewAmount. If this value is present
then NewAmountDate will be
present. Amount entered as an
integer eg. $55.00 = 5500
QueryResponse/Schedule/CurrentPaymen The number of payments processed
Numeric 2
tCount in this schedule.
QueryResponse/Schedule/NextPaymentD 2011-10-2 The next payment date in this
Alpha Numeric
ate 8 schedule. Format yyyy-MM-dd
Example QueryPaymentSchedules XML Response with two returned schedules
<QueryResponseMatchingCount=”2” Error=”0”>
<Schedule>
<Identifier>00004568</Identifier>
<EndDate>2012-12-12</EndDate>
<EndPaymentCount></EndPaymentCount>
<NewAmountDate></NewAmountDate>
<NewAmount></NewAmount>
<CurrentPaymentCount>0<CurrentPaymentCount>
Page 34 of 49
<NextPaymentDate>2012-01-12<NextPaymentDate>
</Schedule>
<Schedule>
<Frequency>S</Frequency>
<EndDate></EndDate>
<EndPaymentCount></EndPaymentCount>
<NewAmountDate></NewAmountDate>
<NewAmount></NewAmount>
<CurrentPaymentCount>0<CurrentPaymentCount>
<NextPaymentDate>2012-01-12<NextPaymentDate>
</Schedule>
</QueryResponse>
Example QueryPaymentSchedules XML Response with error
<QueryResponseMatchingCount=”0” Error=”99”>
</QueryResponse>
11.2.9
Page 35 of 49
Delete Payment Schedule
The following list provides an overview of available transaction elements to delete a payment schedule.
DeletePaymentSchedule – XML Element Description

MAX MANDATORY
SIZE / OPTIONAL
Biller identifier
(account number).
DeleteSchedule/Account
9 Numeric 123456789 M 6 digits for Insurance
Number
Broking clients, 9 digits
for all others
Biller assigned unique
customer reference
number. Minimum
DeleteSchedule/CustNum
10 Numeric 12345678 M length 3 digits,
ber
maximum 10 digits. A
check digit should
NOT be added to this.
DeleteSchedule/Schedule The unique identifier of
10 Alpha Numeric 00004587 M
/Identifier the schedule to delete.
Pre-allocated
Schedule/Security/UserN
32 Alpha Numeric Username M Merchant API user
ame
name
Pre-allocated
Schedule/Security/Passw
16 Alpha Numeric Password M Merchant API
ord
password
Example XML to Delete Payment Schedule

<DeleteSchedule>
<Schedule>
</Schedule>
<Security>
</Security>
</DeleteSchedule>
11.2.10 Delete Payment Schedule XML Response
DeletePaymentSchedule Response – XML Element Description

0 = Deleted
1 = Not Deleted
Response/DeclinedCode Numeric 2 ResponseCode is 1.
Page 36 of 49
2 - Invalid account number
3 - Invalid customer number
4 - Invalid schedule Identifier
Invalid DeclinedMessage value is present only

Alpha
Response/DeclinedMessage schedule when ResponseCode is 1. This contains a
Numeric
identifier textual description of the declined code.
Example Delete Payment Schedule XML Response
<Response>
</Response>
11.2.11 Query Surcharge

The following list provides an overview of available transaction elements to request the surcharge that would be
applicable for a payment.
QuerySurcharge – XML Element Description

MAX MANDATORY
SIZE / OPTIONAL
Biller identifier
(account
number).
QuerySurcharge/Accou 6 digits for
9 Numeric 123456789 M
ntNumber Insurance
Broking clients,
9 digits for all
others
Biller assigned
unique
customer
reference
number.
QuerySurcharge/CustN Minimum
10 Numeric 12345678 O
umber length 3 digits,
maximum 10
digits. A check
digit should
NOT be added
to this.
Amount
QuerySurcharge/Amou entered as an
10 Numeric 5500 O
nt integer eg.
$55.00 = 5500
Customer
QuerySurcharge/Credit 400555000
16 Numeric M credit card
Card/CardNumber 0000001
number
Page 37 of 49
Pre-allocated
QuerySurcharge/Securi Alpha
32 Username M Merchant API
ty/UserName Numeric
user name
Pre-allocated
QuerySurcharge/Securi Alpha
16 Password M Merchant API
ty/Password Numeric
password
Example XML to Query Surcharge

<QuerySurcharge>
<Amount>5500</ Amount >
<CreditCard>
<CardNumber>4005550000000001</ CardNumber>
</ CreditCard>
<Security>
</Security>
</ QuerySurcharge>
11.2.12 Query Surcharge XML Response
QuerySurcharge Response – XML Element Description

FORMA
XML ELEMENT SAMPLE DESCRIPTION
T
0 = Surcharge retrieved successfully.
1 = Error retrieving surcharge.
The card type supplied. One of:
- Visa
Alpha
Response/CardType 12 - MasterCard
Numeric
- Amex
- Diners
Response/SurchargeAmount Numeric 125 The amount of the surcharge in cents
The percentage value of the surcharge that
Response/SurchargePercentage Decimal 1.254 applies to the amount supplied. Values to 3
decimal places.
The amount of the surcharge in cents –
Response/SurchargeFixed Numeric 0
fixed component. 0 if not applicable
ResponseCode is 1.
2 - Invalid account number
3 - Invalid amount
4 - Invalid card number
5 – Card type not accepted
Page 38 of 49
The decline code 2 may occur if :
● AccountNumber does not exist, or
● AccountNumber does not match the
biller where the API user is.
Invalid DeclinedMessage value is present only
Alpha
Response/DeclinedMessage username/passwor when ResponseCode is 1. This contains a
Numeric
d textual description of the declined code.
Example Query Surcharge XML Response – with surcharge

<Response>
<CardType>Visa</CardType>
<SurchargeAmount>125</SurchargeAmount>
<SurchargePercentage>1.254</SurchargePercentage>
<SurchargeFixed>0</SurchargeFixed>
</Response>
Example Query Surcharge XML Response – without surcharge
<Response>
<CardType>Visa</CardType>
<SurchargeAmount>0</SurchargeAmount>
<SurchargePercentage>0</SurchargePercentage>
<SurchargeFixed>0</SurchargeFixed>
</Response>
11.2.13 Query Transaction

IP Payments allow merchants to query the status of a transaction at any time, this API call is useful when the initial
transaction request timed out and the merchant is unaware of the transaction status. Multiple matches can be
returned. The following list provides an overview of available query transaction elements:
QueryTransaction – XML Element Description

MAX MANDATORY
ELEMENT NAME FORMAT SAMPLE DESCRIPTION
SIZE / OPTIONAL
Biller identifier
(account number).
QueryTransaction/Criteria/Ac 6 digits for
9 Numeric 123456789 M
countNumber Insurance Broking
clients, 9 digits for
all others
Biller assigned
unique customer
reference number.
QueryTransaction/Criteria/Cu Minimum length 3
10 Numeric 12345678 M
stNumber digits, maximum 10
digits. A check digit
should NOT be
added to this.
Page 39 of 49
Payment amount
entered as an
integer eg. $55.00
= 5500
The start date/time
for the transaction
QueryTransaction/Criteria/Trn Alpha 2005-01-01
19 M search. Format
StartTimestamp Numeric 00:00:01
yyyy-mm-ddhh:mm:
ss
The end date/time
for the transaction
QueryTransaction/Criteria/Trn Alpha 2005-01-01
19 M search. Format
EndTimestamp Numeric 23:59:59
yyyy-mm-ddhh:mm:
ss
Pre-allocated
QueryTransaction/Security/U Alpha
32 Username M Merchant API user
serName Numeric
name
Pre-allocated
QueryTransaction/Security/P Alpha
16 Password M Merchant API
assword Numeric
password
Example XML Query Transaction

<QueryTransaction>
<Criteria>
< AccountNumber>123456789</AccountNumber >
<TrnStartTimestamp>2005-02-23 00:00:00</TrnStartTimestamp>
<TrnEndTimestamp>2005-02-24 23:59:59</TrnEndTimestamp>
</Criteria>
<Security>
</Security>
</QueryTransaction>
11.2.14 Query Transaction XML Response
QueryTransaction Response – XML Element Description

XML Root Node Only. This node has three attributes:
‘MatchingCount’ - the number of active payment schedules found. This count will
determine how many ‘QueryResponse/Response’ elements there are – one for
each returned transaction.
‘MatchingReturned’ – This is the number of matches actually returned – with a

QueryResponse
maximum of 1000.
‘Error’ – will contain one of the following values:
0 - Transactions retrieved successfully

Page 40 of 49
QueryResponse/Respon 0 = Approved
Numeric 0
se/ResponseCode 1 = Not Approved
Timestamp is the date and time that IP Payments
QueryResponse/Respon Alpha 23-Sep-2011 has received the transaction request. The format
se/Timestamp Numeric 15:33:25 is dd-MMM-yyyyhh:mm:ss
Receipt is a unique reference for this transaction

QueryResponse/Respon Alpha
Invoice1234 issued by IP Payments
se/Receipt Numeric
SettlementDate is the date on which approved
QueryResponse/Respon Alpha funds are settled by the acquiring bank/financial
23-Sep-2011
se/SettlementDate Numeric institution. The format is dd-MMM-yyyy

QueryResponse/Respon ResponseCode is 1. Please see the declined code
Numeric 5
se/DeclinedCode list for all possible values.

QueryResponse/Schedul Alpha ResponseCode is 1. This contains a textual
Do Not Honour
e/DeclinedMessage Numeric description of the declined code.
Example Query Transaction XML Response

<QueryResponseMatchingCount="2" MatchingReturned=”2” Error="0">
<Response>
</Response>
<Response>
</Response>
</QueryResponse>
11.3
Page 41 of 49
Appendix 3 – Declined Codes
The following table presents the potential declined codes that may be presented in a declined transaction result:
Code Response Text

100 System Exception
102 Invalid account identifier
103 Invalid API username or password
104 Invalid transaction type identifier
107 Invalid transaction amount
108 No customer identifier supplied
109 No customer reference supplied
110 Invalid credit card number
111 Invalid credit card expiry date
118 Invalid customer identifier
119 Customer status not active
120 Account status not active
124 CVN required but not supplied
152 Account not set up to accept credit card transactions for the supplied credit card type
153 Account not set up to accept credit card transactions for the supplied amount
154 Merchant account details not set up correctly
180 Exception encountered when retrieving the receipt number
181 Exception encountered when receiving transaction data from client
182 Exception encountered when creating transaction XML log
183 Exception parsing transaction XML
184 Exception validating transaction XML
190 Exception encountered when finding transaction identifier
191 Exception encountered when finding credit card interface to use
192 Exception encountered when submitting transaction to interface
200 Interface error
201 Interface Error with successful automatic reversal
998 Transaction Payment Cancelled
999 Timeout when waiting for a response
11.4
Page 42 of 49
Appendix 4 - Mapping between the previous version of the DEFT API
(hosted by Securepay) and the new DEFT API (hosted by IP Payments)
error codes
The following table presents the equivalent IP Payments decline codes to the Securepay decline codes:
Securepay IP Payments
Comments
Code Equivalent
00-99 00-99 AS2805 Standard
-1 NA Not used as IPP only use a single value for the 'DeclinedCode'
501 111 Invalid credit card number
503 118 Invalid customer identifier
504 102 Invalid account identifier
505 NA Not applicable
Account not set up to accept credit card transactions for the supplied credit card
506 152
type
IPP will not require security code for API payments - an API
509 NA
username/password is used for authentication of the Biller
510 100 System Exception
511 192 Exception encountered when submitting transaction to interface
512 999 Timeout when waiting for a response
516 104 Invalid transaction type identifier
517 183 Exception parsing transaction XML
528 NA Not applicable to IP Payments
Page 43 of 49
ank Response Codes
11.5 Appendix 5 – B
11.5.1 Responses based on payment amount
During testing, the following responses will be returned based on the amount of cents in the final payment (ie,
including surcharge) amount (between $1.01 and $1.99).
Cents Response Text Cents Response Text

APPROVED
00 Approved 08 Honour with ID
11 Approved VIP (not used) 16 Approved, Update Track 3 (not used)
77 Approved (ANZ only)
DECLINED
01 Refer to Card Issuer 41 Lost Card—Pick Up
02 Refer to Issuer’s Special Conditions 42 No Universal Amount
03 Invalid Merchant 43 Stolen Card—Pick Up
04 Pick Up Card 44 No Investment Account
05 Do Not Honour 51 Insufficient Funds
06 Error 52 No Cheque Account
07 Pick Up Card, Special Conditions 53 No Savings Account
09 Request in Progress 54 Expired Card
10 Partial Amount Approved 55 Incorrect PIN
12 Invalid Transaction 56 No Card Record
13 Invalid Amount 57 Trans. not Permitted to Cardholder
14 Invalid Card Number 58 Transaction not Permitted to Terminal
15 No Such Issuer 59 Suspected Fraud
17 Customer Cancellation 60 Card Acceptor Contact Acquirer
18 Customer Dispute 61 Exceeds Withdrawal Amount Limits
19 Re-enter Transaction 62 Restricted Card
20 Invalid Response 63 Security Violation
21 No Action Taken 64 Original Amount Incorrect
22 Suspected Malfunction 65 Exceeds Withdrawal Frequency Limit
23 Unacceptable Transaction Fee 66 Card Acceptor Call Acquirer Security
24 File Update not Supported by 67 Hard Capture—Pick Up Card at ATM
Receiver
25 Unable to Locate Record on File 68 Response Received Too Late
26 Duplicate File Update Record 75 Allowable PIN Tries Exceeded
27 File Update Field Edit Error 86 ATM Malfunction
28 File Update File Locked Out 87 No Envelope Inserted
29 File Update not Successful 88 Unable to Dispense
30 Format Error 89 Administration Error
31 Bank not Supported by Switch 90 Cut-off in Progress
32 Completed Partially 91 Issuer or Switch is Inoperative
33 Expired Card—Pick Up 92 Financial Institution not Found
34 Suspected Fraud—Pick Up 93 Trans Cannot be Completed
35 Contact Acquirer—Pick Up 94 Duplicate Transmission
36 Restricted Card—Pick Up 95 Reconcile Error
37 Call Acquirer Security—Pick Up 96 System Malfunction
38 Allowable PIN Tries Exceeded 97 Reconciliation Totals Reset
39 No CREDIT Account 98 MAC Error
40 Requested Function not Supported 99 Reserved for National Use
Page 44 of 49
11.5.2 Decline codes base on credit card number
The following card number will generate specific declined responses regardless of the payment amount entered.
Card Type Card number Decline Code

Visa 4123 4561 2345 6111 01 – Refer Card Issuer
Visa 4123 4561 2345 6129 04 – Pick Up Card
Visa 4123 4561 2345 6137 12 – Invalid Transaction
Visa 4123 4561 2345 6145 31 – Acquirer Not Supported by Switch
Visa 4123 4561 2345 6152 33 – Invalid Expiry Date
Visa 4123 4561 2345 6160 39 – No Credit Account
Visa 4123 4561 2345 6178 51 – Insufficient Funds
Visa 4123 4561 2345 6186 91 – Card Issuer Unavailable
Visa 4123 4561 2345 6194 96 – System Malfunction
MasterCard 5123 4561 2345 6118 01 – Refer Card Issuer
Amex 3412 3456 1234 561 01 – Refer Card Issuer
Diners 3676 5432 101 232 01 – Refer Card Issuer
11.6
Page 45 of 49
Appendix 6 - Location of Card Verification Number (CVN)
The CVN is an anti-fraud measure used by card issuers to prevent payments from generated card numbers. The
CVN is printed on the physical card, and is randomly assigned and therefore it cannot be auto-generated.
The CVN can be found in the following places:
Card Type Location

Visa Signature strip on back of card. Last digits of card number are
re-printed in reverse italics, followed by 3-digit CVN.
MasterCard Signature strip on back of card. Last digits of card number are
Amex 4 digit CVN above card number on front of card.
Diners Club Signature strip on back of card. Last digits of card number are
11.7
Page 46 of 49
Appendix 7 - DEFT E-Commerce Checklist
This checklist is designed to ensure you have the below requirements in place.
The following items have been identified as fundamental to managing e-Commerce risk. These items may need to
be discussed and implemented by your web designer/service provider.
Complete and return with the DEFT Payment Systems Agency terms and conditions (Agency T&Cs). Any
defined terms in this Checklist have the same meaning as given to them in the Agency T&Cs.
Confirm the following have been implemented:
Requirement Client Response (please tick or

cross)
Website is protected with digital certificate issued by a
Trusted Provider? e.g. SSL certificate via Verizon or
Equifax.
Website is secure i.e. HTTPS?
Mandatory CVN, CVC, CVC2 when accepting credit
card payments?
Payment Screen time-out mechanism?
Payment screen/details clear when refreshed,
timed-out or transaction approved/declined?
Edit and validate required data fields in real-time?
Have current vulnerability assessments and PCI
scanning been performed?
By signing below:
1. I acknowledge that:
(a) If I do not give all information requested, Macquarie may not be able to provide DEFT to or as requested by me.
(b) Macquarie is under no obligation to commence supplying DEFT until Macquarie, in its absolute discretion,
determines I have met the standards stipulated by Macquarie.
2. I represent and warrant that:
(a) All information given in this DEFT E-Commerce Checklist, together with any statements made, are true and
correct; and
(b) I have the power to bind the Customer.
For Companies, two Directors, or a Director and a Company Secretary, must sign.
For Partnerships, two Partners must sign.
Date:
Authorised Signatory Authorised Signatory
Full Name Full Name
Title Title
Page 47 of 49
11.8
Page 48 of 49
Appendix 8 - Abbreviations, acronyms and definitions
Term Definition
API Application Programming Interface. Middleware messaging interface that enables
Billers to embed DEFT functionality into their own website in order to take DEFT
payments securely
BECS Bulk Electronic Clearing System
Biller The organisation who receives the payment from the Payer, ie a client of Macquarie
Bank
BMS Business Management Software
Chargeback Reversal of a credit card transaction by the schemes on request from the Payer.
CVN Credit Card Verification Number. It is an anti-fraud measure used by card issuers to
prevent payments from generated card numbers
DEFT DEFT Payment Systems is a Macquarie Bank product, which offers a flexible
service for the collection of customer account payments
DRN DEFT Reference Number
MBL Macquarie Bank Limited
PAY file Electronic file containing all DEFT transactions for the previous business day. The
file can be downloaded from Macquarie’s internet banking platform (Active
Banking). Further detail can be found in the DEFT File Format Specifications
document.
Payer The customer of the Biller who is paying an account due.
PCI - DSS Payment and Card Industry – Data Security Standard
SOAP Simple Object Access Protocol, is a protocol specification for exchanging structured
information in the implementation of Web Services. It relies on Extensible Markup
Language (XML) for its message format, and usually relies on other Application
Layer protocols, most notably Hypertext Transfer Protocol (HTTP) and Simple Mail
Transfer Protocol (SMTP), for message negotiation and transmission.
TXN file Electronic file containing all DEFT transactions for the previous business day. The
file can be downloaded from Macquarie’s internet banking platform (Active
Banking). Further detail can be found in the DEFT File Format Specifications
document.
WSDL Web Services Description Language. An XML-based language that is used for
describing the functionality offered by a Web service. A WSDL description of a web
service provides a machine-readable description of how the service can be called,
what parameters it expects and what data structures it returns.
XML Extensible Markup Language – a set of rules for encoding documents in
machine-readable form.
Page 49 of 49

TranslatorDEFT API Integration Guide - v1.7 PDF

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

TranslatorDEFT API Integration Guide - v1.7 PDF

Hochgeladen von

Copyright:

Verfügbare Formate

INTEGRATION GUIDE FOR DEFT BILLERS AND WEB

2 PURPOSE OF THE DOCUMENT 4

3 OVERVIEW OF THE DEFT API 5

7.1 SINGLE (ONE-OFF) PAYMENT 7

8 HIGH-LEVEL SOFTWARE REQUIREMENTS 8

8.1 TECHNICAL REQUIREMENTS 8

9 THE INTEGRATION PROCESS 13

9.1 DISCOVERY PHASE 13

11.1 APPENDIX 1 - DRN VALIDATION 17

2 Purpose of the document

Business day cut-off times:

● American Express and Diners Club 7.00pm (AEST)

● Mastercard and Visa 9.30pm (AEST)

The test web service URI is located at:

The live web service URI is located at:

7.1 Single (one-off) Payment

7.3 Scheduled (recurring or future) Payments

7.4 Query Payment Schedule

7.5 Delete Payment Schedule

7.7 Query Transaction

8.1 Technical requirements

8.1.1 Generating and Validating DRNs

Insurance Broker clients– 6 digits.

Account numbers are provided by Macquarie to the Biller.

Customer reference numbers

Insurance Broking clients– Modulus 10.

DRNs generated at time of payment

DRNs generated before payment (ie, on a Biller’s invoice)

8.1.2 Request and response XML message formats

8.1.3 Receipt and Reconciliation of Payments

8.2 Page Design, Content and Flow

Payment details capture page

Receipt or declined page

This page should display the following information

8.3 Payments Card Industry – Data Security Standard (PCI-DSS) compliance

9.1 Discovery phase

9.2 Initiation phase

9.3 Planning and development phase

9.4 Testing phase

9.4.1 Test environment

The test web service URI is located at:

9.4.2 Test cases

Test cases should cover the following as a minimum requirement

9.4.3 Test data

Username and password

Account number and surcharging

Card Type Card Number Expiry Date CVN (security Code)

9.5 Review phase

9.5.1 Transaction validation and processing

9.5.2 Page design, content and flow

● use of the Macquarie and DEFT Logos

9.5.3 PCI-DSS compliance checks

9.6 Sign off phase

● successful completion of the Macquarie review phase

9.7 Implementation phase

The live web service URI is located at:

Example 1 – account number validation

Digit x Weight Values Sum of digits

Step 3 Calculate the remainder when divided by 10

Step 4 Subtract remainder from 10 to obtain the check digit

Therefore, the account number 300567898 is valid.

Example 2 – DEFT Biller Code validation

Digit x Weight Values Sum of digits