# S Pay (S Payment) — hướng dẫn tích hợp cho lập trình viên / AI agent S Pay nhận tiền chuyển khoản ngân hàng (VietQR) vào tài khoản của chính cửa hàng và báo khi tiền về. Ứng dụng tạo "yêu cầu thanh toán" (QR có mã thanh toán), khách quét QR chuyển khoản, S Pay khớp giao dịch rồi gửi webhook. - API: https://spay.devbyspark.com/v2 (JSON, UTF-8). OpenAPI: https://spay.devbyspark.com/v2/openapi.json. Tài liệu: https://spay.devbyspark.com/docs - Số tiền: số nguyên VND (không có phần thập phân). Thời gian: ISO 8601 UTC. ## 1. Xác thực - Tạo khoá ở https://spay.devbyspark.com/developer (Ứng dụng & khoá API): được Access key (`sp_test_…` = sandbox, `sp_live_…` = tiền thật) + Secret (chỉ hiện một lần). - Mọi request: `Authorization: Bearer `. - Đặt trong biến môi trường `SPAY_ACCESS_KEY`, `SPAY_SECRET` (+ `SPAY_WEBHOOK_SECRET`, `SPAY_BASE_URL=https://spay.devbyspark.com`). Chỉ gọi từ máy chủ — KHÔNG đưa khoá vào mã chạy trên trình duyệt / app di động, không commit vào git. - Quyền theo dịch vụ bật cho khoá: `payment_requests:write` (QR thanh toán), `transactions:read`, `bank_accounts:read`, `webhooks:manage`, `usage:read`. Thiếu quyền → 403 `insufficient_scope`. ## 2. Tạo yêu cầu thanh toán `POST /v2/payment-requests` — header `Idempotency-Key: ` để gọi lại không tạo trùng. ```json {"amount": 150000, "orderRef": "DON-1001", "description": "Don hang 1001", "expiresIn": 900, "returnUrl": "https://shop.vn/cam-on", "cancelUrl": "https://shop.vn/gio-hang"} ``` - `amount` bắt buộc. `expiresIn` tính bằng giây (tối thiểu 60). `accountId` (tuỳ chọn): id tài khoản nhận lấy từ `GET /v2/bank-accounts`; bỏ trống = S Pay tự chọn tài khoản. - Trả về: `id`, `status`, `amount`, `amountReceived`, `paymentCode`, `qrPayload` (chuỗi VietQR), `qrImageUrl`, `paymentUrl` (trang thanh toán dựng sẵn), `bankAccount` {bin, bankName, accountNumber, accountName}, `expiresAt`, `confirmation` (`auto` = S Pay tự xác nhận khi tiền về; `manual` = cần người kiểm, ví dụ hết hạn mức gói). - Hiển thị cho khách: chuyển hướng tới `paymentUrl`, HOẶC vẽ QR từ `qrPayload` kèm số TK / số tiền / nội dung. Nội dung chuyển khoản phải chứa `paymentCode` (QR đã điền sẵn). - Xem: `GET /v2/payment-requests/{id}` · danh sách: `GET /v2/payment-requests?status=&from=&to=&page=` · huỷ: `POST /v2/payment-requests/{id}/cancel`. - Trạng thái: `pending` → `paid` | `partially_paid` (khách chuyển thiếu) | `expired` | `cancelled`. ## 3. Webhook (nên dùng thay vì hỏi liên tục) - Đăng ký ở https://spay.devbyspark.com/developer › Webhook hoặc `POST /v2/webhooks` {"url": "https://shop.vn/api/spay/webhook", "events": [...]} → nhận `secret` (`whsec_…`, chỉ trả một lần) để kiểm chữ ký. - Sự kiện: `payment_request.paid`, `payment_request.partially_paid`, `payment_request.expired`, `payment_request.cancelled`, `payment_request.reversed`, `transaction.created` (giao dịch ngân hàng mới), `grant.revoked`; `test.ping` khi bấm gửi thử. - Thân: `{"id": "evt_…", "object": "event", "type": "payment_request.paid", "livemode": true, "workspaceId": "…", "created": "…", "data": {"paymentRequest": {…như mục 2…} } }` (`transaction.created` → `data.transaction`). - Chữ ký: header `X-SPay-Signature: t=,v1=` với v1 = HMAC-SHA256(secret, t + "." + rawBody). Kiểm trên THÂN GỐC (chưa parse JSON), so sánh thời gian hằng, từ chối nếu lệch quá 300 giây. ```js const [t, v1] = sig.split(",").map(p => p.split("=")[1]) const expected = crypto.createHmac("sha256", process.env.SPAY_WEBHOOK_SECRET).update(`${t}.${rawBody}`).digest("hex") const ok = v1 && expected.length === v1.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1)) && Math.abs(Date.now() / 1000 - Number(t)) <= 300 ``` - Trả 2xx trong 10 giây; lỗi thì S Pay gửi lại (tối đa 10 lần) → xử lý trùng theo `id` sự kiện (idempotent). - Đánh dấu đơn đã trả khi nhận `payment_request.paid` đã kiểm chữ ký (hoặc `GET /v2/payment-requests/{id}` trả `paid`), đối chiếu `orderRef` và `amountReceived`. Không tin `returnUrl` — khách tự mở được. ## 4. Thử (sandbox) - Dùng khoá `sp_test_…`: dữ liệu tách khỏi tiền thật. - Giả lập khách trả: `POST /v2/sandbox/simulate` {"paymentRequestId": "", "amount": 150000} (bỏ `amount` = trả đủ) → webhook `payment_request.paid` gửi như thật. Xong thì đổi sang khoá `sp_live_…`. ## 5. Khác - Giao dịch: `GET /v2/transactions?from=&to=&page=` (`transactions:read`). Tài khoản nhận: `GET /v2/bank-accounts`. Hạn mức gói: `GET /v2/usage`. Thông tin khoá: `GET /v2/me`. - Lỗi dạng problem+json `{"title": "…", "code": "…"}`: 400 dữ liệu sai, 401 khoá sai, 403 thiếu quyền, 404, 409, 429 quá nhanh (chờ theo header Retry-After). - Ứng dụng đối tác cần khách tự cấp quyền: OAuth "Kết nối S Payment" — https://spay.devbyspark.com/.well-known/oauth-authorization-server. ## Việc cần làm khi tích hợp (checklist cho agent) 1. Thêm biến môi trường như mục 1 + file mẫu `.env.example` (không chứa giá trị thật). 2. Hàm phía máy chủ tạo yêu cầu thanh toán cho một đơn, lưu `id` ↔ mã đơn; trang thanh toán hiện QR / chuyển tới `paymentUrl`. 3. Endpoint webhook kiểm chữ ký, xử lý trùng, cập nhật trạng thái đơn theo mục 3. 4. Test bằng khoá `sp_test_` + `/v2/sandbox/simulate`; ghi lại cách đổi sang `sp_live_`.