Update API.md
This commit is contained in:
parent
e1ea1ae795
commit
7245497b5b
340
API.md
340
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/<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"
|
||||
"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
|
||||
<?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;
|
||||
```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. |
|
||||
| **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*
|
||||
Loading…
Reference in New Issue