API Specifications
Specification For Virtual Accounts
API KEYS (Test Environment)
- Create an account on our sandbox environment: sandbox.squadco.com
- Retrieve keys from the bottom of the Get Started Page
Authorization Any request made without the authorization key will fail with a 401 (Service Not Authorized) response code.
Authorization would be done via Headers using Keys gotten from your dashboard.
Example: Authorization: Bearer sandbox_sk_94f2b798466408ef4d19e848ee1a4d1a3e93f104046f
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
Please note that you are no longer required to pass a prefix when creating virtual accounts. Prefix are now automatically passed on our end. 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 abbreviations of your business name as one word.
Customer Model
This endpoint is used to create virtual account for individuals/customer 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.
Creating Virtual Accounts for Customers
*asterisked are required and mandatory.
Parameters
Body
first_name*
String
customer first name
last_name*
String
customer last name
middle_name*
String
customer middle name
mobile_num*
String
08012345678 (doesn't take more than 11 digits)
dob*
Date
dd/mm/yyyy
email*
String
customer email
bvn*
String
BVN is compulsory
gender*
String
'1' - Male, '2' -Female
address*
String
customer address
customer_identifier*
String
unique customer identifier as given by merchant
beneficiary_account*
String
Beneficiary Account is the 10 Digit Bank Account Number (GTBank) provided by the Merchant where money sent to this Virtual account is paid into. Please note that when beneficiary account is not provided, money paid into this virtual account go into your wallet and will be paid out/settled in T+1 settlement time.
Responses
{
"success": true,
"message": "Success",
"data": {
"first_name": "Joesph",
"last_name": "Ayodele",
"bank_code": "058",
"virtual_account_number": "7834927713",
"beneficiary_account": "4920299492",
"customer_identifier": "CCC",
"created_at": "2022-03-29T13:17:52.832Z",
"updated_at": "2022-03-29T13:17:52.832Z"
}
}
{
"success": false,
"message": "",
"data": {}
}
{
"success": false,
"message": "Merchant authentication failed",
"data": {}
}
Response expected from the API to signify if the request received was successful
Sample Request
{
"customer_identifier": "CCC",
"first_name": "BusinessName-Joesph",
"last_name": "Ayodele",
"mobile_num": "08139011943",
"email": "ayo@gmail.com",
"bvn": "12343211654",
"dob": "30/10/1990",
"address": "22 Kota street, UK",
"gender": "1",
"beneficiary_account": "4920299492"
}
- 200: Successful
- 400: Validation Failure
- 401: Restricted
- 404: Not Found
- 424: Identity Error
{
status: "200:OK",
responseMsg: "Success Response",
pill: colors?.greenColor,
code: {
"success": true,
"message": "Success",
"data": {
"first_name": "Joesph",
"last_name": "Ayodele",
"bank_code": "058",
"virtual_account_number": "7834927713",
"beneficiary_account": "4920299492",
"customer_identifier": "CCC",
"created_at": "2022-03-29T13:17:52.832Z",
"updated_at": "2022-03-29T13:17:52.832Z"
}
}
}
{
"status": 400,
"success": false,
"message": "Validation Failure, Customer identifier is required",
"data": {}
}
{
"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. For clarity: you need GTB if you are creating accounts for other businesses say you want to create an account for Chicken Fish Limited but if you are creating for Individual say Emeka Joseph, you don't necessarily need to have a GTB account.
Sample Request
{
"customer_identifier": "CCC",
"business_name": "Chicken Limited",
"mobile_num": "08139011943",
"bvn": "22110011001",
"beneficiary_account": "4920299492"
}
Creating Virtual Account for businesses
Parameters
Body
bvn*
String
Bank Verification Number
business_name*
String
Name of Business/Customer
customer_identifier*
String
An alphanumeric string used to identify a customer/business in your system which will be tied to the virtual account being created
mobile_num*
String
Customer's Phone Number Sample: 08012345678 (doesn't take more than 11 digits)
beneficiary_account*
Date
Beneficiary Account is your 10 Digit Bank Account Number (GTBank) where money sent to this Virtual account is paid into. Please note that when beneficiary account is not provided, money paid into this virtual account go into your wallet and will be paid out/settled in T+1 settlement time.
Responses
{
"status": 200,
"success": true,
"message": "Success",
"data": {
"first_name": "Techzilla-Will",
"last_name": "Okoye",
"bank_code": "058",
"virtual_account_number": "2474681469",
"beneficiary_account": null,
"customer_identifier": "Tech910260",
"created_at": "2023-08-07T13:18:21.287Z",
"updated_at": "2023-08-07T13:18:21.287Z"
}
}
{
"status": 400,
"success": false,
"message": ""customer_identifier" is required",
"data": {}
}
{
"success": false,
"message": "",
"data": {}
}
{
"success": false,
"message": "Merchant authentication failed",
"data": {}
}
{
"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
Upon registration and verification as a merchant, you are to create a Webhook and add on your Squad Dashboard to receive notification on payments.
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 carry 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
- C#
- Javascript (Node)
- PHP
- Java
using System;
using System.Security.Cryptography;
using System.Text;
using Newtonsoft.Json.Linq;
namespace HMacExample
{
class Program {
static void Main(string[] args) {
String key = "YOUR_SECRET_KEY"; //replace with your squad secret_key
//Replace with the body of the notification received
String webhookPayload = "THE_BODY_OF_THE_WEBHOOK_PAYLOAD YOU RECEIVED";
String jsonInput = JsonConvert.SerializeObject(webhookPayload);
String result = "";
byte[] secretkeyBytes = Encoding.UTF8.GetBytes(key);
byte[] inputBytes = Encoding.UTF8.GetBytes(jsonInput);
using (var hmac = new HMACSHA512(secretkeyBytes))
{
byte[] hashValue = hmac.ComputeHash(inputBytes);
result = BitConverter.ToString(hashValue).Replace("-", string.Empty);;
}
Console.WriteLine(result);
String x-squad-signature = "Request's header value for x-squad-signature" //replace with the request's header value for x-squad-signature here
if(result.Equals(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
}
}
}
}
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));
if(result.equals(x-squad-signature)) {
// you can trust that this is from squad
}else{
// this isn't from Squad, ignore it
}
}
}
Method 2 (Decryption of Encrypted Body)
To validate the webhook sent to you, you are expected to decrypt the hashed body (encrypted_body) of data sent via the webhook using the Public and Secret Key found on your squad dashboard.
The result of this decryption is to be compared against the body of data sent from the webhook, if they match then you can trust that the notification is from squad and if they don't then you know the notification didn't originate from squad and you are expected to ignore such notifications.
To decrypt the hashed body, kindly visit our encryption and decryption page for sample decryption functions in different languages.
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"
}
You are expected to send us a response confirming receipt of the request
- 200: Successful
- 400: Validation Failure
- 500: System Malfunction
{
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 ERROR LOG
This API allows you retrieve all your missed webhook transactions and use it to update your record without manual input.
- The top 100 missed webhook 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
Example: Authorization: Bearer sandbox_sk_94f2b798466408ef4d19e848ee1a4d1a3e93f104046f
Get Webhook Error Log
This API returns an array of transactions from the webhook error log
Parameters
Query
page*
Integer
The page you are on
perPage*
Integer
Number of records you want to appear on a page
Responses
{
"status": 200,
"success": true,
"message": "Success",
"data": {
"count": 2,
"rows": [
{
"id": "229f9f3d-53e4-450e-a9e9-164a8b882a60",
"payload": {
"hash": "659c24ba0b6c3ac324b587f2f079c8ee876c56609ff11b7106cd868f84674a5c37fcb088373859f8d900713f03c47d819de79623cde67e70bbca945fd20f3cb3",
"meta": {
"freeze_transaction_ref": null,
"reason_for_frozen_transaction": null
},
"channel": "virtual-account",
"remarks": "Transfer FROM OKOYE, CHIZOBA ANTHONY | [CCtyttytC] TO CHIZOBA ANTHONY OKOYE",
"currency": "NGN",
"fee_charged": "0.05",
"sender_name": "OKOYE, CHIZOBA ANTHONY",
"encrypted_body": "DiPEa8Z4Cbfiqulhs3Q8lVJXGjMIFzbWwI2g7utVGbhXihbtK3H2xsA/+ZnjOpFA0AU8vAN5LUTEH6elfrK58ub2wydaRk0ngvQXWUFz3iB19qWBcdGQRnppKAT/AB5xyy1iQZvEHP7zq3Y7na5zcx9ttkU1mZIeAIoisM9k+ghVLxkTeql4UvfFcLyDdGzMd/BC4YgJFyrZxifhfhKi073od7xJnz4Hhz08UBE/FAwNYMWkwWD9izlbcaaJtfh1VIN6t9rl1gotlb5qmNq/UytgoSvuN5uaEXxegdB3VWvmsDMHqoYwDs4oEuv0lp8zUUG3cZ9zPQ6xH3shGQjVOWErkuIfCk62fRzkwxya4Gu/x2KHMSQjutbvD4vNDjVGfuCIoHuZEXPThWrq1jpTy7cNMLc8ZZ8IowJnfwWHL+O6fuepxXxfrJHlswMCI35ZHSvef1AEXgbUlx2O7yzytceCogpUkY+QJ1yLddl1FeE1u2JKOM+casP3pfiT+t3Mv55aSCVQO7hUy46gd6H/bIHaSIp2K3CcjfdflZ/bxCZaZoe/sRqfVdVIzpSpTc0Lq5sOXM2gijOdeg+zex/CgnMIKGJdzUT9YUJtaaVrMmhk0EcM0rHRrqs0iM7xaSTdZ7K8hnzl0RPJhDXIhu5a/Y2NxS3ZTC2lYRVZd6I3lerpoMQG69VfmqvaVgW2k03f",
"settled_amount": "49.95",
"principal_amount": "50.00",
"transaction_date": "2023-09-01T00:00:00.000Z",
"customer_identifier": "CCtyttytC",
"transaction_indicator": "C",
"transaction_reference": "REF20230901162737156459_1",
"virtual_account_number": "0760640237"
},
"transaction_ref": "REF20230901162737156459_1"
}
]
}
}
{
"success": false,
"message": "",
"data": {}
}
Delete Webhook Error Log
This API enables you delete a processed transaction from the webhook error log
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.
Parameters
Path
transaction_ref*
String
Unique Transaction Ref that identifies each virtual account and gotten from the retrieved webhook error log
Responses
{
"status": 200,
"success": true,
"message": "Success",
"data": 1
}
{
"success": false,
"message": "",
"data": {}
}
{
"success": false,
"message": "Merchant authentication failed",
"data": {}
}
Query Customer Transaction by Customer Identifier
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.
Query Customer Transactions
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.
Parameters
Path
customer_identifier*
String
Unique Customer Identifier that identifies each virtual account
Response expected from the API to show queried Virtual Accounts.
- 200: Successful
- 400: Validation Failure
- 401: Restricted
- 404: Not Found
{
"status": 200,
"success": true,
"message": "Success",
"data": [
{
"transaction_reference": "74902084jjjfksoi93004891_1",
"virtual_account_number": "2224449991",
"principal_amount": "30000.00",
"settled_amount": "0.00",
"fee_charged": "0.00",
"transaction_date": "2022-04-21T09:00:00.000Z",
"transaction_indicator": "C",
"remarks": "Payment from 10A2 to 2224449991",
"currency": "NGN",
"frozen_transaction": {
"freeze_transaction_ref": "afbd9b7f-fb98-41c3-bfe8-dc351cfb45c7",
"reason": "Amount above 20000 when BVN not set"
},
"customer": {
"customer_identifier": "SBN1EBZEQ8"
}
},
{
"transaction_reference": "676767_1",
"virtual_account_number": "2224449991",
"principal_amount": "1050.00",
"settled_amount": "1037.00",
"fee_charged": "13.00",
"transaction_date": "2022-03-21T09:00:00.000Z",
"transaction_indicator": "C",
"remarks": "Payment from 10A2 to 2224449991",
"currency": "NGN",
"froze_transaction": null,
"customer": {
"customer_identifier": "SBN1EBZEQ8"
}
}
]
}
{
"status": 400,
"success": false,
"message": "Customer identifier or merchant identifier is required",
"data": {}
}
{
"status": 401,
"success": false,
"message": "Merchant has been restricted, please contact Habaripay support",
"data": {}
}
{
"status": 401,
"success": false,
"message": "",
"data": {}
}
Query All Merchant's Transactions
This is an endpoint to query all the merchant transactions over a period of time.
Query All Transactions
Note: The endpoint is to be queried using just the authorization key from the dashboard
Parameters
No Parameters
- 200: Successful
- 400: Validation Failure
- 401: Restricted
- 404: Not Profiled
{
"status": 200,
"success": true,
"message": "Success",
"data": [
{
"transaction_reference": "4894fe1_1",
"virtual_account_number": "2244441333",
"principal_amount": "5000.00",
"settled_amount": "0.00",
"fee_charged": "0.00",
"transaction_date": "2022-04-21T09:00:00.000Z",
"transaction_indicator": "C",
"remarks": "Payment from 15B8 to 2244441333",
"currency": "NGN",
"frozen_transaction": {
"freeze_transaction_ref": "afbd9b7f-fb98-41c3-bfe8-dc351cfb45c7",
"reason": "Amount above 20000 when BVN not set"
},
"customer": {
"customer_identifier": "SBN1EBZEQ8"
}
},
{
"transaction_reference": "676767_1",
"virtual_account_number": "2224449991",
"principal_amount": "30000.00",
"settled_amount": "1037.00",
"fee_charged": "13.00",
"transaction_date": "2022-03-21T09:00:00.000Z",
"transaction_indicator": "C",
"remarks": "Payment from 10A2 to 2224449991",
"currency": "NGN",
"froze_transaction": null,
"customer": {
"customer_identifier": "SBN1EBZEQ8"
}
}
]
}
{
"status": 400,
"success": false,
"message": "Merchant identifier is required",
"data": {}
}
{
"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 All Merchant Transactions with Multiple Filters
This endpoint allows you query all transactions and filter using multiple parameters like virtual account number, start and end dates, customer Identifier etc
Query All Transactions with Multiple Filters
This endpoint allows you query all transactions and filter using multiple parameters like virtual account number, start and end dates, customer Identifier etc
Parameters
Query
page*
Integer
Page Number to Display
perPage*
Integer
Number of records per Page
virtualAccount*
Integer
a unique 10-digit virtual account number
customerIdentifier*
String
Unique Identifier used to create/identify a customer's virtual account
startDate*
Date
MM-DD-YYYY E.G: 09-19-2022
endDate*
Date
MM-DD-YYYY E.G: 09-19-2022
transactionReference*
String
Unique Identifier of a transaction
session_id*
String
Unique ID that identifies all NIP transactions
dir*
String
Takes two possible values: 'DESC' and 'ASC'. 'DESC' - descending order ,'ASC' - ascending order
Responses
{
"status": 200,
"success": true,
"message": "Success",
"data": {
"count": 15,
"rows": [
{
"transaction_reference": "REF20221007130357_1",
"virtual_account_number": "0713810881",
"principal_amount": "50.00",
"settled_amount": "50.00",
"fee_charged": "0.00",
"transaction_date": "2022-10-07T00:00:00.000Z",
"transaction_indicator": "C",
"remarks": "Transfer FROM Sample | [CCC1234334] TO Sample Name",
"currency": "NGN",
"alerted_merchant": false,
"merchant_settlement_date": "2022-10-07T12:04:11.635Z",
"frozen_transaction": null,
"customer": {
"customer_identifier": "CCC1234334"
}
},
{
"transaction_reference": "REF20221004191517_1",
"virtual_account_number": "0708729381",
"principal_amount": "50.00",
"settled_amount": "49.75",
"fee_charged": "0.25",
"transaction_date": "2022-10-04T00:00:00.000Z",
"transaction_indicator": "C",
"remarks": "Transfer FROM Sample Name4 | [OPPO] TO Sample Name",
"currency": "NGN",
"alerted_merchant": false,
"merchant_settlement_date": "2022-10-04T18:15:29.463Z",
"frozen_transaction": null,
"customer": {
"customer_identifier": "OPPO"
}
},
{
"transaction_reference": "REF20220913181048_1",
"virtual_account_number": "0709108705",
"principal_amount": "50.00",
"settled_amount": "49.75",
"fee_charged": "0.25",
"transaction_date": "2022-09-13T18:10:48.000Z",
"transaction_indicator": "C",
"remarks": "Transfer FROM Sample Name4 | [TSP/00008786500] TO Sample Name",
"currency": "NGN",
"alerted_merchant": false,
"merchant_settlement_date": "2022-09-20T09:51:04.999Z",
"frozen_transaction": null,
"customer": {
"customer_identifier": "TSP/00008786500"
}
},
{
"transaction_reference": "REF20220713143436_1",
"virtual_account_number": "0713694755",
"principal_amount": "50.00",
"settled_amount": "49.75",
"fee_charged": "0.25",
"transaction_date": "2022-07-13T14:34:36.000Z",
"transaction_indicator": "C",
"remarks": "Transfer from Sample Name | [123CCC] to Sample Name5",
"currency": "NGN",
"alerted_merchant": false,
"merchant_settlement_date": "2022-07-13T13:35:13.410Z",
"frozen_transaction": null,
"customer": {
"customer_identifier": "123CCC"
}
},
{
"transaction_reference": "REF20220707162950_1",
"virtual_account_number": "0710954717",
"principal_amount": "50.00",
"settled_amount": "49.75",
"fee_charged": "0.25",
"transaction_date": "2022-07-07T16:29:50.000Z",
"transaction_indicator": "C",
"remarks": "Transfer from Sample Name4 | [12345] to Sample Name",
"currency": "NGN",
"alerted_merchant": false,
"merchant_settlement_date": "2022-07-07T15:30:06.761Z",
"frozen_transaction": null,
"customer": {
"customer_identifier": "12345"
}
},
{
"transaction_reference": "REF20220624160230_1",
"virtual_account_number": "0710954717",
"principal_amount": "30.00",
"settled_amount": "29.85",
"fee_charged": "0.15",
"transaction_date": "2022-06-24T16:02:30.000Z",
"transaction_indicator": "C",
"remarks": "Transfer from Sample Name5 | [12345] to Sample Name",
"currency": "NGN",
"alerted_merchant": false,
"merchant_settlement_date": "2022-06-24T15:03:29.054Z",
"frozen_transaction": null,
"customer": {
"customer_identifier": "12345"
}
},
{
"transaction_reference": "REF20220624155515_1",
"virtual_account_number": "0710954717",
"principal_amount": "30.00",
"settled_amount": "29.85",
"fee_charged": "0.15",
"transaction_date": "2022-06-24T15:55:15.000Z",
"transaction_indicator": "C",
"remarks": "Transfer from Sample Name4 | [12345] to Sample Name",
"currency": "NGN",
"alerted_merchant": false,
"merchant_settlement_date": "2022-06-24T14:56:23.266Z",
"frozen_transaction": null,
"customer": {
"customer_identifier": "12345"
}
},
{
"transaction_reference": "REF20220623095446_1",
"virtual_account_number": "0710954717",
"principal_amount": "30.00",
"settled_amount": "29.85",
"fee_charged": "0.15",
"transaction_date": "2022-06-23T09:54:46.000Z",
"transaction_indicator": "C",
"remarks": "Transfer from Sample Name3 | [12345] to Sample Name",
"currency": "NGN",
"alerted_merchant": false,
"merchant_settlement_date": "2022-06-23T08:55:06.599Z",
"frozen_transaction": null,
"customer": {
"customer_identifier": "12345"
}
},
{
"transaction_reference": "REF20220617131121_1",
"virtual_account_number": "0708729381",
"principal_amount": "30.00",
"settled_amount": "29.85",
"fee_charged": "0.15",
"transaction_date": "2022-06-17T13:11:21.000Z",
"transaction_indicator": "C",
"remarks": "Transfer from Sample Name3 | [OPPO] to Sample Name",
"currency": "NGN",
"alerted_merchant": false,
"merchant_settlement_date": "2022-06-17T12:11:38.228Z",
"frozen_transaction": null,
"customer": {
"customer_identifier": "OPPO"
}
},
{
"transaction_reference": "REF20220617130949_1",
"virtual_account_number": "0708729381",
"principal_amount": "50.00",
"settled_amount": "49.75",
"fee_charged": "0.25",
"transaction_date": "2022-06-17T13:09:49.000Z",
"transaction_indicator": "C",
"remarks": "Transfer from Sample Name3 | [OPPO] to Sample Name",
"currency": "NGN",
"alerted_merchant": false,
"merchant_settlement_date": "2022-06-17T12:10:14.605Z",
"frozen_transaction": null,
"customer": {
"customer_identifier": "OPPO"
}
},
{
"transaction_reference": "REF20220617125618_1",
"virtual_account_number": "0708729381",
"principal_amount": "50.00",
"settled_amount": "49.75",
"fee_charged": "0.25",
"transaction_date": "2022-06-17T12:56:18.000Z",
"transaction_indicator": "C",
"remarks": "Transfer from sample Name1 | [OPPO] to Sample Name",
"currency": "NGN",
"alerted_merchant": false,
"merchant_settlement_date": "2022-06-17T11:56:42.868Z",
"frozen_transaction": null,
"customer": {
"customer_identifier": "OPPO"
}
},
{
"transaction_reference": "REF20220617115436_1",
"virtual_account_number": "0709056301",
"principal_amount": "50.00",
"settled_amount": "49.75",
"fee_charged": "0.25",
"transaction_date": "2022-06-17T11:54:36.000Z",
"transaction_indicator": "C",
"remarks": "Transfer from Sample Name3 | [TSP/00002900] to Sample Name",
"currency": "NGN",
"alerted_merchant": false,
"merchant_settlement_date": "2022-06-17T10:54:54.837Z",
"frozen_transaction": null,
"customer": {
"customer_identifier": "TSP/00002900"
}
}
],
"query": {}
}
}
{
"status": 400,
"success": false,
"message": ""virtualAccount" is not allowed to be empty",
"data": {}
}
{
"success": false,
"message": "",
"data": {}
}
{
"success": false,
"message": "Merchant authentication failed",
"data": {}
}
Get Customer Details by Virtual Account Number
This is an endpoint to retrieve the details of a customer using the Virtual Account Number
Retrieve Virtual Account Details
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.
Parameters
Path
virtual_account_number*
String
Unique 10-digit virtual account number assigned to a customer
Responses
{
"status": 200,
"success": true,
"message": "Success",
"data": {
"first_name": "Timothy",
"last_name": "Oke",
"mobile_num": "08000000000",
"email": "atioke@gmail.com",
"customer_identifier": "CCtyttytC",
"virtual_account_number": "0686786837"
}
}
{
"status": 404,
"success": false,
"message": "Virtual account not found",
"data": {}
}
Get Customer Details Using Customer Identifier
This is an endpoint to retrieve the details of a customer'svirtual account using the Customer Identifier
Retrieve Virtual Account Details
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.
Parameters
Path
customer_identifier*
String
Unique Customer Identifier that identifies each virtual account
- 200: Successful
- 400: Validation Failure
- 404: Not Profiled
{
"status": 200,
"success": true,
"message": "Success",
"data": {
"first_name": "Wisdom",
"last_name": "Trudea",
"bank_code": "737",
"virtual_account_number": "555666777",
"customer_identifier": "10D2",
"created_at": "2022-01-13T11:03:54.252Z",
"updated_at": "2022-01-13T11:09:51.657Z"
}
}
{
"status": 400,
"success": false,
"message": "Merchant identifier is required",
"data": {},
}
{
"status": 404,
"success": false,
"message": "No virtual account is associated",
"data": {}
}
Update Customer's BVN and Unfreeze Transaction
Update customer's BVN and unfreeze transaction
Parameters
Path
customer_bvn*
String
Bank Verification Number of Customer
customer_identifier*
String
Unique number given to customer by merchant.
phone_number*
String
customer's phone number
- 200: Successful
- 400: Validation Failure
- 424: Updated Error
- 409: Conflict
{
"status": 200,
"success": true,
"message": "Success",
"data": {}
}
{
"status": 400,
"success": false,
"message": "BVN verification failed",
"data": {}
}
{
"status": 424,
"success": false,
"message": "An error occurred while trying to update customer's bvn",
"data": {}
}
{
"status": 409,
"success": false,
"message": "Customer's first_name & last_name didn't match or phone_number didn't match.",
"data": {}
}
Query All Merchant's Virtual Accounts
This is an endpoint to look-up the virtual account numbers related to a merchant.
Find All Virtual Account Number by Merchant
This is an endpoint for merchants to query and retrieve all their virtual account.
Parameters
Query
page*
String
Number of Pages
perPage*
String
Number of Accounts to be returned per page
startDate*
Date
YY-MM-DD
EndDate*
Date
YY-MM-DD
- 200: Successful
- 404: Not Profiled
{
"status": 200,
"success": true,
"message": "Success",
"data": [
{
"bank_code": "058",
"virtual_account_number": "2224449991",
"beneficiary_account": "4829023412",
"created_at": "2022-02-09T16:02:39.170Z",
"updated_at": "2022-02-09T16:02:39.170Z",
"customer": {
"first_name": "Ifeanyi",
"last_name": "Igweh",
"customer_identifier": "10A2"
}
},
{
"bank_code": "058",
"virtual_account_number": "111444999",
"beneficiary_account": "9829023411",
"created_at": "2022-02-09T16:02:39.170Z",
"updated_at": "2022-02-09T16:02:39.170Z",
"customer": {
"first_name": "Paul",
"last_name": "Aroso",
"customer_identifier": "10B2"
}
}
]
}
{
"status": 400,
"success": false,
"message": "Merchant identifier is required",
"data": {},
}
Update Beneficiary Account
Sample Request
{
"beneficiary_account":"1111111111",
"virtual_account_number": "4683366555"
}
This is used to update beneficiary account
Parameters
Body
beneficiary_account*
String
10 digit valid NUBAN account number
virtual_account_number*
String
The Virtual account number whose beneficiary account is to be updated
Responses
{
"status": 200,
"success": true,
"message": "Success",
"data": {
"first_name": "Sheena",
"last_name": "Grace",
"virtual_account_number": "3832649897",
"beneficiary_account": "1234567890",
"customer_identifier": "2086601683696"
}
}
{
"status": 400,
"success": false,
"message": ""virtual_account_number" is required",
"data": {}
}
{
"success": false,
"message": "",
"data": {}
}
Simulate Payment
This is an endpoint to simulate payments
Simulate Payment
This is an endpoint to simulate payment *asterisks are required and mandatory.
Parameters
Header
content-type*
String
application/json
Authorization*
String
Private Key or Secret Key (Gotten from your dashboard)
Body
virtual_account_number*
String
Virtual Account number of customer that wants to make payment.
amount*
String
Simulated Amount
Responses
{
"success": true,
"message": "Success",
"data": {}
}
Go Live
To go live, simply:
- Change the base URL for your endpoints from sandbox-api-d.squadco.com to api-d.squadco.com
- Sign up on our Live Environment
- Complete your KYC
- Share the Merchant ID with the Technical Account Manager for Profiling
- Use the secret keys provided on the dashboard to authenticate your live transactions