Checkout Redirect

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.

Let's get started.

1 - Collect Payment Details

To initialize 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.

FieldData typeRequiredDescription
amountintegerRequiredThe amount to charge the customer.
redirectUrlstringOptionalThe URL to redirect your customer when the transaction is complete.
currencystringRequiredThe currency in which the customer should be charged. Only NGN is available for now.
referencestringOptionalYour transaction reference. Must be unique for every transaction.
If you do not provide one, a unique transaction reference would be generated for the transaction.
feeBearerstringRequiredThis 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
metadataobjectOptionalInclude any information you'd want to send to Fincra in this object.
e.g metadata: {userId: "my_user_id" }
customerstringRequiredJSON object containing customer details
customer.namestringRequiredThe name of the customer
customer.emailstringOptionalThe email of the customer
customer.phoneNumberstringOptionalThe mobile number of the customer
successMessagestringOptionalThe message you want customers to see after successful payment.
settlementDestinationstringOptionalSettlement destination is where you want the payments to be settled. It can either be a wallet or bank account. By default the settlement destination is your Fincra wallet.
Values for settlementDestination can be wallet and bank_account
paymentMethodsarrayOptionalThe payment method you want to make available to your customers E.g, Bank (bank_transfer), card (card).
defaultPaymentMethodstringOptionalThe 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 initialize checkout endpoint.

Note : Before making a post request, the public key should be specified in the header.

-H "x-pub-key: your_public_key".

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

   “status” : true,
   “message” : “Payment transaction initiated” ,
   “data”: {
           “reference”: “eyza908ne”,
           “link”: ""

Note: The above reference is not the same as the reference specified in the payment details

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, 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

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

event: "charge.successful", 
type: "charge", 
  data: {
    businessId: "56f591092ceb1ad21ef",
    method: "card",
    paymentReference: "6df5910e1bdde31abf",
    transactionReference: "5f5910e1bdde31abfe",
    amount: 500.42,
    amountToSettle: 500,
    fee: 0.42,
    feeBearer: "customer",
    status: "success",
    settlementDestination: "wallet",
    currency: "NGN",
    customer: { name: "John Thomas", email: "[email protected]", phoneNumber: null },
    metadata: { reference: "my_reference", userId: "my_user_id" },
    createdAt: "@timestamp",
    updatedAt: "@timestamp",

Webhook Response

The webhook response is explained in detail here.

eventThe Webhook event
typeThe type of transaction
dataThe data object
data.methodThe payment method e.g card, bank transfer
data.transactionReferenceThe unique reference generated for the transaction
data.merchantReferenceThe reference the merchant included while initiating the transaction. This is the reference of the transaction on the merchant's application
data.amountThe amount the customer paid
data.amountToSettleThe amount the merchant receives
datafeeThe fee charged for the transaction
data.feeBearerThe bearer of the fees
data.statusThe status of the transaction
data.settlementDestinationThe settlement destination. This is either wallet or bankAccount
data.currencyThe currency in which the payment was made
data.customerThe customer. This is an object that contains the name , email and phoneNumber of the customer
data.metadataThe extra information included in the transaction
data.createdAtThis is the timestamp the transaction was created
data.updatedAtThis is the timestamp the transaction was updated