Getting Started

Payments API

Webhooks

API Reference

Welcome to the ChalakPay API documentation. Our API allows you to programmatically create checkout sessions and receive automated payment confirmations for bKash, Nagad, Rocket, and other gateways.

Authentication

ChalakPay uses API keys to authenticate requests. You can view and manage your API keys in the ChalakPay Dashboard under Developer Settings.

Important: Keep your Secret Keys confidential. Do not share them publicly or commit them to version control.

Authentication to the API is performed via HTTP Bearer Auth. Provide your secret key as the bearer token in the Authorization header.

Authorization: Bearer sk_live_YOUR_SECRET_KEY

Create Checkout Session

To accept a payment, you first need to create a Checkout Session. This endpoint returns a checkout_url that you should redirect your customer to.

Endpoint

POST /api/v1/checkout

Request Body (JSON)

ParameterTypeDescription
amount *numberThe amount to charge the customer.
merchant_order_id *stringYour internal system's unique order ID.
redirect_url *stringThe URL to redirect the customer to after payment.
customer_emailstringOptional. Customer's email address.
customer_namestringOptional. Customer's full name.
metadataobjectOptional. Any custom JSON data you want to attach.

Example Request

curl -X POST https://yourdomain.com/api/v1/checkout \
  -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "merchant_order_id": "ORD-12345",
    "redirect_url": "https://yourshop.com/checkout/success",
    "customer_name": "John Doe",
    "customer_email": "john@example.com"
  }'

Example Response

{
  "checkout_url": "https://yourdomain.com/pay/a1b2c3d4-e5f6-7890",
  "transaction_id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab"
}

Webhooks

Webhooks are HTTP callbacks that receive notification messages for events. To receive webhooks, you must configure a Webhook URL in your ChalakPay Dashboard.

When a payment is successful, we will send a POST request to your endpoint with the following JSON payload:

{
  "id": "a1b2c3d4-e5f6...",
  "store_id": "98765432-10ab...",
  "amount": 500.00,
  "currency": "BDT",
  "status": "success",
  "gateway": "bkash",
  "provider_transaction_id": "9B5X8J2Z",
  "merchant_order_id": "ORD-12345",
  "customer_email": "john@example.com",
  "metadata": {},
  "created_at": "2024-03-10T12:00:00Z"
}

Verifying Webhook Signatures

If you configure a Webhook Secret in your dashboard, ChalakPay will sign the webhook payload and include the signature in the X-Signature HTTP header.

The signature is generated using HMAC SHA-256 with your webhook secret. You should verify this signature in your server to ensure the request is genuinely from ChalakPay.

Node.js / Express Example

const crypto = require('crypto');

app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
  const payload = req.body; // Raw buffer is required
  const signature = req.headers['x-signature'];
  const secret = 'YOUR_WEBHOOK_SECRET';
  
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
    
  if (signature === expectedSignature) {
    // Valid request, process the payment
    const event = JSON.parse(payload);
    console.log('Payment successful for Order:', event.merchant_order_id);
    res.status(200).send('Webhook Received');
  } else {
    // Invalid signature
    res.status(400).send('Invalid signature');
  }
});