Tài liệu nhà phát triển

Chào mừng bạn đến với cổng thông tin dành cho lập trình viên tích hợp vào DIP Payment Gateway. Tài liệu này cung cấp các thông số kỹ thuật, hướng dẫn cấu hình và mẫu mã nguồn để bạn có thể tích hợp tính năng thanh toán QR tự động vào hệ thống ERP, Web hoặc App của mình.

Luồng hoạt động hệ thống

Quy trình 7 bước tích hợp

Để hệ thống của bạn (App/Web/ERP) có thể thực hiện thanh toán và gạch nợ tự động, vui lòng thực hiện đúng theo các bước sau:

1. Xác thực API (Authentication)

DIP Gateway sử dụng hai cơ chế xác thực riêng biệt tùy theo mục đích sử dụng của bạn:

{
  "Email": "admin@your-company.com",
  "Password": "••••••••"
}

2. Thiết lập Merchant & Ngân hàng

Trước khi tạo thanh toán, bạn cần cấu hình điểm bán (Merchant) và liên kết tài khoản ngân hàng thực tế để nhận tiền.

3. Đăng ký Merchant tự động (Cho Đối tác phần mềm)

Cơ chế này sử dụng X-Platform-Auth (Header) và TenantKey (JSON Body) để xác thực 2 lớp, đảm bảo an toàn tuyệt đối ngay cả khi lộ mã công ty.

{
  "Name": "Cửa hàng Chi nhánh Quận 1",
  "TenantKey": "EXT_A1B2C3D4",
  "NotifyUrl": "https://api.your-app.com/webhook"
}

{
  "success": true,
  "data": {
    "ApiKey": "GA_XYZ789...",
    "SecretKey": "ecc012...",
    "HostedLinkUrl": "https://bankhub.dip.vn/link/...",
    "PrivateKey": "..."
  }
}

4. Khởi tạo thanh toán (Tạo QR Code)

Đây là API quan trọng nhất để ứng dụng của bạn yêu cầu DIP Gateway sinh mã QR thanh toán động cho khách hàng.

{
  "PaymentCode": "PMT1715077421234",
  "OrderCode": "INV-1002",
  "Amount": 500000.0,
  "QrContent": "00020101021238580010A000000727...",
  "QrLink": "https://img.vietqr.io/image/ICB-123456...png?addInfo=PMT1715",
  "Deeplink": "https://bankhub.dip.vn/pay/PMT1715077421234"
}

5. Kiểm tra trạng thái giao dịch

Dùng để truy vấn trạng thái thanh toán của một hóa đơn thủ công (Polling) nếu cần thiết.

{
  "Status": "COMPLETED"
}

6. Webhook thông báo kết quả (Gạch nợ tự động)

{
  "merchant_id": 105,
  "order_code": "INV-2024-001",
  "payment_code": "PMT1715077421",
  "amount": 1500000.0,
  "status": "PAID",
  "transaction_id": "FT24042399182"
}

7. Cơ chế bảo mật & Chữ ký số

Để đảm bảo an toàn, các API của DIP Payment Gateway yêu cầu ký gói tin hoặc xác thực mã băm.

Hướng dẫn Ký số RSA (X-Signature)

Chuỗi cần ký được tạo bằng cách nối Body và Timestamp bằng dấu gạch đứng: {body_content}|{timestamp}.

Hướng dẫn Xác thực Webhook (X-Signature)

Mọi Webhook từ DIP Gateway đều gửi kèm Header X-Signature chứa mã băm HMAC-SHA256 của gói tin JSON. Bạn nên kiểm tra mã này bằng công thức:

Dùng SecretKey làm khóa băm và RawBody làm dữ liệu đầu vào.

using (var hmac = new HMACSHA256(keyBytes)) {
    var hash = hmac.ComputeHash(bodyBytes);
    return BitConverter.ToString(hash).Replace("-", "").ToLower();
}

8. Nạp tiền & Quản lý ký quỹ (SaaS Billing)

Nhằm đảm bảo dịch vụ thông báo (SMS/Webhook) hoạt động ổn định, mỗi Merchant cần duy trì một số dư ký quỹ nhất định. Hệ thống sử dụng mô hình Ký quỹ trước. Bạn cần nạp tiền vào ví của Merchant để hệ thống có thể khấu trừ phí giao dịch tự động.

9. Bảng mã lỗi (Error Codes)

Danh sách các mã phản hồi từ hệ thống để bạn xử lý logic phía ứng dụng.