Paperless API Reference

Quick Start

Get your first payment running in under 10 minutes. You’ll need a Paperless merchant account and your API keys from the dashboard.

curl -X POST https://api.paperlessltd.com/v1/payments/initiate   -H "Content-Type: application/json"   -H "Authorization: Bearer YOUR_API_KEY"   -d '{
    "merchant_id": "PLMRCH_001",
    "amount": 5000,
    "currency": "BDT",
    "order_id": "ORD_20250101_001",
    "customer_name": "Rahim Uddin",
    "customer_email": "rahim@example.com",
    "redirect_url": "https://yoursite.com/success",
    "webhook_url": "https://yoursite.com/webhooks/paperless"
  }'

Authentication

Paperless uses Bearer token authentication. Pass your API key in every request via the Authorization header.

Authorization: Bearer pl_live_xxxxxxxxxxxxxxxxxxxxxxxx

Key types

Environments

Paperless maintains two fully isolated environments with separate credentials and data.

SDKs & Libraries

Official libraries handle request signing, retries, and response parsing. All are open-source on GitHub.

Payments

The core of Paperless. Initiate a payment session and redirect your customer to the hosted checkout. The page handles provider selection, OTP, and confirmation entirely.

{
  "success": true,
  "txn_id": "PL_TXN_9F3A2C8D",
  "order_id": "ORD_20250101_001",
  "status": "INITIATED",
  "payment_url": "https://pay.paperlessltd.com/checkout/PL_TXN_9F3A2C8D",
  "expires_at": "2025-01-01T11:30:00+06:00",
  "amount": 5000,
  "currency": "BDT"
}

{
  "success": false,
  "error": {
    "code": "INVALID_AMOUNT",
    "message": "Amount must be a positive integer in paisa.",
    "field": "amount"
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key."
  }
}

Payment Status

Fetch the current state of any transaction by its txn_id. Useful for polling if you haven’t set up webhooks yet, or for verifying a webhook payload.

curl https://api.paperlessltd.com/v1/payments/PL_TXN_9F3A2C8D   -H "Authorization: Bearer pl_live_xxxx"

{
  "txn_id": "PL_TXN_9F3A2C8D",
  "order_id": "ORD_20250101_001",
  "status": "COMPLETED",
  "amount": 5000,
  "currency": "BDT",
  "payment_method": "bkash",
  "provider_ref": "BKH8736210000",
  "completed_at": "2025-01-01T11:03:22+06:00"
}

Possible statuses

Refunds

Issue full or partial refunds on any COMPLETED payment. Refunds are processed asynchronously — listen for the refund.completed webhook event to confirm.

curl -X POST https://api.paperlessltd.com/v1/refunds   -H "Authorization: Bearer pl_live_xxxx"   -H "Idempotency-Key: refund-ORD_001"   -d '{"txn_id":"PL_TXN_9F3A2C8D","amount":2500}'

Transactions

Retrieve a paginated list of all transactions for your merchant account. Useful for reconciliation and reporting.

Merchants

Merchant management endpoints require an admin API key (pl_admin_). Contact support@paperlessltd.com to request admin access.

Webhooks

Webhooks deliver real-time event notifications to your server. Configure your endpoint in Dashboard → Settings → Webhooks.

Payload structure

{
  "event": "payment.completed",
  "event_id": "evt_A1B2C3D4E5",
  "timestamp": "2025-01-01T11:03:22+06:00",
  "data": {
    "txn_id": "PL_TXN_9F3A2C8D",
    "order_id": "ORD_20250101_001",
    "status": "COMPLETED",
    "amount": 5000,
    "payment_method": "bkash"
  }
}

Webhook Event Reference

Signature Verification

Every webhook includes a X-Paperless-Signature header — an HMAC-SHA256 of the raw body using your webhook secret. Always verify before processing.

const crypto = require('crypto');

function verifyWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(signature)
  );
}

app.post('/webhooks/paperless', (req, res) => {
  const sig = req.headers['x-paperless-signature'];
  if (!verifyWebhook(req.rawBody, sig, process.env.WH_SECRET))
    return res.status(401).send('Invalid signature');
  // handle event...
  res.sendStatus(200);
});

function verifyWebhook($payload, $sig, $secret): bool {
  $expected = hash_hmac('sha256', $payload, $secret);
  return hash_equals($expected, $sig);
}
$payload = file_get_contents('php://input');
$sig     = $_SERVER['HTTP_X_PAPERLESS_SIGNATURE'];
if (!verifyWebhook($payload, $sig, $_ENV['WH_SECRET'])) {
  http_response_code(401); exit;
}

Idempotency

Supply an Idempotency-Key header on any POST request to safely retry without the risk of duplicate operations.

Idempotency-Key: order-ORD_20250101_001-attempt-1

Error Codes

All errors return a consistent JSON body. code is machine-readable; message is human-readable.

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "The customer wallet does not have sufficient balance.",
    "field": null
  }
}

Testing

Use the sandbox environment with these credentials. No real money moves and all transactions reset daily.

Test cards

Test mobile wallets

Rate Limits

Limits are per API key and reset every 60 seconds. When exceeded a 429 is returned with a Retry-After header.