Quickstart

Goal: from zero to your first payment_request.paid webhook in 5 minutes, entirely in test mode – no one to contact, no real transfer.

1. Get a test key

   Go to Dashboard › Settings › Developer › Create key and choose Test. The key looks like hk_test_… and is shown once – put it in an environment variable:

   export HENSA_API_KEY="hk_test_..."

   Caution

   Never put API keys in browser code or mobile apps. Call the API from your server only.

2. Create a payment request

   One request per order. Send an Idempotency-Key so a flaky-network retry never creates a duplicate.

   cURL

   curl https://api.hensa.example/v1/payment_requests \
     -H "Authorization: Bearer $HENSA_API_KEY" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{ "amount": 150000, "externalOrderRef": "DH-1024" }'

   Node.js

   // Node.js 18+ (built-in fetch)
   const res = await fetch('https://api.hensa.example/v1/payment_requests', {
     method: 'POST',
     headers: {
       Authorization: `Bearer ${process.env.HENSA_API_KEY}`,
       'Idempotency-Key': crypto.randomUUID(), // reuse the same key when you retry
       'Content-Type': 'application/json'
     },
     body: JSON.stringify({ amount: 150000, externalOrderRef: 'DH-1024' })
   })
   if (!res.ok) throw new Error((await res.json()).error.code)
   const paymentRequest = await res.json()
   console.log(paymentRequest.referenceCode, paymentRequest.qrPayload)

   PHP

   <?php
   $ch = curl_init('https://api.hensa.example/v1/payment_requests');
   curl_setopt_array($ch, [
       CURLOPT_POST => true,
       CURLOPT_RETURNTRANSFER => true,
       CURLOPT_HTTPHEADER => [
           'Authorization: Bearer ' . getenv('HENSA_API_KEY'),
           'Idempotency-Key: ' . bin2hex(random_bytes(16)), // reuse the same key when you retry
           'Content-Type: application/json',
       ],
       CURLOPT_POSTFIELDS => json_encode(['amount' => 150000, 'externalOrderRef' => 'DH-1024']),
   ]);
   $paymentRequest = json_decode(curl_exec($ch), true);
   echo $paymentRequest['referenceCode'];

   Python

   import os, uuid, requests
   
   res = requests.post(
       "https://api.hensa.example/v1/payment_requests",
       headers={
           "Authorization": f"Bearer {os.environ['HENSA_API_KEY']}",
           "Idempotency-Key": str(uuid.uuid4()),  # reuse the same key when you retry
       },
       json={"amount": 150000, "externalOrderRef": "DH-1024"},
       timeout=10,
   )
   res.raise_for_status()
   payment_request = res.json()
   print(payment_request["referenceCode"])

   Response (201 Created):

   {
     "id": "prq_01JD7Q8M4K2X9V3T6B5N0R1W8Y",
     "amount": 150000,
     "currency": "VND",
     "referenceCode": "LK7F3K9",
     "status": "pending",
     "qrPayload": "00020101021238…",
     "receiver": { "name": "CA PHE MOC", "bankName": "MB Bank", "accountMasked": "•••• 6789" },
     "externalOrderRef": "DH-1024",
     "expiresAt": "2026-11-03T08:15:00Z",
     "createdAt": "2026-11-03T08:00:00Z"
   }

3. Show the QR to the customer

   Render qrPayload as a QR code with any QR library, together with the receiver name (receiver.name) and the amount so the customer can check before paying. It expires at expiresAt (15 minutes).

4. Register a webhook

   Dashboard › Developer › Add endpoint → enter your HTTPS URL and pick payment_request.paid. Store the signing secret whsec_… (shown once).

   Working locally? Use an HTTPS tunnel (e.g. ngrok, Cloudflare Tunnel) to get a public URL pointing at localhost.

5. Receive and verify the webhook

   Node.js

   server.js

   import express from 'express'
   import { verifyHensaSignature } from './verify-hensa-signature.js'
   
   const app = express()
   
   // Use the RAW body – parsing JSON first changes the bytes and breaks the signature.
   app.post('/webhooks/hensa', express.raw({ type: 'application/json' }), async (req, res) => {
     const raw = req.body.toString('utf8')
     if (!verifyHensaSignature(raw, req.get('Hensa-Signature'), process.env.HENSA_WEBHOOK_SECRET)) {
       return res.sendStatus(400)
     }
     const event = JSON.parse(raw)
   
     // Idempotent: the same event id can arrive more than once.
     if (await db.processedEvents.exists(event.id)) return res.sendStatus(200)
   
     if (event.type === 'payment_request.paid') {
       await orders.markPaid(event.data.externalOrderRef, event.data.id)
     }
     await db.processedEvents.insert(event.id)
     res.sendStatus(200) // answer within 10 s – do slow work in a queue
   })

   PHP

   webhooks/hensa.php

   <?php
   // webhooks/hensa.php – plain PHP (works in Laravel/WordPress too: read the raw body, not the parsed array)
   $payload = file_get_contents('php://input');
   $header  = $_SERVER['HTTP_HENSA_SIGNATURE'] ?? '';
   $secret  = getenv('HENSA_WEBHOOK_SECRET');
   
   $t = null; $signatures = [];
   foreach (explode(',', $header) as $part) {
       [$k, $v] = array_pad(explode('=', trim($part), 2), 2, null);
       if ($k === 't')  { $t = $v; }
       if ($k === 'v1') { $signatures[] = $v; }
   }
   if (!$t || abs(time() - (int) $t) > 300) { http_response_code(400); exit; }
   
   $expected = hash_hmac('sha256', $t . '.' . $payload, $secret);
   $valid = false;
   foreach ($signatures as $s) { if (hash_equals($expected, $s)) { $valid = true; break; } }
   if (!$valid) { http_response_code(400); exit; }
   
   $event = json_decode($payload, true);
   // Idempotent: skip if $event['id'] was already processed.
   if ($event['type'] === 'payment_request.paid') {
       mark_order_paid($event['data']['externalOrderRef'], $event['data']['id']);
   }
   http_response_code(200);

   Python

   app.py

   # Flask
   import hashlib, hmac, os, time
   from flask import Flask, request, abort
   
   app = Flask(__name__)
   SECRET = os.environ["HENSA_WEBHOOK_SECRET"].encode()
   
   def verify(raw: bytes, header: str, tolerance: int = 300) -> bool:
       items = [p.strip().split("=", 1) for p in (header or "").split(",") if "=" in p]
       t = next((v for k, v in items if k == "t"), None)
       signatures = [v for k, v in items if k == "v1"]
       if not t or abs(time.time() - int(t)) > tolerance:
           return False
       expected = hmac.new(SECRET, f"{t}.".encode() + raw, hashlib.sha256).hexdigest()
       return any(hmac.compare_digest(expected, s) for s in signatures)
   
   @app.post("/webhooks/hensa")
   def hensa_webhook():
       raw = request.get_data()  # raw bytes, before any JSON parsing
       if not verify(raw, request.headers.get("Hensa-Signature", "")):
           abort(400)
       event = request.get_json()
       # Idempotent: skip if event["id"] was already processed.
       if event["type"] == "payment_request.paid":
           mark_order_paid(event["data"]["externalOrderRef"], event["data"]["id"])
       return "", 200

   verifyHensaSignature is in Verify signatures.

6. Simulate the customer’s transfer

   In test mode you “transfer” with one command – put the reference code in the description so Hensa matches it:

   curl https://api.hensa.example/v1/test/bank_transfers \
     -H "Authorization: Bearer $HENSA_TEST_KEY" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{ "amount": 150000, "description": "LK7F3K9 thanh toan don hang", "counterpartyName": "NGUYEN VAN AN" }'

   Within seconds your server receives bank_transaction.created and then payment_request.paid. Order DH-1024 is now paid.

Going live

• Switch to an hk_live_… key (separate environment variable for production)
• Create a production webhook endpoint with your real URL and store the new secret
• Handle duplicates by event.id – see Webhooks
• Run periodic reconciliation as a safety net
• Handle payment_request.expired (release reserved stock)