API Reference

Pay27 REST API

Tài liệu tham khảo đầy đủ cho Pay27 API. Tất cả endpoint đều trả về JSON và sử dụng authentication qua Bearer token hoặc API Key.

Base URL: https://api.pay27.vn

API Version: v1

Tổng quan

Pay27 API là REST API cho phép bạn tích hợp thanh toán từ 27+ cổng toàn cầu vào ứng dụng của mình. API sử dụng JSON cho request/response, xác thực qua Bearer token hoặc API Key, và tuân thủ các chuẩn HTTP convention.

Với Pay27 API, bạn có thể:

Tạo payout — Gửi tiền qua 27+ cổng thanh toán chỉ với một API call
Quản lý kết nối — Kết nối tài khoản PayPal, Stripe, Payoneer và nhiều cổng khác
Tra cứu giao dịch — Lấy danh sách và chi tiết payout theo thời gian thực
Quy đổi tiền tệ — Tỉ giá real-time cho 30+ loại tiền tệ
Webhook real-time — Nhận thông báo ngay khi giao dịch thay đổi trạng thái

Authentication

Pay27 hỗ trợ 2 phương thức xác thực. Bạn có thể chọn phương thức phù hợp với use case của mình.

1. Bearer Token (Khuyến nghị cho Dashboard & Server-to-Server)

Sử dụng Bearer token trong header Authorization. Token được tạo từ Dashboard Pay27, phù hợp cho các ứng dụng server-side. Token có dạng pb_live_xxx cho production và pb_test_xxx cho sandbox.

shell

# Bearer Token — Gửi trong header Authorization
curl -H "Authorization: Bearer pb_live_x1y2z3a4b5c6d7e8f9" \
     https://api.pay27.vn/v1/payouts

2. X-API-Key (Cho third-party integrations & Webhooks)

Đối với tích hợp bên thứ ba hoặc các ứng dụng client-side (sau proxy của bạn), bạn có thể sử dụng API Key trong header X-API-Key. API Key có thể được tạo và quản lý tại Dashboard Pay27.

shell

# X-API-Key — Gửi trong custom header
curl -H "X-API-Key: pk_live_a1b2c3d4e5f6g7h8" \
     https://api.pay27.vn/v1/payouts

Lưu ý bảo mật

Không bao giờ hardcode API Key hoặc Bearer token trực tiếp trong code frontend. Luôn lưu trong biến môi trường (server-side) hoặc sử dụng proxy API của bạn để tránh lộ key ra client.

Payouts API

Quản lý giao dịch thanh toán — tạo, tra cứu danh sách và chi tiết payout.

POST/v1/payouts

Tạo một payout mới. Pay27 sẽ xử lý giao dịch qua cổng thanh toán được chỉ định và trả về trạng thái giao dịch.

Request Body

Tên	Kiểu	Bắt buộc	Mô tả
`gateway`	string	Có	Mã cổng thanh toán. VD: paypal, stripe, payoneer
`amount`	number	Có	Số tiền cần chuyển (sử dụng dấu chấm cho số thập phân)
`currency`	string	Có	Mã tiền tệ theo ISO 4217. VD: USD, VND, EUR
`recipient`	string	Có	Email hoặc ID người nhận trên cổng đích
`note`	string	Không	Ghi chú cho giao dịch (tối đa 255 ký tự)
`metadata`	object	Không	Dữ liệu tùy chỉnh dạng key-value. Hữu ích để lưu order_id, invoice_number...
`idempotency_key`	string	Không	Khóa chống trùng lặp. Nếu gửi lại request với cùng key, API trả về kết quả cũ.

Example Request

shell

curl -X POST https://api.pay27.vn/v1/payouts \
  -H "Authorization: Bearer pb_live_x1y2z3a4b5c6d7e8f9" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ik_abc123def456" \
  -d '{
    "gateway": "paypal",
    "amount": 150.00,
    "currency": "USD",
    "recipient": "freelancer@example.com",
    "note": "Thanh toán dự án tháng 6/2026",
    "metadata": {
      "order_id": "ORD-2026-00142",
      "invoice_number": "INV-8842"
    }
  }'

# 201 Created
{
  "id": "txn_9k8j7h6g5f4e3d2c1b0",
  "object": "payout",
  "status": "pending",
  "gateway": "paypal",
  "amount": 150.00,
  "currency": "USD",
  "recipient": "freelancer@example.com",
  "note": "Thanh toán dự án tháng 6/2026",
  "fee": 4.50,
  "net_amount": 145.50,
  "metadata": {
    "order_id": "ORD-2026-00142",
    "invoice_number": "INV-8842"
  },
  "created_at": "2026-06-02T07:30:00Z",
  "updated_at": "2026-06-02T07:30:00Z"
}

Example Response

json

{
  "id": "txn_9k8j7h6g5f4e3d2c1b0",
  "object": "payout",
  "status": "pending",
  "gateway": "paypal",
  "amount": 150.00,
  "currency": "USD",
  "recipient": "freelancer@example.com",
  "note": "Thanh toán dự án tháng 6/2026",
  "fee": 4.50,
  "net_amount": 145.50,
  "metadata": {
    "order_id": "ORD-2026-00142",
    "invoice_number": "INV-8842"
  },
  "status_history": [
    {
      "status": "pending",
      "timestamp": "2026-06-02T07:30:00Z",
      "message": "Payout created, waiting for processing"
    }
  ],
  "created_at": "2026-06-02T07:30:00Z",
  "updated_at": "2026-06-02T07:30:00Z"
}

GET/v1/payouts

Lấy danh sách payout với hỗ trợ phân trang và bộ lọc theo trạng thái, cổng thanh toán, khoảng thời gian.

Query Parameters

Tên	Kiểu	Bắt buộc	Mô tả
`page`	integer	Không	Số trang. Mặc định: 1
`limit`	integer	Không	Số lượng kết quả mỗi trang. Mặc định: 20, tối đa: 100
`status`	string	Không	Lọc theo trạng thái: pending, processing, completed, failed, cancelled
`gateway`	string	Không	Lọc theo mã cổng thanh toán
`from_date`	string	Không	Lọc từ ngày (ISO 8601). VD: 2026-05-01T00:00:00Z
`to_date`	string	Không	Lọc đến ngày (ISO 8601). VD: 2026-06-01T23:59:59Z
`sort`	string	Không	Sắp xếp: created_at.desc (mặc định), created_at.asc, amount.desc

Example Request

shell

curl -X GET "https://api.pay27.vn/v1/payouts?page=1&limit=20&status=completed&gateway=paypal" \
  -H "Authorization: Bearer pb_live_x1y2z3a4b5c6d7e8f9"

# 200 OK
{
  "object": "list",
  "data": [
    {
      "id": "txn_9k8j7h6g5f4e3d2c1b0",
      "object": "payout",
      "status": "completed",
      "gateway": "paypal",
      "amount": 150.00,
      "currency": "USD",
      "recipient": "freelancer@example.com",
      "fee": 4.50,
      "net_amount": 145.50,
      "created_at": "2026-06-02T07:30:00Z"
    }
  ],
  "pagination": {
    "total": 142,
    "page": 1,
    "limit": 20,
    "total_pages": 8
  }
}

Example Response

json

{
  "object": "list",
  "data": [
    {
      "id": "txn_9k8j7h6g5f4e3d2c1b0",
      "object": "payout",
      "status": "completed",
      "gateway": "paypal",
      "amount": 150.00,
      "currency": "USD",
      "recipient": "freelancer@example.com",
      "fee": 4.50,
      "net_amount": 145.50,
      "created_at": "2026-06-02T07:30:00Z",
      "updated_at": "2026-06-02T07:31:45Z"
    }
  ],
  "pagination": {
    "total": 142,
    "page": 1,
    "limit": 20,
    "total_pages": 8
  }
}

GET/v1/payouts/:id

Lấy thông tin chi tiết của một payout cụ thể, bao gồm toàn bộ lịch sử trạng thái và metadata.

Query Parameters

Tên	Kiểu	Bắt buộc	Mô tả
`id`	string	Có	ID của payout (path parameter). VD: txn_9k8j7h6g5f4e3d2c1b0

Example Request

shell

curl -X GET https://api.pay27.vn/v1/payouts/txn_9k8j7h6g5f4e3d2c1b0 \
  -H "Authorization: Bearer pb_live_x1y2z3a4b5c6d7e8f9"

# 200 OK
{
  "id": "txn_9k8j7h6g5f4e3d2c1b0",
  "object": "payout",
  "status": "completed",
  "gateway": "paypal",
  "amount": 150.00,
  "currency": "USD",
  "recipient": "freelancer@example.com",
  "note": "Thanh toán dự án tháng 6/2026",
  "fee": 4.50,
  "net_amount": 145.50,
  "metadata": {
    "order_id": "ORD-2026-00142",
    "invoice_number": "INV-8842"
  },
  "gateway_reference": "PP-TXN-8H7G6F5E4D",
  "status_history": [
    { "status": "pending", "timestamp": "2026-06-02T07:30:00Z" },
    { "status": "processing", "timestamp": "2026-06-02T07:30:05Z" },
    { "status": "completed", "timestamp": "2026-06-02T07:31:45Z" }
  ],
  "created_at": "2026-06-02T07:30:00Z",
  "updated_at": "2026-06-02T07:31:45Z"
}

Example Response

json

{
  "id": "txn_9k8j7h6g5f4e3d2c1b0",
  "object": "payout",
  "status": "completed",
  "gateway": "paypal",
  "amount": 150.00,
  "currency": "USD",
  "recipient": "freelancer@example.com",
  "note": "Thanh toán dự án tháng 6/2026",
  "fee": 4.50,
  "net_amount": 145.50,
  "metadata": {
    "order_id": "ORD-2026-00142",
    "invoice_number": "INV-8842"
  },
  "gateway_reference": "PP-TXN-8H7G6F5E4D",
  "status_history": [
    { "status": "pending", "timestamp": "2026-06-02T07:30:00Z" },
    { "status": "processing", "timestamp": "2026-06-02T07:30:05Z" },
    { "status": "completed", "timestamp": "2026-06-02T07:31:45Z" }
  ],
  "created_at": "2026-06-02T07:30:00Z",
  "updated_at": "2026-06-02T07:31:45Z"
}

Connections API

Quản lý kết nối đến các cổng thanh toán — xem danh sách cổng hỗ trợ, tạo và quản lý kết nối.

GET/v1/connections/gateways

Lấy danh sách tất cả các cổng thanh toán được Pay27 hỗ trợ, bao gồm thông tin phí, tiền tệ hỗ trợ và trạng thái.

Query Parameters

Tên	Kiểu	Bắt buộc	Mô tả
`country`	string	Không	Lọc cổng khả dụng theo quốc gia (ISO 3166-1 alpha-2). VD: VN
`currency`	string	Không	Lọc cổng hỗ trợ loại tiền tệ. VD: USD

Example Request

shell

curl -X GET "https://api.pay27.vn/v1/connections/gateways?country=VN&currency=USD" \
  -H "Authorization: Bearer pb_live_x1y2z3a4b5c6d7e8f9"

# 200 OK
{
  "object": "list",
  "data": [
    {
      "code": "paypal",
      "name": "PayPal",
      "type": "ewallet",
      "status": "active",
      "supported_currencies": ["USD", "EUR", "GBP", "AUD"],
      "fee_percentage": 2.9,
      "fee_fixed": 0.30,
      "min_amount": 1.00,
      "max_amount": 10000.00,
      "estimated_time": "1-2 giờ",
      "logo_url": "https://cdn.pay27.vn/gateways/paypal.svg"
    },
    {
      "code": "stripe",
      "name": "Stripe",
      "type": "payment_processor",
      "status": "active",
      "supported_currencies": ["USD", "EUR", "GBP", "CAD"],
      "fee_percentage": 2.9,
      "fee_fixed": 0.30,
      "min_amount": 1.00,
      "max_amount": 50000.00,
      "estimated_time": "2-3 ngay",
      "logo_url": "https://cdn.pay27.vn/gateways/stripe.svg"
    }
  ]
}

Example Response

json

{
  "object": "list",
  "data": [
    {
      "code": "paypal",
      "name": "PayPal",
      "type": "ewallet",
      "status": "active",
      "supported_currencies": ["USD", "EUR", "GBP", "AUD"],
      "fee_percentage": 2.9,
      "fee_fixed": 0.30,
      "min_amount": 1.00,
      "max_amount": 10000.00,
      "estimated_time": "1-2 giờ",
      "logo_url": "https://cdn.pay27.vn/gateways/paypal.svg"
    },
    {
      "code": "stripe",
      "name": "Stripe",
      "type": "payment_processor",
      "status": "active",
      "supported_currencies": ["USD", "EUR", "GBP", "CAD"],
      "fee_percentage": 2.9,
      "fee_fixed": 0.30,
      "min_amount": 1.00,
      "max_amount": 50000.00,
      "estimated_time": "2-3 ngay",
      "logo_url": "https://cdn.pay27.vn/gateways/stripe.svg"
    }
  ]
}

POST/v1/connections

Tạo kết nối đến một cổng thanh toán. Bạn cần cung cấp credentials của cổng (API key, secret...) để Pay27 có thể thực hiện giao dịch thay bạn.

Request Body

Tên	Kiểu	Bắt buộc	Mô tả
`gateway`	string	Có	Mã cổng thanh toán. VD: paypal, stripe
`name`	string	Có	Tên hiển thị cho kết nối này (để bạn dễ quản lý)
`credentials`	object	Có	Thông tin xác thực của cổng. Cấu trúc tùy thuộc vào từng gateway. VD với PayPal: { client_id, client_secret }
`environment`	string	Không	Môi trường: sandbox hoặc production. Mặc định: sandbox

Example Request

shell

curl -X POST https://api.pay27.vn/v1/connections \
  -H "Authorization: Bearer pb_live_x1y2z3a4b5c6d7e8f9" \
  -H "Content-Type: application/json" \
  -d '{
    "gateway": "paypal",
    "name": "PayPal Business - Công ty ABC",
    "credentials": {
      "client_id": "AXy9k8j7h6g5f4e3d2c1b0a",
      "client_secret": "ELx9k8j7h6g5f4e3d2c1b0a"
    },
    "environment": "production"
  }'

# 201 Created
{
  "id": "conn_x9k8j7h6g5f",
  "object": "connection",
  "gateway": "paypal",
  "name": "PayPal Business - Công ty ABC",
  "status": "active",
  "environment": "production",
  "created_at": "2026-06-02T08:00:00Z",
  "updated_at": "2026-06-02T08:00:00Z"
}

Example Response

json

{
  "id": "conn_x9k8j7h6g5f",
  "object": "connection",
  "gateway": "paypal",
  "name": "PayPal Business - Công ty ABC",
  "status": "active",
  "environment": "production",
  "created_at": "2026-06-02T08:00:00Z",
  "updated_at": "2026-06-02T08:00:00Z"
}

GET/v1/connections

Lấy danh sách tất cả kết nối của bạn đến các cổng thanh toán, bao gồm trạng thái và thời gian tạo.

Query Parameters

Tên	Kiểu	Bắt buộc	Mô tả
`status`	string	Không	Lọc theo trạng thái: active, inactive, error
`gateway`	string	Không	Lọc theo mã cổng. VD: paypal

Example Request

shell

curl -X GET "https://api.pay27.vn/v1/connections?status=active" \
  -H "Authorization: Bearer pb_live_x1y2z3a4b5c6d7e8f9"

# 200 OK
{
  "object": "list",
  "data": [
    {
      "id": "conn_x9k8j7h6g5f",
      "object": "connection",
      "gateway": "paypal",
      "name": "PayPal Business - Công ty ABC",
      "status": "active",
      "environment": "production",
      "created_at": "2026-06-02T08:00:00Z",
      "updated_at": "2026-06-02T08:00:00Z"
    },
    {
      "id": "conn_w8v7u6t5s4",
      "object": "connection",
      "gateway": "stripe",
      "name": "Stripe Connect",
      "status": "active",
      "environment": "sandbox",
      "created_at": "2026-05-20T03:15:00Z",
      "updated_at": "2026-05-20T03:15:00Z"
    }
  ]
}

Example Response

json

{
  "object": "list",
  "data": [
    {
      "id": "conn_x9k8j7h6g5f",
      "object": "connection",
      "gateway": "paypal",
      "name": "PayPal Business - Công ty ABC",
      "status": "active",
      "environment": "production",
      "created_at": "2026-06-02T08:00:00Z",
      "updated_at": "2026-06-02T08:00:00Z"
    },
    {
      "id": "conn_w8v7u6t5s4",
      "object": "connection",
      "gateway": "stripe",
      "name": "Stripe Connect",
      "status": "active",
      "environment": "sandbox",
      "created_at": "2026-05-20T03:15:00Z",
      "updated_at": "2026-05-20T03:15:00Z"
    }
  ]
}

Currencies API

Tra cứu danh sách tiền tệ được hỗ trợ và công cụ quy đổi tỉ giá real-time.

GET/v1/currencies

Lấy danh sách tất cả các loại tiền tệ được Pay27 hỗ trợ, bao gồm mã ISO, ký hiệu, số thập phân và loại (fiat/crypto).

Query Parameters

Tên	Kiểu	Bắt buộc	Mô tả
`type`	string	Không	Lọc theo loại: fiat hoặc crypto

Example Request

shell

curl -X GET "https://api.pay27.vn/v1/currencies" \
  -H "Authorization: Bearer pb_live_x1y2z3a4b5c6d7e8f9"

# 200 OK
{
  "object": "list",
  "data": [
    {
      "code": "USD",
      "name": "US Dollar",
      "symbol": "$",
      "decimals": 2,
      "type": "fiat"
    },
    {
      "code": "VND",
      "name": "Vietnamese Dong",
      "symbol": "₫",
      "decimals": 0,
      "type": "fiat"
    },
    {
      "code": "EUR",
      "name": "Euro",
      "symbol": "€",
      "decimals": 2,
      "type": "fiat"
    },
    {
      "code": "USDC",
      "name": "USD Coin",
      "symbol": "USDC",
      "decimals": 6,
      "type": "crypto"
    }
  ]
}

Example Response

json

{
  "object": "list",
  "data": [
    {
      "code": "USD",
      "name": "US Dollar",
      "symbol": "$",
      "decimals": 2,
      "type": "fiat"
    },
    {
      "code": "VND",
      "name": "Vietnamese Dong",
      "symbol": "₫",
      "decimals": 0,
      "type": "fiat"
    },
    {
      "code": "EUR",
      "name": "Euro",
      "symbol": "€",
      "decimals": 2,
      "type": "fiat"
    },
    {
      "code": "USDC",
      "name": "USD Coin",
      "symbol": "USDC",
      "decimals": 6,
      "type": "crypto"
    }
  ]
}

GET/v1/currencies/convert

Quy đổi số tiền giữa hai loại tiền tệ. Tỉ giá được cập nhật real-time từ các nguồn uy tín.

Query Parameters

Tên	Kiểu	Bắt buộc	Mô tả
`from`	string	Có	Mã tiền tệ nguồn. VD: USD
`to`	string	Có	Mã tiền tệ đích. VD: VND
`amount`	number	Có	Số tiền cần quy đổi (số dương)

Example Request

shell

curl -X GET "https://api.pay27.vn/v1/currencies/convert?from=USD&to=VND&amount=100" \
  -H "Authorization: Bearer pb_live_x1y2z3a4b5c6d7e8f9"

# 200 OK
{
  "object": "conversion",
  "from": "USD",
  "to": "VND",
  "amount": 100.00,
  "result": 2545000.00,
  "rate": 25450.00,
  "timestamp": "2026-06-02T08:00:00Z"
}

Example Response

json

{
  "object": "conversion",
  "from": "USD",
  "to": "VND",
  "amount": 100.00,
  "result": 2545000.00,
  "rate": 25450.00,
  "timestamp": "2026-06-02T08:00:00Z"
}

Webhooks API

Webhooks cho phép Pay27 gửi thông báo real-time đến server của bạn khi có sự kiện xảy ra (payout hoàn thành, thất bại, kết nối hết hạn...).

Pay27 sẽ gửi HTTP POST request đến URL webhook bạn đã đăng ký. Mỗi request đều có chữ ký HMAC-SHA256 trong header để bạn xác thực.

Xem hướng dẫn chi tiết tại trang Webhooks Guide.

Rate Limits

Pay27 áp dụng rate limiting để đảm bảo chất lượng dịch vụ cho tất cả người dùng. Giới hạn được tính trên mỗi API Key hoặc Bearer token.

Production

120req/phút

Trên mỗi API Key

Sandbox / Dev

1,000req/phút

Trên mỗi API Key (môi trường test)

Khi vượt quá rate limit, API sẽ trả về HTTP 429 Too Many Requests. Response sẽ bao gồm header Retry-After cho biết số giây cần đợi trước khi thử lại. Chúng tôi khuyến nghị áp dụng exponential backoff khi gặp lỗi 429.

Mã lỗi

Danh sách các HTTP status code và mã lỗi mà Pay27 API có thể trả về.

HTTP	Code	Mô tả	Cách xử lý
400	`bad_request`	Request không hợp lệ. Kiểm tra lại body/query params.	Xác minh định dạng JSON và các trường bắt buộc.
401	`unauthorized`	Thiếu hoặc sai API Key / Bearer Token.	Kiểm tra header Authorization hoặc X-API-Key.
403	`forbidden`	Không có quyền truy cập tài nguyên.	Kiểm tra scope của API Key hoặc quyền tài khoản.
404	`not_found`	Tài nguyên không tồn tại.	Kiểm tra ID hoặc đường dẫn endpoint.
409	`conflict`	Xung đột dữ liệu (VD: idempotency key trùng).	API an toàn với idempotency key, bạn có thể retry.
422	`unprocessable_entity`	Dữ liệu hợp lệ về cú pháp nhưng không thể xử lý.	Kiểm tra logic nghiệp vụ (VD: số dư không đủ).
429	`rate_limit_exceeded`	Vượt quá giới hạn request.	Giảm tần suất gọi, kiểm tra header Retry-After.
500	`internal_error`	Lỗi máy chủ nội bộ.	Thử lại sau. Liên hệ support nếu lỗi kéo dài.
502	`gateway_error`	Lỗi từ cổng thanh toán bên thứ ba.	Thử lại sau vài phút. Pay27 sẽ tự động retry nếu có thể.
503	`service_unavailable`	Dịch vụ tạm thời không khả dụng.	Kiểm tra trang Status. Thử lại với exponential backoff.

Cần hỗ trợ thêm?

Tham khảo Webhooks Guide để tích hợp real-time, hoặc liên hệ đội ngũ kỹ thuật của Pay27.

Webhooks Guide Quickstart Guide