Berikut adalah **Dokumentasi Teknis (API Documentation)** lengkap untuk integrasi **Middleware Payment Gateway** Anda.

Dokumentasi ini ditujukan untuk developer (Frontend/Backend) yang akan menghubungkan aplikasi lain (seperti Billing System, Toko Online, Aplikasi Donasi) ke gateway ini.

---

# 📚 Dokumentasi API Payment Gateway

**Version:** 1.0.0
**Base URL:** `http://ip-server-anda:5000` (Sesuaikan dengan IP/Domain VPS)

## 🔐 Autentikasi

Setiap request ke API ini **wajib** menyertakan kredensial otentikasi yang didapatkan dari **Dashboard Admin** (`Menu App Keys`).

Kredensial dikirim melalui **HTTP Headers**:

| Header Name | Value | Keterangan |
| --- | --- | --- |
| `X-App-Code` | `biling` (contoh) | Kode unik aplikasi klien |
| `X-Api-Key` | `fb93...` | Secret Key aplikasi klien |

---

## 🚀 Endpoints

### 1. Buat Transaksi (Create Transaction)

Membuat token pembayaran dan link redirect Snap Midtrans.

* **URL:** `/charge`
* **Method:** `POST`
* **Content-Type:** `application/json`

**Parameter Body (JSON):**

| Field | Tipe | Wajib? | Deskripsi |
| --- | --- | --- | --- |
| `order_id` | String | **Ya** | ID unik tagihan (misal: `INV-1001`) |
| `amount` | Integer | **Ya** | Nominal pembayaran (tanpa desimal) |
| `item_details` | Array | Tidak | Detail barang/jasa (lihat contoh) |
| `customer_details` | Object | Tidak | Data pelanggan (Nama, Email, HP) |

**Contoh Request:**

```json
{
    "order_id": "INV-2025-001",
    "amount": 150000,
    "customer_details": {
        "first_name": "Budi",
        "last_name": "Santoso",
        "email": "budi@example.com",
        "phone": "08123456789"
    },
    "item_details": [
        {
            "id": "VPS-01",
            "price": 150000,
            "quantity": 1,
            "name": "Cloud VPS Basic"
        }
    ]
}

```

**Contoh Response Sukses (201 Created):**

```json
{
  "redirect_url": "https://app.midtrans.com/snap/v4/redirection/0f8736b5-...",
  "token": "0f8736b5-2f1f-40bd-b3ad-0ef0a06d3443"
}

```

> **Catatan:** Gunakan `redirect_url` untuk mengarahkan user ke halaman pembayaran, atau gunakan `token` jika Anda menggunakan Snap.js di frontend.

---

### 2. Cek Status Transaksi

Mengecek status pembayaran secara realtime ke Midtrans.

* **URL:** `/status/<order_id>`
* **Method:** `GET`

**Contoh Request:**
`GET /status/INV-2025-001`

**Contoh Response (200 OK):**

```json
{
  "id": "e67a2012-3208-4b3e-...",
  "transaction_status": "settlement",
  "fraud_status": "accept",
  "status_code": "200",
  "status_message": "Success, transaction is found"
}

```

> **Status Penting:**
> * `settlement` / `capture`: Pembayaran Sukses.
> * `pending`: Menunggu pembayaran.
> * `expire`: Kadaluarsa.
> * `cancel` / `deny`: Gagal.
> 
> 

---

## 💻 Contoh Implementasi Code

Berikut adalah contoh cara menembak API ini menggunakan Python dan PHP.

### A. Python (Requests)

```python
import requests
import json

url = "http://localhost:5000/charge"

payload = {
    "order_id": "TAGIHAN-001",
    "amount": 50000,
    "customer_details": {
        "first_name": "Andri",
        "email": "andri@indoweb.id",
        "phone": "08123456789"
    }
}

headers = {
    'X-App-Code': 'biling',
    'X-Api-Key': 'fb93b4e802314a189809f393d913bba6', # Ganti dengan API Key asli
    'Content-Type': 'application/json'
}

try:
    response = requests.post(url, headers=headers, json=payload)
    if response.status_code == 201:
        data = response.json()
        print("Link Bayar:", data['redirect_url'])
    else:
        print("Error:", response.text)
except Exception as e:
    print(e)

```

### B. PHP (cURL)

Cocok untuk diintegrasikan ke WHMCS atau Billing berbasis PHP.

```php
<?php

$curl = curl_init();

$payload = [
    "order_id" => "INV-" . time(),
    "amount" => 100000,
    "customer_details" => [
        "first_name" => "Client",
        "email" => "client@example.com"
    ]
];

curl_setopt_array($curl, array(
  CURLOPT_URL => 'http://localhost:5000/charge',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode($payload),
  CURLOPT_HTTPHEADER => array(
    'X-App-Code: biling',
    'X-Api-Key: fb93b4e802314a189809f393d913bba6',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);
$httpcode = curl_getinfo($curl, CURLINFO_HTTP_CODE);

curl_close($curl);

if ($httpcode == 201) {
    $data = json_decode($response, true);
    echo "Silakan bayar di sini: " . $data['redirect_url'];
} else {
    echo "Gagal membuat transaksi: " . $response;
}
?>

```

---

## ⚙️ Konfigurasi Server (Info Admin)

Informasi ini untuk Administrator Server Gateway.

**1. File Konfigurasi (`.env`)**
Lokasi: `/opt/midtrans_flask/.env`
Pastikan data berikut benar:

```ini
# Security App
SECRET_KEY=rahasia_negara_api_2025

# Midtrans Credentials (Dapat dari Dashboard Midtrans)
MIDTRANS_SERVER_KEY=Mid-server-YXLR8xjEkrISCXtlDvS7FDFX
MIDTRANS_CLIENT_KEY=Mid-client-j8BudqVadevtaNbQ
MIDTRANS_MERCHANT_ID=G996317131

# Mode Environment
# Ubah ke 'false' jika masih testing (Sandbox)
# Ubah ke 'true' jika sudah live (Production) - Uang Asli!
MIDTRANS_IS_PRODUCTION=true 

```

**2. Cara Restart Service**
Jika Anda mengubah file `.env`, service harus direstart:

```bash
systemctl restart midtrans-gateway

```

**3. Logs**
Untuk melihat log transaksi atau error:

```bash
journalctl -u midtrans-gateway -f
# Atau jika manual:
tail -f /opt/midtrans_flask/app.log

```

---

## ⚠️ Troubleshooting Common Errors

| Status Code | Pesan Error | Penyebab & Solusi |
| --- | --- | --- |
| `401` | Unauthorized | **API Key/App Code salah.** Cek kembali header request Anda. |
| `400` | Bad Request | **Data JSON tidak valid.** Pastikan `order_id` unik dan `amount` berupa angka (integer). |
| `500` | Internal Server Error | **Masalah koneksi ke Midtrans.** Cek koneksi internet server atau Server Key Midtrans di `.env`. |
| `404` | Endpoint not found | **Salah URL.** Pastikan endpoint `/charge` atau `/status` benar. |