Finecore

Appearance

Payment Gateway ​

This API allows processing of payments via Card, USSD, and Bank Transfer (Dynamic Account). Each folder represents a payment method, with multiple endpoints for handling transactions, approvals, and verification.

Finecore Checkout Integration Guide ​

Overview ​

Finecore Checkout makes it easy for developers and businesses to accept payments through a simple, secure, and customizable modal — no complex setup required.

You can integrate it in minutes by embedding a single script and initializing the payment modal with your API key and transaction details.

Include Finecore Checkout Script ​

Copy and paste this script inside your HTML before the closing tag:

html
<script src="https://checkout.finecore.co/finecore_pay.js"></script>

This script automatically attaches the FinecorePay object to your window.

Initialize and Open the Payment Modal ​

Add the following JavaScript code to your site or app:

html
<script>
  function payWithFinecore() {
    window.FinecorePay.open({
      key: "flk_xxxxxxxxxxxxxx", // Replace with your Finecore public key
      amount: 5000, // Amount in kobo (₦50.00)
      reference: "FC_" + new Date().getTime(), // Unique transaction reference
      metadata: {
        name: "John Doe",
        phone: "+2348012345678",
        email: "customer@example.com",
      },
      onSuccess: function (response) {
        console.log("Payment successful:", response);
        alert("Payment successful! Reference: " + response.reference);
      },
      onClose: function () {
        console.log("Payment modal closed.");
      },
    });
  }
</script>

Add a Payment Button ​

html
<button onclick="payWithFinecore()">Pay Now</button>

When the user clicks the Pay Now button, the Finecore Checkout modal opens, allowing them to complete payment using their preferred method.

How It Works ​

  1. The FinecorePay script securely loads your payment modal.
  2. The modal connects to Finecore servers and processes payments via your provided key and reference.
  3. Once payment is completed, the onSuccess callback returns the transaction details.
  4. You can verify the payment on your backend using the reference ID.

Initiate Payment with card ​

Starts a card payment. Depending on the card type, the transaction may require OTP or 3DS authentication.

Method: POST ​

{{BASE_URL}}/payments/card

Headers ​

Content-TypeValue
X-API-KeyX-API-Key

Body (raw) ​

json
{
  "amount": 10000.0,
  "currency": "NGN",
  "reference": "txn_20231201_001",
  "metadata": {
    "someData": "someData"
  },
  "card_details": {
    "pan": "5123450000000008",
    "expiry_date": "3901",
    "cvv": "100",
    "pin": "1111"
  }
}

Response: 201 ​

Response example:
json
{
  "success": true,
  "message": "A verification code has been sent to your registered mobile number:234805***1111",
  "data": {
    "transaction_reference": "txn_20231201_0015",
    "requires_authentication": true,
    "auth_type": "OTP",
    "message": "A verification code has been sent to your registered mobile number:234805***1111",
    "next_action": "submit_otp"
  }
}

Response: 201 ​

Response example:
json
{
  "success": true,
  "message": "Please complete the secure authentication process with your bank",
  "data": {
    "transaction_reference": "txn_20231201_0029",
    "requires_authentication": true,
    "auth_type": "3DS",
    "message": "Please complete the secure authentication process with your bank",
    "next_action": "redirect_3ds",
    "payment_id": "474982513",
    "bank_code": "058",
    "acs_url": "https://qa.interswitchng.com/collections/wibmosecure",
    "term_url": "http://localhost:6081/collections/api/v1/pay/wibmoCallBack",
    "md": "474982513",
    "jwt": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjRkMDVlYmY1LTJjYzMtNGIzNS05MDkyLWIyMmE0YzMxYTAxNyIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJodHRwczovLzNkczItYXBpLTNkc3NlcnZlci1pbnRnLnBjLmVuc3RhZ2Utc2FzLmNvbS93cmFwcGVyYXBpL2Flcmlvbi8zZHNzL2VtdmNvL3BBcnEvMzg3MTQ1ZDQtMGM5MC00OTI0LWFiYTYtMmViMTMyNGZlOWE1In0=",
    "eci_flag": "07"
  }
}

Approve Card Payment ​

Approves card payment using OTP received.

Method: POST ​

{{BASE_URL}}/payments/card/approve

Headers ​

Content-TypeValue
X-API-KeyX-API-Key

Body (raw) ​

json
{
  "otp": "123456",
  "transaction_reference": "txn_20231201_0020"
}

Response: undefined ​

Response example:
json
{
  "success": true,
  "message": "Approved by Financial Institution",
  "data": {
    "transaction_reference": "txn_20231201_0020",
    "message": "Approved by Financial Institution",
    "status": "COMPLETED",
    "amount": "10000.00"
  }
}

Response: undefined ​

Response example:
json
{
    "success": true,
    "message": "Approved by Financial Institution",
    "data": {
        "transaction_reference": "txn_20231201_0020",
        "message": "Approved by Financial Institution",
        "status": "COMPLETED",
        "amount": "10000.00"
    }

Resend OTP For Payment With Card ​

Resends OTP if the user did not receive it.

Method: POST ​

{{BASE_URL}}/payments/card/resend-otp

Headers ​

Content-TypeValue
X-API-KeyX-API-Key

Body (raw) ​

json
{
  "transaction_reference": "txn_20231201_0024"
}

Response: 201 ​

Response example:
json
{
  "success": true,
  "message": "A verification code has been sent to your registered mobile number: 234805***1111",
  "data": {
    "transaction_reference": "txn_20231201_0024",
    "requires_authentication": true,
    "auth_type": "OTP",
    "message": "A verification code has been sent to your registered mobile number: 234805***1111",
    "next_action": "submit_otp"
  }
}

Initiate Payment With USSD ​

Starts a USSD payment by generating a code for the user to dial.

Method: POST ​

{{BASE_URL}}/payments/ussd

Headers ​

Content-TypeValue
X-API-KeyX-API-Key

Body (raw) ​

json
{
  "amount": "100",
  "bank_code": "GTB",
  "currency_code": "566",
  "transaction_reference": "TX1R69HAAEAEYVTD1UEY93O4",
  "sursurge": 5,
  "metadata": {
    "someData": "some kind of object"
  }
}

Response: 201 ​

Response example:
json
{
  "success": true,
  "message": "USSD payment initiated",
  "data": {
    "bank_short_code": "*737*000*3865#",
    "default_short_code": "*322*419*051691201*3865#",
    "reference": "3865",
    "response_code": "00",
    "transaction_reference": "bn12222z2aaz"
  }
}

Get USSD Banks ​

Method: GET ​

{{BASE_URL}}/payments/ussd/banks

Headers ​

Content-TypeValue
X-API-KeyX-API-Key

Body (raw) ​

json
{
  "amount": 10000.0,
  "currency": "NGN",
  "reference": "txn_20231201_001",
  "metadata": {
    "someData": "someData"
  },
  "card_details": {
    "pan": "5123450000000008",
    "expiry_date": "3901",
    "cvv": "100",
    "pin": "1111"
  }
}

Response: 201 ​

Response example:
json
{
  "success": true,
  "message": "USSD Banks successfully retrieved",
  "data": [
    {
      "cbn_code": "ABP",
      "code": "ABP",
      "name": "Access Bank"
    },
    {
      "cbn_code": "DBP",
      "code": "DBP",
      "name": "Diamond Bank"
    },
    {
      "cbn_code": "ECO",
      "code": "ECO",
      "name": "Ecobank"
    },
    {
      "cbn_code": "FBP",
      "code": "FBP",
      "name": "Fidelity Bank"
    },
    {
      "cbn_code": "SBP",
      "code": "SBP",
      "name": "First"
    },
    {
      "cbn_code": "FBN",
      "code": "FBN",
      "name": "First Bank"
    },
    {
      "cbn_code": "GTB",
      "code": "GTB",
      "name": "Guarantee Trust  Bank"
    },
    {
      "cbn_code": "KSB",
      "code": "KSB",
      "name": "Keystone Bank"
    },
    {
      "cbn_code": "QUICKTELLER",
      "code": "QUICKTELLER",
      "name": "QUICKTELLER"
    },
    {
      "cbn_code": "SKYE",
      "code": "SKYE",
      "name": "Skye Bank"
    },
    {
      "cbn_code": "JAIZ",
      "code": "JAIZ",
      "name": "Test Bank"
    },
    {
      "cbn_code": "IBTC",
      "code": "IBTC",
      "name": "Test USSD"
    },
    {
      "cbn_code": "UBP",
      "code": "UBP",
      "name": "Test USSD"
    },
    {
      "cbn_code": "WEMA",
      "code": "WEMA",
      "name": "Test USSD"
    },
    {
      "cbn_code": "HBP",
      "code": "HBP",
      "name": "Test USSD"
    },
    {
      "cbn_code": "FCMB",
      "code": "FCMB",
      "name": "Test USSD"
    },
    {
      "cbn_code": "UBN",
      "code": "UBN",
      "name": "Union Bank"
    },
    {
      "cbn_code": "UBA",
      "code": "UBA",
      "name": "United Bank for Africa"
    },
    {
      "cbn_code": "ZIB",
      "code": "ZIB",
      "name": "Zenith Bank"
    }
  ]
}

Get USSD Bank By Code ​

Method: GET ​

{{BASE_URL}}/payments/ussd/banks/:code

Headers ​

Content-TypeValue
x-api-keyX-API-Key

Response: 201 ​

Response example:
json
{
  "success": true,
  "message": "USSD Bank successfully retrieved",
  "data": { "name": "Heritage Bank", "code": "HBP", "cbn_code": "HBP" }
}

Generate Virtual Account (Dynamic) ​

Generates a unique account number for a user to receive payments.

Method: POST ​

{{BASE_URL}}/payments/virtual-account/generate

Headers ​

Content-TypeValue
X-API-KeyX-API-Key

Body (raw) ​

json
{
  "amount": "100",
  "currency_code": "566",
  "provider": "WEMA",
  "transaction_reference": "TX3XIW7WYY11QQQP97UJ22IJO270",
  "metadata": {
    "someData": "some kind of object"
  }
}

Response: 201 ​

Response example:
json
{
  "success": true,
  "message": "Virtual account created",
  "data": {
    "account_name": "Quickteller Business Payment",
    "account_number": "7610665773",
    "amount": 10000,
    "bank_name": "Wema Bank",
    "provider": "WEMA",
    "response_code": "Z0",
    "transaction_reference": "bn1yy2222z2aAaz",
    "validity_period_mins": 30
  }
}