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.

FieldData TypeRequiredDescription
keystringRequiredYour public key
currencystringOptionalThe currency in which the customer should be charged. Available currencies: [NGN, KES, UGX, GHS, ZAR]
customerobjectRequiredThe JSON object containing the customer name, email, and phone number
customer.namestringRequiredThe name of the customer
customer.emailstringRequiredThe email of the customer
customer.PhoneNumberstringOptionalThe phone number of the customer
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.
metadataobjectRequiredInclude any information you'd want to send to Fincra in this object.
e.g metadata: {userId: "my_user_id" }
settlementDestinationstringOptionalSettlement 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]OptionalA 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]OptionalJavascript function that is called if the customer closes the payment modal instead of making a payment
paymentMethodsarrayOptionalThe payment method you want to make available to your customers E.g, Bank (bank_transfer), card (card), payAttitude.
defaultPaymentMethodstringOptionalThe 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.

eventThe Webhook event
typeThe type of transaction
dataThe data object
data.methodThe payment method e.g card, bank transfer
data.paymentReference
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
data.feeThe fee charged for the transaction
data.feeBearerThe bearer of the fees
data.statusThe status of the transaction
data.settlementDestinationThe settlement destination. This is always, wallet
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