Direct API Integration

This suite of APIs allows you to directly initiate CARD, 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 CARD

This suite of API's allows merchants to directly collect customer card details and charge the cards following the expected steps. Only PCI-DSS-certified and profiled merchants will be able to make use of the service

Due to the nature of payment systems around cards, several possible scenarios may play out, which are broadly classified as:

  1. Payments requiring only PIN for completion

  2. Payments requiring only OTP for completion

  3. Payments requiring a combination of both PIN and OTP for completion

  4. Payments requiring a challenge (3DS) for completion

The Expected next step to take will be based on the transaction_status in the response body after the Step 1 (Charge Card)

Test Cards for Different Scenarios

4242424242424242 >> Direct OTP validation (Use Amount < ₦7,500)

5200000000001096 >> 3DS authentication

5555555555554444 >> PIN + OTP (Two-step validation: PIN verification → OTP validation)

Step #1: Charge Card

This endpoint allows you to pass collected card details and other required fields

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

Request Body

Name
Type
Description

transaction_reference

String

An alphanumeric string that uniquely identifies a transaction (where none is presented, the system generates one for you)

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

pass_charge

Boolean

Allows charges to be passed to customer when set as True, else merchant bears charges

webhook_url

String

Specifies where successfull notification is sent on payment completion (superseded by webhook_url set on dashboard)

card*

Object

Collects card details comprising of card number, cvv, expiry_month & expiry_year

payment_method*

String

Either "card" or "ussd"

customer*

Object

Collects name and email of customer making payment, email receives receipt of successfull payment

redirect_url

String

Specifies site to be redirected to after successfull payment

Sample Request

{
    // "transaction_reference": "hell333o123",
    "amount": 1000000,
    "pass_charge": true,
    "currency": "NGN",
    "webhook_url": "https://webhook.site/50733ce1-f957-4900-9f4a-3eddf0a1f270",
    "card": {
        "number": "5555555555554444",
        "cvv": "121",
        "expiry_month": "12",
        "expiry_year": "50"
    },
    "payment_method": "card",
    "customer": {
        "name": "Tams Bills",
        "email": "50733ce1-f957-4900-9f4a-3eddf0a1f270@emailhook.site"
    },
    "redirect_url": "https://www.squadco.com/"
}

Sample Response

{
    "status": 200,
    "success": true,
    "message": "Success",
    "data": {
        "amount": 1001000,
        "transaction_ref": "SQDEMO6388697447108000002",
        "currency": "NGN",
        "transaction_type": "Card",
        "gateway_ref": "SQDEMO6388697447108000002_1_1_1",
        "merchant_amount": 1000000,
        "message": "Charge Attempted",
        "transaction_status": "ValidatePin"
    }
}

Step #2: Authorize Payment

This endpoint allows you to authorize a payment based on the transaction_status from the charge card process

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

For ValidatePin, use PIN: 1234 For ValidateOTP, use OTP: 123456

Sample Request for ValidatePin

{
    "transaction_reference": "SQDEMO6388591221547800002",
    "authorization": {
        "pin": "1234"
    }
}

Sample Request for ValidateOTP

{
    "transaction_reference": "SQDEMO6388591221547800002",
    "authorization": {
        "otp": "123456"
    }
}

Response

{
    "status": 200,
    "success": true,
    "message": "Success",
    "data": {
        "amount": 1001000,
        "transaction_ref": "SQDEMO6388697447108000002",
        "currency": "NGN",
        "transaction_type": "Card",
        "gateway_ref": "SQDEMO6388697447108000002_1_1_1",
        "merchant_amount": 1000000,
        "message": "Validate pin attempted",
        "transaction_status": "ValidateOTP"
    }
}

3DS (ThreeDSecure)

Where transaction_status is ThreeDSecure, the challenge is to be completed by following the URL specified in the auth_url field. When executed, a challenge page is initiate,d and once the challenge is completed, a payment successful page is displayed and then redirected to redirect_url provided.

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": "squadtest@gmail.com"
  }
}
{
    "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"
    }
}

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

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

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": "TestUser@gmail.com"
  }
}

Sample Response

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

PreviousChannelsNextSquad Payment Modal

Last updated

Was this helpful?