This page describes how to create a payment through Bambora's Checkout solution.
Creating a payment with Integrated Checkout consists of two steps. This solution requires that you have a Bambora account and have created an API for authentication.
When you create the Checkout Session you submit required transaction data (eg. amount and serverURL) to Bambora. In return Bambora provide you with an Secure Session Token (SST) for this specific transaction. Once the session is established, your backend application notifies your website which then POSTs (GET also supported) the SessionIDand SST to Bambora’s server URL.
Upon posting the below values, the integrated chekcout page will be displayed. This can be embedded in your website using an iFrame solution.
The following sections will describe the two step in details.
A Checkout Session relates to an order in your system. When an order has been placed you create a corresponding Checkout Session to receive payment for that order.
The Checkout Session can be created by constructing the following request.
POSThttps://demo.bambora.co.nz/access/index.aspx
curl -X POST \
https://demo.bambora.co.nz/access/index.aspx \
-H 'cache-control: no-cache' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'UserName=[API Username]'
-d 'password=[API Password]'
-d 'CustRef=[reference]'
-d 'CustNumber=[customer number]'
-d 'Amount=[amount value]'
-d 'SessionId=[SessionId]'
-d 'SessionKey=[SessionKey]'
-d 'DL=checkout_v1_purchase'
-d 'ServerURL=[ServerURL]'
-d 'UserURL=[UserURL]'
-d 'AccountNumber=[Account Number]'
REQUEST BODY SCHEMA
The example request contains only the required fields that must be POST to Bambora to initiate the checkout session.
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 |
|---|---|---|---|
| Username | Alpha/Num(32) | Required | API Username |
| Password | Alpha/Num(16) | Required | API Password |
| CustNumber * | Alpha/Num(64) | Optional | An additional reference for the transaction sent by you for reporting purposes. |
| CustRef * | Alpha/Num(64) | Required | A reference for the transaction sent by you for reporting purposes. |
| Amount | Numeric(10) | Required | Amount entered in cent value e.g. $55.00 = 5500 |
| SessionID * | Alpha/Num(64) | Required | Merchant’s unique session identifier. Maintain this session identifier throughout the life of the transaction. |
| SessionKey * | Alpha/Num(64) | Required | Generated by you, can be any value e.g. random generated number, timestamp etc. The session key is to be included for security and authentication purposes. This Key should only be passed to Bambora’s server and should not be sent to your front end. Bambora will return the SessionKey to your ServerURL in the transaction response once the payment has been processed. If you do not receive a SessionKey or receive an invalid SessionKey, then this should be treated as a possible fraudulent transaction. Bambora needs to be notified of this event along with your internal teams for investigation. |
| DL | Alpha/Num(32) | Required | This value is used to specify the styling Bambora should display to the user and the functionality you require the checkout page to carry out when the user clicks submit. Please see section DL Values for full details. |
| ServerURL | Alpha/Num(512) | Required | The URL of your server that Bambora will POST the first notification to including the transaction result data. This value must be Base 64 encoded. |
| UserURL | Alpha/Num(512) | Required | The URL to force the user browser to POST to; this is the second notification. This value must be Base 64 encoded. |
| AccountNumber | Alpha/Num(16) | Optional | This value dictates which account the transaction will be processed through. |
| Email * | Text(64) | Optional | An additional reference for the transaction sent by you for reporting purposes.
Please note Bambora enable this field to send an email receipt to the email address entered in this field. Feel Free to contact Bambora if you require this service. |
| Reference1 * | Text(32) | Optional | This field name can be changed to something more suitable to your business for example “AccountID”. Please advise Bambora if you wish to change it. An additional reference that can be sent by you for reporting purposes e.g. a customer identifier unique to your system. Stored for payment requests only i.e. not for the card storage only transaction. This will be available to view and download with the transaction details in our reporting tool, BackOffice. |
| Reference2 * | Text(64) | Optional | See Reference 1. |
| Reference3 * | Text(128) | Optional | See Reference 1. |
| Reference4 * | Text(1024) | Optional | See Reference 1. |
| Reference5 * | Text(1024) | Optional | See Reference 1. |
| UserDeclinedURL | Alpha/Num(512) | Optional | Bambora offers the ability to have a cancel button on your checkout page. By default this page will redirect to the UserURL. If you wish this button to redirect to a different page other than the UserURL, you can specify the UserDeclinedURL in this field. If the user selects the cancel button on the checkout page, the page will be redirected to the declined URL. Please note if you send a value in this field, all responses for declined transactions will be sent to this URL including cancelled transactions and transactions which have been declined by the bank. |
| CustomerStorage Number | Alpha/Num(32) | Optional | Additional fields only required for card storage. This value dictates which account the card details will be stored against. |
The DL value will be created using the following naming convention TemplateName_Functionality
| AU/NZ Payment Gateway merchat | NZ PayFac merchant |
|---|---|
| 1. Purchase = bambora_purchase 2. Direct Debit = bambora_directdebit 3. Pre-Auth = bambora_preauth 4. Purchase & Tokenise = bambora_purchasetokenise 5. Pre-Auth & Tokenise = bambora_preauthtokenise 6. Tokenise Only = bambora_tokenise | There are 2 version of the checkout pages that you can launch by submitting the "DL" values below in the Checkout Session request. Version 1, which allows you to pre-populate the "amount" value before launching the checkout page to the user. 1. Purchase = checkout_v1_purchase 2. Pre-Auth = checkout_v1_preauth 3. Purchase & Customer Registration = checkout_v1_purchaseregistercc 4. Pre-Auth & Customer Registration = checkout_v1_preauthregistercc Version 2, which allows the user to enter the "amount" and "reference" details on the checkout page. 1. Purchase = checkout_v2_purchase 2. Pre-Auth = checkout_v2_preauth 3. Purchase & Customer Registration = checkout_v2_purchaseregistercc 4. Pre-Auth & Customer Registration = checkout_v2_preauthregistercc |
The response contains the SST if the Checkout Session initiation is successful, or an error description if the session cannot be initiated. This result is presented as XML parsable HTML. The value of SessionStored is ‘True’ if the session was initiated and stored correctly.
A Checkout Session is valid for 20 Minutes.
Example 1 - HTML returned upon successful session initiation
<html>
<body>
<form>
<input type=”hidden” name=”SessionStored” value=”True” />
<input type=”hidden” name=”SessionStoredError” value=”” />
<input type=”hidden” name=”SST” value=”3skygj450xenmtrg4bbyoimh” />
</form>
</body>
</html>
Example 2 - HTML returned upon failed session initiation
<html>
<body>
<form>
<input type=”hidden” name=”SessionStored” value=”False” />
<input type=”hidden” name=”SessionStoredError” value=”Invalid username or password” />
<input type=”hidden” name=”SST” value=”” />
</form>
</body>
</html>
| Parameter | Format | Description | Always returned |
|---|---|---|---|
| SessionStored | Alpha/Num | Value that can be either True or False | Yes |
| SessionStoredError | Alpha/Num | Textual description of the error. This field will only be populated if the SessionStored value is False. | Yes |
| SST | Alpha/Num | Secure Session Token. This field will only be populated if the SessionStored value is True | Yes |
The redirection to the checkout page is done via POST (GET also supported). Upon posting the SST (provided by Bambora) and SessionID (provided by you in the checkout session) values to Bambora's server URL, the user will be redirected to the checkout page where the payment can be performed. The checkout page can be embedded in your website using an iFrame solution. The user will be required to enter the following payment details into the checkout page.
Bambora sends the payment for authorisation to your acquiring bank who connect via the schemes (Visa, Mastercard, American Express or Diners) to your customer’s issuing bank who checks their balance, card data, etc. The transaction response is passed back via the same route to Bambora.
Next step in the integration is to handle the responses that are returned as a result of the payment.
Creating a payment with Bambora's Standalone Checkout by simply directing the user to a predefined URL which will show the checkout page. Transactions are processed in real-time and the response are displayed back to the user. Utilise our insights and transaction management tool, Backoffice, to carry out any reconciliation required for transactions processed through the standalone checkout page.
The following sections will describe the steps in details.
AU - <https://demo.ippayments.com.au/access/index.aspx?a=InsertAccount#&dl=InsertDLValue>
Please contact our Onboarding team to receive your unique Account#. Once provided, you are ready to use the DL values below to make test transactions in your Demo account.
There are 2 versions of the checkout page ideal for those who need to provide a URL to their customers and accept a once off payments. The link that can be configured through the DL values, you can specify the styling Bambora should display to the user and the functionality you require the checkout page to carry out by constructing the URL as per below.
New Zealand - <https://demo.bambora.co.nz/access/index.aspx?a=[BAMBORA ID]&dl=[INSERT DL VALUE]&accountnumber=InsertAccountNumber>
Version 1, allows you to pre-populate the amount on the checkout page, the variables amount must be passed in the URL along with DL value and Account ID which will be provided to you by Bambora via the onboarding email. Additionally, you can specify the customer reference and customer number in the URL for reporting purpose.
| Functionality | Variables passed in URL | Sample URL |
|---|---|---|
| Process a payment | Sample | |
| Pre-auth a payment | Sample |
Version 2, allows the user to enter the amount and their customer reference on the checkout page, all you need to do is pass the DL value and AccountNumber in the URL which will be provided to you by Bambora via the onboarding email.
| Functionality | Variables passed in URL | Sample URL |
|---|---|---|
| Process a payment | Sample | |
| Pre-auth a payment | Sample |
Once the user enters all the required information on the checkout page and clicks submit, Bambora sends the payment for authorisation to your acquiring bank and displays the result page to the customer upon receiving the response.