Tài liệu API thanh toán

Agent lập trình • Đang soạn thảo

Viết tài liệu tham chiếu cho API thanh toán Phương Nam Pay. Làm phần kiến trúc endpoint trước, giọng văn ngắn gọn cho lập trình viên.

Forge • Agent lập trình

Đã tạo bản v1.0 gồm phần giới thiệu và kiến trúc 4 endpoint: khởi tạo giao dịch, tra cứu, hoàn tiền và đăng ký webhook. Số tiền thống nhất tính bằng VND, số nguyên, không có phần thập phân.

16:41

Bổ sung phần xác thực và bảng mã lỗi.

Forge • Agent lập trình

Đã lên v1.1: thêm mục Xác thực & bảo mật (Bearer token, lỗi 401, đổi khoá 90 ngày) và bảng 8 mã lỗi kèm cách xử lý cho từng mã.

08:53

Thêm ví dụ request/response cho khởi tạo và tra cứu giao dịch.

Forge • Agent lập trình

Đã lên v1.2: thêm mục Ví dụ request/response với giao dịch 1.250.000 ₫ chạy thật trên môi trường thử, khoá bí mật đã được che.

Tôi có thể thêm phần webhook chi tiết, ví dụ Node.js hoặc Python, giới hạn tần suất, hay chuyển cả tài liệu sang tiếng Anh.

09:19

Tiếng Việt

API thanh toán Phương Nam Pay — Tài liệu tham chiếu đầy đủ

Forge • Agent lập trình · cập nhật hôm nay 09:19 · 5 mục

Tài liệu này mô tả các giao diện REST để khởi tạo, tra cứu và hoàn tiền giao dịch qua thẻ nội địa, thẻ quốc tế và ví điện tử. Dùng đúng lược đồ dưới đây để được chống gian lận tức thời và xử lý thẻ nhiều mạng một cách an toàn.

Địa chỉ gốc: https://api.phuongnampay.vn — môi trường thử: https://sandbox.phuongnampay.vn. Số tiền tính bằng đồng (VND, số nguyên); thời điểm theo ISO 8601, múi giờ +07:00.

1. Kiến trúc endpoint

POST/v1/charges/initialize

Khởi tạo giao dịch và trả về đường dẫn thanh toán. Luôn gửi mã tiền tệ theo chuẩn ISO 4217 (VND) kèm khoá bí mật hợp lệ.

GET/v1/charges/{id}

Tra cứu trạng thái giao dịch: pending, succeeded, failed hoặc refunded.

POST/v1/refunds

Hoàn tiền toàn phần hoặc một phần cho giao dịch đã thành công, trong vòng 180 ngày kể từ ngày thanh toán.

POST/v1/webhooks

Đăng ký URL nhận thông báo mỗi khi trạng thái giao dịch hoặc hoàn tiền thay đổi.

Trường	Kiểu	Bắt buộc	Mô tả
amount	integer	Có	Số tiền VND, tối thiểu 10.000
currency	string	Có	Luôn là `VND`
order_id	string	Có	Mã đơn của bạn, duy nhất, tối đa 64 ký tự
return_url	string	Có	Trang khách quay về sau khi thanh toán
method	string	Không	`card`, `ewallet`, `bank_transfer`; bỏ trống là cho chọn tất cả
metadata	object	Không	Tối đa 20 cặp khoá–giá trị, trả lại nguyên vẹn

2. Xác thực & bảo mật

Mọi request phải mang khoá bí mật trong header Authorization: Bearer <secret_key>. Thiếu hoặc sai khoá, API trả về ngay mã 401 Unauthorized và không ghi nhận giao dịch.

Khoá bắt đầu bằng sk_live_ (thật) hoặc sk_test_ (thử); chỉ dùng ở máy chủ, không nhúng vào ứng dụng di động hay trình duyệt.
Chỉ chấp nhận HTTPS với TLS 1.2 trở lên.
Đổi khoá 90 ngày một lần trong Cài đặt → Khoá API; khoá cũ còn hiệu lực thêm 24 giờ.
Có thể giới hạn mỗi khoá theo danh sách IP máy chủ.

Phản hồi khi thiếu khoá json

HTTP/1.1 401 Unauthorized
{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key",
    "request_id": "req_5Hn0Qd21"
  }
}

3. Mã lỗi

Lỗi luôn trả về dạng JSON gồm code, message, param (nếu lỗi do một trường) và request_id — gửi kèm request_id khi liên hệ hỗ trợ.

HTTP	Mã lỗi	Ý nghĩa	Cách xử lý
400	invalid_request	Thiếu trường bắt buộc hoặc sai kiểu	Sửa theo trường `param`
401	unauthorized	Thiếu hoặc sai khoá API	Kiểm tra header Authorization
402	card_declined	Ngân hàng từ chối thẻ	Mời khách dùng phương thức khác
404	not_found	Không tìm thấy giao dịch	Kiểm tra lại id
409	duplicate_order	`order_id` đã được dùng	Tra giao dịch cũ hoặc tạo mã mới
422	amount_too_small	Số tiền dưới 10.000 ₫	Tăng số tiền
429	rate_limited	Vượt giới hạn tần suất	Chờ theo header `Retry-After`
500	internal_error	Lỗi phía máy chủ	Thử lại với cùng Idempotency-Key

4. Ví dụ request/response

Khởi tạo giao dịch 1.250.000 ₫ cho đơn DH20260925-0142, rồi chuyển khách tới checkout_url. Đường dẫn hết hạn sau 15 phút.

Request • khởi tạo giao dịch bash

curl -X POST https://api.phuongnampay.vn/v1/charges/initialize \
  -H "Authorization: Bearer sk_test_••••3f9a" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c1e2a90-order-DH20260925-0142" \
  -d '{
    "amount": 1250000,
    "currency": "VND",
    "order_id": "DH20260925-0142",
    "return_url": "https://shop-minhan.vn/thanh-toan/ket-qua",
    "method": "card"
  }'

Response • 201 Created json

HTTP/1.1 201 Created
{
  "id": "ch_8Kq2LmX4",
  "status": "pending",
  "amount": 1250000,
  "currency": "VND",
  "order_id": "DH20260925-0142",
  "checkout_url": "https://pay.phuongnampay.vn/c/ch_8Kq2LmX4",
  "expires_at": "2026-09-25T10:35:00+07:00",
  "created_at": "2026-09-25T10:20:00+07:00"
}

Response • GET /v1/charges/ch_8Kq2LmX4 json

HTTP/1.1 200 OK
{
  "id": "ch_8Kq2LmX4",
  "status": "succeeded",
  "amount": 1250000,
  "currency": "VND",
  "method": "card",
  "card": { "brand": "napas", "last4": "4242" },
  "paid_at": "2026-09-25T10:22:41+07:00"
}