TZPayWay API Docs
Sign in Get API Keys

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

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 browser
POST

Create Payment Session

Initiates a payment order and generates a checkout link.

/api/v1/payment/create

Request Parameters (JSON Body)

amount *required
Total order amount (numeric decimal e.g., 100.00).
charge_payer optional
Specifies who pays the fee: "merchant" (default, deducted from settlement) or "customer" (added on top of customer order total).
allowed_methods optional
Array of method slugs e.g., ["bkash", "nagad"]. Restricts methods available to the user.
webhook_url optional
Custom HTTPS URL to receive instant AES-256 encrypted JSON webhook notifications.
success_url optional
Redirect URL after payment is complete.
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 browser
GET

Verify 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"
API Response Examples by Status
{
  "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 browser

Webhooks & 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.

HTTP POST Webhook Payload Examples by Status
Status: paid (Fully Completed)
{
  "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 Backend Decryption Helper
<?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.

200 OK Request completed successfully.
400 Bad Request Invalid payload formatting or missing required JSON fields.
401 Unauthorized Missing or invalid X-API-KEY header.
422 Unprocessable Validation failed e.g., amount below minimum threshold (10.00).