Collection Modal


Korapay’s Collection Modals are secure, Korapay-hosted payment pages that you can easily integrate into your website or applications to seamlessly collect payments from your customers. Collection Modals give your customers access to multiple payment methods, including bank transfers and card payments. As a merchant, the Collection Modals let you create customizable payment pages, and greatly reduces the burden of compliance with Payment Card Industry (PCI), as Korapay handles all card data.

On the merchant dashboard, the Collection Modals also come in the form of Checkouts which have payment links that you can easily share with your customers or embed in buttons on your applications.

 

You can only receive real payments with the Collections Modal or Checkout in Live mode. At this point, you must have completed the Go-Live requirements.

 

Integrating the Collections Modal 

The Korapay Collection Modal is the easiest way to start accepting payment on your web applications. It offers a secure and convenient flow for users. The best part is that the payment gateway renders in an iframe independent of site styling, allowing you to maintain your site’s brand and identity. You'll find comprehensive guides and documentation to help you get started as quickly as possible. Feel free to contact our Support Team if you get stuck.

Let's jump right in!

 

To integrate Korapay Collection Modal into your website within minutes, do the following things:

  • Create your Korapay account and get your API keys. This is required for all requests to the Korapay platform. 

  • Set webhook endpoints on the dashboard.

Integration Guide

Here you'll learn how to integrate Korapay Collection Modal with your product, with an adequate example. In this use case, clicking the "Pay" button should load the Korapay payment form on your webpage.

To get started:

Step 1 - Obtain your merchant key credentials from your dashboard: Test key/Public key.

Step 2 - Add the Korapay collections script on your website or application.

 

Code: Form

1 2 3 4 <form>     <script src="https://korablobstorage.blob.core.windows.net/modal-bucket/korapay-collections.min.js"></script>     <button type="button" onclick="payKorapay()"> Pay </button> </form>


Code: Script

1 2 3 4 5 6 7 8 9 10 11 12 13 14 <script>     function payKorapay() {         window.Korapay.initialize({             key: "pk_live_*********************",             amount: 3000,             currency: "NGN",             customer: { name: "John Doe", email: "john@doe.com" },             notification_url: "https://example.com/webhook"         });     } </script>

 

STEP 3: Use the Korapay.initialize function passing the relevant transaction details to initialize the modal and start accepting payments.

  • Set the sample API key with your test mode key obtained from your dashboard. This allows you to test through your modal account.

  • Indicate your amount and currency.

  • Indicate your customer name and email to show on the modal as the sender of the transaction.

  • When you’re ready to accept live card payments, replace the test key with your live/production key.

STEP 4: When the payment is complete, we will make a POST request to your webhook URL (as set up in your dashboard or while initializing the transaction (using the key: “notification_url”) with a request in this format:


Code: Response Format

1 2 3 4 5 6 7 8 9 10 {    event:  "charge.success" // can be "charge.success" or "charge.failed",    data: {        reference: "KPY-C-cUBkIH&98n8b",        currency: "NGN",        amount: "3000",        fee: "25",        status: "success"    } }

 

Here’s an example of what displays on the model when parameters are passes as data attributes from the function to the form.

Code: Form

1 2 3 4 <form id="Korapay-form">     <p> Your name <input type="text" id='customerName' value=''></p>     <p> Email Address <input type="text" id='customerEmail' value=''></p> </form>

 

Code: Script

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 <script> function payKorapay(){     const customerName = document.getElementById('customerName') ? document.getElementById('customerName').value : null;     const customerEmail = document.getElementById('customerEmail') ? document.getElementById('customerEmail').value : null;     const customerAmount = document.getElementById('customerAmount') ? document.getElementById('customerAmount').value : null; window.Korapay.initialize({      key: 'pk_live_*********************',      amount: 1000,      currency: customerAmount, customer: { name: `${customerName}` || 'Smart Company', email: customerEmail ||'smartcompany@korapay.com' } } </script>

 

Configuration parameters

Field

Data type

Description

Field

Data type

Description

key

string

Required - Your public key from Korapay. Use the test public key for test transactions and live public key for live transactions

amount

integer

Required - Amount in naira

currency

String

Optional - Currency of the charge. Default is NGN (Nigerian Naira)

reference

string

Optional - transaction reference. If you do not provide one, a unique transaction reference would be generated for the transaction.

customer

 

Required - JSON object containing customer details

customer.name

string

Required - field in the customer object. Customer name derived from name enquiry.

customer.email

string

Required - field in the customer object. Customer email address

notification_url

string

Optional - HTTP endpoint to send information to on payment termination, success, or failure. This overrides the webhook URL set on your merchant dashboard for this particular transaction 

narration

string

Optional - Information/narration about the transaction

channels

array[string]

Optional - Methods of payment eg. Bank (bank_transfer), card(card). Default is [“bank_transfer”, “card”]

container

string

Optional - Id of HTML element you want the payment gateway to be contained in. Note that this would reset all styling on this element. The payment gateway would be resized to fit the container. If this is not set, the payment gateway fills the available screen size.

onClose

[Function]

Optional - function to be called when the payment gateway is closed

onSuccess

[Function]

Optional - function to be called when the payment is completed successfully 

onFailed

[Function]

Optional - function to be called when the payment failed

onTokenized

[Function]

Optional - function to be called when card tokenization is completed successfully 

onPending

[Function]

Optional - sometimes, bank transfers could take some time before they get resolved. In such a case, this function would be called after 20 seconds. This could allow you manage the experience for your customer by showing a notification or some other information.

 

Interacting with the Collections Modal

Through the Korapay Collections script

When the Collections Modal is called through the Korapay collections script as explained above. The Collections modal is opened in an iframe to ensure security. Some functions are exposed to interact with the modal when specific events occur during a transaction.

These are:

Event

Field

Event

Field

successful transaction

onSuccess

failed transaction

onFailed

payment modal closed

onClose

card tokenized

onTokenized

bank transfer pending

onPending

You can pass in functions to these fields while calling Korapay.initialize as shown in the script below.

Code: Script

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 <script>     function payKorapay() {         window.Korapay.initialize({             key: "pk_juigfweofyfewby732gwo8923e",             amount: 3000,             currency: "NGN",             customer: { name: "John Doe", email: "john@doe.com", phone: '08155687638' }, onClose: function () { // Handle when modal is closed }, onSuccess: function (data) { // Handle when payment is successful }, onFailed: function (data) { // Handle when payment fails } ...         });     } </script>

The data returned should have the following fields. Note that no data is returned for the onPending function as the transaction is not yet completed:

Field

Data Type

Description

Field

Data Type

Description

amount

string

Transaction amount

reference

string

Transaction reference

status

string

Transaction status.

To close the modal programmatically, use the Korapay.close function.

Through the Checkout URL

When a collections transaction is initialized through the Collections API, a checkout URL is returned in the response. That URL can be opened in a browser window or web view depending on the implementation of choice. To handle that, the collection modal exposes messages to the browser or web view window that can be latched on to.

When using the Korapay Collections Modal in this manner, the “Korapay” object and its functions would not be available on your browser/web view and cannot be used.

To receive those messages, you have to attach an event listener to the browser as shown in the script below. It is important that the appropriate checkout URL is passed in as an argument to ensure security and the fidelity of the messages received.

 

Code: Script

1 2 3 4 5 6 window.addEventListener('message', handleResponse, checkoutURL); function handleResponse(event) { if (typeof event.data === 'string' && (event.origin === checkoutURL)) { // Handle response } }

 

The response (event.data) returned should have the following fields:

Field

Data Type

Description

Field

Data Type

Description

result

string

Event being triggered. Could be “success”, “failed”, “close”, or “tokenised”

data

 

JSON object containing transaction details

data.amount

string

Transaction amount

data.reference

string

Transaction reference

data.status

string

Transaction status