POST/api/generate-ideal
Tạo Link thanh toán iDEAL
Gửi mã CDK và danh sách Access Token của tài khoản để khởi tạo tác vụ. Kết quả sẽ được lấy thông qua API kiểm tra tiến độ. Số lượng CDK tương ứng sẽ được hoàn trả nếu tạo lỗi.
Tham số yêu cầu
cdkstring, bắt buộc, mã thẻ CDK kích hoạt
session_jsonstring, bắt buộc, một hoặc nhiều token tài khoản
client_request_idstring, tùy chọn, khóa chống trùng lắp (idempotency key)
providerstring, tùy chọn, mặc định là local
Định dạng gửi đơn tài khoản
{
"cdk": "MÃ_CDK_CỦA_BẠN",
"session_json": "eyJhbGciOi...",
"provider": "local",
"client_request_id": "order-20260710-001"
}
Định dạng gửi nhiều tài khoản (Bulk)
{
"cdk": "MÃ_CDK_CỦA_BẠN",
"session_json": "accessToken=eyJ...\n{\"accessToken\":\"eyJ...\"}\nBearer eyJ...",
"provider": "local"
}
Phản hồi tạo mới (HTTP 202)
{
"ok": true,
"created": true,
"task_id": "ideal_xxx",
"task_token": "ideal_xxx.chu-ky",
"task": {"state": "queued", "total": 1}
}
POST/api/check-cdk
Tra cứu số dư của thẻ CDK
Khuyến nghị kiểm tra số dư CDK trước khi gửi các yêu cầu tạo link thanh toán.
{
"cdk": "MÃ_CDK_CỦA_BẠN"
}
Phản hồi
{
"ok": true,
"code": "cdk_xxx",
"quota": 100,
"used": 1,
"remaining": 99,
"status": "active"
}
POST/api/account-info
Nhận diện email tài khoản
Dùng để lấy nhanh địa chỉ email từ Access Token tài khoản gửi lên.
{
"accessToken": "eyJhbGciOi..."
}
Phản hồi
{
"ok": true,
"token_count": 1,
"account": {
"email": "user@domain.com",
"account_label": "user@domain.com"
}
}
GET/api/tasks/{task_id}
Kiểm tra tiến độ tác vụ
Yêu cầu lặp lại (polling) mỗi 1-2 giây để nhận trạng thái mới nhất. Cần gửi kèm Header X-Task-Token.
GET /api/tasks/ideal_xxx
X-Task-Token: ideal_xxx.chu-ky
Phản hồi
{
"ok": true,
"task": {"state": "running", "total": 3, "success_count": 1},
"events": [{"id": 12, "phase": "item_success", "message": "Tài khoản thứ 1 đã tạo link iDEAL thành công"}],
"cursor": 12
}
POST/api/qrcode-token
Tạo mã QR thanh toán
Chuyển đổi URL thanh toán thành mã QR để người dùng có thể quét trực tiếp.
{
"data": "https://pay.ideal.nl/transactions/..."
}
Phản hồi
{"ok": true, "token": "abc123"}
Đường dẫn ảnh QR: /api/qrcode/abc123
Đường dẫn tải ảnh QR: /api/qrcode/abc123?download=1
ERRORLỗi thường gặp
Bảng lỗi chi tiết & Hướng khắc phục
non_zero_trialTài khoản không đủ điều kiện dùng thử 0đ.
payment_method_types_mismatchStripe chỉ hỗ trợ thẻ/link mà không mở thanh toán iDEAL cho tài khoản này.
openai_blockOpenAI chặn thanh toán/xác nhận do phát hiện hoạt động đáng ngờ. Hệ thống sẽ tự đổi IP và thử lại.
checkout_invoice_mismatchCheckout session đã lỗi thời hoặc trạng thái hóa đơn thay đổi. Hãy xuất lại AT.
stripe_submission_failedLỗi khi Stripe xử lý yêu cầu, liên quan đến thông tin tài khoản hoặc khu vực địa lý.
proxy_errorMạng kết nối bị gián đoạn. Thử chạy lại sau vài giây.
token_invalidToken bị sai định dạng, hết hạn hoặc bị thu hồi. Vui lòng lấy lại Token mới.
cdkThẻ CDK không tồn tại, hết lượt sử dụng hoặc bị khóa.