Learn how to integrate our APIs into your application.

API Basics

Set up in minutes. Get secure payments, configurable shipping options, and more, out of the box – for free.

The IcadPay API lets you access all the features you use from your dashboard through a beautiful restful API that is easy to extend and sync with database.

Before you can start integrating ICADPAY, you need a IcadPay account, Create a free account now if you haven’t already.

While testing our API, use https://icadpay.com as your base URL. Always remember that all request to the API must be via https

To proceed with integrating any of our services, you will need to create your corporate profile by visiting https://icadpay.com/.

Creating your profile gives you access to your test credentials for integration on the staging environment. Before you start reading the documentation, you should obtain your demo and live API keys from your account Settings.

A redirect(callback) url provided via you merchant account will be triggered upon completing the transaction. The transaction ref along with the status of the transaction will be passed to this redirect url. Redirect(callback) url can also be provided in your request payload. With which, you can verify the final state of the transaction by calling our Transaction verification endpoint https://app-service.icadpay.com/api/query-status with the provided transaction_id in the URL

Payment HTML

  
    
		
		<script src="https://pay-service.icadpay.com/host/new-inline-stage-pay.js"> </script>
			<div style="display: flex; justify-content: center;;background: #00000059; height: 100vh;">
			<form  style="display: flex; flex-direction: column; gap: 10px; width: 450px; margin-top: 50px;" id="payment-form">
				<input type="text" style="padding: 15px 20px; border-radius: 10px; border: none;" class="form-control" id="firstName" placeholder="Enter First Name" name="firstName">
				<input type="text" style="padding: 15px 20px; border-radius: 10px; border: none;" class="form-control" id="lastName" placeholder="Enter Last Name" name="lastName">
				<input type="text" style="padding: 15px 20px; border-radius: 10px; border: none;" class="form-control" id="email" placeholder="Enter Email" name="email">
				<input type="text" style="padding: 15px 20px; border-radius: 10px; border: none;" class="form-control" id="phone" placeholder="Enter Phone" name="phone">
				<input type="text" style="padding: 15px 20px; border-radius: 10px; border: none;" class="form-control" id="narration" placeholder="Enter Narration" name="narration">
				<input type="text" style="padding: 15px 20px; border-radius: 10px; border: none;" class="form-control" id="amount" placeholder="Enter Amount" name="amount">
				<input type="button" style="padding: 15px 20px; border-radius: 10px; border: none; background-color: #15089c; color: #ffffff;" value="Submit" button class="button" onclick="iCadPay()"/>
			</form>
			</div>
		

<script>
	function iCadPay() {
	const form = document.getElementById("payment-form");
	const handler = IcadPay.setup({
		key: 'test_YzA1MmNmYzE0OTc1Y2QyM2ViNWUwNTIxOGMzZjA2MjI5N2M4ZDU3YmY5ZDg1ZmU1OWIwNWE1NDU0YjkzYTZkOQ', //this is a demo key.
		email: document.getElementById("email").value, // customer email 
		amount: document.getElementById("amount").value,  // amount to be processed
		currency: "NGN", // currency
		first_name: document.getElementById("firstName").value, 
		last_name: document.getElementById("lastName").value,
		phone_number: document.getElementById("phone").value, // customer's phone number (optional)
		customerId: document.getElementById("email").value,
		ref: ` ${Math.floor((Math.random() * 1000000000) + 1)}`, // generates a pseudo-unique reference. Please replace with a reference you generated. Or remove the line entirely so our API will generate one for you
		narration: document.getElementById("narration").value,
		callback_url: 'https://icadpay.com', // specified redirect URL (optional)
		meta: { // optional parameters
			consumer_id: 'data.customer_id',
			item_ref: 'payment.res',
		    },
			callback: (response) => {
			console.log(response);
			},
		onSuccess: (response) => {
			console.log(response);
			// alert(`success. transaction ref is ${response.paymentReference}`);
			// alert('Success');
		},
		onError: (response) => {
			console.log(response);
			alert('Error');
		},
		onClose: () => {
			console.log('window closed');
			// alert('window closed');
		}
	});
	}
</script>

Verify Transaction

  
    "curl -X GET": "https://staging-api.icadpay.com/api/stage/query-status?transactionRefId=201232324482713&key=test_YzA1MmNmYzE0OTc1Y2QyM2ViNWUwNTIxOGMzZjA2MjI5N2M4ZDU3YmY5ZDg1ZmU1OWIwNWE1NDU0YjkzYTZkOQ" -H  "accept: */*",

Verify Transaction Response

 {
   "requestSuccessful": true,
   "responseData": {
   "id": 5055,
   "transactionId": "17a2d9a2ba4540e9b3484e445979609f",
   "transactionRef": "593295764586462NZZQA", 
   "status": "SUCCESSFUL",
   "customerName": "Yakubu Emmanuel",
   "customerEmail": "customer@mail.com", 
   "customerPhone": "+2348000000000",
   "amountPaid": 4,
   "transactionDate": "2024-12-16T13:24:06", 
   "paymentReference": "GTB|API|27-01-2025|386436605|521001", 
   "subAccountId": 0,
   "cardType": "MasterCard",
   "exPaymentChannel": null, 
   "narration":"Parcel Shipping",
   "meta": { //Extral data parameters passed at point of payment
      "consumer_id": "4", 
      "item_ref": "6456505253",
	}
  }
 }

Here you have a test Card for testing out the solution at your end.

Test Card Details

	  
	  Card PAN: 5060990580000217499
	  Expiry Date: 05/30
	  PIN: 1111
	  CVV: 111
	  

Webhook Notifications for New Transactions

Every time a transaction is processed, a webhook is automatically triggered to notify the appropriate system. For this notification to be delivered successfully, merchants must provide a dedicated webhook URL. This URL serves as the destination for receiving transaction updates.

Merchants can easily configure their webhook URL and secret Key by navigating to the settings section within their dashboard after signing in. By setting up this unique URL, they ensure that their system stays updated with real-time transaction information.

Sample Webhook Payload

Below is an example of the webhook response payload:

 {
   "Event": "TRANSACTION.COMPLETED",
   "Timestamp": "1738016388034", 
   "Data":{
   "TransactionId": "638736167879346594",
   "PaymentReference": "GTB|API|27-01-2025|386436605|521001",
   "amountPaid": 0.0,
   "TotalAmount": 100.0,
   "Status": "Approved by Financial Institution",
   "transactionDate": "2025-01-27T23:19:48.0222373+01:00", 
   "customerName": "Yakubu Emmanuel",
   "customerEmail": "customer@mail.com", 
   "customerPhone": "+2348000000000",
   "MerchantId": 0000,
   "Narration": 'API TEST',
   "MerchantTransactionRef": "SP2448212721213",
   "Channel": WEB,
   "Fee": 0.0,
   "FeeBearer": "Merchant",
   "CustomerIpAddress": "127.0.0.1",
        }
   
 }