Checkout Standard

Checkout Standard provides a simplified and secure flow for collecting payments from customers. It's easy to integrate.

The check-out standard option can be integrated such that your application displays our payment modal allowing your customers to complete their transactions by entering their payment information.

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. Email, name, and amount are required.

Please find below the request parameters for the endpoint.

Field	Data Type	Required	Description
key	string	Required	Your public key
currency	string	Optional	The currency in which the customer should be charged. Available currencies: [NGN, KES, UGX, GHS, ZAR]
customer	object	Required	The JSON object containing the customer name, email, and phone number
customer.name	string	Required	The name of the customer
customer.email	string	Required	The email of the customer
customer.PhoneNumber	string	Optional	The phone number of the customer
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	Required	Include any information you'd want to send to Fincra in this object. e.g metadata: {userId: "my_user_id" }
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
onSuccess	[Function]	Optional	A function that executes any action you want to perform when the transaction is successful, can be a success message or a redirect Url.
onClose	[Function]	Optional	Javascript function that is called if the customer closes the payment modal instead of making a payment
paymentMethods	array	Optional	The payment method you want to make available to your customers E.g, Bank (bank_transfer), card (card), payAttitude.
defaultPaymentMethod	string	Optional	The Payment method that should be active by default on the checkout page E.g bank_transfer, card, payAttitude.

If you already have the client information recorded in your database, you can retrieve it from there, or through a form like the one below:

<form id="payment-form">
  <div class="form-group">
    <label for="name"> Name</label>
    <input type="text" id="name" required />
  </div>
  <div class="form-group">
    <label for="email">Email Address</label>
    <input type="email" id="email" required />
  </div>
  <div class="form-group">
    <label for="phoneNumber">Phone Number</label>
    <input type="number" id="phoneNumber" required />
  </div>
  <div class="form-group">
    <label for="amount">Amount</label>
    <input type="tel" id="amount" required />
  </div>
  <div class="form-submit">
    <button type="submit" id="submit-button"> Pay </button>
  </div>
</form>
<script src="https://unpkg.com/@fincra-engineering/[email protected]/dist/inline.min.js"></script>

Note : The Fincra inline javascript is included using a script tag. This is how you import Fincra Checkout into your code. The Pay button has been tied to an onClick function called payFincra. This is the action that causes the Fincra popup to load.

2 - Initiate Payment

When you have all of the information needed to begin the transaction, you must connect it to the javascript function that sends it to Fincra and displays the checkout popup modal.

const paymentForm = document.getElementById('payment-form');
     paymentForm.addEventListener("submit", payFincra, false);
function payFincra(e) {
     e.preventDefault();
       Fincra.initialize({
         key: "pk_##########",
         amount: parseInt(document.getElementById("amount").value),
         currency: "NGN",
         customer: {
             name: document.getElementById("name").value,
             email: document.getElementById("email").value,
             phoneNumber: document.getElementById("phoneNumber").value,
           },
        //Kindly chose the bearer of the fees
        feeBearer: "business" || "customer",
 
         onClose: function () {
           alert("Transaction was not completed, window closed.");
         },
         onSuccess: function (data) {
           const reference = data.reference;
    alert("Payment complete! Reference: " + reference);
         },
       });
     }

Take note of the following:

The key field here takes your Fincra public key.
The amount field here is the amount to be collected.

3 - Receive and validate webhook notification

Listen for webhook events. We will send a notification to your webhook URL that indicates the status of the conversion. 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",
  "data": {
    "id": 4704,
    "authorization": {
      "mode": null,
      "redirect": null,
      "metadata": null
    },
    "auth_model": null,
    "amount": 1725.59,
    "amountReceived": 1725.59,
    "currency": "NGN",
    "fee": 25.58,
    "vat": 1.78,
    "message": “”,
    "status": "success",
    "reference": "fcr-p-5b7a603c01",
    "description": "checkout",
    "type": "bank_transfer",
    "customer": {
      "name": "Taofiq Taofiq",
      "email": "[email protected]",
      "phoneNumber": null
    },
    "metadata": {
      "id": 209,
      "name":"Testing",
      "amount": 1700,
      "currency": "NGN",
      "disabled": false,
      "metadata": null,
      "shortUrl": null,
      "createdAt":"2023-07-27T09:14:31.636Z",
      "customUrl": null,
      "deletedAt": null,
      "feeBearer": "customer",
      "reference": "89c512379b98a7876923e",
      "updatedAt": "2023-07-27T09:14:31.636Z",
      "businessId": "200ab2015e137543357df000",
      "description": "Testss",
      "redirectUrl": null,
      "isAmountFixed": false,
      "successMessage": null,
      "collectPhoneNumbers": false,
      "settlementDestination":"wallet"
    },
    "settlementDestination": "wallet",
    "virtualAccount": {
      "bankName": "wema",
      "bankCode": "035",
      "accountName": "FIN-Tega and Sons",
      "accountNumber": "7946814353",
      "sessionId": "2322",
      "channelName": "wema",
      "payerAccountNumber": "7820444125",
      "payerAccountName": "Taofiq Taofiq",
      "payerBankName": "gtb",
      "payerBankCode": "042",
      "expiresAt": "2023-08-11T09:12:34.000Z"
    },
    "amountToSettle": 1700,
    "chargeReference": "fcr-bt-3e02354cc0b00d61e"
  }
}

Webhook Response

The webhook response is explained in detail here.

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
data.fee	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 always, 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