TeasyPay Microaccounts API Documentation

Version 1.0

The TeasyPay Microaccounts API provides a robust and secure way for businesses to manage and automate payment collections through virtual and static accounts. This documentation serves as a guide for developers to integrate with our system, covering authentication, signature generation, and the core API endpoints for account creation and transaction verification.

All API communication is secured using HTTPS and requires a valid JWT Bearer Token for authentication and an HMAC-SHA256 signature for request integrity. All request and response bodies are formatted as JSON.

2.0 Authentication & Security

All API calls must be authenticated and secured using a combination of a JWT Bearer Token and HMAC-SHA256 signature headers.

2.1 Generating an Access Token

To begin, you must generate a short-lived access token using your unique client_id and client_secret. This token expires in 1 hour and must be refreshed.

Endpoint:

POST https://payments.teasypay.ng/tap2/tokentest/v1/generatetoken

Headers:

Content-Type: application/json

Request Body:

{
  "client_id": "{your_client_id}",
  "client_secret": "{your_client_secret}"
}

Successful Response:

{
  "code": "00",
  "status": "success",
  "expires": "1 hour",
  "description": "Token generated successfully",
  "Bearer": {
    "token": "{your_token}"
  }
}

2.2 Request Headers

Once you have a valid token, every subsequent API request must include the following headers:

Header Description Example
Authorization The JWT access token. Format: Bearer {token} Bearer {your_token}
X-Timestamp The current Unix timestamp (in seconds). 1752431097
X-Signature The HMAC-SHA256 signature. See next section. {your_signature}
X-IV The Initialization Vector (IV) for encryption. WU0e/f==
Content-Type Must be application/json. application/json

2.3 Signature Generation

The X-Signature header is a cryptographic signature that verifies the integrity of your request. It is generated by computing an HMAC-SHA256 hash of the concatenated string of the mainWalletNo and the X-Timestamp, using your private API key (apkkey) as the secret key.

Signature Formula: signature = HMAC-SHA256(mainWalletNo + X-Timestamp, apkkey)

Java Code Example:

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;

public class SignatureHelper {
    public static String getSignature(String mainWalletNo, String apkkey) {
        String timeStamp = String.valueOf(System.currentTimeMillis() / 1000L);
        String dataToSign = mainWalletNo + timeStamp;
        
        try {
            Mac mac = Mac.getInstance("HmacSHA256");
            SecretKeySpec secretKeySpec = new SecretKeySpec(apkkey.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
            mac.init(secretKeySpec);
            byte[] hmacBytes = mac.doFinal(dataToSign.getBytes(StandardCharsets.UTF_8));
            
            StringBuilder hexString = new StringBuilder();
            for (byte b : hmacBytes) {
                hexString.append(String.format("%02x", b));
            }
            return hexString.toString();
        } catch (NoSuchAlgorithmException | InvalidKeyException e) {
            throw new RuntimeException("Error generating HMAC-SHA256 signature.", e);
        }
    }
}

3.0 Endpoints

3.1 Create a Static Sub-account

Creates a permanent sub-account tied to your main wallet for consistent collections.

Endpoint:

POST https://payments.teasypay.ng/tap2/microaccounts/v1/addstaticaccount

Request Body Parameters:

Parameter Type Description Required Example
mainWalletNo string The main wallet number. Yes {your_main_wallet_number}
city string The city of the sub-account owner. Yes Lagos
lga string The Local Government Area. Yes Ikeja
state string The state. Yes Lagos
address string The street address. Yes 123 Allen Avenue
subwalletowner string The name of the sub-account owner. Yes Teasypay

Successful Response:

{
  "code": "0",
  "status": "success",
  "accountType": "STATIC",
  "subWalletNo": "5515620688",
  "bank": "TeasyPay/Teasy Mobile",
  "accountName": "TEASY INTL. COMPANY LTD DANIEL IDAKWOJI 1 D6469",
  "message": "Subaccount created successfully"
}

3.2 Create a Dynamic Virtual Account (DVA)

Generates a temporary, single-use virtual account for a specific transaction amount and reference.

Endpoint:

POST https://payments.teasypay.ng/tap2/microaccounts/v1/adddynamicaccount

Request Body Parameters:

Parameter Type Description Required Example
mainWalletNo string The main wallet number. Yes {your_main_wallet_number}
city string City of the sub-account owner. Yes Lagos
lga string Local Government Area. Yes Ikeja
state string State. Yes Lagos
address string Street address. Yes 123 Allen Avenue
subwalletowner string The name of the sub-account owner. Yes Teasypay
expiryTime string The expiry time. Can be left empty. No ""
dvaAmount string The specific amount for the virtual account. Yes 1000
dvaRef string A unique reference for this transaction. Yes 20250918122
dvaEmail string An email for transaction notifications. No testemail@gmail.com

Successful Response:

{
  "code": "0",
  "status": "success",
  "expiryTime": 1758223124,
  "genTime": 1758219524,
  "accountType": "DVA",
  "subWalletNo": "5586696884",
  "bank": "TeasyPay/Teasy Mobile",
  "accountName": "TEASY INTL. COMPANY LTD DANIEL IDAKWOJI 1 D5095",
  "dvaAmount": "1000",
  "dvaRef": "20250918122",
  "dvaEmail": "testemail@gmail.com",
  "message": "Subaccount created successfully"
}

3.3 Verify a Transaction

Queries the status and details of a specific transaction.

Endpoint:

POST https://payments.teasypay.ng/tap2/microaccounts/v1/verifytransaction

Request Body Parameters:

Parameter Type Description Required Example
mainWalletNo string The main wallet number. Yes {your_main_wallet_number}
subWalletNo string The sub-wallet number to verify. Yes 5586696884
dvaRef string The unique reference for the DVA transaction. No 20250918122

Successful Response:

{
  "code": "0",
  "status": "success",
  "Transactions": [
    {
      "Transaction ID": "20250171191221121",
      "Transaction Date": "2025-09-18 19:20:17",
      "Main Wallet No": "2348100158586",
      "Sub Wallet No": "5586696884",
      "Transaction Type": "Credit",
      "Transaction Name": "Bank_Trasnfer",
      "Amount": "5000",
      "Fee": null,
      "Source Name": "Emmanuel UBA",
      "Source Number": "7031366649",
      "Destination Number": "5586696884",
      "Destination Name": "",
      "Transaction Status": "Success",
      "Response Code": "0",
      "Description": "narate",
      "Created At": "2025-09-18 18:20:17",
      "Source Bank": "Opay",
      "Destination Bank": "TeasyPay",
      "destinationBankCode": "100010",
      "sourceBankCode": "100101",
      "sessionID_unit": "11120250511111117",
      "dvaRef": "20250918122"
      }
    ]
  }

3.4 Get Static Accounts

Retrieves a list of all static sub-accounts created under a main wallet.

Endpoint:

POST https://payments.teasypay.ng/tap2/microaccounts/v1/getstaticaccounts

Request Body Parameters:

Parameter Type Description Required Example
mainWalletNo string The main wallet number. Yes {your_main_wallet_number}
subWalletNo string The specific sub-wallet number. Leave empty to get all. No ""
posSerial string POS serial number. Leave empty if not applicable. No ""

Successful Response:

{
  "code": "0",
  "status": "success",
  "Subdata": {
    "1": {
      "MainWallet": "2348100158586",
      "SubWallet": "5515620688",
      "Organization Name": "TEASY INTL. COMPANY LTD DANIEL IDAKWOJI 1 D",
      "SubWallet Org Name": "TEASY INTL. COMPANY LTD DANIEL IDAKWOJI 1 D6469",
      "City": "Lagos",
      "LGA": "Ikeja",
      "State": "LAGOS",
      "Address": "123 Allen Avenue",
      "Status": "Inactive",
      "Created At": "2025-09-19 09:10:11"
    }
  }
}

3.5 Simulate NIP Inward Transfer (Testing Only)

Simulates an incoming NIP transfer for testing purposes.

Endpoint:

POST https://payments.teasypay.ng/tap2/microaccounts/v1/nipftinwardsimulate

Request Body Parameters:

Parameter Type Description Required Example
beneficiarymainWalletNo string The recipient's main wallet number. Yes {your_main_wallet_number}
beneficiarysubWalletNo string The recipient's sub-wallet number. Yes 5586696884
twpTransactionID string A unique transaction ID from your system. Yes 233434556654324
nipSessionID string A unique NIP session ID. Yes 11120250511111117
nameEnquiryRef string The name enquiry reference. Yes 22222025051511127
beneficiaryAccountName string The recipient's account name. Yes Daniel Idakwoji
originatorAccountName string The sender's account name. Yes Emmanuel UBA
originatorAccountNumber string The sender's account number. Yes 7031366649
originatorbankName string The sender's bank name. Yes Opay
originatorbankCode string The sender's bank code. Yes 100101
responseCode string The response code. 0 for success. Yes 0
amount string The transfer amount. Yes 5000
fee string The transaction fee. No 0
narration string A description for the transaction. No narate
timestamp string The transaction timestamp. Yes 2025-08-18 12:00:00
signature string Transaction payload signature. No a1b2c3d4e5f6

Successful Response:

{
  "code": "0",
  "status": "success",
  "message": "Transaction successful",
  "newBalance": 10000
}

4.0 Webhooks

TeasyPay uses webhooks to notify you in real-time about events that occur on your account, such as successful payments. This eliminates the need for constant polling and allows for a more efficient integration.

4.1 Webhook URL Configuration

To receive webhook notifications, you must configure a secure endpoint URL in your TeasyPay account settings. Our system will send HTTP POST requests with event payloads to this URL.

4.2 Security

For security, every webhook request is signed with a signature that you must verify to confirm its authenticity. The signature is an HMAC-SHA256 hash of the raw request body, and it is signed using your private API key (apkkey). The signature is sent in a header, typically X-Teasy-Signature.

Webhook Signature Formula: signature = HMAC-SHA256(request_body, apkkey)

To verify, compute the signature of the raw request body and compare it with the X-Teasy-Signature header value.

4.3 Webhook Payload

The webhook payload is a JSON object that provides detailed information about the event.

Sample Payload:

{
  "event": "credit.successful",
  "data": {
    "code": "0",
    "status": "success",
    "Transactions": [
      {
        "Transaction ID": "20250171191221121",
        "Transaction Date": "2025-09-18 19:20:17",
        "Main Wallet No": "2348100158586",
        "Sub Wallet No": "5586696884",
        "Transaction Type": "Credit",
        "Transaction Name": "Bank_Trasnfer",
        "Amount": "5000",
        "Fee": null,
        "Source Name": "Emmanuel UBA",
        "Source Number": "7031366649",
        "Destination Number": "5586696884",
        "Destination Name": "",
        "Transaction Status": "Success",
        "Response Code": "0",
        "Description": "narate",
        "Created At": "2025-09-18 18:20:17",
        "Source Bank": "Opay",
        "Destination Bank": "TeasyPay",
        "destinationBankCode": "100010",
        "sourceBankCode": "100101",
        "sessionID_unit": "11120250511111117",
        "dvaRef": "20250918122"
      }
    ]
  }
}

5.0 Contact Us

For any technical support, questions, or integration assistance, please don't hesitate to reach out to our team.