Tài liệu tích hợp

Xác thực API

Mỗi request cần hai header. API Key chỉ hiển thị một lần khi tạo hoặc làm mới khóa.

X-Merchant-Id: MER_XXXXXXXXXXXX
X-API-Key: your_api_key
Content-Type: application/json

Tạo hóa đơn

POST /api/AddInvoice. Trường request_id là khóa idempotency: gửi lại cùng mã sẽ nhận đúng hóa đơn cũ.

{
  "request_id": "ORDER-10001",
  "name": "Thanh toán đơn hàng #10001",
  "description": "Gói dịch vụ 1 tháng",
  "amount": 11,
  "callback_url": "https://merchant.example.com/webhook",
  "success_url": "https://merchant.example.com/success",
  "cancel_url": "https://merchant.example.com/cancel"
}

{
  "status": "success",
  "data": {
    "trans_id": "INV_...",
    "amount": 11,
    "pay_amount": 11.237,
    "invoice_status": "waiting",
    "payment_url": "https://pay.example.com/payment/INV_...",
    "expires_at": "2026-07-27 21:30:00"
  }
}

Kiểm tra trạng thái

POST /api/GetInvoiceStatus với trans_id hoặc request_id.

{
  "trans_id": "INV_..."
}

Xác minh callback HMAC

Callback không truyền API Key. Hãy lấy timestamp và chữ ký từ header, sau đó tính HMAC-SHA256 trên chuỗi timestamp.raw_body.

$raw = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_NEXORA_TIMESTAMP'];
$received = str_replace('sha256=', '', $_SERVER['HTTP_X_NEXORA_SIGNATURE']);
$expected = hash_hmac('sha256', $timestamp.'.'.$raw, $webhookSecret);

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}
http_response_code(200);

Hệ thống gửi kèm Idempotency-Key. Merchant nên lưu khóa này để tránh xử lý callback trùng.

Trạng thái hóa đơn

waiting: đang chờ · completed: đã nhận đủ · expired: hết thời gian · cancelled: đã hủy.