Skip to main content

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.

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 may contain instruction id string value

onPaymentFailed will be called when the payment fails, it contains an error object with properties:

  • code: string - error code
  • message: string - error message

Error codes:

CodeMessageDescription
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.

CodeMessageDescription
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) {
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

StatusDescription
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 : 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:

    paymentInstructionId : The system ID for the payment instruction 
reference : The reference passed to the bank associated with the payment instruction
amount : The amount paid
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.