From 7245497b5b5c9ed3e0d29bbc8cbcbe04f0cc1b3e Mon Sep 17 00:00:00 2001 From: andri Date: Mon, 22 Dec 2025 14:39:14 +0000 Subject: [PATCH] Update API.md --- API.md | 340 +++++++++++++++++++++------------------------------------ 1 file changed, 122 insertions(+), 218 deletions(-) diff --git a/API.md b/API.md index bc86421..48b0de1 100644 --- a/API.md +++ b/API.md @@ -1,258 +1,162 @@ -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. +```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. --- -# 📚 Dokumentasi API Payment Gateway +## 🔐 Authentication +Setiap request ke endpoint API harus menyertakan header berikut untuk keamanan. Kredensial bisa didapatkan di Dashboard Admin menu **App Keys**. -**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 | +| 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. Buat Transaksi (Create Transaction) +### 1. Create Transaction (Charge) +Membuat transaksi baru untuk mendapatkan Snap Token dan Redirect URL pembayaran. -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:** +* **Endpoint**: `POST /charge` +* **Auth**: Required +**Request Body:** ```json { + "transaction_details": { "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" + "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" } + ] } -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) +**Response (Success - 201/200):** -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; +```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" } -?> ``` --- -## ⚙️ Konfigurasi Server (Info Admin) +### 2. Check Transaction Status -Informasi ini untuk Administrator Server Gateway. +Mengecek status pembayaran terkini langsung ke Midtrans dan mengupdate database lokal jika ada perubahan. -**1. File Konfigurasi (`.env`)** -Lokasi: `/opt/midtrans_flask/.env` -Pastikan data berikut benar: +* **Endpoint**: `GET /status/{order_id}` +* **Auth**: Required -```ini -# Security App -SECRET_KEY=rahasia_negara_api_2025 +**Request:** +`GET https://midtrans.pasang.cloud/api/v1/status/INV-2025-001` -# Midtrans Credentials (Dapat dari Dashboard Midtrans) -MIDTRANS_SERVER_KEY=Mid-server-YXLR8xjEkrISCXtlDvS7FDFX -MIDTRANS_CLIENT_KEY=Mid-client-j8BudqVadevtaNbQ -MIDTRANS_MERCHANT_ID=G996317131 +**Response (Success - 200):** -# Mode Environment -# Ubah ke 'false' jika masih testing (Sandbox) -# Ubah ke 'true' jika sudah live (Production) - Uang Asli! -MIDTRANS_IS_PRODUCTION=true +```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" +} ``` -**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 - -``` +*Note: `transaction_status` bisa berupa: `pending`, `settlement` (sukses), `expire`, `deny`, atau `cancel`.* --- -## ⚠️ Troubleshooting Common Errors +### 3. Handle Webhook (Callback) -| Status Code | Pesan Error | Penyebab & Solusi | +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 | | --- | --- | --- | -| `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 +| **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* \ No newline at end of file