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

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

200: OK Success

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

401: Unauthorized No Authorization

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

403: Forbidden Invalid / Wrong Authorization

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

Get Pool Count

This API gives you the total count of the virtual accounts you have in your pool.

This API gives you the total count of the virtual accounts you have in your pool

GET https://sandbox-api-d.squadco.com/virtual-account/count-dynamic-virtual-accounts

200: OK Success

{
    "status": 200,
    "success": true,
    "message": "Success",
    "data": {
        "count_dynamic_virtual_account": 8
    }
}

401: Unauthorized No Authorization

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

403: Forbidden Invalid / Wrong API Keys

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

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

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

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

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.

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

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