Konnect logo
Documentation Powered by ReDoc

Gateway API (0.23.0)

Overview

Konnect provides an easy payment experience for your customers and an easy integration process for the developers. Payment process works by initializing Payment Requests and then the customers accepting those Payment Requests.

  1. Create payment request URLs, each request has a unique Payment Reference.
  2. Your customers have the choice to specify their payment methods.
  3. You receive the payment confirmation with a unique Payment ID.

Setup

  1. Create an account on https://dashboard.sandbox.konnect.network for testing
  2. Create an account on https://dashboard.konnect.network to start accepting payments
  3. Create an organisation
  4. Copy the wallet key from the organisation dashboard
  5. generate an api key from organisation dashboard
  6. Use your wallet & api key to initiate and receive payments

Environments

It is highly recommended that you make the integration and test the full payment flow on our Sandbox environment before moving to Production.

Environment API URL Dashboard URL
Sandbox https://api.preprod.konnect.network/api/v2/ https://dashboard.sandbox.konnect.network
Production https://api.konnect.network/api/v2/ https://dashboard.konnect.network

Testing Payments

To test your integration on Sandbox environment you can use the following cards:

Brand Output Number Exp Date CVC
Visa Successful Payment 4509211111111119 12/26 748
MasterCard Successful Payment 5440212711111110 12/26 665
MasterCard Failed Payment 5471251111111116 11/23 858

API Key

Konnect authenticates your API requests using your organisation's API key.
Konnect raises an Unauthorized error if you don't include a key or if the key is incorrect or outdated.
It can be generated from the organisation profile in the Dashboard. Make sure you save it somewhere safe because it is accessible only once.
It has a specific format like the following example: '6137ad140c181c5eb44a7f88:Rp2dpHPb0mBpj3_51s86zzp3PXs5w1'

Payments

Init payment

This API initiates a new payment. It returns a payment link where the client can make the payment.

header Parameters
x-api-key
required
string
Example: 6137ad140c181c5eb44a7f88:Rp2dpHPb0mBpj3_51s86zzp3PXs5w1

An API key is a unique identifier for each organisation used to perform API calls to Konnect API.

Request Body schema: application/json
receiverWalletId
required
string

The konnect wallet id of the payment receiver. Your Wallet ID is accessible on the dashboard.

token
string
Enum: "TND" "EUR" "USD"

The currency of the payment.
When token is different from TND, we will handle conversion ourlselves so the receiver gets paid in TND.

amount
required
number

The amount to be paid (in Millimes for TND / Centimes for EUR and USD).

type
string
Enum: "immediate" "partial"

The type decides if the payment could be paid partially (partial) or should be paid all at once (immediate).

description
string

A description you can add to the payment. It will be seen by the payer in the gateway payment page.

acceptedPaymentMethods
Array of strings
Default: ["wallet","bank_card","e-DINAR"]
Items Enum: "wallet" "bank_card" "e-DINAR" "flouci"

An array containing the payment methods you wish to get paid with

lifespan
number

Duration before the payment expires, in minutes.

checkoutForm
boolean

Ask the payer to fill a checkout form before payment.

addPaymentFeesToAmount
boolean
Default: false

Ask the client to pay an extra amount to cover Konnect fees. This will slightly raise the amount of the payment from the payer side.

firstName
string

The first name of the payer

lastName
string

The last name of the payer

phoneNumber
string

The phone number of the payer

email
string

The email of the payer

orderId
string

An identifier that you can give to this order.

webhook
string

When the payment is done, Konnect system will send a request to your system on
GET WEBHOOK/payments?payment_ref=paymentId

silentWebhook
boolean

If this is true, Konnect will make the call to the webhook without redirecting the payer to the webhook URL.

successUrl
string

A URL to redirect the user to when the payment succeeds.
This will be ignored if the webook is activated and not set to silent.

failUrl
string

A URL to redirect the user to when the payment fails.
This will be ignored if the webook is activated and not set to silent.

theme
string
Default: "light"
Enum: "dark" "light"

Theme for the payment gateway

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Get Payment details

To know whether the payment was done successfully, you should check the payment status and the transaction status:

  • payment.status is "completed" => The payment was successful
  • payment.status is "pending" => The payment has failed or not attempted yet
path Parameters
paymentId
string
Example: 5e68ed190a43a43998c6eeba

The ID of the payment

Responses

Response samples

Content type
application/json
{
  • "payment": {
    }
}

Webhook

Once the payment is done, your system will be notified by a call from our server on the webhook. The request you will get is a GET request on https://your_webhook.com?payment_ref=PAYMENT_ID For example:
https://www.monsite.tn/module/konnect/webhook?payment_ref=5f9498735289e405fc7c18ac

If you are handling this on your server side and you don't wish your client to be redirected to the webhook,
you can change that by setting the silentWebhook parameter to true when you call /init-payment. Once you access the payment_ref from the request query params of the webhook request, you'll be able to use it to fetch the status of the payment. You can do that by calling GET https://konnect.network/api/v2/payments/payment_ref

Prestashop

You can activate online payment in your Prestashop e-commerce website with Konnect!
You can get access to our addon from this link.

Wordpress

If you are looking to accept payments on your Wordpress website, Konnect is here for you!
You can get our Woocommerce plugin from this link.

WHMCS

Konnect allows you to activate online payments for your WHMCS website.
You can get our plugin from this link.