API Reference Documentation
Integrate TZPayWay payment checkout directly into your platform or e-commerce shop using standard HTTPS REST endpoints and AES-256 encrypted JSON payloads.
Authentication
Learn how API Keys and Secret Keys work.
Create Payment
Initiate payment orders using your API Key.
Webhooks & Decryption
Decrypt webhook payloads using your backend Secret Key.
API Keys vs. Secret Key
Understanding request headers and backend decryption keys.
1. API Key (Sent in Headers)
Passed in the X-API-KEY HTTP header for all endpoint requests to authenticate your merchant account.
X-API-KEY: key_merchant_123456
2. Secret Key (Backend Server Only)
Kept strictly confidential on your backend server. Never pass this in client requests or expose it publicly. Used to decrypt webhook payloads and verify signatures.
Secret Key: sec_xxxxxxxxxxxxxxxx
Sandbox Testing
How to test your integration without moving real funds.
TzPayway provides a dedicated Sandbox environment for testing your API integration. You can simulate creating transactions and processing webhook callbacks.
How to test your API Keys:
- Navigate to the API Credentials page.
- Click the Sandbox Test button next to any of your active API keys.
- Configure the test parameters (amount, method filters, currency).
- Generate the test payment. You will be redirected to the checkout page, just like a live customer would.
Note: Method inclusion and exclusion rules applied to your API Keys are strictly enforced in the Sandbox environment. This ensures your test integration behaves exactly as it will in production.
Get Available Payment Methods
Retrieve a list of all active payment methods on the platform.
https://tzpayway.com/api/v1/payment/methods
Headers
| Header | Value |
|---|---|
| X-API-KEY | Your valid Merchant API Key |
curl -X GET "https://tzpayway.com/api/v1/payment/methods" \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Accept: application/json"
Response Format
{
"success": true,
"data": [
{
"name": "bKash",
"slug": "bkash",
"logo": "url_to_logo",
"type": "mobile_banking"
},
{
"name": "Nagad",
"slug": "nagad",
"logo": "url_to_logo",
"type": "mobile_banking"
}
]
}
Live Request Playground (Interactive Sandbox)
Test directly from browserCreate Payment Session
Initiates a payment order and generates a checkout link.
/api/v1/payment/create
Request Parameters (JSON Body)
100.00).
"merchant" (default, deducted from settlement) or "customer" (added on top of customer order total).
["bkash", "nagad"]. Restricts methods available to the user.
curl -X POST "https://tzpayway.com/api/v1/payment/create" \
-H "X-API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": 100.00,
"charge_payer": "merchant",
"allowed_methods": ["bkash", "nagad"],
"webhook_url": "https://yourwebsite.com/api/payment-webhook",
"success_url": "https://yourwebsite.com/checkout/success"
}'
Response Format
{
"success": true,
"transaction": {
"trx_id": "TZD8W3HF96I",
"amount": 100,
"status": "assigned",
"allowed_methods": [
"bkash",
"nagad",
"rocket",
"upay"
]
},
"checkout_url": "https://tzpayway.com/checkout/pay/TZD8W3HF96I"
}
Live Request Playground (Interactive Sandbox)
Test directly from browserVerify Transaction Status
Query transaction status and received breakdown by transaction ID.
/api/v1/payment/status/{trx_id}
curl -X GET "https://tzpayway.com/api/v1/payment/status/TZD8W3HF96I" \
-H "X-API-KEY: YOUR_API_KEY"
{
"success": true,
"data": {
"trx_id": "TZD8W3HF96I",
"status": "paid",
"amount": 100.00,
"received_amount": 100.00,
"due_amount": 0.00,
"currency": "BDT",
"method": "bkash"
}
}
Live Request Playground (Interactive Sandbox)
Test directly from browserWebhooks & Backend Decryption
Real-time callbacks encrypted with AES-256-CBC and HMAC signature verification.
When a transaction status updates (paid, partial, or canceled), TZPayWay dispatches an instant HTTP POST request to your specified webhook_url. Note: Webhooks are not triggered for initial pending status.
Tamper-Proof Encryption & Signature Security
Sensitive payment data inside encrypted_data is encrypted using AES-256-CBC with your private Secret Key. You decrypt this parameter on your backend server. Additionally, an X-Webhook-Signature HTTP header is attached to verify request authenticity.
{
"event": "transaction.updated",
"trx_id": "TZD8W3HF96I",
"status": "paid",
"amount": 100.00,
"received_amount": 100.00,
"due_amount": 0.00,
"currency": "BDT",
"encrypted_data": "f8a92b...[Base64 IV + AES-256 CipherText]...",
"timestamp": "2026-07-26T18:15:00Z"
}
Backend Decryption Helper (Using Secret Key)
<?php
function decryptPayload(string $encryptedBase64, string $secretKey): array
{
$raw = base64_decode($encryptedBase64);
$iv = substr($raw, 0, 16);
$cipherText = substr($raw, 16);
$key = hash('sha256', $secretKey, true);
$json = openssl_decrypt($cipherText, 'AES-256-CBC', $key, OPENSSL_RAW_DATA, $iv);
return json_decode($json, true) ?? [];
}
$secretKey = "YOUR_SECRET_KEY";
$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$expectedSignature = hash_hmac('sha256', $rawBody, $secretKey);
if (!hash_equals($expectedSignature, $signature)) {
http_response_code(401);
exit("Invalid Webhook Signature!");
}
$payload = json_decode($rawBody, true);
$decryptedData = decryptPayload($payload['encrypted_data'], $secretKey);
$trxId = $decryptedData['trx_id'];
$amount = $decryptedData['amount'];
$status = $decryptedData['status'];
HTTP Response & Error Codes
Standard HTTP status codes returned by the API.