Callbacks
The bopp Checkout flow supports a variety of callback mechanisms to provide its hosting page and associated systems with a programmatic indication of of the result of the payment process.
- In Page Javascript
- Status Posts to external rest servers
- Page Redirection
Each of these methods is configured on page by calling methods on the BoppButton object prior to initiating a payment.
The table below describes the content of the fields used by all of the above callback methods:
| Parameter | Type | Description |
|---|---|---|
| amount | string (number) | The amount which was paid by the payment instrcution - this is a numeric value passed as a string to avoid rounding issues |
| reference | string (constrained) | This is the reference field which is passed to the payer and payees bank, it is constrcined to the values allowed by external bank systems |
| instructionId | string (identifier) | This is the internal system identifier created by the BOPP system to uniquely identity a payment instrcution. It can be used as a primary identifier when requesting payment details via the BOPP reporting API |
| transactionId | string (bank identifier) | This is the transaction identifier generated by the paying bank and passed via the Open Banking API. It can be used to query payments when making support requests to the paying bank. It is displayed as the ID to the BOPP desktop user so it can be used for customer support purposes. Its format will vary by paying bank |
| internalReference | string | This is a user/developer defined identifies which can be used by external systems for thier own purposes. It is not transmitted to any third parties in the mayment flow and has no formatting restrictions |
In Page Callbacks
To get the status of a payment and be able to respond to any error messages returned you can attach a callback to the boppButton variable that you have declared.
The .setCallback method will accept four parameters, onPaymentSuccess, onPaymentFailed, onError and onPaymentStatusChange.
boppButton.setCallback(onPaymentSuccess, onPaymentFailed, onError, onPaymentStatusChange);
onPaymentSuccess will be called when the payment is finished successfully it contains result object with properties:
amount: string - Payment amount
reference: string - The reference passed to the bank associated with the payment instruction
instructionId: string - The system ID for the payment instruction
transactionId: string - Bank transaction id
internalReference: string - Internal reference which is not visible to user and can be used for application logic
function onPaymentSuccess(result) {}`
onPaymentFailed will be called when the payment fails, it contains an error object with properties:
code: string - error code
message: string - error message
internalReference: string - internal reference which is not visible to user and can be used for application logic
function onPaymentFailed(result) {}`
Error codes:
| Code | Message | Description |
|---|---|---|
| 301 | Failed to create paylink | Triggered if failed to initiate payment |
| 302 | Not defined | Triggered if failed to initiate payment according to server error |
| 302 | Payment cancelled | Triggered if payment cancelled on payer's side |
| 303 | Not defined | Triggered if failed to initiate payment due to server not responding |
| 304 | Limit reached | Triggered if limit reached for particular account |
onError will be called when an error occurs. The function will be passed two parameters, the error code and associated message. See the table below for more details on the possible errors.
| Code | Message | Description |
|---|---|---|
| 100 | Not defined | API key is incorrect or does not exist |
| 101 | Amount and currency is required | Triggered when amount or currency not passed in setAmount function |
| 201 | Order number should be string type | Triggered when payment reference is not a string passed to setPaymentReference function |
| 201 | Order number should be less that 19 characters | Triggered when payment reference passed to setPaymentReference function is more than 18 characters |
| 201 | Order number should not contain special characters | Triggered when payment reference passed to setPaymentReference function contains special characters, in this case order number will be set as 'BOPP Transaction' |
| 202 | Amount should be number type | Triggered when amount is not a number passed to setAmount function |
| 203 | Currency should be string type | Triggered when currency is not a string passed to setAmount function |
| 204 | Should be boolean value | Triggered when value is not a boolean passed to setEnabled function |
| 401 | Redirect url should be string type | Triggered when redirect url is not a string passed to setSuccessRedirectUrl, setFailRedirectUrl, setCancelRedirectUrl functions |
| 501 | Failed to find instruction id | Payment finished succesfully but filed to get payment instruction id, success callback will be called without instruction id |
function onPaymentSuccess () {
//Payment succeeded
}
function onPaymentFailed () {
//Handle a payment failure
}
function onError (error) {
console.log(error);
}
boppButton.setCallback(onPaymentSuccess, onPaymentFailed, onError);
When the error occurs, BOPP Checkout will call the previously passed ' onError' function in which it passes 2 parameters: code (which is the error code essentially) and message (short error description). For instance:
.onError({ code: '200', message: 'order number should be string type' })
onPaymentStatusChange will be called when payment status changed and passes strin parameter. All statuses described in table below
| Status | Description |
|---|---|
| Initiated | QR code was generated |
| ConnectingToBank | Started connecting to bank |
| PaymentInProcess | Started payment process |
| PaymentCompleted | Payment was successful |
| PaymentFailed | Payment was not successful |
| Aborted | Payer has closed modal |
External Server Posting
You can use .setOnSuccessPost(url) to request that the SDK POSTs a message to the given URL endpoint on completion of a successful payment.
You will need to set CORS for your endpoint to use the following headers:
Access-Control-Allow-Origin : https://bopp.io
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers : Origin, Content-Type, XMLHttpRequest, user-agent, accept, x-requested-with
The POST message will contain in the body the following parameters:
amount : The amount paid
reference : The reference passed to the bank associated with the payment instruction
instructionId : The system ID for the payment instruction
transactionId : Bank transaction id
signature : EdDSA / JSON Web Key signature
The signature can be verified by getting the BOPP public key, which is in JSON Web Key format and using and EdDSA supporting library from https://jwt.io/libraries
Page Redirects
Using .setSuccessRedirectUrl, .setFailRedirectUrl, .setCancelRedirectUrl you are able to set the redirect URL on the Payers side, for a particular payment which will be called when the payment is finished, it should be string value. These settings are Optional. This means that the Payer will be taken to the redirect URL on payment completion, this original page hosting the BOPP Button will remain open and receive the payment complete message.
boppButton.setSuccessRedirectUrl(SuccessRedirectUrl);
boppButton.setFailRedirectUrl(FailRedirectUrl);
boppButton.setCancelRedirectUrl(CancelRedirectUrl);
The RedirectUrl will be called with the parameter instructionId= appended. This will have a String value that represents the ID for the PaymentInstruction.
If a redirect is set, the BOPP screen at the end of the payment process will immediately redirect to the supplied URL. Otherwise the payment process will follow the default flow ending on the BOPP Payment Results Screen.