Dynamic Virtual Account
This module contains APIs that allow you generate a pool of Virtual Accounts that can be assigned on a transaction basis. This means that you can set a timer for expiry, a transaction ref, determine the amount to be collected.
Please note that all accounts created will now bear the merchant's business name and no longer SQUAD CHECKOUT as it used to be. The format will now be SQUAD_MERCHANT BUSINESS NAME. (Also note that this doesn't affect already created accounts in the pool).
After creating the pool of accounts, the system automatically assigns accounts from your pool on a transaction basis.
It has various webhook notifications for mismatch, expired and successful transaction as we as a re-query endpoint to see all transactions that have been queued for refunds, and those that have been refunded.
Please note that to create dynamic virtual accounts for your pools, your KYC account needs to be a GTB account number and is mapped to the BVN provided.
Process Flow
- All accounts must be profiled before you can use this service as it is a restricted service for selected business. Kindly send a mail to help@squadco.com or growth@habaripay.com requesting permission to use this service.
- Each merchant is assigned a separate pool of accounts and as such they are expected to create their accounts based on their use case and expected transaction volume.
- To initiate a transaction, the merchant is to call the generate Dynamic virtual account endpoint and an account from your own pool will be made available for transaction and will be tied to the amount and duration you set.
- Webhook notification is fired for 3 events: success, expired and mismatch.
- There is a re-query that shows all payment attempts for a single transaction reference. It returns an array which contains the payment attempts and you can see the various status of either success, expired or mismatch where applicable.
API KEYS (Test Environment)
- Create an account on our sandbox environment: sandbox.squadco.com
- Share the merchant ID with the Technical Account Managers for Profiling.
- Retrieve Authorization keys from the bottom of the Get Started Page.
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
Create Dynamic VA Accounts
This allows you create and assign dynamic virtual accounts to your pool. Only one account is generated per request.
This allows you create and assign dynamic virtual accounts to your pool
Responses
{
"status": 200,
"success": true,
"message": "Success",
"data": {}
}
{
"success": false,
"message": "",
"data": {}
}
{
"success": false,
"message": "Merchant authentication failed",
"data": {}
}
Initiate Dynamic Virtual Account Transaction
This API allows you generate a Dynamic Virtual Account to be assigned to a customer. This is used to initiate a transaction.
This API allows you generate a Dynamic Virtual Account to be assigned to a customer
This API allows you generate a Dynamic Virtual Account to be assigned to a customer. This is used to initiate a transaction.
Parameters
Body
amount*
Integer
Amount is in Kobo
duration*
Integer
Time allowed before an account/transaction is expired. Duration is in seconds. i.e duration:60 = 1 minute
email*
string
a valid email address for notification to customer
transaction_ref*
string
Unique transaction Reference that identifies the transaction on your system
Responses
{
"status": 200,
"success": true,
"message": "Success",
"data": {
"is_blocked": false,
"account_name": "SQUAD CHECKOUT",
"account_number": "4879261135",
"expected_amount": "100.00",
"expires_at": "2023-08-08T08:23:27.791Z",
"transaction_reference": "dva123",
"bank": "GTBank",
"currency": "NGN"
}
}
{
"success": false,
"message": "",
"data": {}
}
{
"success": false,
"message": "Merchant authentication failed",
"data": {}
}
Sample Request
{
"amount":100,
"transaction_ref":"Aq1111BddCDqdddqdqqEw2",
"duration":600,
"email":"hittommyi02@gmail.com"
}
Re-query Transaction
This API allows you re-query a transaction to see its status. It returns an array of all transaction attempts made including those that returned as a mismatch, those that expired and the successful transaction. Ultimately all expired and mismatched transactions will eventually be refunded.
This API allows you re-query a transaction to see it's status.
This API allows you re-query a transaction to see its status. It returns an array of all transaction attempts made including those that returned as a mismatch, those that expired and the successful transaction. Ultimately all expired and mismatched transactions will eventually be refunded.
Parameters
Path
transaction_reference*
String
Merchant's transaction reference passed when initiating / generating the dynamic virtual account.
Responses
{
"status": 200,
"success": true,
"message": "Success",
"data": {
"count": 3,
"rows": [
{
"transaction_status": "EXPIRED",
"transaction_reference": "Aq1111BddCDqdddqdqqEw4",
"created_at": "2023-08-08T07:02:59.672Z",
"refund": false
},
{
"transaction_status": "SUCCESS",
"transaction_reference": "Aq1111BddCDqdddqdqqEw4",
"created_at": "2023-08-08T07:02:54.052Z",
"refund": null
},
{
"transaction_status": "MISMATCH",
"transaction_reference": "Aq1111BddCDqdddqdqqEw4",
"created_at": "2023-08-08T07:02:29.392Z",
"refund": false
}
]
}
}
{
"success": false,
"message": "",
"data": {}
}
{
"success": false,
"message": "Merchant authentication failed",
"data": {}
}
Edit Amount/Duration
This API allows you to edit the amount/duration of a dynamic transaction that has already been initiated. It takes the transction reference, the amount and duration.
Sample Request
{
"transaction_reference": "ify21",
"amount": 5000
}
This API allows you to edit the amount/duration of a dynamic transaction
Parameters
Body
transaction_reference*
String
The transaction ref of the already initiated transaction.
amount*
Integer
Amount is in Kobo
duration*
Integer
Amount of time before transaction expires. Duration is in seconds.
Responses
{
"status": 200,
"success": true,
"message": "Success",
"data": {
"account_number": "0852491446",
"currency": "NGN",
"amount": 5000,
"expires_at": "2023-08-30T17:01:46.973Z",
"transaction_reference": "ify21"
}
}
{
"success": false,
"message": "",
"data": {}
}
{
"success": false,
"message": "Merchant authentication failed",
"data": {}
}
{
"status": 404,
"success": false,
"message": "Transaction not found",
"data": {}
}
Simulate Payment Endpoint
This API allows you push test transactions. Please note that this APi is to be used only on the sandbox environment.
This is to be used only on the sandbox environment to do test transactions.
Parameters
Body
virtual_account_number*
String
10-digit Dynamic Account gotten after initiating a virtual transfer.
amount*
String
Amount is in naira. This is the expected amount to be transferred into the dynamic virtual account.
dva*
boolean
true
Responses
{
"status": 200,
"success": true,
"message": "Success",
"data": "Payment successful"
}
{
"success": false,
"message": "",
"data": {}
}
{
"success": false,
"message": "Merchant authentication failed",
"data": {}
}
WEBHOOKS
Webhook Notification is sent for 3 different events/ status
- Success: first transfer/transaction that is equal to the expected/specified amount and within the set duration.
- Mismatch: A transfer that happens within the specified duration but expected amount is not equal to the transfered amount.
- Expired: Transaction that happens after the set duration or after a successful transaction has been recorded, it doesn't matter if the transferred amount is equivalent to the expected amount.
To set your webhook, kindly visit your squad dashboard and go to the merchant setting page you will see a field labelled webhook URL. Only accounts with a valid webhook URL will receive notification.
Sample Webhook Notification (Success)
{
"transaction_status": "SUCCESS",
"merchant_reference": "Aq1111BddCDqdddqdqqEw4",
"merchant_amount": "100.00",
"amount_received": "100.00",
"transaction_reference": "REFFX8U72GD6/1691478173792",
"email": "igwehifeanyi02@gmail.com",
"merchant_id": "SBN1EBZEQ8",
"transaction_type": "dynamic_virtual_account",
"date": "2023-08-08T07:02:54.052Z"
}
Sample Webhook Notification (Expired)
{
"transaction_status": "EXPIRED",
"merchant_reference": "Aq1111BddCDqdddqdqqEw4",
"merchant_amount": "100.00",
"amount_received": "100.00",
"transaction_reference": "REFKGXAMXEDR/1691478179452",
"email": "igwehifeanyi02@gmail.com",
"merchant_id": "SBN1EBZEQ8",
"transaction_type": "dynamic_virtual_account",
"date": "2023-08-08T07:02:59.672Z"
}
Sample Webhook Notification (Mismatch)
{
"transaction_status": "MISMATCH",
"merchant_reference": "Aq1111BddCDqdddqdqqEw4",
"merchant_amount": "100.00",
"amount_received": "101.00",
"transaction_reference": "REFRQR681DB8/1691478149192",
"email": "igwehifeanyi02@gmail.com",
"merchant_id": "SBN1EBZEQ8",
"transaction_type": "dynamic_virtual_account",
"date": "2023-08-08T07:02:29.392Z"
}
HASH SIGNATURE VALIDATION
Every webhook request comes with a hash signature on the request header. You are expected as a form of security to create a hash and compare to the hash sent via the header. The hash is a sha512 hash of some parameters in the payload using your squad secret/private key.
The signature in the header has the key: x-squad-encrypted-body . The parameters to be hashed are seen below:
Webhook Payload to be hashed
{
transaction_reference: "REF202308010384993",
amount_received: "3000",
merchant_reference: "test_1",
}
Webhook Error Log
This contains all missed webhook notifications that we didn't get a 200 response for. The aim of this is to mitigate against missed webhooks. Click to open API specifications
Sample Error Log Response for DVA
{
"status": 200,
"success": true,
"message": "Success",
"data": {
"count": 2,
"rows": [
{
"id": "2dc56eb3-d997-4e68-adf9-53b603c16a43",
"payload": {
"date": "2023-08-09T15:09:54.958Z",
"email": "igwehifeanyi02@gmail.com",
"merchant_id": "SBN1EBZEQ8",
"amount_received": "100.00",
"merchant_amount": "100.00",
"transaction_type": "dynamic_virtual_account",
"merchant_reference": "C2",
"transaction_status": "SUCCESS",
"transaction_reference": "REF7VDV8JV25/1691593794798"
},
"transaction_ref": "REF7VDV8JV25/1691593794798"
},
{
"id": "b7983af4-ad3e-40ef-91d4-55af04bb2173",
"payload": {
"date": "2023-08-09T15:04:41.017Z",
"email": "igwehifeanyi02@gmail.com",
"merchant_id": "SBN1EBZEQ8",
"amount_received": "100.00",
"merchant_amount": "100.00",
"transaction_type": "dynamic_virtual_account",
"merchant_reference": "Cw2",
"transaction_status": "SUCCESS",
"transaction_reference": "REFANGDGNQ1N/1691593480709"
},
"transaction_ref": "REFANGDGNQ1N/1691593480709"
}
]
}
}