Checkout Redirect
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.
Parameter | Data Type | Description |
---|---|---|
amount | Integer | Required - The amount to charge the customer. |
redirect_url | String | Optional - The URL to redirect your customer when the transaction is complete. |
currency | String | Required - The currency in which the customer should be charged. For example; NGN, KES, GHS, etc. |
reference | String | Required - Your transaction reference. Must be unique for every transaction. |
notification_url | String | Optional - The webhook URL to be called when the transaction is complete. |
narration | String | Optional - This is the transaction description. |
channels | Array [String] | Optional - Methods of payment eg. Bank Transfer (bank_transfer), card (card), Pay with Bank (pay_with_bank), Mobile money (mobile_money). If only one payment method is available, the customer cannot change to another payment method. |
default_channel | String | Optional - Method of payment that should be active by default. E.g Bank Transfer (bank_transfer), card (card), Pay with Bank (pay_with_bank), Mobile money (mobile_money). The payment method selection page is skipped on the first load. Note that the default channel must also be specified in the channels parameter. |
metadata | Object | Optional - It takes a JSON object with a maximum of 5 fields/keys. Empty JSON objects are not allowed. Each field name has a maximum length of 20 characters. Allowed characters: A-Z , a-z , 0-9 , and - . |
customer | Required - This is the JSON object containing the targeted customer information. | |
customer.email | String | Required - The email of the customer to be charged. |
customer.name | String | Optional - The name of the customer to be charged |
merchant_bears_cost | Boolean | Optional - This will set who bears the fees of the transaction. If it is set to true , the merchant will bear the fee, while if it is set to false , the customer will bear the fee. By default, it is set to true . |
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:
Field | Data Type | Description |
---|---|---|
result | string | Event being triggered. Could be success , failed , or close . |
data | object | JSON object containing transaction details |
data.amount | string | Transaction Amount |
data.reference | string | Transaction Reference |
data.status | string | Transaction Status |
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
}
}
Updated over 1 year ago