Direct API Integration

This suite of APIs allows you to directly initiate BANK and USSD transactions without using the Squad Modal.

Authorization Any request made without the authorization key (secret key) will fail with a 401 (Unauthorized) response code.

If using other services such as dynamic virtual accounts, do not use the same transaction reference

The authorization key is sent via the request header as Bearer Token Authorization

Example: Authorization: Bearer sandbox_sk_94f2b798466408ef4d19e848ee1a4d1a3e93f104046f

DIRECT GTBANK ACCOUNT DEBIT

POST https://sandbox-api-squadco.com/transaction/initiate/process-payment

This endpoint allows you to initiate the direct debit of a GTBank account by passing the account number. After initiating the request using this endpoint, you are then to call the validate endpoint to complete the transaction.

Headers

Name	Type	Description
Authorization*	String	API keys (Secret Key) that authorizes your transactions and gotten from your squad dashboard

Request Body

Name	Type	Description
email*	String	Customer's email address.
amount*	Integer	The amount in kobo you are debiting customer (expressed in the lowest currency value - kobo). 10000 = 100NGN
currency	String	The currency you want the amount to be charged in. Allowed value is NGN
name	String	Name of Customer carrying out the transaction
bank_code*	String	Unique NIP code that identifies a bank.
payment_method*	String	method of payment (should use BANK)
transaction_ref	String	An alphanumeric string that uniquely identifies a transaction (where none is presented, the sytem generates one for you)
webhook_url	String	Allows you define where webhook notification is sent (where none is presented, the default webhook for merchant is notified)
account_or_phoneno*	String	The GTBank account number to be debitted
pass_charge	Boolean	It takes two possible values: True or False. It is set to False by default. When set to True, the charges on the transaction is computed and passed on to the customer(payer). But when set to False, the charge is passed to the merchant and will be deducted from the amount to be settled to the merchant.

Sample Request

{
  "transaction_reference": "test001",
  "amount": 51800,
  "pass_charge": false,
  "currency": "NGN",
  "webhook_url": "www.sampleurl.com",
  "bank": {
    "bank_code": "058",
    "account_or_phoneno": "08146663666"
  },
  "payment_method": "bank",
  "customer": {
     "name": "William Udousoro",
   "email": "[e-mail]"
  }
}

200: OK Successful

{
    "status": 200,
    "success": true,
    "message": "Success",
    "data": {
        "amount": 51800,
        "transaction_ref": "SQDEMO6386363720055500003",
        "transaction_type": "Bank",
        "gateway_ref": "SQDEMO6386363720055500003_2_2_1",
        "merchant_amount": 46178.4,
        "message": "Please enter the 6-digit code from your GTBank token / e-Token or dial *737*7# with your registered GTBank phone number.",
        "auth_model": "ValidateTOKEN"
    }
}

401: Unauthorized Invalid/No Authorization Key

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

400: Bad Request Bad Request

{
    "status": 400,
    "success": false,
    "message": "\"account_or_phoneno\" is required",
    "data": {}
}

Validate Payment for Direct Bank API Payment

POST https://sandbox-api-squadco.com/transaction/validate-payment

Once a payment is initiated using the Direct Bank API, the transaction must be authenticated. This is done using this endpoint to receive details from the user.

For the auth_model: The value could be either ValidateTOKEN or ValidateOTP.

If ValidateTOKEN is received, the payee is expected to input OTP from *737*7#, hardware token or e-token to complete the transaction.

If ValidateOTP is returned, then an OTP will be sent to the phone number linked to the customer account number which the payee inputs to complete the transaction.

Name	Type	Description
transaction_reference*	String	Transaction Refrence from the initiated payment
otp_token*	String	Unique OTP or Token sent to customer, required for transaction completion
authorization	Object	Contains otp_token

Sample Request

{
  "transaction_reference": "SQDEMO6386363261862600002",
  "authorization": {
    "otp_token": "123456"
  }
}

Sample Response

ValidateTOKEN

{
    "status": 200,
    "success": true,
    "message": "Success",
    "data": {
        "amount": 56800,
        "transaction_ref": "SQDEMO6386313153377900002",
        "transaction_type": "Bank",
        "gateway_ref": "SQDEMO6386313153377900002_2_2_1",
        "merchant_amount": 51118.4,
        "auth_model": "ValidateTOKEN",
        "message": "Charge attempted"
    }
}

ValidateOTP

{
    "status": 200,
    "success": true,
    "message": "Success",
    "data": {
        "amount": 56800,
        "transaction_ref": "SQDEMO6386313153377900002",
        "transaction_type": "Bank",
        "gateway_ref": "SQDEMO6386313153377900002_2_2_1",
        "merchant_amount": 51118.4,
        "auth_model": "ValidateOTP",
        "message": "Charge attempted"
    }
}

DIRECT USSD Transactions

These suites of APIs allow you to make use of the USSD endpoints to directly access USSD codes.

Bank USSD List

GET https://sandbox-api-d.squadco.com/transaction/ussd/banklist

This API allows you to retrieve the list of all USSD-supported banks along with their bank codes

Response

{
    "status": 200,
    "success": true,
    "message": "Success",
    "data": [
        {
            "label": "Access (Diamond)",
            "bank_code": "063"
        },
        {
            "label": "Access",
            "bank_code": "044"
        },
        {
            "label": "Fidelity Bank",
            "bank_code": "070"
        },
        {
            "label": "First Bank",
            "bank_code": "011"
        },
        {
            "label": "Globus Bank",
            "bank_code": "00103"
        },
        {
            "label": "Guaranty Trust Bank",
            "bank_code": "058"
        },
       
        
    ]
}

USSD-SUPPORTED BANKS AND BANK CODES

BANK	BANK CODE
Access (Diamond)	063
Access	044
Ecobank	050
FCMB	214
Fidelity Bank	070
First Bank	011
Guaranty Trust Bank	058
Heritage Bank	030
Keystone Bank	082
Rubies (Highstreet) MFB	125
Stanbic Bank	221
Sterling Bank	232
UBA	033
Union Bank	032
Unity Bank	215
VFD Bank	566
Wema Bank	035
Zenith Bank	057
Globus bank	00103
Premium Trust Bank	105
LOTUS bank	303
Optimum Trust Bank	107
Kuda MFB	50211

The bank code provided is what should be populated in the bank_code parameter.

USSD INITIATE

POST https://sandbox-api-squadco.com/transaction/initiate/process-payment

This API allows you to directly process USSD transactions directly with the same parameter details as direct bank payments.

Sample Request

{
  "transaction_reference": "testussd",
  "amount": 56800,
  "pass_charge": false,
  "currency": "NGN",
  "webhook_url": "www.sampleurl.com",
  "ussd": {
    "bank_code": "058"
  },
  "payment_method": "ussd",
  "customer": {
    "name": "Test User",
    "email": "[e-mail]"
  }
}

Sample Response

200 OK

{
    "status": 200,
    "success": true,
    "message": "Success",
    "data": {
        "amount": 56800,
        "transaction_ref": "SQDEMO6386363261862600002",
        "transaction_type": "Ussd",
        "gateway_ref": "SQDEMO6386363261862600002_3_3_1",
        "merchant_amount": 51118.4,
        "message": "USSD Payment Reference Generated",
        "auth_model": "USSDCodeGenerated",
        "ussd_details": {
            "ussd_reference": "*737*000*1914",
            "expiresAt": "2024-10-04T11:01:59.8888866"
        }
    }
}

QUERY USSD Transaction

GET https://sandbox-api-d.squadco.com/transaction/verify/ussd/{{transaction_ref}}

This endpoint allows you requery a USSD transaction for testing purposes in the sandbox environment

Sampe response

{
    "status": 200,
    "success": true,
    "message": "Success",
    "data": {
        "amount": 10000,
        "transaction_ref": "test001",
        "currency": "NGN",
        "transaction_type": "Ussd",
        "gateway_ref": "test001",
        "message": "success",
        "transaction_status": "Success"
    }
}

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. Complete your KYC

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