POST - Tạo hóa đơn

Tạo một hóa đơn thanh toán crypto. Merchant gửi số tiền (USD), thông tin đơn hàng và callback URL; hệ thống trả về trans_id và url_payment để chuyển khách đến trang thanh toán.

Endpoint

POST https://api.payerscan.com/payment/crypto

Headers

Header	Bắt buộc	Mô tả
Content-Type	Có	application/json
x-api-key	Có	API Key của Store

Request Body (JSON)

Trường	Kiểu	Bắt buộc	Giới hạn	Mô tả
merchant_id	string	Có	Không rỗng	Mã merchant của Store (phải khớp với API Key).
amount	number | string	Có	> 0 và ≤ 1,000,000	Số tiền thanh toán (USD). Ví dụ: 100, "100".
callback_url	string	Khuyến nghị	Tối đa 500 ký tự, URL hợp lệ	URL nhận webhook khi trạng thái completed hoặc expired.
completed_url	string	Không	Tối đa 500 ký tự, URL hợp lệ	URL chuyển hướng sau khi khách thanh toán thành công.
expired_url	string	Không	Tối đa 500 ký tự, URL hợp lệ	URL chuyển hướng khi hóa đơn hết hạn.
name	string	Không	Tối đa 255 ký tự	Tên/title hóa đơn.
description	string	Không	Tối đa 1000 ký tự	Mô tả hóa đơn.
request_id	string	Không	Tối đa 255 ký tự	ID đơn hàng bên Merchant để đối chiếu (trả lại trong response và webhook). Cũng dùng cho idempotency — xem ghi chú bên dưới.

Ví dụ request

{
  "merchant_id": "MID-XXXXXXXXXX",
  "amount": 100,
  "name": "Top-up balance",
  "description": "Top-up the balance for username: [USERNAME]",
  "callback_url": "https://your-server.com/webhook/payment",
  "completed_url": "https://your-website.com/thank-you",
  "expired_url": "https://your-website.com/",
  "request_id": "ORDER_123456"
}

Response

Thành công (HTTP 200)

{
  "status": "success",
  "data": {
    "request_id": "ORDER_123456",
    "trans_id": "TID-ABC123DEF4567890",
    "status": "waiting",
    "amount": "100",
    "url_payment": "https://app.payerscan.com/bill/TID-ABC123DEF4567890",
    "expires_in_minutes": 15
  }
}

Trường	Mô tả
request_id	Giá trị bạn đã gửi trong request.
trans_id	Mã hóa đơn duy nhất, dùng để tra cứu và đối chiếu webhook.
status	Luôn là "waiting" khi mới tạo.
amount	Số tiền USD (string).
url_payment	URL trang thanh toán — redirect khách đến đây.
expires_in_minutes	Thời gian hết hạn hóa đơn (phút).

Lỗi (4xx / 5xx)

Tất cả lỗi có dạng:

{
  "status": "error",
  "message": "Mô tả lỗi",
  "error_code": "ERROR_CODE",
  "request_id": "ORDER_123456",
  "details": { }
}

HTTP	error_code	Mô tả
400	VALIDATION_ERROR	Body không hợp lệ (thiếu trường bắt buộc, sai kiểu, vượt giới hạn). details.errors có chi tiết.
400	INVALID_MERCHANT_ID	merchant_id không khớp với Store của API Key.
400	NO_PAYMENT_METHOD	Store chưa cấu hình phương thức thanh toán. Thêm ít nhất một ví hoặc cấu hình sàn giao dịch trước khi tạo hóa đơn.
401	MISSING_API_KEY	Không có header x-api-key.
401	INVALID_API_KEY	API key không hợp lệ hoặc không tồn tại.
403	ACCOUNT_INACTIVE	Tài khoản liên kết với API key này đã bị vô hiệu hóa.
403	STORE_INACTIVE	Store liên kết với API key này đã bị vô hiệu hóa.
402	INSUFFICIENT_BALANCE	Số dư Store không đủ trả phí. details có current_balance, required_fee, shortage, fee_rate_percent, discount_percent, invoice_amount.
429	RATE_LIMIT_EXCEEDED	Vượt giới hạn request (burst hoặc sustained). Có limit_type, retry_after_seconds.
500	INTERNAL_ERROR	Lỗi server.

Chi tiết mã lỗi: Mã lỗi API.

Rate Limit

• Burst: 5 request/giây (theo API Key hoặc IP).
• Sustained: 60 request/phút (theo API Key hoặc IP).

Vượt limit → HTTP 429, body có error_code: "RATE_LIMIT_EXCEEDED", retry_after_seconds.

Lưu ý

• Phương thức thanh toán: Store phải cấu hình ít nhất một địa chỉ ví hoặc sàn giao dịch (Binance Pay, OKX, Bybit, MEXC, Gate.io, Bitget, v.v.) trước khi tạo hóa đơn. Nếu chưa có, API sẽ trả lỗi NO_PAYMENT_METHOD.
• Idempotency: Nếu bạn gửi request_id đã tồn tại cho cùng store, API sẽ trả về hóa đơn cũ thay vì tạo mới. Response sẽ có idempotent: true để cho biết điều này. Điều này ngăn tạo hóa đơn trùng lặp khi retry.
• Phí: Phí được tính trên amount (USD) và trừ vào balance của Store. Cần đảm bảo balance đủ trước khi tạo hóa đơn. Trong thời gian dùng thử miễn phí, phí được miễn.
• Callback: Nên luôn gửi callback_url để nhận webhook completed/expired; nếu không có, bạn chỉ có thể tra cứu qua GET https://api.payerscan.com/invoice/:trans_id.
• request_id: Nên gửi để dễ ghép webhook với đơn hàng nội bộ và hỗ trợ idempotency.