Skip to main content


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:

amountstring (number)The amount which was paid by the payment instrcution - this is a numeric value passed as a string to avoid rounding issues
referencestring (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
instructionIdstring (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
transactionIdstring (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
internalReferencestringThis 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:

301Failed to create paylinkTriggered if failed to initiate payment
302Not definedTriggered if failed to initiate payment according to server error
302Payment cancelledTriggered if payment cancelled on payer's side
303Not definedTriggered if failed to initiate payment due to server not responding
304Limit reachedTriggered 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.

100Not definedAPI key is incorrect or does not exist
101Amount and currency is requiredTriggered when amount or currency not passed in setAmount function
201Order number should be string typeTriggered when payment reference is not a string passed to setPaymentReference function
201Order number should be less that 19 charactersTriggered when payment reference passed to setPaymentReference function is more than 18 characters
201Order number should not contain special charactersTriggered when payment reference passed to setPaymentReference function contains special characters, in this case order number will be set as 'BOPP Transaction'
202Amount should be number typeTriggered when amount is not a number passed to setAmount function
203Currency should be string typeTriggered when currency is not a string passed to setAmount function
204Should be boolean valueTriggered when value is not a boolean passed to setEnabled function
401Redirect url should be string typeTriggered when redirect url is not a string passed to setSuccessRedirectUrl, setFailRedirectUrl, setCancelRedirectUrl functions
501Failed to find instruction idPayment 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) {

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

InitiatedQR code was generated
ConnectingToBankStarted connecting to bank
PaymentInProcessStarted payment process
PaymentCompletedPayment was successful
PaymentFailedPayment was not successful
AbortedPayer 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 :
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

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.


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.