From e1ea1ae795ea1074444871920ae09e2ad612ef88 Mon Sep 17 00:00:00 2001 From: andri Date: Mon, 22 Dec 2025 10:11:51 +0000 Subject: [PATCH] Add API.md --- API.md | 258 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 258 insertions(+) create mode 100644 API.md diff --git a/API.md b/API.md new file mode 100644 index 0000000..bc86421 --- /dev/null +++ b/API.md @@ -0,0 +1,258 @@ +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/` +* **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 + "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. | \ No newline at end of file