Payment API

Bambora offers the ability to securely and efficiently process online, real-time transactions via an API, our user-friendly interface. The API web service accepts and processes SOAP requests from a remote location over TCP/IP. Transaction results are returned in real-time via the API.

Using Bambora’s API to capture and transmit credit card data will bring your website, development process and internal systems in to scope for PCI-DSS.

Purchase

The following process outlines how you can use Bambora’s API to carry out transaction requests for single payment.

You can test the service by copy and pasting the sample code into a text editor, replacing the API credentials allocated to you and then executing the updated code sample in your server. The most important parameter is the AccountNumber value added to the tag. This identifies your account when communicating with Bambora.

SOAP Method: SubmitSinglePayment

POSThttps://demo.bambora.co.nz/interface/api/dts.asmx

Example 1 - Single credit card payment

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:dts="http://www.ippayments.com.au/interface/api/dts">
<soapenv:Header/>
<soapenv:Body>
<dts:SubmitSinglePayment>
<dts:trnXML>
<![CDATA[
	 <Transaction>
      		<CustNumber>your_custnumber</CustNumber>
      		<CustRef>your_custref</CustRef>
      		<Amount>1000</Amount>
     		<TrnType>1</TrnType>
      		<AccountNumber>your_accountnumber</AccountNumber>
      		<CreditCard Registered="False">
                  	<CardNumber>4242424242424242</CardNumber>
                  	<ExpM>02</ExpM>
                  	<ExpY>2019</ExpY>
                  	<CVN>123</CVN>
                  	<CardHolderName>Test</CardHolderName>
       		</CreditCard>
       		<Security>
                  	<UserName>your_api_username</UserName>
                  	<Password>your_api_password</Password>
       		</Security>
	</Transaction>
]]>    
</dts:trnXML>
</dts:SubmitSinglePayment>
</soapenv:Body>
</soapenv:Envelope>

Example 2 - Single direct debit payment

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:dts="http://www.ippayments.com.au/interface/api/dts">
<soapenv:Header/>
<soapenv:Body>
<dts:SubmitSinglePayment>
<dts:trnXML>
<![CDATA[
	<Transaction>
      		<CustNumber>your_custnumber</CustNumber>
      		<CustRef>your_custref</CustRef>
      		<Amount>1000</Amount>
      		<TrnType>7</TrnType>
      		<AccountNumber>your_accountnumber</AccountNumber>
      		<DirectEntry Registered="False">
                  	<AccNo>098124564</AccNo>
                  	<AccRouting>013259</AccRouting>
                  	<AccTitle>Test</AccTitle>
       		</DirectEntry>
       		<Security>
                  	<UserName>your_api_username</UserName>
                  	<Password>your_api_password</Password>
	       </Security>
	</Transaction>
]]>    
</dts:trnXML>
</dts:SubmitSinglePayment>
</soapenv:Body>
</soapenv:Envelope>

Example 3 - Pre-Auth payment

After the pre-auth has been completed and if you want to proceed with the transaction, then you must send a capture request to notify Bambora to initiate the settlement process. Please see section Capture for details on how to capture the funds reserved by a pre-auth.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:dts="http://www.ippayments.com.au/interface/api/dts">
<soapenv:Header/>
<soapenv:Body>
<dts:SubmitSinglePayment>
<dts:trnXML>
<![CDATA[
	 <Transaction>
      		<CustNumber>your_custnumber</CustNumber>
      		<CustRef>your_custref</CustRef>
      		<Amount>1000</Amount>
     		<TrnType>2</TrnType>
      		<AccountNumber>your_accountnumber</AccountNumber>
      		<CreditCard Registered="False">
                  	<CardNumber>4242424242424242</CardNumber>
                  	<ExpM>02</ExpM>
                  	<ExpY>2019</ExpY>
                  	<CVN>123</CVN>
                  	<CardHolderName>Test</CardHolderName>
       		</CreditCard>
       		<Security>
                  	<UserName>your_api_username</UserName>
                  	<Password>your_api_password</Password>
       		</Security>
	</Transaction>
]]>    
</dts:trnXML>
</dts:SubmitSinglePayment>
</soapenv:Body>
</soapenv:Envelope>

Example 3.1 - Pre-Auth payment with reference/user defined fields

Pre-auth request can be submitted with reference/UD fields which will carry over with the corresponding capture request to notify Bambora to initiate the settlement process. Reference/UD fields defined in a pre-auth payment request can be updated later on, in the subsequent capture or refund request. Please see section Capture for details on how to capture the funds reserved by a pre-auth with reference/UD fields.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:dts="http://www.ippayments.com.au/interface/api/dts">
<soapenv:Header/>
<soapenv:Body>
<dts:SubmitSinglePayment>
<dts:trnXML>
<![CDATA[
	 <Transaction>
      		<CustNumber>your_custnumber</CustNumber>
      		<CustRef>your_custref</CustRef>
      		<Amount>1000</Amount>
     		<TrnType>2</TrnType>
      		<AccountNumber>your_accountnumber</AccountNumber>
      		<CreditCard Registered="False">
                  	<CardNumber>4242424242424242</CardNumber>
                  	<ExpM>02</ExpM>
                  	<ExpY>2019</ExpY>
                  	<CVN>123</CVN>
                  	<CardHolderName>Test</CardHolderName>
       		</CreditCard>
       		<Security>
                  	<UserName>your_api_username</UserName>
                  	<Password>your_api_password</Password>
       		</Security>
		<UserDefined>   
                        <Reference1>your_reference1</Reference1>
                        <Reference2>your_reference2</Reference2>
                </UserDefined>
	</Transaction>
]]>    
</dts:trnXML>
</dts:SubmitSinglePayment>
</soapenv:Body>
</soapenv:Envelope>

Example 4 - One-off Purchase using the Custom Checkout One Time Token (OTT)

SOAP Method: SubmitSinglePayment

POSThttps://demo.ippayments.com.au/interface/api/dts.asmx

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:dts="http://www.ippayments.com.au/interface/api/dts">
<soapenv:Header/>
<soapenv:Body>
<dts:SubmitSinglePayment>
<dts:trnXML>
<![CDATA[
	<Transaction>
		<CustNumber>your_custnumber</CustNumber> 
		<CustRef>your_custref</CustRef>
		<Amount>1000</Amount>
		<TrnType>1</TrnType>
		<AccountNumber>your_accountnumber</AccountNumber>
		<CreditCard>
			<OneTimeToken>OTT_returned_by_custom_checkout</OneTimeToken>
		</CreditCard>
		<Security>
			<UserName>your_api_username</UserName>
			<Password>your_api_password</Password>
		</Security>
	</Transaction>
]]>    
</dts:trnXML>
</dts:SubmitSinglePayment>
</soapenv:Body>
</soapenv:Envelope>

Example 5 - One-off Purchase using the Custom Checkout Secure Transaction Token (STT)

SOAP Method: SubmitSinglePayment

POSThttps://demo.ippayments.com.au/interface/api/dts.asmx

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:dts="http://www.ippayments.com.au/interface/api/dts">
<soapenv:Header/>
<soapenv:Body>
<dts:SubmitSinglePayment>
<dts:trnXML>
<![CDATA[
	<Transaction>
		<CustNumber>your_custnumber</CustNumber> 
		<CustRef>your_custref</CustRef>
		<Amount>1000</Amount>
		<TrnType>1</TrnType>
		<AccountNumber>your_accountnumber</AccountNumber>
		<CreditCard>
			<SecureTransactionToken>STT_returned_by_custom_checkout</SecureTransactionToken>
		</CreditCard>
		<Security>
			<UserName>your_api_username</UserName>
			<Password>your_api_password</Password>
		</Security>
	</Transaction>
]]>    
</dts:trnXML>
</dts:SubmitSinglePayment>
</soapenv:Body>
</soapenv:Envelope>

Example 6 - One-off Purchase using the Custom Checkout One Time Token (OTT) or Secure Transaction Token (STT) with additional card details requested

You can present AdditionalReturnValues in the request if you wish to recieve additional card details includes masked card number, expiry or card type in the response. Where it is requested, the value will be returned to you for both approved and declined transactions.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:dts="http://www.ippayments.com.au/interface/api/dts">
<soapenv:Header/>
<soapenv:Body>
<dts:SubmitSinglePayment>
<dts:trnXML>
<![CDATA[
	<Transaction>
		<CustNumber>your_custnumber</CustNumber> 
		<CustRef>your_custref</CustRef>
		<Amount>1000</Amount>
		<TrnType>1</TrnType>
		<AccountNumber>your_accountnumber</AccountNumber>
		<CreditCard>
			<SecureTransactionToken>STT_returned</SecureTransactionToken> or <OneTimeToken>OTT_returned</OneTimeToken>
		</CreditCard>
                <AdditionalReturnValues>
			<CardType>true</CardType>
    			<TruncatedCard>true</TruncatedCard>
    			<ExpM>true</ExpM>
    			<ExpY>true</ExpY>
		</AdditionalReturnValues>
		<Security>
			<UserName>your_api_username</UserName>
			<Password>your_api_password</Password>
		</Security>
	</Transaction>
]]>    
</dts:trnXML>
</dts:SubmitSinglePayment>
</soapenv:Body>
</soapenv:Envelope>

RESPONSE

<Response>
    	<ResponseCode>1</ResponseCode>
	<Timestamp>26-Jul-2019 13:51:57</Timestamp>
	<Receipt></Receipt>
	<SettlementDate>26-Jul-2019</SettlementDate>
	<DeclinedCode>01</DeclinedCode>
	<DeclinedMessage>Refer to Card Issuer</DeclinedMessage>
    	<CardType>Visa</CardType>
	<TruncatedCard>400555******0001</TruncatedCard>
    	<ExpM>08</ExpM>
	<ExpY>2021</ExpY>
</Response>

Example 7 - Payment with Bambora token - Credential on File

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:dts="http://www.ippayments.com.au/interface/api/dts">
<soapenv:Header/>
<soapenv:Body>
<dts:SubmitSinglePayment>
<dts:trnXML>
<![CDATA[
	 <Transaction>
      		<CustNumber>your_custnumber</CustNumber>
      		<CustRef>your_custref</CustRef>
      		<Amount>1000</Amount>
     		<TrnType>1</TrnType>
      		<AccountNumber>your_accountnumber</AccountNumber>
      		<CreditCard>
                  	<CardNumber>Bambora_token</CardNumber>
                  	<TokeniseAlgorithmID>2</TokeniseAlgorithmID>
       		</CreditCard>
                <CredentialOnFile>
                   <InitiatedBy>Customer</InitiatedBy>
                   <Type>InitialRecurring</Type>
                </CredentialOnFile>
       		<Security>
                  	<UserName>your_api_username</UserName>
                  	<Password>your_api_password</Password>
       		</Security>
	</Transaction>
]]>    
</dts:trnXML>
</dts:SubmitSinglePayment>
</soapenv:Body>
</soapenv:Envelope>

REQUEST BODY SCHEMA

Please be aware to be compliant with PCI rules. We encourage validating data sent in the marked fields (*) for PCI compliance, before submitting the request to Bambora.

Parameter	Format	Required Optional	Description
AccountNumber	Alpha/Num(16)	Required	This value dictates which account the transaction will be processed through.
CustRef *	Alpha/Num(64)	Required	A reference for the transaction sent by you for reporting purposes.
CustNumber *	Alpha/Num(64)	O	An additional reference for the transaction sent by you for reporting purposes.
Amount	Numeric(10)	Required	Amount entered in cent value e.g. $55.00 = 5500
TrnType	Numeric(2)	Required	1 is for Credit Card - Purchase 2 is for Credit Card - Auth 5 is for Credit Card - Refund
CustomerStorage Number *	Alpha/Num(16)	O	Additional field only required if Customer Registration is enabled.
Credit Card	N/A	O	This is an XML node only. Please note, either the CreditCard node or the DirectEntry node will be submitted in a transaction depending on the payment type. This node has one attribute, ‘Registered’. This attribute is used for recurring payments where you have previously registered the customer’s details. This is set to ‘True’ if a previously registered credit card is to be used or ‘False’ if processing a payment for an unregistered customer / payment method. For single submission payments this attribute should be set to ‘False’.
CreditCard/ CardNumber	Numeric(20)	O	The credit card number. E.g. 1234 5678 9065 4321
CreditCard/ ExpM	Numeric(2)	O	Month when the credit card expires.
CreditCard/ ExpY	Numeric(4)	O	Year when the credit card expires.
CreditCard/ CVN	Numeric(3)	O	Card Security Code
CreditCard/ CardHolderName *	Alpha/Num(64)	O	The name of the credit card holder. Valid characters are all alphabet characters (a-z and A-Z), numbers (0-9), space and the following special characters ` ! @ # $ & ( ) * , . : ? - + = _ / Formatting requirements MUST be followed to avoid issues with transaction processing. If converting from text to html, make sure conversion back to text is in place before sending the API request.
CreditCard/ OneTimeToken	GUID	O	The One Time Token returned by Custom Checkout.
CreditCard/ SecureTransactionToken	GUID	O	The Secure Transaction Token returned by Custom Checkout.
CredentialOnFile/ InitiatedBy	Text	O	Indicates the entity initiating the request. Can be either ‘Customer’ or ‘Merchant’. If not present, will be defaulted to ‘Merchant’. If InitiatedBy=‘Customer’, Type can only be set to ‘Unscheduled’ or ‘InitialRecurring’.
CredentialOnFile/ Type	Text	C	Indicates the type of relationship for this request. Can be ‘Unscheduled’, ‘InitialRecurring’ or ‘SubsequentRecurring’. If ‘CredentialOnFile’ node is present, this parameter is mandatory.
Direct Entry	N/A	O	This is an XML node only. Please note, either the CreditCard node or the DirectEntry node will be submitted in a transaction depending on the payment type. This node has one attribute, ‘Registered’. This attribute is used for recurring payments where you have previously registered the customer’s details. This is set to ‘True’ if a previously registered credit card is to be used or ‘False’ if processing a payment for an unregistered customer / payment method. For single submission payments this attribute should be set to ‘False’.
Direct Entry/ AccNo	Numeric(24)	O	AU Bank account number. For NZ bank details: The NZ Bank Account and Suffix should be included in this field with hyphen. For example, 0111110-00
Direct Entry/ AccRouting	Numeric(16)	O	Account routing number (BSB in Australia). For NZ bank details: The NZ Bank and Branch codes should be included in this field with with hyphen. For example, 03-0105
Direct Entry/ AccTitle	Alpha/Num(64)	O	Title of bank account.
UserDefined	N/A	O	This is an XML node only.
Reference1 *	Text(32)	O	User defined elements can be included in the transaction request and used for reporting purposes at a later stage.
Reference2 *	Text(64)	O	User defined elements can be included in the transaction request and used for reporting purposes at a later stage.
Reference3 *	Text(128)	O	User defined elements can be included in the transaction request and used for reporting purposes at a later stage.
Reference4 *	Text(1024)	O	User defined elements can be included in the transaction request and used for reporting purposes at a later stage.
Reference5 *	Text(1024)	O	User defined elements can be included in the transaction request and used for reporting purposes at a later stage.
Register/ Customer	N/A	O	This is an XML node only. Additional fields only required if Registered attribute is set to False. See section Saving Cards for example API.
Register/ Customer/ CustNumber *	Alpha/Num(64)	O	Merchant assigned unique customer number used to store the customer data and card data against.
Register/ Customer/ Contact/ FirstName *	Alpha/Num(32)	O	Customer first name.
Register/ Customer/ Contact/ LastName *	Alpha/Num(32)	O	Customer last name.
Register/ Customer/ Credit Card	N/A	O	This is an XML node only. This tag containing card data fields for registration.
Register/ Customer/ Credit Card CardNumber	Numeric(20)	O	The credit card number. E.g. 1234 5678 9065 4321
Register/ Customer/ Credit Card/ ExpM	Numeric(2)	O	Month when the credit card expires.
Register/ Customer/ Credit Card/ ExpY	Numeric(4)	O	Year when the credit card expires.
Register/ Customer/ Credit Card/ CVN	Numeric(3)	O	Card Security Code
Register/ Customer/ Credit Card/ CardHolderName *	Alpha/Num(64)	O	The name of the credit card holder.
Register/ Customer/ Direct Entry	N/A	O	This is an XML node only. This tag containing bank account fields for registration.
Register/ Customer/ Direct Entry/ AccNo	Numeric(16)	O	AU Bank account number. For NZ bank details: The NZ Bank Account and Suffix should be included in this field with hyphen. For example, 0111110-00
Register/ Customer/ Direct Entry/ AccRouting	Numeric(16)	O	Account routing number (BSB in Australia). For NZ bank details: The NZ Bank and Branch codes should be included in this field with hyphen. For example, 03-0105
Register/ Customer/ Direct Entry AccTitle	Alpha/Num(64)	O	Title of bank account.
Register/ Customer/ Direct Entry/ BankName	Alpha/Num(32)	O	The name of the bank/ financial institution.
Register/ Customer/ Direct Entry/ BankSuburb	Alpha/Num(32)	O	The suburb of the bank/ financial institution.
Register/ Customer/ Direct Entry/ BankState	Alpha/Num(32)	O	The state of the bank/financial institution.
Security/UserName	Alpha/Num(32)	Required	API Username
Security/Password	Alpha/Num(16)	Required	API Password

RESPONSE

<Response>
    <ResponseCode>0</ResponseCode>
    <Timestamp>23-Feb-2017 16:06:41</Timestamp>
    <Receipt>90891389</Receipt>
    <SettlementDate>23-Feb-2017</SettlementDate>
    <DeclinedCode></DeclinedCode>
    <DeclinedMessage></DeclinedMessage>
</Response>

RESPONSE BODY SCHEMA

Parameter	Format	Description
ResponseCode	Numeric	Response code of the submitted payment. 0 = Approved 1 = Not Approved
Timestamp	Alpha/Num	Timestamp is the date and time that Bambora has received the transaction request. The format is dd-MMM-yyyy hh:mm:ss
Receipt	Alpha/Num	Receipt number of the submitted payment. Please note the receipt number will be required for any follow up transactions such as capture or refund requests.
SettlementDate	Alpha/Num	The settlement date of the submitted payment returned in the following format DD-MMM-YYYY
DeclinedCode	Alpha/Num	This field is blank if the submitted payment is approved, otherwise, declined code is populated.
DeclinedMessage	Alpha/Num	This field is black if the submitted payment is approved, otherwise, declined message is populated.

Capture

A pre-auth transaction reserves the funds on the customer’s card without charging the money from their card. A follow up capture request must be sent with this transaction type to settle the transaction and capture the funds.

SOAP Method: SubmitSingleCapture

POSThttps://demo.bambora.co.nz/interface/api/dts.asmx

Example 1 - Single credit card capture payment

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:dts="http://www.ippayments.com.au/interface/api/dts">
<soapenv:Header/>
<soapenv:Body>
<dts:SubmitSingleCapture>
<dts:trnXML>
<![CDATA[
	<Capture>
      		<Receipt>12345678</Receipt>
      		<Amount>1000</Amount>
      		<Security>
                  	<UserName>your_api_username</UserName>
                  	<Password>your_api_password</Password>
      		</Security>
	</Capture>	
]]>    
</dts:trnXML>
</dts:SubmitSingleCapture>
</soapenv:Body>
</soapenv:Envelope>

Example 2 - Single credit card capture payment with reference/user defined fields. In this capture call new reference data can be introduced and/or original reference data from the pre-auth request can be updated to suit your business requirements.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:dts="http://www.ippayments.com.au/interface/api/dts">
<soapenv:Header/>
<soapenv:Body>
<dts:SubmitSingleCapture>
<dts:trnXML>
<![CDATA[
	<Capture>
      		<Receipt>12345678</Receipt>
      		<Amount>1000</Amount>
      		<Security>
                  	<UserName>your_api_username</UserName>
                  	<Password>your_api_password</Password>
      		</Security>
                <UserDefined>   
                        <Reference1>your_reference1</Reference1>
                        <Reference2>your_reference2</Reference2>
                </UserDefined>
	</Capture>	
]]>    
</dts:trnXML>
</dts:SubmitSingleCapture>
</soapenv:Body>
</soapenv:Envelope>

REQUEST BODY SCHEMA

Parameter	Format	Description
Receipt	Numeric(8)	Receipt number returned from capture, the same receipt number will be utilised from when the linked authorisation was processed.
Amount	Numeric(10)	Amount entered in cent value e.g. $55.00 = 5500
Security/UserName	Alpha/Num(32)	API Username
Security/Password	Alpha/Num(16)	API Password
UserDefined/Reference1	Text(32)	New user defined elements can be introduced and/or the values in the associated preauth request can be overwritten in the capture request. This data can then be used for reporting purposes at a later stage.
UserDefined/Reference2	Text(64)	New user defined elements can be introduced and/or the values in the associated preauth request can be overwritten in the capture request. This data can then be used for reporting purposes at a later stage.
UserDefined/Reference3	Text(128)	New user defined elements can be introduced and/or the values in the associated preauth request can be overwritten in the capture request. This data can then be used for reporting purposes at a later stage.
UserDefined/Reference4	Text(1024)	New user defined elements can be introduced and/or the values in the associated preauth request can be overwritten in the capture request. This data can then be used for reporting purposes at a later stage.
UserDefined/Reference5	Text(1024)	New user defined elements can be introduced and/or the values in the associated preauth request can be overwritten in the capture request. This data can then be used for reporting purposes at a later stage.

RESPONSE

<Response>
    <ResponseCode>0</ResponseCode>
    <Timestamp>23-Feb-2017 16:06:41</Timestamp>
    <Receipt>90891785</Receipt>
    <SettlementDate>23-Feb-2017</SettlementDate>
    <DeclinedCode></DeclinedCode>
    <DeclinedMessage></DeclinedMessage>
</Response>