Dynamic Virtual Account - v2

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

1. 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 [e-mail] or [e-mail] requesting permission to use this service.

2. 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.

3. 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.

4. Webhook notification is fired for 3 events: success, expired and mismatch.

5. 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)

1. Create an account on our sandbox environment: sandbox.squadco.com

2. Share the merchant ID with the Technical Account Managers for Profiling.

3. Retrieve Authorization keys from the bottom of the Get Started Page.

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

If using other services such as payment gateway, do not use the same transaction reference

Example: Authorization: Bearer sandbox_sk_94f2b798466408ef4d19e848ee1a4d1a3e93f104046f

Create Dynamic VA Accounts

This allows you to create and assign dynamic virtual accounts to your pool. Only one account is generated per request.

This allows you to create and assign dynamic virtual accounts to your pool

POST https://sandbox-api-d.squadco.com/virtual-account/create-dynamic-virtual-account

200: OK Success

{
    "status": 200,
    "success": true,
    "message": "Success",
    "data": {
        "last_used": "2024-11-13T13:45:19.751Z",
        "is_suspicious": false,
        "bank_code": "058",
        "virtual_account_number": "9111228017",
        "customer_identifier": "84684a-c4f8-4bc3-bdb5-88fsfs1375946a6",
        "beneficiary_account": null,
        "first_name": "Techzilla",
        "last_name": "Inc",
        "account_type": "dynamic",
        "settlement_type": "next_day",
        "user_id": "9111228017",
        "updatedAt": "2024-11-13T13:45:19.784Z",
        "createdAt": "2024-11-13T13:45:19.784Z",
        "fixed_amount": null,
        "expiry_date": null,
        "external_ref": null,
        "meta": null,
        "ptsp_identifier": null,
        "deletedAt": null
    }
}

401: Unauthorized No Authorization

{
    "success": false,
    "message": "",
    "data": {}
}

403: Forbidden Invalid / Wrong Authorization

{
    "success": false,
    "message": "Merchant authentication failed",
    "data": {}
}

Where instant settlement is required, please pass the beneficiary_account parameter along with a GTBank account to the request body. Note: Only a GTBank should be used.

Sample:

{
"beneficiary_account": "0147799000"
}

Where a customized business name is required, please pass the name as "first_name" and "last_name" to the request body. Note: Only permitted merchants can use this feature.

Sample:

{
 "first_name": "Jerry",
 "last_name": "Eze"
 }

Initiate Dynamic Virtual Account Transaction

This API allows you to generate a Dynamic Virtual Account to be assigned to a customer. This is used to initiate a transaction.

POST https://sandbox-api-d.squadco.com/virtual-account/initiate-dynamic-virtual-account

Request Body

Name	Type	Description
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

200: OK Success

{
    "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"
    }
}

401: Unauthorized No Authorization

{
    "success": false,
    "message": "",
    "data": {}
}

403: Forbidden Wrong / Invalid API Keys

{
    "success": false,
    "message": "Merchant authentication failed",
    "data": {}
}

Sample Request

{
    "amount":100,
    "transaction_ref":"Aq1111BddCDqdddqdqqEw2",
    "duration":600,
    "email":"[e-mail]"
}

Get Transactions

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 retrieve transactions to see their status.

GET https://sandbox-api-d.squadco.com/virtual-account/get-dynamic-virtual-account-transactions/:transaction_reference

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.

Path Parameters

Name	Type	Description
transaction_reference*	String	Merchant's transaction reference passed when initiating / generating the dynamic virtual account.

200: OK Success

{
    "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
            }
        ]
    }
}

401: Unauthorized No Authorization

{
    "success": false,
    "message": "",
    "data": {}
}

403: Forbidden Invalid / Wrong API Keys

{
    "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

PATCH https://sandbox-api-d.squadco.com/virtual-account/update-dynamic-virtual-account-time-and-amount

Request Body

Name	Type	Description
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.

200: OK Success

{
    "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"
    }
}

403: Forbidden Wrong / Invalid API Keys

{
    "success": false,
    "message": "Merchant authentication failed",
    "data": {}
}

401: Unauthorized No Authorization

{
    "success": false,
    "message": "",
    "data": {}
}

404: Not Found Invalid Transaction Ref

{
    "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.

POST https://sandbox-api-d.squadco.com/virtual-account/simulate/payment

Request Body

Name	Type	Description
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

200: OK Success

{
    "status": 200,
    "success": true,
    "message": "Success",
    "data": "Payment successful"
}

401: Unauthorized No Authorization

{
    "success": false,
    "message": "",
    "data": {}
}

403: Forbidden Invalid / Wrong API Keys

{
    "success": false,
    "message": "Merchant authentication failed",
    "data": {}
}

DVA REFUNDS

As earlier highlighted in this documentation, customers are expected to pay the exact amount specified for each initiated Dynamic Virtual Account within the specified time. Where a customer fails in any of these (mismatched or expired) the default flow is that the customer is automatically refunded.

However, for use cases where merchants require the mismatched or expired funds to be settled to them and they take on the responsibility of refunding the customers this can now be done:

Expired or mismatched DVA transactions will be processed to one of the following:

1. Merchant's Dashboard

2. Merchant's GTBank settlement account

3. Sub- merchant's wallet

PROCESS FLOW

1. A merchant must send a written request via mail for any of the profiling options. The mail should contain

   1. Merchant ID

   2. Where the mismatched/expired transactions should be settled (Merchant Dashboard, GTBank Settlement account or Sub-Merchant Wallet). The mail should be sent to the Key account manager with [e-mail] in copy of the mail.

2. If the request is approved, the merchant will be profiled internally and Informed

WEBHOOKS

Webhook Notification is sent for 3 different events/ status

1. Success: first transfer/transaction that is equal to the expected/specified amount and within the set duration.

2. Mismatch: A transfer that happens within the specified duration but expected amount is not equal to the transfered amount.

3. 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.

Webhook & Redirect URLSquad API Documentation

Sample Webhook Notification (Success)

{
  "transaction_status": "SUCCESS",
  "merchant_reference": "Aq1111BddCDqdddqdqqEw4",
  "merchant_amount": "100.00",
  "amount_received": "100.00",
  "transaction_reference": "REFFX8U72GD6/1691478173792",
  "email": "[e-mail]",
  "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": "[e-mail]",
  "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": "[e-mail]",
  "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.

API SpecificationsVirtual Accounts

Click to Open Link

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": "[e-mail]",
                    "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": "[e-mail]",
                    "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"
            }
        ]
    }
}

Go Live

To go live, simply:

1. Change the base URL of your endpoints from sandbox-api-d.squadco.com to api-d.squadco.com

2. Sign up on our Live Environment

3. Sign the integration sign-off document after completing the UAT

4. Complete your KYC on the Live Environment

5. Use the secret key provided on the dashboard to replace the test keys from the sandbox environment to authenticate your live transactions.