Managing Page Level Bank Interactions

Communication between your payment page and the Bank which is handling the users payment needs to be done via top level page redirection. For security reasons banks do not allow embedded components (e.g. Iframes) to initiate open banking interactions. They also require a pre-registration of the redirect page they will call back to upon payment authorization.

By default these interactions are initiated on a separate browser tab, so that we can undertake this redirect handshake on our own domain.

If you want to streamline the user's interactions with your page Bopp button has an extension API which allows you to handle this interaction directly from your own page.

To achieve this you need to perform the following operations.

1. Initiate the bopp button as described above
2. Call the setBankCallback method on the button API to the page you want to receive the bank call back on
3. Register a callback using setOnAuthUrl so we can pass you the bank's authorization url when it is ready for processing
4. Upon receipt of the bank's authorization url in your callback, you should redirect your top level page location to the supplied url
5. The bank will now process the payment for the paying user and then redirect back to the url you supplied in step 2.
6. On your redirected callback page back you need to pass locator for the page to the bopp button sdk by calling the processBankCallbackUrl. It will then parse the parameters from the bank, complete the payment and call the completion callbacks outlined above to indicate success or failure.

Details of the functions you need to invoke to operate this flow are described below:

Method	Parameters	Description
setBankCallbackUrl	url	Sets the callback URL for your page return which will be appended to the bank authorization to initiate the return processing from the payers bank
setOnAuthUrl	function(url)	Identifies the callback function which will get invoked by the bopp button sdk to initiate transfer to the bank for payment processing
processBankCallbackUrl	url	Initiates the completion of the bank payment flow between the BOPP button sdk and the payers bank using the authorization parameters returned by the bank. Some banks use '#' and some use '?' to pass these parameters.

Usage examples:

boppButton.setBankCallbackUrl("https://example.com/callback");

// where auth url is e.g. https://democonsentapp.netlify.app/democonsentapp?arg=https://bopp.dev/ucb?code=accept&state=7meEXh892V4BMOJ9DJ4bKK5P-21PnAq-consentid
// democonsentapp.netlify.app will be replaced with the banks open banking access api endpoint

boppButton.setOnAuthUrl(function (authUrl) {
    window.location = authUrl
});

// where the url is e.g. 
//  https://example.com/callback#code=accept&id_token=jvfsnvfkunkfu2433&state=7mZMu5w8p1vkiJjJpxCWtdGN-5zvbbilUr7GwOVu7uHZCRVASciJyctDmbHAsQ5smWC-consentid

boppButton.processBankCallbackUrl(window.location)

Setting Callback Parameters

The example callback URL above is a plain URL https://example.com/callback. If this URL has '?' query parameters, for example https://example.com/callback?param0=val0&param1=val1 set on it these will be passed back to the caller on the bank not redirect.

The interaction between the bank and the bopp network uses the fragment element in the URL (after the #), which will not be sent to the backend server by the browser on redirect but the parameters passed into the boppButton.setBankCallbackUrl will be.

Some banks apply limits to the length of the data they are prepared to receive on the encoded auth url they process. So it may be necessary to limit the length of data being passed. A typical limit we have seen in testing is 1024 bytes, but a number like 256 bytes may be a safer length constraint.