# API lấy danh sách kết nối

**Endpoint:** `POST https://payment.pay2s.vn/api/card-popup-session.php`

**Content-Type:** `application/json`. Gọi từ backend với bốn header HMAC trong [Xác thực](/docs/card-popup/authentication/). Cả ba thao tác dùng cùng URL, phân biệt bằng `action`. Không mở URL API trực tiếp bằng trình duyệt.

Các ví dụ dưới đây dùng dữ liệu minh họa, không phải phiên thanh toán đang hoạt động. Timestamp, ID và token phải lấy từ response thật.

## Request
```json
{
  "action": "connections"
}
```

| Trường | Kiểu | Bắt buộc | Ý nghĩa |
| --- | --- | --- | --- |
| action | string | Có | Luôn là connections |

## Response HTTP 200
```json
{
  "status": true,
  "success": true,
  "message": "OK",
  "data": {
    "connections": [
      {
        "connectionId": 12,
        "name": "ePay thử nghiệm",
        "merchantId": "TEST000001",
        "environment": "sandbox",
        "enabled": true,
        "isDefault": true
      },
      {
        "connectionId": 15,
        "name": "Kết nối tạm tắt",
        "merchantId": "TEST000002",
        "environment": "sandbox",
        "enabled": false,
        "isDefault": false
      }
    ]
  }
}
```

| Trường data.connections[] | Kiểu | Ý nghĩa |
| --- | --- | --- |
| connectionId | integer | ID Pay2S dùng khi tạo phiên; không phải Merchant ID |
| name | string | Tên kết nối để hiển thị |
| merchantId | string | Merchant ID ePay; không phải khóa xác thực |
| environment | string | sandbox hoặc production |
| enabled | boolean | Kết nối đang bật hay tắt |
| isDefault | boolean | Kết nối mặc định được gán cho phạm vi bộ khóa |

Không có kết nối: ```json
{
  "status": true,
  "success": true,
  "message": "OK",
  "data": {
    "connections": []
  }
}
```

## Phạm vi và lưu ID

- Khóa tài khoản: trả kết nối thuộc tài khoản; không bắt buộc có cửa hàng.
- Khóa cửa hàng: chỉ trả kết nối đang gán cho cửa hàng đó.
- Demo không trả kết nối production. API không trả encode key, secret hoặc khóa ký ePay.
- Danh sách có thể chứa kết nối tắt. enabled=true không đảm bảo đã đủ gói, loại thẻ, phê duyệt website. API tạo phiên kiểm tra lại.
- Khách lấy danh sách lúc cấu hình, tự lưu connectionId, truyền thẳng ID khi tạo phiên. Không cần lấy lại mỗi lần. Chỉ làm mới khi quản trị thay đổi cấu hình hoặc muốn chọn kết nối khác.
- Không được sửa ID để truy cập kết nối của tài khoản khác.

## Code PHP, Node.js, Python

Tải client tương ứng và đặt cạnh file ví dụ: [PHP](/downloads/card-popup/client.php), [Node.js](/downloads/card-popup/client.mjs), [Python](/downloads/card-popup/pay2s_client.py). Cấu hình biến môi trường theo [Xác thực](/docs/card-popup/authentication/). Client ký đúng body gửi đi, kiểm tra HTTP và trả về phần `data`.

### PHP 8.1+ với cURL
```php
<?php
require __DIR__.'/client.php';
$payload=json_decode('{"action":"connections"}',true,32,JSON_THROW_ON_ERROR);
try {
    $data=pay2s($payload);
    // Xử lý $data tại backend. Không log popupUrl/token hoặc khóa.
} catch (Throwable $e) {
    // Giữ orderId nếu có; tra cứu khi chưa rõ kết quả, không tạo đơn mới tự động.
    throw $e;
}
```

### Node.js 20+ (ES modules)
```js
import {pay2s} from './client.mjs';
const payload={
  "action": "connections"
};
const data=await pay2s(payload);
// Xử lý data ở backend; chỉ trả data phiên cho đúng người mua.
```

### Python 3.10+ (thư viện chuẩn)
```python
import json
from pay2s_client import pay2s
payload = json.loads(r'''{
  "action": "connections"
}''')
data = pay2s(payload)
# Xử lý data ở backend, không ghi token/khóa vào log.
```

### cURL

Lưu body request ở trên thành `request.json`. Tạo `TIMESTAMP` và `SIGNATURE` trên đúng byte của file theo trang xác thực; không ký một body khác.
```bash
curl --request POST 'https://payment.pay2s.vn/api/card-popup-session.php' \
  --header 'Content-Type: application/json' \
  --header "X-Pay2S-Partner: $PAY2S_PARTNER_CODE" \
  --header "X-Pay2S-Access-Key: $PAY2S_ACCESS_KEY" \
  --header "X-Pay2S-Timestamp: $TIMESTAMP" \
  --header "X-Pay2S-Signature: $SIGNATURE" \
  --data-binary @request.json
```


## Response lỗi

### HTTP 403
```json
{
  "status": false,
  "success": false,
  "message": "Tích hợp popup chưa được bật.",
  "data": []
}
```

### HTTP 409
```json
{
  "status": false,
  "success": false,
  "message": "Kết nối không tồn tại, đã tắt hoặc không thuộc phạm vi bộ khóa.",
  "data": {
    "reference": "MGP-example-reference"
  }
}
```

### HTTP 429
```json
{
  "status": false,
  "success": false,
  "message": "Quá nhiều yêu cầu.",
  "data": []
}
```

### HTTP 503
```json
{
  "status": false,
  "success": false,
  "message": "Chưa thể xử lý thanh toán thẻ. Vui lòng thử lại sau.",
  "data": {
    "reference": "MGP-example-reference"
  }
}
```

Không dựa vào chuỗi `message` để quyết định thanh toán thành công/thất bại. `data` có thể là mảng rỗng hoặc object chứa `reference`. Xem [bảng HTTP và cách thử lại](/docs/card-popup/authentication/).