162 lines
4.3 KiB
Markdown
162 lines
4.3 KiB
Markdown
|
|
```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* |