Dokumentasi API & Integrasi

1. Alur & Arsitektur Pembayaran

PAYMITRA menggunakan standar QRIS Dinamis (National Standard QR Code) yang dapat dibayar menggunakan seluruh aplikasi perbankan (BCA, Mandiri, BRI, BNI, CIMB, dll) dan dompet digital (Dana, GoPay, OVO, ShopeePay, LinkAja).

Generate Tagihan

Aplikasi Anda memanggil endpoint /api/v1/createqris dengan order_id dan amount.

Tampilkan QR Code

Tampilkan URL gambar QRIS atau raw string QRIS di halaman checkout kasir kepada pembeli.

Pelanggan Bayar

Pelanggan memindai QR Code melalui aplikasi m-Banking atau E-Wallet pilihan mereka.

Callback Webhook

Server PAYMITRA otomatis mengirim HTTP POST notifikasi pelunasan ke URL Webhook toko Anda secara real-time.

2. Kredensial & Autentikasi

Semua request API wajib dikirim menggunakan protokol HTTPS dan menyertakan API Key pada header Authorization: Bearer <API_KEY>.

Belum memiliki API Key? Daftar akun Merchant gratis untuk mendapatkan API Key toko Anda di Dashboard.

BASE URL RESMI API

https://paymitra.id/api/v1

Wajib Disertakan pada Setiap Request

Content-Type: application/json
Authorization: Bearer MC-xxxxxxxxxxxxxxxxxxxxX-Requested-With: XMLHttpRequest

Interactive Live API Console

Uji coba endpoint transaksi API secara real-time langsung dari browser menggunakan format JSON asli.

Siap Diuji (Live Runner)

Kredensial API Key Merchant

Method

Target Endpoint Publik

                        URL:
                        https://paymitra.id/api/v1/createqris
                    

Request Payload (JSON)

Klik tombol untuk mengirim HTTP request.

Response Body Server

Status: Menunggu Eksekusi

// Respon JSON server akan muncul di sini setelah request dikirim...

4. Official PHP SDK (Paymitra.php)

Gunakan class wrapper PHP siap pakai untuk melakukan integrasi tanpa perlu menyusun cURL secara manual. File yang diunduh sudah dikonfigurasi dengan Base URL resmi server ini.

Contoh Pemanggilan SDK PHP

<?php
require_once 'Paymitra.php';

// Inisialisasi SDK dengan API Key Anda
$paymitra = new Paymitra('MC-YOUR-API-KEY');

// 1. Buat Tagihan QRIS Dinamis
$response = $paymitra->createQRIS('INV-' . time(), 50000, 'Budi Santoso', '081234567890');

if (!empty($response['status'])) {
    $qrisImageUrl = $response['data']['qris_image_url'];
    $totalAmount  = $response['data']['amount'];
    echo "QR Code: " . $qrisImageUrl;
} else {
    echo "Gagal: " . ($response['message'] ?? 'Error');
}
?>

POST /api/v1/createqris

Menghasilkan tagihan QRIS dinamis baru dengan kode unik anti-tabrakan otomatis dan URL gambar QR Code PNG yang siap ditampilkan langsung di frontend.

Parameter Request (JSON Body)

Field	Tipe	Wajib/Opsional	Keterangan
order_id	string	Wajib	ID Transaksi unik dari sistem Anda (Contoh: `INV-20261001-001`).
amount	integer	Wajib	Nominal pembayaran dalam Rupiah (Minimal Rp 1.000).
customer_name	string	Opsional	Nama lengkap pelanggan yang melakukan pemesanan.
customer_phone	string	Opsional	Nomor handphone atau WhatsApp pelanggan.

curl -X POST "https://paymitra.id/api/v1/createqris" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "order_id": "INV-20261001-001",
    "amount": 50000,
    "customer_name": "Budi Santoso",
    "customer_phone": "08123456789"
  }'

<?php
$payload = [
    'order_id'       => 'INV-20261001-001',
    'amount'         => 50000,
    'customer_name'  => 'Budi Santoso',
    'customer_phone' => '08123456789'
];

$ch = curl_init('https://paymitra.id/api/v1/createqris');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'Authorization: Bearer YOUR_API_KEY'
    ]
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($res);
?>

const response = await fetch('https://paymitra.id/api/v1/createqris', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    order_id: 'INV-20261001-001',
    amount: 50000,
    customer_name: 'Budi Santoso',
    customer_phone: '08123456789'
  })
});
const data = await response.json();
console.log(data);

import requests

url = "https://paymitra.id/api/v1/createqris"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}
payload = {
    "order_id": "INV-20261001-001",
    "amount": 50000,
    "customer_name": "Budi Santoso",
    "customer_phone": "08123456789"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Contoh Respon Berhasil (200 OK)

JSON Response Success

{
  "status": true,
  "message": "QRIS Berhasil Dibuat",
  "data": {
    "order_id": "INV-20261001-001",
    "base_amount": 50000,
    "unique_code": 124,
    "amount": 50124,
    "qris_string": "00020101021226670016ID.INTERACTIVE.WWW.011893600503000008985102150000000000000000303UMI51440014ID.LINKAJA.WWW02152026100100100005204581253033605405501245802ID5911PAYMITRA QPAY6013KOTA JAKARTA 61051011062070703A01630489AB",
    "qris_image_url": "https://paymitra.id/qris/INV-20261001-001.png",
    "expired_at": "2026-10-09 03:24:26",
    "expires_in": 3600
  }
}

POST/GET /api/v1/check-status

Memeriksa status pembayaran transaksi secara on-demand menggunakan order_id. Berguna untuk fallback pengecekan berkala jika koneksi webhook mengalami kendala.

Parameter Request

Field	Tipe	Wajib/Opsional	Keterangan
order_id	string	Wajib	ID Transaksi yang ingin diperiksa status pembayarannya.

Contoh Request cURL

curl -X POST "https://paymitra.id/api/v1/check-status" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "order_id": "INV-20261001-001"
  }'

Contoh Respon Berhasil (200 OK)

JSON Response Success

{
  "status": true,
  "message": "Detail transaksi",
  "data": {
    "order_id": "INV-20261001-001",
    "amount": 50124,
    "status": "SUCCESS",
    "paid_at": "2026-10-09 02:24:26",
    "created_at": "2026-10-09 02:19:26"
  }
}

7. Callback Webhook Otomatis HTTP POST

Ketika pembeli menyelesaikan pembayaran QRIS, server PAYMITRA secara otomatis mengirimkan panggilan HTTP POST real-time ke URL Webhook yang Anda konfigurasikan di menu Pengaturan Merchant.

Header Notifikasi Webhook

Content-Type: application/json
X-Webhook-Timestamp: 1772541600
X-Webhook-Signature: sha256=4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e1af...

Payload Notifikasi Webhook (JSON)

{
  "event": "payment.completed",
  "order_id": "INV-20261001-001",
  "amount": 50124,
  "base_amount": 50000,
  "unique_code": 124,
  "net_amount": 49773,
  "status": "COMPLETED",
  "paid_at": "2026-10-09 02:24:26"
}

Contoh Skrip Handler Webhook (PHP)

webhook.php di Server Toko Anda

<?php
// webhook.php di server toko Anda
$raw = file_get_contents('php://input');
$data = json_decode($raw, true);

if (!$data || empty($data['order_id'])) {
    http_response_code(400);
    echo json_encode(["status" => "invalid_payload"]);
    exit;
}

$orderId = $data['order_id'];
$status  = $data['status'] ?? '';

// Pastikan status adalah COMPLETED atau SUCCESS
if ($status === 'COMPLETED' || $status === 'SUCCESS') {
    // 1. Verifikasi orderId pada database Anda
    // 2. Tandai pesanan sebagai LUNAS
    // 3. Kirimkan respon 200 OK dalam format JSON agar server PAYMITRA tidak melakukan retry
    
    http_response_code(200);
    echo json_encode(["status" => "ok"]);
    exit;
}

http_response_code(400);
echo json_encode(["status" => "ignored"]);
?>

8. Status HTTP & Penanganan Error

Setiap request akan menghasilkan kode status standar HTTP untuk mengindikasikan keberhasilan atau penyebab kegagalan transaksi.

HTTP Code	Status	Penyebab & Solusi
200 OK	Success	Permintaan berhasil dieksekusi dengan benar.
400 Bad Request	Invalid Parameter	Format JSON tidak valid atau parameter wajib (seperti `order_id` atau `amount`) belum disertakan.
401 Unauthorized	Invalid API Key	Header `Authorization: Bearer <API_KEY>` tidak ada atau nilai API Key salah/tidak terdaftar.
404 Not Found	Resource Not Found	Transaksi dengan `order_id` tersebut tidak ditemukan di sistem.
422 Unprocessable	Business Logic Error	Nominal pembayaran di bawah batas minimum (Rp 1.000) atau order_id duplikat yang masih aktif.
500 Internal Error	Server Error	Kendala koneksi internal gateway. Sistem memiliki retry otomatis.

9. Rekomendasi Keamanan

Terapkan praktik keamanan berikut untuk menjaga integritas transaksi dan saldo merchant Anda:

Simpan Kredensial di Backend Server Saja

Jangan pernah menyimpan atau memanggil API Key PAYMITRA dari frontend (JavaScript client, HTML, atau aplikasi mobile client yang tidak terenkripsi). Simpan di file environment (.env) pada server backend Anda.

Terapkan Idempotensi pada Handler Webhook

Pastikan skrip webhook Anda memeriksa status pesanan di database terlebih dahulu. Jika pesanan sudah berstatus lunas, jangan lakukan penambahan saldo atau proses pengiriman barang ganda jika notifikasi yang sama terkirim ulang.

Wajib Menggunakan Protokol HTTPS

Semua endpoint API dan URL Webhook toko Anda wajib beroperasi pada protokol HTTPS dengan sertifikat SSL aktif untuk mencegah intersepsi data sensitif.

Logo ditampilkan sebagai informasi referensi institusi. Penampilan logo tidak dimaksudkan sebagai pernyataan bahwa PAYMITRA telah berizin, diawasi, terdaftar, atau berafiliasi dengan institusi tersebut.