Lấy danh sách phương thức thanh toán (Backend)

API getPaymentMethods cho phép Order Backend/Merchant Backend lấy danh sách phương thức thanh toán đang enable theo terminal (xác định bằng X-Payment-API-Key) và điều kiện giao dịch (amount, currency).

Endpoint

Endpoint: GET /api/payments/v1/payment-methods

Authentication

API yêu cầu xác thực bằng X-Payment-API-Key (service-to-service). API này không dành cho client/frontend gọi trực tiếp.

Headers

Header	Required	Mô tả
`X-Payment-API-Key`	✅	API key của merchant/terminal
`Accept-Language`	❌	Ngôn ngữ phản hồi (nếu hệ thống có cấu hình localization)

Query Parameters

Parameter	Required	Type	Mô tả
`amount`	✅	number	Số tiền giao dịch, dùng để filter theo min/max giới hạn của từng payment method theo currency
`currency`	✅	string	Mã tiền tệ (VD: `VND`, `USD`)

Lưu ý:

API hiện trả về full list (không phân trang).
merchantId/terminalId (nếu có trong request struct nội bộ) sẽ được enforce từ X-Payment-API-Key (không tin vào client-provided values).

Response

Success Response (200):

{
  "items": [
    {
      "paymentMethodId": "uuid-string",
      "code": "string",
      "name": "string",
      "type": "CARD",
      "category": "CREDIT",
      "iconUrl": "string",
      "provider": {
        "id": "uuid-string",
        "name": "string",
        "code": "string"
      },
      "supportsTokenization": true,
      "requiresRedirect": false,
      "sortOrder": 1,
      "verificationAmount": 0.0,
      "currencies": [
        {
          "currency": "VND",
          "minAmount": 10000.0,
          "maxAmount": 50000000.0
        }
      ]
    }
  ]
}

Response Field Details

items[] là danh sách PaymentMethodResponse đã được filter theo terminal/merchant config và điều kiện amount/currency.
Nếu nhiều provider cùng hỗ trợ một payment method, hệ thống sẽ chọn provider có priority cao nhất (giá trị ưu tiên nhỏ hơn).

Bảng chi tiết các field trong response:

Field	Type	Mô tả
`items`	array	Danh sách phương thức thanh toán (PaymentMethodResponse)
`items[].paymentMethodId`	string (UUID)	ID phương thức thanh toán
`items[].code`	string	Mã phương thức (VD: CREDIT_CARD, WALLET)
`items[].name`	string	Tên hiển thị phương thức thanh toán
`items[].type`	string	Loại: `CARD`, `WALLET`, `BANK_TRANSFER`, v.v.
`items[].category`	string	Hạng mục (VD: `CREDIT`, `DEBIT`)
`items[].iconUrl`	string	URL icon hiển thị
`items[].provider`	object	Provider được chọn cho method này
`items[].provider.id`	string (UUID)	ID provider
`items[].provider.name`	string	Tên provider
`items[].provider.code`	string	Mã provider
`items[].supportsTokenization`	boolean	Có hỗ trợ lưu thẻ/tokenization không
`items[].requiresRedirect`	boolean	Có cần redirect user sang trang provider không
`items[].sortOrder`	number	Thứ tự ưu tiên hiển thị (số nhỏ ưu tiên cao hơn)
`items[].verificationAmount`	number	Số tiền verification (nếu có)
`items[].currencies`	array	Danh sách currency và giới hạn min/max cho method này
`items[].currencies[].currency`	string	Mã tiền tệ (VD: VND, USD)
`items[].currencies[].minAmount`	number	Số tiền tối thiểu áp dụng cho currency này
`items[].currencies[].maxAmount`	number	Số tiền tối đa áp dụng cho currency này

Error Responses

HTTP Status	Code	Message	Mô tả
400	4001	Invalid request	Thiếu/invalid `amount` hoặc `currency`
401	4101	X-API-Key header is required	Thiếu `X-Payment-API-Key`
401	4100	Invalid API key	API key không hợp lệ / bị revoke
500	5000	Internal server error	Lỗi hệ thống

Routing qua Mule (Payment Hub)

Quan trọng: API getPaymentMethods được gọi trực tiếp từ Order Backend/Merchant Backend tới Payment Hub thông qua MuleSoft, không được gọi trực tiếp tới Payment Hub.

Internal (PnL)

Kết nối Internal dành cho các PnL trong Vingroup.

Base URL trên Mule (endpoint tới Payment Hub):

DEV: {MULE_INTERNAL_BASE_URL}/payment-hub/
SIT: {MULE_INTERNAL_BASE_URL}/sit/payment-hub/
UAT: {MULE_INTERNAL_BASE_URL}/uat/payment-hub/
Production: {MULE_INTERNAL_PROD_URL}/payment-hub/

Lưu ý: Với môi trường Production, các bên kết nối sẽ được team Mule cấp key riêng (client_id và client_secret). Với môi trường DEV/SIT/UAT dùng chung key.

External (Đối tác)

Kết nối External dành cho các đối tác bên ngoài Vingroup. Chỉ hỗ trợ 2 môi trường: Production và UAT.

Base URL trên Mule (endpoint tới Payment Hub):

UAT: https://test-api.vingroup.net:7445/payment-hub/
Production: https://api-cloud.vingroup.net/payment-hub/

Yêu cầu kết nối External:

Tất cả các request từ đối tác external cần cung cấp danh sách IPs để whitelist
Phía Mule sẽ cấp client_id và client_secret riêng cho từng đối tác
Có whitelist và limit access theo endpoint

Ví dụ

cURL Example

curl --location 'https://api.example.com/api/payments/v1/payment-methods?amount=100000&currency=VND' \
--header 'accept: */*' \
--header 'X-Payment-API-Key: <YOUR_PAYMENT_API_KEY>'

cURL Example (qua Mule)

curl --location '{MULE_INTERNAL_BASE_URL}/payment-hub/api/payments/v1/payment-methods?amount=100000&currency=VND' \
--header 'accept: */*' \
--header 'X-Payment-API-Key: <YOUR_PAYMENT_API_KEY>' \
--header 'client_id: YOUR_CLIENT_ID' \
--header 'client_secret: YOUR_CLIENT_SECRET'

Liên kết liên quan

Khởi tạo thanh toán từ Backend - API initPayment được gọi từ Backend qua Mule
Tích hợp thanh toán - Luồng thanh toán tổng quan

Endpoint​

Authentication​

Headers​

Query Parameters​

Response​

Response Field Details​

Error Responses​

Routing qua Mule (Payment Hub)​

Internal (PnL)​

External (Đối tác)​

Ví dụ​

cURL Example​

cURL Example (qua Mule)​

Liên kết liên quan​