APIMIDTRANS/API.md

# 💳 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):

{
  "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):

{
  "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):

{
  "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.
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