PayGate API Reference

Cổng thanh toán (mock) cho English app — thu tiền gói Premium (1 lần hoặc thuê bao định kỳ). Trình bày kiểu Stripe để IT-BA/QC đọc hiểu & test.

Base URL: http://localhost:4242 · Đặc tả máy đọc: openapi.yaml

Server giả phục vụ đào tạo. Dữ liệu lưu trong RAM, mất khi restart. Không dùng cho thật.

Giới thiệu

REST API trả JSON. Tài nguyên: customers, payment_methods, charges, refunds, subscriptions, events. Mọi request /v1/* cần khóa Bearer.

Xác thực

Gửi khóa bí mật trong header Authorization (Bearer). Khóa test bắt đầu bằng sk_test_.

Khóa là bí mật — không để lộ trong tài liệu, ảnh chụp, mã client hay commit git.
Header
Authorization: Bearer sk_test_demo_4242

Lỗi

Body lỗi: { "error": { "code", "message" } }.

HTTPcodeÝ nghĩa nghiệp vụ
400missing_field / invalid_json / invalid_planDữ liệu gửi lên thiếu/sai
401unauthorizedThiếu/sai khóa
402card_declined, insufficient_funds, expired_card, incorrect_cvcThẻ lỗi (mỗi loại 1 thông báo cho user)
404resource_missingKhông tìm thấy tài nguyên
429rate_limitedGọi quá nhiều
500processing_errorLỗi tạm phía cổng, nên retry

Token thẻ thử (field source)

tok_chargeabletok_declinedtok_insufficienttok_expiredtok_cvc_failtok_error

Rate limit

Mặc định 30 request / 10 giây / mỗi IP. Vượt ngưỡng trả 429. App nên retry/backoff.

Phân trang

Các endpoint GET danh sách trả { object:"list", has_more, data:[...] }. Tham số ?limit= và ?starting_after=<id> (cursor).

POST/v1/customers

Tạo khách hàng (gắn email). Khách dùng để lưu thẻ + đăng ký gói.

Tham sốMô tả
email bắt buộcEmail khách
nameTên (tùy chọn)
Request
curl -s $BASE/v1/customers \
  -H "Authorization: Bearer sk_test_demo_4242" \
  -d '{"email":"hv@example.com","name":"Nguyen A"}'
Response 201
{ "id":"cus_...", "object":"customer", "email":"hv@example.com" }

POST/v1/payment_methods

Lưu thẻ cho khách để thanh toán lần sau (không nhập lại thẻ).

Tham sốMô tả
customer bắt buộcid khách
card bắt buộc{ number, brand, exp }
Response 201
{ "id":"pm_...", "brand":"visa", "last4":"4242" }

POST/v1/charges

Tạo thanh toán 1 lần. Dùng source (token thử) hoặc payment_method (thẻ đã lưu). Header tùy chọn Idempotency-Key chống thu trùng.

Tham sốMô tả
amount bắt buộcSố tiền (đồng VND)
currency bắt buộcvnd
source / payment_methodToken thẻ hoặc thẻ đã lưu
Request
curl -s $BASE/v1/charges \
  -H "Authorization: Bearer sk_test_demo_4242" \
  -d '{"amount":99000,"currency":"vnd","source":"tok_chargeable"}'
Response 201
{ "id":"ch_...", "status":"succeeded", "amount":99000 }
Response 402 (vd insufficient_funds)
{ "error":{ "code":"insufficient_funds" } }

GET/v1/charges/{id}

Tra trạng thái 1 thanh toán. Trạng thái: pendingsucceededfailedrefunded

curl -s $BASE/v1/charges/ch_abc \
  -H "Authorization: Bearer sk_test_demo_4242"

GET/v1/charges

Liệt kê thanh toán có phân trang (cho màn hình Lịch sử giao dịch).

curl -s $BASE/v1/charges?limit=5 \
  -H "Authorization: Bearer sk_test_demo_4242"

POST/v1/refunds

Hoàn tiền 1 charge đã succeeded. Sau hoàn, charge chuyển refunded.

Tham sốMô tả
charge bắt buộcid charge cần hoàn
amountMặc định hoàn toàn bộ
curl -s $BASE/v1/refunds \
  -H "Authorization: Bearer sk_test_demo_4242" \
  -d '{"charge":"ch_abc"}'

POST/v1/subscriptions

Đăng ký gói Premium định kỳ. Plan: premium_monthly (99.000đ/tháng) · premium_yearly (990.000đ/năm).

Tham sốMô tả
customer bắt buộcid khách
plan bắt buộcpremium_monthly | premium_yearly
Response 201
{ "id":"sub_...", "status":"active",
  "plan":"premium_monthly", "current_period_end":... }

POST/v1/subscriptions/{id}/cancel

Hủy gói. Trạng thái chuyển canceled. Sinh event subscription.canceled.

curl -s -X POST $BASE/v1/subscriptions/sub_abc/cancel \
  -H "Authorization: Bearer sk_test_demo_4242"

GET/v1/events · POST/v1/events/simulate

Hệ thống sinh sự kiện cho mỗi hành động (charge.succeeded, charge.failed, charge.refunded, subscription.created, subscription.canceled). App polling endpoint này thay cho nhận webhook callback. Dùng ?type= để lọc. simulate để tự tạo event test (vd subscription.renewed).

Poll feed
curl -s $BASE/v1/events?type=charge.failed \
  -H "Authorization: Bearer sk_test_demo_4242"
Simulate
curl -s $BASE/v1/events/simulate \
  -H "Authorization: Bearer sk_test_demo_4242" \
  -d '{"type":"subscription.renewed"}'

PayGate mock · tài liệu phục vụ Buổi 6 — Integrate.