Checkout Redirect lets you securely accept payments without having to embed the Korapay payment gateway on your website. It's fast, saves development time and comes with an extra advantage - the redirect functionality.

With the Checkout Redirect option, you can access the Korapay payment gateway by making a request from your server to our initialize charge endpoint. We would return a response that includes a Checkout URL that loads the payment gateway where your customers can make secure payments. After payment is completed the customer is returned to any URL specified by you.

Now, let's walk you through integrating Checkout Redirect. 👊🏼

1 - Collect Payment Details

Collecting details from your customer is essential to initializing and tracking the transaction. These details are passed to the initialize charge endpoint.

Please find below the request parameters for the endpoint.

2 - Initialize Transaction

After collecting the necessary payment details for the transaction. Make a POST request to our initialize charge endpoint.

https://api.korapay.com/merchant/api/v1/charges/initialize

Authorization: Bearer {SECRET_KEY} REQUIRED

This endpoint is protected by the secret key authentication mechanism. So when calling it, append your secret key to the authorization headers.

If the API call is successful, Korapay returns the following response:

{
   “status” : true,
   “message” : “Charge created successfully” ,
   “data”: {
           “reference”: “{{your transaction reference}}”,
           “checkout_url”: "https://checkout.korapay.com/reference/pay"
     }
}

You should then redirect your customer to the Checkout URL provided in the response to enable them complete their payment. Once the payment is complete or in the event of a failure, Korapay will redirect your customer to your specified redirect_url. The transaction reference will be appended as a query parameter to your redirect_url as well.

https://website_redirect_url/?reference=YOUR_REFERENCE

In a situation where noredirect_url is passed, the customer receives visual confirmation on the completion of the payment and is NOT redirected out of the current webpage.

3 - Verify the Transaction

When the transaction is completed, Korapay will redirect your customer to your specified redirect_url and send a webhook notification to the notification_url that was passed in the API request body.

Notice that along with redirecting the customer to your redirect_url, we append the transaction reference as a query parameter.

https://website_redirect_url/?reference=YOUR_REFERENCE

Korapay redirects the customer to your redirect_url when the transaction is complete, when the checkout is closed, or when the payment session ends abruptly. This allows you to take full control of your customers' payment experience by enabling you to reinitialise a new session if the current payment session ended abruptly. A perfect use case for this could be when your customer’s session mistakenly closes the payment page while waiting for confirmation of a bank transfer. The customer would be redirected to your ‘redirect_url’, so you can query the transaction status and give visual feedback when the transaction is completed rather than reinitialise another transaction.

It is expected that you retrieve the reference from the URL parameters and call our verify charge endpoint to get the status of the transaction. Make sure to always call direct endpoints from your server, and not from the client-side (frontend) of your application.

🚧

Heads up!

It is very important to confirm the status of the transaction before you give value to the customer.

4 - Adding an Event Listener (Optional - for better control)

Before we redirect the customer to your redirect URL, the payment gateway exposes events to the browser. To receive those events, you have to attach an event listener to the browser window as shown in the script below. To ensure security and the fidelity of the messages received, it is important that the appropriate Checkout URL gotten from the initialize endpoint is passed as an argument when attaching an event listener to the browser window.

window.addEventListener(type, handleResponse, checkoutURL);
function handleResponse(event) {
    if (event.origin === checkoutURL) {
        // Handle response
    }
}
// ‘type’ represents the transaction event type and could be one of the following: ‘success’, ‘failed’, ‘pending’, ‘close’.

The response {event.detail} returned should have the following fields:

5 - Receive confirmation via webhook

When the payment is successful, we make a POST request to your webhook URL (as set up in your dashboard or while initializing the transaction using the key: notification_url). This is the format of the response:

{
  "event":  "charge.success" // the notification is only sent for successful charge,
  "data": {
    "reference": "9965128", // the unique transaction reference
    "currency": "NGN",
    "amount": 100000,
    "fee": 1075,
    "status": "success",
    "payment_method": "bank_transfer", // can be bank_transfer, card, pay_with_bank
    "payment_reference": "9965128" // DEPRECATED the unique transaction reference
  }
}