Handling responses from Bambora Checkout is important. It enables you to update your order dependent on the result of the payment and ensure a good user flow. This section is part of the guide describing how to handle responses once you have created a payment using the Intergrated Checkout.
Bambora provides two notification of the transaction upon the completion to you in two steps.
Once the payment is completed Bambora will POST the first notification that including the transaction result data to the ServerURL as supplied in the Checkout session. The response data should be stored in your database and made accessible to your website.
This value must be Base 64 encoded when being submitted in the Checkout session. If you do not require data to be sent to the ServerURL, please leave this field empty.
Bambora redirects the user to the ‘UserURL’ as supplied in the Checkout session request and POSTs the SessionID and SST. The UserURL page can use these details to access the transaction results stored in your database from the first notification.
Once your UserURL page receives the transaction result, it can display the transaction results to the user.
The configuration of the different URLs is done when creating the Checkout Session. Assign an object of URLs as follow to the serverurl-parameter and userurl-parameter.
{
"ServerURL": "https://example.org/SessionResult"
"UserURL": "https://example.org/SessionResult"
}
The example provided only contains two parameters and the following presents all available parameters.
| Parameter | Format | Description | Always returned |
|---|---|---|---|
| Result | Numeric | 0 = Declined; 1 = Approve; 2 = In progress; 3 = Session Expired | Yes |
| Receipt | Numeric | The Bambora receipt number generated for this transaction | Yes |
| DeclinedCode | Alpha/Num | Declined code interprets the error message. If result = 0, then this will be the reason for the declined transaction as an error code. If result = 1, then this will be blank | Yes |
| DeclinedMessage | Alpha/Num | Reason message for declined. If result = 0, then this will be the textual description of the error. If result = 1, then this will be blank | Yes |
| SST | Alpha/Num | The Secure Session Token | Yes |
| SessionKey | Alpha/Num | The session key submitted by you only to Bambora in the session initiation request | Yes |
| SessionId | Alpha/Num | Merchant unique session identifier | Yes |
| MaskedCard | Numeric | The masked credit card number. This will show first 6 and last 4 digits of card number. E.g. 1234 56** ***4 321 | Yes |
| ExpiryDate | Alpha/Num | The credit card expiry date. Format: MM/YY | Yes |
| CardHolderName | Alpha/Num | The card holder name (if captured) | No |
| CardType | Alpha/Num | E.g. MasterCard, Visa | Yes |
| CardSubType | Alpha/Num | A value can be passed back giving further details on the card. This field is only returned if you have the CardSubType functionality enabled. Please see section Card SubType Recongition for further information | No |
| TxDateTime | Alpha/Num | The transaction date/time. Format: YYYY-MM-DD HH:MM:SS E.g. 2017-01-20 18:32:30 | Yes |
| CustNumber | Alpha/Num | An additional referencor the transaction sent by you for reporting purposes | No |
| CustRef | Alpha/Num | Merchant Reference for the transaction. | No |
| Amount | Numeric | Transaction amount in cent value e.g. $55.00 = 5500. This is the originally submitted amount and does not include any surcharge amount that may have been applied by Bambora | Yes |
| Surcharge | Numeric | Surcharge amount applied to the transaction in cent value. This is only populated if surcharging is enabled on your account | No |
| Totalamount | Numeric | Transcation amount plus surcharge amount applied to the transaction in cent value. This is only populated if surcharging is enabled on your account | No |
| SettlementDate | Alpha/Num | The settlement date of the transaction returned in the following format YYYY-MM-DD | Yes |
| Reference1 | Alpha/Num | Additional optional reference submitted by you in the transaction request | No |
| Reference2 | Alpha/Num | Additional optional reference submitted by you in the transaction request | No |
| Reference3 | Alpha/Num | Additional optional reference submitted by you in the transaction request | No |
| Reference4 | Alpha/Num | Additional optional reference submitted by you in the transaction request | No |
| Reference5 | Alpha/Num | Additional optional reference submitted by you in the transaction request | No |
| AU/NZ Bank Account fields | N/A | Additional fields returned in the response after processing AU Bank Account Transactions. | No |
| Acctitle | Alpha/Num | Bank account holder name | No |
| AccRouting | Numeric | Bank account BSB. For NZ direct debit processing, this will include Bank and Branch Codes | No |
| Accno | Numeric | Bank account number.For NZ direct debit processing, this will include NZ Account number and Suffix | No |
| Tokenisation fields | N/A | Additional fields returned in the response after tokenising the card | No |
| Token | Numeric | Token generated by Bambora to uniquely identify this customer/credit card. (not to be confused with the Secure Session Token) | No |
| TokenResult | Numeric | 0 - Failed Tokenisation 1 - Successful Tokenisation. Please note: TokenDeclinedCode and TokenDeclinedMessage will be blank for TokenResult of 1 (Successful tokenisation). If Querying the Access Portal Session (using SST, SessionID and Query=true), the following results are also possible: 2 (Session In Progress) 3 (Session expired) | No |
| TokenDeclinedCode | Numeric | Please see possible decline codes below: 110 998 | No |
| TokenDeclinedMessage | Alpha/Num | The message sent depends on the 3 values for TokenDeclinedCode: 0: “System Exception” 110: “Invalid Credit Card Number” 998: “Transaction Payment Cancelled” | No |
| Parameter | Format | Description | Always returned |
|---|---|---|---|
| SessionId | Alpha/Num | Merchant’s unique session identifier. Defined by the merchant in the session initiation request | Yes |
| SST | Alpha/Num | The Secure Session Token. Provided by Bambora in the session initiation response | Yes |
Next step in the proces of integration Bambora Checkout is to test your integration by performing test transactions.
You can query the results of a transaction by submitting a POST or GET request as detailed below. You can use this query method until the SST expires (24 hours after it was created). If you need to query the transaction after this period, you can submit a query API request.
POSThttps://demo.bambora.co.nz/access/index.aspx
| Parameter | Format | Description |
|---|---|---|
| Username | Alpha/Num | API Username |
| Password | Alpha/Num | API Password |
| SST | Alpha/Num | The Secure Session Token that preivously provided by Bambora |
| SessionId | Alpha/Num | Merchant’s unique session identifier. Provide by you in the checkout session request. |
| Query | Alpha | Value set to true |
Example Query Structure
</br>https://< Bambora server>/access/index.aspx?UserName=<account login>&Password=<account password>&SST=<Secure Session Token>&SessionId=<SessionId>&Query=true
The response fields returned will be the same as the fields returned in the Notification 1 step of the response detailed in the section 1st Response POST to SeverURL.