```markdown
# 💳 Payment Gateway API Documentation
**Base URL**: `https://midtrans.pasang.cloud/api/v1`

Layanan API Gateway yang menjembatani aplikasi internal dengan Midtrans Payment Gateway. Mendukung pembuatan transaksi (Snap), pengecekan status otomatis, dan handling webhook.

---

## 🔐 Authentication
Setiap request ke endpoint API harus menyertakan header berikut untuk keamanan. Kredensial bisa didapatkan di Dashboard Admin menu **App Keys**.

| Header | Tipe | Deskripsi |
| :--- | :--- | :--- |
| `X-App-Code` | String | Kode unik aplikasi (misal: `ANDROID_APP`) |
| `X-Api-Key` | String | Kunci rahasia API (32 karakter hex) |
| `Content-Type` | String | Wajib bernilai `application/json` |

---

## 🚀 Endpoints

### 1. Create Transaction (Charge)
Membuat transaksi baru untuk mendapatkan Snap Token dan Redirect URL pembayaran.

* **Endpoint**: `POST /charge`
* **Auth**: Required

**Request Body:**
```json
{
  "transaction_details": {
    "order_id": "INV-2025-001",
    "gross_amount": 150000
  },
  "customer_details": {
    "first_name": "Budi",
    "last_name": "Santoso",
    "email": "budi@example.com",
    "phone": "08123456789"
  },
  "item_details": [
    {
      "id": "ITEM1",
      "price": 150000,
      "quantity": 1,
      "name": "Premium Membership"
    }
  ]
}

```

**Response (Success - 201/200):**

```json
{
  "token": "c740c4c4-1186-4f73-9c86-xxxxxxxx",
  "redirect_url": "[https://app.sandbox.midtrans.com/snap/v4/redirection/c740c4c4-](https://app.sandbox.midtrans.com/snap/v4/redirection/c740c4c4-)...",
  "status_code": "201",
  "success": true
}

```

**Response (Error - 400/500):**

```json
{
  "status": "error",
  "message": "Invalid Payload: transaction_details required"
}

```

---

### 2. Check Transaction Status

Mengecek status pembayaran terkini langsung ke Midtrans dan mengupdate database lokal jika ada perubahan.

* **Endpoint**: `GET /status/{order_id}`
* **Auth**: Required

**Request:**
`GET https://midtrans.pasang.cloud/api/v1/status/INV-2025-001`

**Response (Success - 200):**

```json
{
  "transaction_id": "bf692822-45a8-444b-b35d-xxxxxxxxx",
  "order_id": "INV-2025-001",
  "gross_amount": "150000.00",
  "payment_type": "bank_transfer",
  "transaction_status": "settlement",
  "transaction_time": "2025-12-22 10:20:15",
  "status_code": "200"
}

```

*Note: `transaction_status` bisa berupa: `pending`, `settlement` (sukses), `expire`, `deny`, atau `cancel`.*

---

### 3. Handle Webhook (Callback)

Endpoint ini didaftarkan di Dashboard Midtrans untuk menerima notifikasi pembayaran otomatis.

* **Endpoint**: `POST /callback`
* **Auth**: Tidak perlu header auth manual (Verifikasi menggunakan Signature Key internal).

**Cara Setup di Midtrans:**

1. Login ke [Midtrans Dashboard](https://www.google.com/search?q=https://dashboard.midtrans.com).
2. Masuk ke **Settings** > **Configuration**.
3. Pada **Notification Configuration**, masukkan URL:
`https://midtrans.pasang.cloud/api/v1/callback`

---

## 🌐 Public Handling (Redirect)

Ketika user selesai melakukan pembayaran di halaman Midtrans, user akan diarahkan kembali ke URL ini.

**Redirect URL:**
`https://midtrans.pasang.cloud/payment-finish`

**Parameter URL:**
Midtrans akan otomatis menambahkan parameter:
`?order_id=XXX&status_code=200&transaction_status=settlement`

Halaman ini akan menampilkan UI Status Pembayaran (Sukses/Gagal) yang ramah pengguna.

---

## ⚠️ Error Codes

| Kode | Keterangan | Solusi |
| --- | --- | --- |
| **200/201** | OK / Created | Request berhasil diproses. |
| **400** | Bad Request | Cek format JSON, pastikan field `order_id` dan `gross_amount` ada. |
| **401** | Unauthorized | Header `X-App-Code` atau `X-Api-Key` salah/tidak ada. |
| **403** | Forbidden | Signature tidak valid (khusus callback) atau akses ditolak. |
| **404** | Not Found | Endpoint atau Order ID tidak ditemukan. |
| **500** | Server Error | Masalah koneksi ke Midtrans atau error database. Hubungi Admin. |

---

## 🛠 Testing Guide

1. **Login Admin Panel** di `https://midtrans.pasang.cloud`.
2. Buat App Key baru di menu **App Keys**.
3. Gunakan **Postman** atau **cURL** dengan App Code & API Key yang didapat.
4. Hit endpoint `/charge` untuk mendapatkan link pembayaran.
5. Bayar menggunakan Simulator Midtrans (jika Sandbox).
6. Cek endpoint `/status/{order_id}` untuk memverifikasi update status.

---

*Built with Flask & Tailwind CSS*