# CentralPay SHOP — Developer Integration

โปรเจกต์นี้เป็น Reference Implementation สำหรับโปรแกรมเมอร์ร้านค้าที่ต้องการเชื่อม CentralPay โดยไม่ต้องรู้โครงสร้างฐานข้อมูลของ CentralPay

## หลักการสำคัญ

- `POST Create Invoice` ใช้สร้างบิล/QR
- `GET Invoice` / `GET Invoices` / `GET Transactions` / `GET Candidates` เป็นการอ่านข้อมูลเท่านั้น
- `POST Cancel Invoice` ใช้ยกเลิกบิล PENDING
- `POST Manual Match` และ `POST Manual Confirm` เป็นคำสั่งให้ CentralPay ตัดสิน Invoice
- **การเติมเครดิต/ส่งสินค้า/ปิด Order เกิดจาก `payment.paid` Webhook เพียงทางเดียว**
- AUTO, MANUAL_MATCH และ MANUAL_CONFIRM จบที่ Webhook เดียวกัน

## Flow

```text
Create Invoice ───────────────→ CentralPay
                                  │
                     ┌────────────┼─────────────┐
                     │            │             │
                    AUTO      MANUAL_MATCH  MANUAL_CONFIRM
                     │            │             │
                     └────────────┼─────────────┘
                                  ↓
                                PAID
                                  ↓
                         payment.paid Webhook
                                  ↓
SHOP /webhook/centralpay.php
  ├─ Verify HMAC-SHA256
  ├─ Verify event_id
  ├─ Idempotency by event_id / invoice_no
  ├─ เติมเครดิต / Fulfill Order
  └─ HTTP 200
```

## API ที่ SHOP ใช้

1. `POST /api/v1/invoices.php` — Create Invoice
2. `GET /api/v1/invoices.php?invoice_no=...` — Get Invoice
3. `POST /api/v1/cancel-invoice.php` — Cancel Invoice
4. `GET /api/v1/invoices.php` — Get Invoices
5. `GET /api/v1/transactions.php` — Get Transactions
6. `GET /api/v1/match-candidates.php?transaction_id=...` — Get Match Candidates
7. `POST /api/v1/manual-match.php` — Manual Match
8. `POST /api/v1/manual-confirm.php` — Manual Confirm

ทุก Request จาก SHOP ไป CentralPay ใช้ Merchant API Key:

```http
Authorization: Bearer {{api_key}}
Accept: application/json
Content-Type: application/json   # เฉพาะ request ที่มี JSON body
```

## Manual ไม่เติมเครดิตตรง

หลังบ้าน SHOP ส่ง `matched_by` / `confirmed_by` และ `remark` ไป CentralPay เท่านั้น ห้าม `UPDATE credit` จาก response ของ Manual API เพราะ CentralPay จะสร้าง `payment.paid` event หลัง Invoice เป็น PAID แล้ว Webhook จะเป็นผู้ Fulfill เพียงจุดเดียว

## Status Polling

หน้า QR สามารถเรียก Get Invoice เพื่อแสดง `PENDING / PAID / EXPIRED / CANCELLED` ได้ แต่การเห็น `PAID` จาก GET **ไม่ใช่คำสั่งให้เติมเครดิต** ในโปรเจกต์นี้ เมื่อเห็น PAID หน้าเว็บเพียงรีเฟรชเครดิตจากฐานข้อมูล SHOP เพื่อแสดงผลที่ Webhook อัปเดตแล้ว

## Callback

ตั้ง Callback URL ให้ตรงตำแหน่ง deploy จริง เช่น:

```text
http://YOUR-SHOP/public/webhook/centralpay.php
```

SHOP ตรวจ `X-Payment-Signature` จาก raw request body ด้วย callback secret และตรวจ `X-Payment-Event` / `event_id` ก่อนดำเนินการ