This API specification helps you create a virtual account and also integrates payment reconciliation for your customers.
You can also trace payments to virtual accounts and link them up with customer details.
Reconciliation:For instant settlement when using our Virtual Account, All merchant and beneficiary accounts must be GTCO Bank Accounts.
Creating Virtual Account
You need to make a POST Request to a dedicated endpoint containing your customer information.
IMPORTANT NOTICE
Kindly share your preferred prefix with your Technical Account Manager to configure before going Live. The prefix must be a portion of your business name or an abbreviation of your business name as one word.
Customer Model
This endpoint is used to create virtual accounts for individuals/customers on your platform. Please note that there is a strict validation of the BVN against the names, Date of Birth and Phone Number. (B2C)
The implication of this is that if any of the details mentioned above doesn't tally with what you have on the BVN passed, an account will not be generated.
Please note that you can create virtual accounts for individuals regardless of the type of bank you provided during KYC.
{
"status": 401,
"success": false,
"message": "Merchant has been restricted, please contact Habaripay support",
"data": {}
}
{
"success": false,
"message": "",
"data": {}
}
{
"status": 424,
"message": "{"status":424,"success":false,"message":"Identity verification failed. Kindly pass a valid Id to continue","data":{}}",
"data": null
}
Business Model
This API allows you to create virtual accounts for your customers who are businesses and not individuals. That is, these customers are actually businesses (B2B) or other merchants.
Please note that due to CBN's Guidelines on validation before account creation as well as other related Fraud concerns, you are required to request for profiling before you can have access to create accounts for businesses.
Once profiled, you can go ahead and keep creating accounts for your businesses.
Please note that to create virtual accounts for BUSINESSES, your KYC account needs to be a GTB account number and is mapped to the BVN provided. This doesn't apply if you are creating for individuals.
{
"success": false,
"message": "Validation Failure No record found for Account number- 1237398433",
"data": {
"first_name": null,
"last_name": null,
"bank_code": null,
"virtual_account_number": null,
"beneficiary_account": null,
"customer_identifier": null,
"created_at": "0001-01-01T00:00:00",
"updated_at": "0001-01-01T00:00:00"
},
"status": "424"
}
Transaction Notification Service
WEBHOOK: If a webhook is not provided, notifications won't be sent.
KINDLY ENSURE YOU HAVE A TRANSACTION REFERENCE CHECKER WHEN IMPLEMENTING WEBHOOKS TO AVOID GIVING DOUBLE VALUE ON TRANSACTIONS.
Webhook Validation
Method 1 (Hash Comparison)
The webhook notification sent carries the x-squad-signature in the header. The hash value (x-squad-signature) is an HMAC SHA512 signature of the webhook payload signed using your secret key.
You are expected to create a hash and compare the value of the hash created with the hash sent in the header of the POST request sent to your webhook URL.
To create the hash, you use the entire payload sent via the webhook.
Sample Implementations
using System;
using System.Text;
using System.Security.Cryptography;
using Newtonsoft.Json;
public class Program
{
public static void Main()
{
var chargeResponse = new VirtualAccount_VM()
{
transaction_reference = "REFE52ARZHTS/1668421222619_1",
virtual_account_number = "2129125316",
principal_amount = "222.00",
settled_amount = "221.78",
fee_charged = "0.22",
transaction_date = "2022-11-14T10:20:22.619Z",
customer_identifier = "SBN1EBZEQ8",
transaction_indicator = "C",
remarks = "Transfer FROM sandbox sandbox | [SBN1EBZEQ8] TO sandbox sandbox",
currency = "NGN",
channel = "virtual-account",
meta = new MetaBody_VM()
{
freeze_transaction_ref = null,
reason_for_frozen_transaction = null
},
encrypted_body = "ViASuHLhO+SP3KtmcdAOis+3Obg54d5SgCFPFMcguYfkkYs/i44jeT5Dbx52TcOvHRp9HlnCoFwbATkEihzv2C8UyPoC38sRb90S5Z9Fq7vRwjDQz/hYi/nKbWA0btPr3A+UXhX1Nu5ek+TL0ENUC8W1ZX/FrowX3HQaYiwe3tU/Kfr2XvAGwT7IAx5CQBhpzL34faHP4jbwSVmSgVYmW5rd2ClWQ7WWJjDMakrqYJva8qd0vhkqSpyz2KywOV9t9zSHRx3VpbvlDsBdkNGr+4Axh/7Gspu3xo9mMOIdv73OzjN4VA/qQP+fQMCjU1pbS8oh81HjwkHjzC5SBhzR8IU8bsmvFUyzJMfDoJuUB+fs09SLW7pdfODwK5vB8LtdKPnAuTPlv5dHVAPeMG/ubtl/HOqCZs4axjuO557srw0GpKk86bwaVKt4IQ17nY/QCJFC273HWU1CawP7d3nQasRZf/TU7ra+fOjQBHQ7Gtz2Pnfp3gLljBKenMT4Cabks1X2/6ZQpd/yGFkloYdS7ZW3kEvrorjcyma4WNDmJfhcdR9XGsom6Y/M/n/gMMa0z2KPbHDRoEBeRYbQHcnu5LnGWzBA4Y4RMSTDesD876PDB1bOnMzNPrWYam6ZVRHz"
};
String SerializedPayload = JsonConvert.SerializeObject(chargeResponse);
Console.WriteLine(SerializedPayload);
string result = "";
var secretKeyBytes = Encoding.UTF8.GetBytes("sandbox_sk_9ac9418e847972dd45f5fe845b5716ef305589808eda");
var inputBytes = Encoding.UTF8.GetBytes(SerializedPayload);
var hmac = new HMACSHA512(secretKeyBytes);
byte[] hashValue = hmac.ComputeHash(inputBytes);
result = BitConverter.ToString(hashValue).Replace("-", string.Empty);
Console.WriteLine(result);
Console.WriteLine(result.ToLower() == "18b9eb6ca68f92ca9f058da7bce6545efb12660cf75f960e552cf6098bb5ee8e71f20331dcfe0dfaea07439cc6629f901850291a39f374a1bd076c4eff1026c8");
}
}
public class VirtualAccount_VM
{
public string transaction_reference { get; set; }
public string virtual_account_number { get; set; }
public string principal_amount { get; set; }
public string settled_amount { get; set; }
public string fee_charged { get; set; }
public string transaction_date { get; set; }
public string customer_identifier { get; set; }
public string transaction_indicator { get; set; }
public string remarks { get; set; }
public string currency { get; set; }
public string channel { get; set; }
public MetaBody_VM meta { get; set; }
public string encrypted_body { get; set; }
}
public class MetaBody_VM
{
public string freeze_transaction_ref { get; set; }
public string reason_for_frozen_transaction { get; set; }
}
const crypto = require('crypto');
const secret = "Your Squad Secret Key";
// Using Express
app.post("/MY-WEBHOOK-URL", function(req, res) {
//validate event
const hash = crypto.createHmac('sha512', secret).update(JSON.stringify(req.body)).digest('hex');
if (hash == req.headers['x-squad-signature']) {
// you can trust the event came from squad and so you can give value to customer
} else {
// this request didn't come from Squad, ignore it
}
res.send(200);
<?php
if ((strtoupper($_SERVER['REQUEST_METHOD']) != 'POST' ) || !array_key_exists('x-squad-signature', $_SERVER) )
exit();
// Retrieve the request's body
$input = @file_get_contents("php://input");
$body = json_decode($input);
define('SQUAD_SECRET_KEY','YOUR_SECRET_KEY'); //ENTER YOUR SECRET KEY HERE
if($_SERVER['x-squad-signature'] !== hash_hmac('sha512', json_encode($body, JSON_UNESCAPED_SLASHES), SQUAD_SECRET_KEY))
// The Webhook request is not from SQUAD
exit();
http_response_code(200);
// The Webhook request is from SQUAD
exit();
?>
package hmacexample;
import java.io.UnsupportedEncodingException;
import java.math.BigInteger;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.json.JSONException;
import org.json.JSONObject;
public class HMacExample {
public static void main(String[] args) throws UnsupportedEncodingException, InvalidKeyException, NoSuchAlgorithmException, JSONException {
//This verifies that the request is from Squad
String key = "YOUR_SECRET_KEY"; //replace with your squad secret_key
String body = "BODY_OF_THE_WEBHOOK_PAYLOAD"; //Replace with body of the webhook payload
String result = "";
String HMAC_SHA512 = "HmacSHA512";
String x-squad-signature = ""; //put in the request's header value for x-squad-signature
byte [] byteKey = key.getBytes("UTF-8");
SecretKeySpec keySpec = new SecretKeySpec(byteKey, HMAC_SHA512);
Mac sha512_HMAC = Mac.getInstance(HMAC_SHA512);
sha512_HMAC.init(keySpec);
byte [] mac_data = sha512_HMAC.
doFinal(body.toString().getBytes("UTF-8"));
result = String.format("%040x", new BigInteger(1, mac_data));
while (result.length() < 128) result = "0"+ result;
if(result.equals(x-squad-signature)) {
// you can trust that this is from squad
}else{
// this isn't from Squad, ignore it
}
}
}
Sample Webhook Notification
{
"transaction_reference": "REF2023022815174720339_1",
"virtual_account_number": "0733848693",
"principal_amount": "0.20",
"settled_amount": "0.20",
"fee_charged": "0.00",
"transaction_date": "2023-02-28T00:00:00.000Z",
"customer_identifier": "5UMKKK3R",
"transaction_indicator": "C",
"remarks": "Transfer FROM WILLIAM JAMES | [5UM2B63R] TO CHIZOBA ANTHONY OKOYE",
"currency": "NGN",
"channel": "virtual-account",
"sender_name": "WILLIAM JAMES",
"meta": {
"freeze_transaction_ref": null,
"reason_for_frozen_transaction": null
},
"encrypted_body": "DiPEa8Z4Cbfiqulhs3Q8lVJXGjMIFzbWwI2g7utVGbiI96TjcbjW+64iQrDR+kbZBwisMLMfB5l+Bn0/9kchGjB+xj6bLc6SnyCaku3pCMKmiVSkr/US1lsk+dBBI53nkGcUFkhige35wBYtXC7IpB/N2DCrzXTW5kEGnr9lCvpEFvDhZzDIUVeUCxV14V92vYYP/8O8Zjj3WR9keUc7Qq0H+fl/jmm7VwCtKMSp0OXNGMVPk5TJkLR52hQ8Rap+oorORLoNau1FRLzA24AW0d+nQfqbI+B4hf5+RztP7F1PpiRlo5qR7EthNpaHW6EMYp9fFUQdJRzsQNLbU/IfnH5oK9zFjHaOfKAa5rnoWP3N5IQjz6wobLq9T2KHei3UpCioFMcKYoigtJxple26auq0vCDkDoalPF6+YaqpuKFWdjX0mLz9+Xh5OCq4AI4u3GhioYFbpAvkrzk/Eyh5OdrEvDDLsbSu8lnXymOoiYXuS1Y4Y5jVZpzAArJ7wX7rdi1KLawHu8/m6fBkQLq/82olUuGLtGdPKF1JZnbv3eAXa7+IMhF4QUvsd52uMRnBdEHXfij+WHp7mz4jMP4Gxsx19Xzt7gyWqBhyswEJobDMSZhk/9GRcETwnT0dlSlWxVOL2pVSzKhc73ASxEQCZCO3/5/i1Nq6qSTjsbplLKuwP2Qr/15rP6TvVWAIpxa8"
}
Note: You are expected to send us a response confirming receipt of the request
{
response_code:200,
transaction_reference: 'unique reference sent through the post',
response_description: 'Success'
}
{
response_code:400,
transaction_reference: 'unique reference sent through the post',
response_description: 'Validation failure'
}
{
response_code:500,
transaction_reference: 'unique reference sent through the post',
response_description: 'System malfunction'
}
WEBHOOK VALIDATION V3
The Webhook Version 3 (V3) is an upgrade to the existing version. It follows the same structure with 3 critical updates
The Transaction Ref follows a different format (N.b. Re-queries were necessary, are to be done with the previous format)
The addition of a new field (Version Number)
The Method of Hash Validation: Unlike previous versions, which required the hashing of the entire payload, the webhook v3 only requires the hashing of six (6) fields, each separated by a pipe (|). The values to be hashed are:
The webhook notification sent carries the x-squad-signature in the header. The hash value (x-squad-signature) is an HMAC SHA512 signature of the webhook payload signed using your secret key.
You are expected to create a hash and compare the value of the hash created with the hash sent in the header of the POST request sent to your webhook URL.
This API allows you to retrieve all your missed webhook transactions and use it to update your record without manual input.
The top 100 missed webhooks will always be returned by default and it
This flow involves integration of two(2) APIs
Once you have updated the record of a particular transaction, you are expected to use the second API to delete the record from the error log. If this is not done, the transaction will continuously be returned to you in the first 100 transactions until you delete it.
This will only work for those who respond correctly to our webhook calls.
Also, ensure you have a transaction duplicate checker to ensure you don't update a record twice or update a record you have updated using the webhook or the transaction API.
Authorization Any request made without the authorization key (secret key) will fail with a 401 (Unauthorized) response code.
The authorization key is sent via the request header as Bearer Token Authorization
When you delete the transaction from the log, it won't be returned to you again. Failure to delete a transaction will result in the transaction being returned to you in the top 100 transactions returned each time you retry.
Path Parameters
Name
Type
Description
transaction_ref*
String
Unique Transaction Ref that identifies each virtual account and gotten from the retrieved webhook error log
This is an endpoint to query the transactions a customer has made. This is done using the customer's identifier which was passed when creating the virtual account.
Note: The customer identifier is to be passed via the endpoint being queried.
That is: replace {{customer_identifier}} on the end point with the customer identifier of the customer whose transactions you want to query.
Path Parameters
Name
Type
Description
customer_identifier
String
Unique Customer Identifier that identifies each virtual account
Response expected from the API to show queried Virtual Accounts.
{
"status": 401,
"success": false,
"message": "Merchant has been restricted, please contact Habaripay support",
"data": {}
}
{
"status": 404,
"success": false,
"message": "Merchant is not profiled for this service, please contact Habaripay support",
"data": {}
}
Query Single Transaction Using Transaction Ref
This endpoint allows you to query a single transaction using the system-generated transaction reference, which can be obtained from the webhook notification or dashboard.
Note: The virtual account number is to be passed via the endpoint being queried.
That is: replace {{virtual_account_number}} on the end point with the virtual account number whose details you want to retrieve.
Path Parameters
Name
Type
Description
virtual_account_number*
String
Unique 10-digit virtual account number assigned to a customer
Note: The customer_identifier is to be passed via the endpoint being queried.
That is: replace {{customer_identifier}} on the end point with the customer identifier of the customer whose virtual account you want to retrieve.
Path Parameters
Name
Type
Description
customer_identifier
String
Unique Customer Identifier that identifies each virtual account
