6.0 KiB

Raw Blame History

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:

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

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

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

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

$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;
}
?>

⚙️ Konfigurasi Server (Info Admin)

Informasi ini untuk Administrator Server Gateway.

1. File Konfigurasi (.env) Lokasi: /opt/midtrans_flask/.env Pastikan data berikut benar:

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

systemctl restart midtrans-gateway

3. Logs Untuk melihat log transaksi atau error:

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.

6.0 KiB Raw Blame History