Dynamic Integration

The dynamic payments integration allows you to pass in dynamic payment information (amounts, frequencies, etc) into the Checkout widget and is best for applications like e-commerce where end users are purchasing variable amounts and the integrator is maintaining some sort or cart and order system.

This integration has three pieces:

A backend integration with banq's Open API for Inbound Payments to create the specific payment that needs to be processed.
Subscribing to our web hooks to receive notifications that the payment succeeded.
A front end integration of the Checkout widget for the end to end flow the end user can use to pay.

🚧
Intermediary Endpoint
Note that while it's technically possible to call banq's Open API directly from the widget, we highly recommend creating an intermediary endpoint on your backend so that you can pass in fields like Order Id, Customer Id, etc from the widget to your backend and then use your backend to configure the payment and return it to the widget.
This is the specific integration that's described in the example below.

Generate Payment Link

Contact Banq Team to obtain YOUR-CLIENT-ID, YOUR-CLIENT-USERNAME/PASSWORD

From your Backend, make a POST request to https://banq-staging.auth0.com/oauth/token. This will generate an access token that will be needed for /payments/get-paid-link requests.

// POST https://banq-staging.auth0.com/oauth/token
{
    "client_id":"YOUR-CLIENT-ID",
    "username":"YOUR-CLIENT-USERNAME",
    "password":"YOUR-CLIENT-PASSWORD",
    "audience":"https://banq.com/open/api/",
    "grant_type":"password"
}

To generate payment link. See BANQ API Docs Swagger. Make a request POST https://sandbox.banq.com/api/v1/payments/get-paid-link. With access token obtained from /auth/token request

// Request params to https://sandbox.banq.com/api/v1/payments/get-paid-link
// Headers: Authorization
{
  "destination": {
    "banqGuid": "<MERCHANT-BANQ-GUID>"// Destination Banq Acccount guid.
  },
  "comment": "string", // Shows in the Banq App on payment screen (example: Title of your product)
  "funds": 100, // Amount of money you want to charge
  "externalOrderCode": "<YOUR-ORDER-ID>", // This is orderId from your database
  "frequency": "once", // Check BANQ API Docs for recurrent payment options
  "startDate": "2021-06-15", // You don't need to specify startDate 
  "endDate": "2021-06-15" // or endDate if payment is not recurrent
}

Obtain a BANQ account guid MERCHANT-BANQ-GUID. Make a GET request in Docs Swagger https://sandbox.banq.com/api/v1/users/me?include=accountSpaces,banqAccounts. With access token obtained from /auth/token request below

// POST https://banq-staging.auth0.com/oauth/token
{
	audience: 'https://banq.com/api',
	scope: 'offline_access',
	client_id: 'kFLEhEsxxBWCf0X19hAIjbzYaSyn2cim', // This should always be static. This is client ID of BANQ API
	grant_type: 'password',
	username: '<[email protected]>',
	password: '<YOUR_MERCHANT_PASSWORD>'
};

Find banq guid MERCHANT-BANQ-GUID of account you want to use as destination Banq Account
And add this MERCHANT-BANQ-GUID to step 2 https://sandbox.banq.com/api/v1/payments/get-paid-link

Subscribing to Webhooks

You need to create an endpoint that will receive POST https://PATH-TO-YOUR-WEBSITE/your-web-hooks/payment-status With a webHook event as Stream.
Convert webhook event steam to JSON. And if action == completed and resourceType == Payment make GET request to https://sandbox.banq.com/api/v1/payments/${resourceId}, resourceId - from webHook event,

// GET https://sandbox.banq.com/api/v1/payments/${resourceId}
// Headers: Authorization

Obtain ACCOUNT-SPACE-ID. Make a GET request in Swagger https://sandbox.banq.com/api/v1/users/me?include=accountSpaces,banqAccounts. With access token obtained from /auth/token request below

// POST https://banq-staging.auth0.com/oauth/token
{
	audience: 'https://banq.com/api',
	scope: 'offline_access',
	client_id: 'kFLEhEsxxBWCf0X19hAIjbzYaSyn2cim', // This should always be static. This is client ID of BANQ API
	grant_type: 'password',
	username: '<[email protected]>',
	password: '<YOUR_MERCHANT_PASSWORD>'
};

Find your merchant banq and find a property accountSpaceId

// POST https://sandbox.banq.com/api/v1/account-spaces/ACCOUNT-SPACE-ID/webhook-config
// Headers: Authorization,
{
   url: `https://PATH-TO-YOUR-WEBSITE/your-web-hooks/payment-status`,
   enabled: true,
   retryCount: 5,
   webHookTypes: ['payment', 'transaction'],
}

Adding the Widget

For example, you will have to create an endpoint https://PATH-TO-YOUR-WEBSITE/generate-payment-link, on your own backend.

Place the “pay with banq” button anywhere on your page.

<script src="https://sandbox.banq.com/widget/ecommerce.js"></script>
<div id="pay-with-banq"></div>

Copy embedded code to your website that will obtain a payment link from your backend.

<script>
	const app = new window.ecommerceBanqWidget({
		selector: '#pay-with-banq',
		getPaymentInfo: () => {
			// this endpoint should be implemented on your own backend, see instruction below
			return fetch('https://<PATH-TO-YOUR-WEBSITE>/generate-payment-link', {
				method: 'POST',
				headers: {
					'Content-Type': 'application/json'
				},
				body: JSON.stringify({
					orderId: '009221', // This is orderId from your database
					comment: 'Demo Widget Banq', // Shows in the Banq App on payment screen (example: Title of your product)
					funds: 2 // Amount of money you want to charge
				})
			})
				.then((response) => response.json())
				.then((data) => data.data.url); // Should return payment link
		},
		onPopUpClose: () => {
			console.log('pop up is closed');
		},
		onPaymentSuccess: () => {
			// If payment was handled by Mobile App onPaymentSuccess won't be triggered. Has to be implemented separatly.
			// See Pay with QR Code Integration section below
			console.log('this triggers after payment completed successfully');
		}
	});
	app.bootstrapApp();
	</script>

Force Closing the Widget

If you'd like to force close the widget, simply call app.destroyWidget()

Pay with QR Code Integration

Instead of authenticating, the Checkout widget also allows users to scan the QR code with the banq application and finish eh checkout process in app. If payments are completed in this manner, the widget will not know the payment was completed and hence will not fire the onPaymentSuccess() function.

In this case, you will want to send the webhok event to your front end to show if the purchase was successful. Possible variants: Web Sockets, Server Side Event, Long Polling

Going to production

Change https://banq-staging.auth0.com/oauth/token endpoint to https://banq-prod.auth0.com/oauth/token
Replace user credentials on your backend YOUR-CLIENT-ID, YOUR-CLIENT-USERNAME/PASSWORD, MERCHANT-BANQ-GUID with production credentials

Change https://sandbox.banq.com/api/ to https://api.banq.com/api/ for all endpoints

🚧Intermediary Endpoint

Generate Payment Link

Subscribing to Webhooks

Adding the Widget

Force Closing the Widget

Pay with QR Code Integration

Going to production

🚧
Intermediary Endpoint