The Checkout API allows you to safely and securely receive payments from your customers. Your server calls the Create Payment API to generate a checkout link, which you then redirect your users to so they can make a payment. After making a payment, your users are redirected to your website.

Payment methods

Our checkout solution offers a gateway to various payment methods. Some of the supported methods include:

Card
Bank Transfer
Mobile money
USSD via PayAttitude

Method	API variable
Card	card
Bank Transfer	bank_transfer
Mobile money	mobile_money
PayAttitude	PayAttitude

Supported currencies for checkout

Currencies	Bank Transfer	Cards	Mobile money	USSD
KES	YES	N/A	YES	N/A
ZMW	N/A	YES	YES	N/A
UGX	YES	N/A	YES	N/A
ZAR	YES	YES	N/A	N/A
GHS	YES	N/A	YES	N/A
NGN	YES	YES	N/A	YES
USD	N/A	YES	N/A	N/A

How to use the checkout redirect API

1 - Collect Payment Details

To initialise the transaction, you'll need to pass information such as email, first name, last name, amount, transaction reference, etc.

Please find below the request parameters for the endpoint.

Field	Data type	Required	Description
amount	integer	Required	The amount to charge the customer.
redirectUrl	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. Options are [NGN, GHS, KES, UGX, ZAR, ZMW]
reference	string	Optional	Your transaction reference. Must be unique for every transaction. If you do not provide one, a unique transaction reference would be generated for the transaction.
feeBearer	string	Required	This will set who bears the fees of the transaction. If it is set to `business`, the merchant will bear the fee, while if it is set to `customer`, the customer will bear the fee. By default, it is set to `business`
metadata	object	Optional	Include any information you'd want to send to Fincra in this object. e.g metadata: {userId: "my_user_id" }
customer	string	Required	JSON object containing customer details
customer.name	string	Required	The name of the customer
customer.email	string	Required	The email of the customer
customer.phoneNumber	string	Optional	The mobile number of the customer
successMessage	string	Optional	The message you want customers to see after successful payment.
settlementDestination	string	Optional	Settlement destination is the location where you want your payments to be settled. Settlements are only to wallets (balances) for now Value for settlementDestination would be wallet
paymentMethods	array	Optional	The payment method you want to make available to your customers E.g, Bank (bank_transfer), Card (card), Mobile Money (mobile_money), Pay Attitude (payAttitude).
defaultPaymentMethod	string	Optional	The Payment method that should be active by default on the checkout page E.g bank_transfer or card

2 - Initiate Payment

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

Endpoint:

{{host}}/checkout/payments

curl --location 'https://api.fincra.com/checkout/payments' \
--header 'accept: application/json' \
--header 'api-key: <Your API secret key>' \
--header 'x-pub-key: <Your API public key>' \
--header 'Content-Type: application/json' \

Here's a sample payload to initialise a transaction:

{
    "amount": 350,
    "currency": "NGN",
    "customer":{
        "name":"Customer Name",
        "email":"[email protected]"
    },
  	"paymentMethods": ["bank_transfer", "card", "payAttitude"],
    "feeBearer":"customer",
    "reference":"your-internal-reference-id",
    "redirectUrl":"https://yoursite.com/redirect-destination"
}

{
    "amount": 350,
    "currency": "GHS",
    "customer":{
        "name":"Customer Name",
        "email":"[email protected]"
    },
  	"paymentMethods": ["mobile_money"],
    "feeBearer":"customer",
    "reference":"your-internal-reference-id",
    "redirectUrl":"https://yoursite.com/redirect-destination"
}

{
    "amount": 350,
    "currency": "KES",
    "customer":{
        "name":"Customer Name",
        "email":"[email protected]"
    },
  	"paymentMethods": ["mobile_money"],
    "feeBearer":"customer",
    "reference":"your-internal-reference-id",
    "redirectUrl":"https://yoursite.com/redirect-destination"
}

{
    "amount": 350,
    "currency": "UGX",
    "customer":{
        "name":"Customer Name",
        "email":"[email protected]"
    },
  	"paymentMethods": ["mobile_money"],
    "feeBearer":"customer",
    "reference":"your-internal-reference-id",
    "redirectUrl":"https://yoursite.com/redirect-destination"
}

{
    "amount": 350,
    "currency": "KES",
    "customer":{
        "name":"Customer Name",
        "email":"[email protected]"
    },
  	"paymentMethods": ["bank_transfer"],
    "feeBearer":"customer",
    "reference":"your-internal-reference-id",
    "redirectUrl":"https://yoursite.com/redirect-destination"
}

{
    "amount": 30,
    "currency": "ZMW",
    "customer":{
        "name":"Customer Name",
        "email":"[email protected]",
        "phoneNumber": "0961111111"
    },
  	"paymentMethods": ["mobile_money", "card"],
    "feeBearer":"customer",
    "reference":"your-internal-reference-id",
    "redirectUrl":"https://yoursite.com/redirect-destination"
}

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

{
    "status": true,
    "message": "Hosted link generated",
    "data": {
        "link": "https://checkout.fincra.com/pay/fcr-p-********",
        "payCode": "fcr-p-********"
    }
}

{
    "status": true,
    "message": "Hosted link generated",
    "data": {
        "link": "https://checkout.fincra.com/pay/fcr-p-********",
        "reference": "*********************",
        "payCode": "fcr-p-********"
    }
}

Note: When no reference is passed from your end, the payCode is used as the transaction reference.

After you get the above response, you should then redirect your customer to the checkout URL provided in the response ("link"), to enable them complete their payment. Once the payment is complete or in the event of a failure, Fincra will redirect your customer to your specified redirectUrl. The transaction reference will be appended as a query parameter to your redirectUrl as well.

e.g https://website_redirectUrl/?reference=YOUR_REFERENCE

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

3 - Verify payment

It is critical that you confirm the transaction using its reference, just because the redirectUrl was visited doesn't prove that transaction was successful. You can confirm payment by using the verify payment endpoint.

Note: It is advised that you consult the Overpayments and Underpayments doc to see how to treat such transactions. A sample response for an underpayment has been added. You would note the varianceType which marks it as an underpayment, and also the amountReceived field which tells you the true amount paid by customers in the case where bank_transfer is the payment method uses.

Endpoint:

{{host}}/checkout/payments/merchant-reference/{{reference}}

curl --location 'https://api.fincra.com/checkout/payments/merchant-reference/{{reference}}' \
--header 'accept: application/json' \
--header 'api-key: <Your API secret key>' \
--header 'x-business-id: <Your business ID>' \

Here's the api response:

{
    "status": true,
    "message": "Payment details fetched",
    "data": {
        "id": 1093510,
        "businessId": "******************",
        "paymentLinkId": null,
        "amount": 100,
        "currency": "NGN",
        "convertedAmount": 100,
        "amountReceived": 101.51,
        "convertedCurrency": "NGN",
        "paymentMethods": [
            "card",
            "bank_transfer",
            "payattitude"
        ],
        "defaultPaymentMethod": "card",
        "redirectUrl": "https://yoursite.com/redirect-destination",
        "customUrl": null,
        "successMessage": null,
        "settlementDestination": "wallet",
        "settlementTime": "instant",
        "feeBearer": "customer",
        "reference": "fcr-p-fc99410576",
        "merchantReference": "31c1169c-d535-4e0b-90eb-a03a99c2f334",
        "isDisabled": false,
        "metadata": null,
        "status": "success",
        "varianceType": null,
        "createdAt": "2024-05-16T10:31:08.680Z",
        "updatedAt": "2024-05-16T10:33:07.000Z",
        "customer": {
            "name": "Customer name",
            "email": "[email protected]",
            "phoneNumber": "2348189299860"
        },
        "amountExpected": 100,
        "message": null,
        "actionRequired": null
    }
}

{
    "status": true,
    "message": "Payment details fetched",
    "data": {
        "id": 1162018,
        "businessId": "******************",
        "paymentLinkId": null,
        "amount": 7000,
        "currency": "NGN",
        "convertedAmount": 7000,
        "amountReceived": 73,
        "convertedCurrency": "NGN",
        "paymentMethods": [
            "card",
            "bank_transfer",
            "payattitude"
        ],
        "defaultPaymentMethod": "card",
        "redirectUrl": "https://yoursite.com/redirect-destination",
        "customUrl": null,
        "successMessage": null,
        "settlementDestination": "wallet",
        "settlementTime": "instant",
        "feeBearer": "customer",
        "reference": "fcr-p-24a8b52ca5",
        "merchantReference": "15c3eb79-67de-445f-8cbe-acce91e5aca2",
        "isDisabled": false,
        "metadata": null,
        "status": "success",
        "varianceType": "underpayment",
        "createdAt": "2024-05-27T09:46:52.708Z",
        "updatedAt": "2024-05-27T09:48:06.000Z",
        "customer": {
            "name": "Customer name",
            "email": "[email protected]",
            "phoneNumber": "2348173729860"
        },
        "amountExpected": 7000,
        "message": "INCORRECT_AMOUNT",
        "actionRequired": "Process refund via dashboard/Refund API"
    }
}

4 - Receive and validate webhook notification

Listen for webhook events. We will send a notification to your webhook URL that indicates the status of the collection. Read our guide on securing and validating the webhook notification on your end.

Note: We will only send you a webhook when the transaction is successful. Also, ensure to consult our Overpayments and Underpayments doc to see how to treat when webhook for such is received.

Webhook response:

{
  "event": "charge.successful",
  "data": {
    "id": 601227,
    "authorization": {
      "mode": null,
      "redirect": null,
      "metadata": null
    },
    "auth_model": null,
    "amount": 355.27,
    "amountReceived": 200,
    "currency": "NGN",
    "fee": 3.01,
    "vat": 0.21,
    "message": "",
    "status": "success",
    "reference": "fcr-p-********",
    "description": "checkout",
    "type": "bank_transfer",
    "customer": {
      "name": "Christopher Chukwuemeka",
      "email": "[email protected]",
      "phoneNumber": null
    },
    "metadata": {},
    "settlementDestination": "wallet",
    "virtualAccount": {
      "bankName": "globus",
      "id": "*************************",
      "bankCode": "103",
      "accountName": "Fincra DevRel",
      "accountNumber": "3994698574",
      "sessionId": "100006231127112001938859294368",
      "channelName": "globus",
      "payerAccountNumber": "***********",
      "payerAccountName": "*************************",
      "payerBankName": "***********",
      "payerBankCode": null,
      "expiresAt": "@timestamp",
      "business": "*********************"
    },
    "amountToSettle": 196.99,
    "chargeReference": "fcr-bt-************"
  }
}

Webhook Response

The webhook response is explained in detail here.

Data	description
event	The Webhook event
type	The type of transaction
data	The data object
data.method	The payment method e.g card, bank transfer
data.paymentReference
data.transactionReference	The unique reference generated for the transaction
data.merchantReference	The reference the merchant included while initiating the transaction. This is the reference of the transaction on the merchant's application
data.amount	The amount the customer paid
data.amountToSettle	The amount the merchant receives
datafee	The fee charged for the transaction
data.feeBearer	The bearer of the fees
data.status	The status of the transaction
data.settlementDestination	The settlement destination. This is by default, wallet
data.currency	The currency in which the payment was made
data.customer	The customer. This is an object that contains the name , email and phoneNumber of the customer
data.metadata	The extra information included in the transaction
data.createdAt	This is the timestamp the transaction was created
data.updatedAt	This is the timestamp the transaction was updated