Agent API Key:

Agent Guide • v1.0 Agent API

Agent API Documentation

Automatically verify customer deposits, check agent float balances, and approve payment transactions in real time.

API Base URL: https://tzpayway.com/api/v1/agent

Core Features

Instant Deposit Alerts

Send automated alerts as soon as customer money arrives in your bKash, Nagad, Rocket, or Upay wallet.

Approve Payments

Confirm pending transactions programmatically upon receipt of payment details.

Secure Header Key

Send your API key in the request header to secure every API call.

Quick Links

SPEC

Method Inputs

Method required fields

GET

Check Balance

View float & status

GET

Pending Deposits

List pending deposits

POST

Approve Deposit

Confirm deposit

GET

Pending Withdrawals

List open withdrawals

POST

Approve Withdrawal

Confirm withdrawal

Getting Started

Authentication

Send your API key in the request header to authenticate every request.

Request Header

X-AGENT-API-KEY

Pass your Agent API key in the X-AGENT-API-KEY header on every HTTP request.

X-AGENT-API-KEY:

Security Control

IP Whitelisting

Restrict API requests to specific server IP addresses from your Agent Dashboard for extra protection.

Configuration & Specifications

Method-Based Required Inputs

Every payment gateway (bKash, Nagad, Rocket, Upay, etc.) defines specific input requirements for verifying deposits and approving withdrawals. Below is the active schema breakdown for all supported payment methods.

Filter Payment Methods:

bKash

bkash BDT

Deposit: 10.00 - 50,000.00 BDT • Withdraw: 500.00 - 50,000.00 BDT

Withdrawal Enabled

Deposit Ping Inputs (`/api/v1/agent/ping`)

Passed in request body

Field Key	Label	Type	Status	Validation & Notes
`amount`	Deposit Amount	number	Required	Must be greater than 0 e.g. `500.00`
`payment_details.sender_number` or root `sender_number`	Sender Number	text	Required	Min 11 chars Max 11 chars
`payment_details.transaction_id` or root `transaction_id`	Transaction ID	text	Required	Min 8 chars Max 25 chars • Unique transaction ID required

Withdrawal Settlement Inputs (`/api/v1/agent/transactions/{id}/accept`)

Required when agent confirms payout

Field Key	Purpose	Type	Required	Notes
`confirm_amount`	Confirmed Payout Amount	number	Optional	Auto-fills from order `amount` if omitted
`payment_details.transaction_id` or root `transaction_id`	Transaction ID	text	Required	Accepts as `transaction_id`, `payment_details.transaction_id`, or `dynamic_data.transaction_id`

Nagad

nagad BDT

Deposit: 10.00 - 50,000.00 BDT • Withdraw: 300.00 - 50,000.00 BDT

Deposit Enabled Withdrawal Enabled

Deposit Ping Inputs (`/api/v1/agent/ping`)

Passed in request body

Field Key	Label	Type	Status	Validation & Notes
`amount`	Deposit Amount	number	Required	Must be greater than 0 e.g. `500.00`
`payment_details.sender_number` or root `sender_number`	Sender Number	text	Required	Min 11 chars Max 11 chars
`payment_details.transaction_id` or root `transaction_id`	Transaction ID	text	Required	Min 8 chars Max 25 chars • Unique transaction ID required

Withdrawal Settlement Inputs (`/api/v1/agent/transactions/{id}/accept`)

Required when agent confirms payout

Field Key	Purpose	Type	Required	Notes
`confirm_amount`	Confirmed Payout Amount	number	Optional	Auto-fills from order `amount` if omitted
`payment_details.transaction_id` or root `transaction_id`	Transaction ID	text	Required	Accepts as `transaction_id`, `payment_details.transaction_id`, or `dynamic_data.transaction_id`

Rocket

rocket BDT

Deposit: 10.00 - 50,000.00 BDT • Withdraw: 300.00 - 50,000.00 BDT

Deposit Enabled Withdrawal Enabled

Deposit Ping Inputs (`/api/v1/agent/ping`)

Passed in request body

Field Key	Label	Type	Status	Validation & Notes
`amount`	Deposit Amount	number	Required	Must be greater than 0 e.g. `500.00`
`payment_details.sender_number` or root `sender_number`	Sender Number	text	Required	Min 11 chars Max 11 chars
`payment_details.transaction_id` or root `transaction_id`	Transaction ID	text	Required	Min 8 chars Max 25 chars • Unique transaction ID required

Withdrawal Settlement Inputs (`/api/v1/agent/transactions/{id}/accept`)

Required when agent confirms payout

Field Key	Purpose	Type	Required	Notes
`confirm_amount`	Confirmed Payout Amount	number	Optional	Auto-fills from order `amount` if omitted
`payment_details.transaction_id` or root `transaction_id`	Transaction ID	text	Required	Accepts as `transaction_id`, `payment_details.transaction_id`, or `dynamic_data.transaction_id`

API Endpoints

Check Agent Balance

Check your current agent float balance and active status.

GET /api/v1/agent/status

Headers

X-AGENT-API-KEY header required

Response Fields

agent_id integer

name string

balance number (Total Balance)

available_balance number (Available Float)

pending_deposits_usd number (Pending Locked)

status string ("active")

last_heartbeat ISO 8601 timestamp

curl --request GET \
  --url https://tzpayway.com/api/v1/agent/status \
  --header 'X-AGENT-API-KEY: YOUR_AGENT_KEY'

const res = await fetch("https://tzpayway.com/api/v1/agent/status", {
  headers: { "X-AGENT-API-KEY": "YOUR_AGENT_KEY" }
});
const data = await res.json();

$ch = curl_init("https://tzpayway.com/api/v1/agent/status");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-AGENT-API-KEY: YOUR_AGENT_KEY"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$res = json_decode(curl_exec($ch), true);

import requests

res = requests.get(
    "https://tzpayway.com/api/v1/agent/status",
    headers={"X-AGENT-API-KEY": "YOUR_AGENT_KEY"}
)
data = res.json()

200 OK Response

{
  "success": true,
  "data": {
    "agent_id": 3,
    "name": "Shakhawat Hossain",
    "balance": 100,
    "available_balance": 95.10000001,
    "pending_deposits_usd": 4.89999999,
    "status": "active",
    "last_heartbeat": "2026-08-18T12:15:05+06:00"
  }
}

API Endpoints

Pending Transactions

Get all assigned pending transactions waiting for agent approval.

GET /api/v1/agent/transactions/pending

Headers

X-AGENT-API-KEY header required

curl --request GET \
  --url https://tzpayway.com/api/v1/agent/transactions/pending \
  --header 'X-AGENT-API-KEY: YOUR_AGENT_KEY'

const res = await fetch("https://tzpayway.com/api/v1/agent/transactions/pending", {
  headers: { "X-AGENT-API-KEY": "YOUR_AGENT_KEY" }
});
const data = await res.json();

200 OK Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "trx_id": "TZDUJURCKD55W",
      "amount": 500.00,
      "usd_amount": 4.00,
      "method_currency": "BDT",
      "status": "pending",
      "method": "bkash",
      "type": "deposit",
      "customer_number": "01798616779",
      "submitted_info": {
        "sender_number": "01798616779",
        "transaction_id": "ASDFGH12"
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "total": 1
  }
}

API Endpoints

Approve Payment

Approve or confirm payment for a pending transaction ID.

POST /api/v1/agent/transactions/{id}/accept

Headers

X-AGENT-API-KEY header required

Request Body

confirm_amount number required

The amount confirmed e.g. 500.00.

curl --request POST \
  --url https://tzpayway.com/api/v1/agent/transactions/1/accept \
  --header 'X-AGENT-API-KEY: YOUR_AGENT_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "confirm_amount": 500.00
  }'

const res = await fetch("https://tzpayway.com/api/v1/agent/transactions/1/accept", {
  method: "POST",
  headers: {
    "X-AGENT-API-KEY": "YOUR_AGENT_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    confirm_amount: 500.00
  })
});
const data = await res.json();

200 OK Response

{
  "success": true,
  "message": "Transaction is now fully paid.",
  "data": {
    "trx_id": "TZDUJURCKD55W",
    "status": "paid",
    "received_amount": 500.00
  }
}

API Endpoints

Pending Withdrawals

Get all assigned pending withdrawal requests waiting for agent processing and approval.

GET /api/v1/agent/withdraw/pending

Headers

X-AGENT-API-KEY header required

curl --request GET \
  --url https://tzpayway.com/api/v1/agent/withdraw/pending \
  --header 'X-AGENT-API-KEY: YOUR_AGENT_KEY'

const res = await fetch("https://tzpayway.com/api/v1/agent/withdraw/pending", {
  headers: { "X-AGENT-API-KEY": "YOUR_AGENT_KEY" }
});
const data = await res.json();

200 OK Response

{
  "success": true,
  "data": [
    {
      "id": 4,
      "trx_id": "TZDTESTKBOK9RBA",
      "amount": 100,
      "usd_amount": 0.8,
      "method_currency": "BDT",
      "status": "pending",
      "method": "nagad",
      "type": "withdrawal",
      "customer_number": "01798616779",
      "submitted_info": {
        "account_number": "01798616779"
      },
      "created_at": "2026-08-18T06:06:29.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "total": 1
  }
}

API Endpoints

Approve Withdrawal

Approve or settle a pending withdrawal request with reference and payment proof.

POST /api/v1/agent/withdraw/approve

Headers

X-AGENT-API-KEY header required

Active Methods with Withdrawal Enabled

Select a method to view required fields

bKash Settlement Info Required: Currency: BDT

transaction_id *

Nagad Settlement Info Required: Currency: BDT

transaction_id *

Rocket Settlement Info Required: Currency: BDT

transaction_id *

Request Body

trx_id required

The withdrawal transaction ID or DB numeric ID e.g. TZDTESTKBOK9RBA.

confirm_amount optional

The confirmed amount settled to customer e.g. 100.00.

payment_details.transaction_id required

Transaction ID. Send inside payment_details object.

curl --request POST \
  --url https://tzpayway.com/api/v1/agent/withdraw/approve \
  --header 'X-AGENT-API-KEY: YOUR_AGENT_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "trx_id": "TZDTESTKBOK9RBA",
    "confirm_amount": 100.00,
    "payment_details": {
      "transaction_id": "EXAMPLE_VALUE"    }
  }'

const res = await fetch("https://tzpayway.com/api/v1/agent/withdraw/approve", {
  method: "POST",
  headers: {
    "X-AGENT-API-KEY": "YOUR_AGENT_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    trx_id: "TZDTESTKBOK9RBA",
    confirm_amount: 100.00,
    payment_details: {
      transaction_id: "EXAMPLE_VALUE"    }
  })
});
const data = await res.json();

200 OK Response

{
  "success": true,
  "message": "Withdrawal request approved successfully.",
  "data": {
    "trx_id": "TZDTESTKBOK9RBA",
    "status": "paid",
    "received_amount": 100.00
  }
}

Error Reference

Error Codes

Common HTTP status codes returned by the Agent API.

200 OK Request completed successfully.

401 Unauthorized Missing or invalid X-AGENT-API-KEY header.

Agent API Documentation

Core Features

Instant Deposit Alerts

Approve Payments

Secure Header Key

Quick Links

Method Inputs

Check Balance

Pending Deposits

Approve Deposit

Pending Withdrawals

Approve Withdrawal

Authentication

X-AGENT-API-KEY

IP Whitelisting

Method-Based Required Inputs

bKash

Deposit Ping Inputs (/api/v1/agent/ping)

Withdrawal Settlement Inputs (/api/v1/agent/transactions/{id}/accept)

Nagad

Deposit Ping Inputs (/api/v1/agent/ping)

Withdrawal Settlement Inputs (/api/v1/agent/transactions/{id}/accept)

Rocket

Deposit Ping Inputs (/api/v1/agent/ping)

Withdrawal Settlement Inputs (/api/v1/agent/transactions/{id}/accept)

Check Agent Balance

Headers

Response Fields

Pending Transactions

Headers

Approve Payment

Headers

Request Body

Pending Withdrawals

Headers

Approve Withdrawal

Headers

Request Body

Error Codes

Test Agent API Sandbox

Deposit Ping Inputs (`/api/v1/agent/ping`)

Withdrawal Settlement Inputs (`/api/v1/agent/transactions/{id}/accept`)

Deposit Ping Inputs (`/api/v1/agent/ping`)

Withdrawal Settlement Inputs (`/api/v1/agent/transactions/{id}/accept`)

Deposit Ping Inputs (`/api/v1/agent/ping`)

Withdrawal Settlement Inputs (`/api/v1/agent/transactions/{id}/accept`)