Dokumentasi API Aulaa

Aulaa menggunakan Bearer Token. Sertakan API Key project Anda di header Authorization pada setiap request. Format key: pgw_id_a1b2c3….

Authorization: Bearer pgw_id_xxxxxxxxxxxxxxxx

Saat project dalam mode Sandbox, transaksi tidak diteruskan ke payment provider asli. Aulaa membuat kode pembayaran dummy yang bisa Anda "bayar" sendiri lewat halaman simulasi — cocok untuk menguji alur integrasi dan webhook sebelum Go Live. Transaksi sandbox tidak masuk ke saldo/pendapatan dan ditampilkan terpisah di dashboard.

1. 1Pastikan switch project pada posisi Sandbox, lalu buat transaksi seperti biasa (Via Halaman atau Via API).
2. 2Anda menerima kode pembayaran dummy pada field payment_number (mis. SBX1A2B3C4D). Untuk QRIS, kode inilah yang di-render menjadi QR.
3. 3Buka halaman simulasi, masukkan kode tersebut (atau scan QR untuk QRIS).
4. 4Klik Bayar (Sukses) atau Simulasikan Gagal. Status invoice berubah dan Webhook dikirim ke project Anda — persis seperti produksi.

Mengembalikan metode pembayaran yang tersedia dan aktif untuk project Anda saat ini. Negara dideteksi otomatis dari API Key Anda — tidak perlu parameter tambahan. Metode yang sedang maintenance otomatis disaring dari respons. Gunakan field code sebagai nilai payment_method saat membuat transaksi.

Daftarnya berbeda per project: setiap project punya pengaturan sendiri tentang metode apa saja yang diterima, diatur di halaman detail project. Metode yang dimatikan di sana tidak muncul di sini, dan ditolak bila tetap dikirim sebagai payment_method saat membuat transaksi. Jadi panggil endpoint ini dengan API Key project yang bersangkutan — jangan menyalin daftarnya antar project.

Setiap metode menyertakan batas nominal transaksi: min_amount dan max_amount (dalam Rupiah). Nilai 0 berarti tidak ada batas khusus. Gunakan data ini untuk memvalidasi nominal di sisi frontend Anda sebelum memanggil Buat Pembayaran.

Contoh Request

curl https://api.aulaa.co/v1/payments/methods \
  -H "Authorization: Bearer pgw_id_xxxxxxxxxxxxxxxx"

Response (200 OK)

{
  "country": "ID",
  "currency": "IDR",
  "methods": [
    { "code": "credit_card", "name": "Credit/Debit Card", "type": "card",       "is_available": true, "min_amount": 10000, "max_amount": 10000000 },
    { "code": "qris",   "name": "QRIS",                "type": "qr_code",         "is_available": true, "min_amount": 1,     "max_amount": 10000000 },
    { "code": "bca_va", "name": "BCA Virtual Account", "type": "virtual_account", "is_available": true, "min_amount": 10000, "max_amount": 100000000 },
    { "code": "bri_va", "name": "BRI Virtual Account", "type": "virtual_account", "is_available": true, "min_amount": 10000, "max_amount": 100000000 },
    { "code": "dana",   "name": "DANA",               "type": "ewallet",         "is_available": true, "min_amount": 1000,  "max_amount": 10000000 },
    { "code": "ovo",    "name": "OVO",                "type": "ewallet",         "is_available": true, "min_amount": 1000,  "max_amount": 10000000 }
    // ...
  ]
} 

Kode Metode (Indonesia)

Membuat transaksi pembayaran baru di Aulaa. order_id bersifat unik per project: mengirim ulang order_id yang sama akan ditolak dengan 409 Conflict — bukan membuat transaksi kedua, sehingga pelanggan tidak mungkin tertagih dua kali.

Request Body

2 Cara Menyajikan Pembayaran ke Pelanggan

Setelah memanggil POST /v1/payments, Anda dapat memilih salah satu cara penyajian berikut:

https://payment.aulaa.co/pay/{ID}

// 1. Buat pembayaran dari backend Anda
const res = await fetch('https://api.aulaa.co/v1/payments', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer pgw_id_xxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    order_id: 'INV-20260627-001',
    amount: 50000,
    payment_method: 'qris',
    redirect_url: 'https://toko-anda.com/checkout/sukses',
  }),
});
const payment = await res.json();

// 2. Arahkan pelanggan ke halaman pembayaran Aulaa
const url = `https://payment.aulaa.co/pay/${payment.id}`;
window.location.href = url; // atau kirim 'url' ini ke pelanggan

// Library QR — pilih sesuai stack Anda:
//   React  : npm i qrcode.react        Node : npm i qrcode
//   Python : pip install qrcode        PHP  : composer require endroid/qr-code
//   Go     : go get github.com/skip2/go-qrcode

// --- Contoh React (qrcode.react) ---
import { QRCodeCanvas } from 'qrcode.react'

// payment.payment_number = string QRIS dari response POST /v1/payments
<QRCodeCanvas value={payment.payment_number} size={256} />

// --- Contoh Node.js (qrcode) → data URL untuk <img src=...> ---
import QRCode from 'qrcode'
const qrImg = await QRCode.toDataURL(payment.payment_number)
// <img src={qrImg} alt="QRIS" />

// Untuk Virtual Account, payment_number cukup ditampilkan apa adanya
// sebagai teks + tombol "Salin" (tidak perlu library QR).

Contoh Request (Semua Bahasa)

curl -X POST https://api.aulaa.co/v1/payments \
  -H "Authorization: Bearer pgw_id_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "INV-20260627-001",
    "amount": 50000,
    "payment_method": "qris"
  }'

Response (201 Created)

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "order_id": "INV-20260627-001",
  "status": "pending",
  "amount": 50000,
  "fee_amount": 350,
  "charged_amount": 50000,
  "currency": "IDR",
  "country_code": "ID",
  "payment_method": "qris",
  "payment_number": "00020101021226670016COM.NOBUBANK...",
  "redirect_url": "https://toko-anda.com/checkout/sukses",
  "is_test": false,
  "expired_at": "2026-06-27T08:00:00Z",
  "paid_at": null,
  "created_at": "2026-06-27T07:00:00Z"
}

Respons 409 — order_id sudah pernah dipakai

{
  "error": "Pesanan dengan order_id INV-20260627-001 sudah pernah dibuat",
  "payment_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

payment_id berisi id transaksi yang sudah ada. Ini jalan pulang bila panggilan pertama Anda putus sebelum responsnya sampai: kirim ulang order_id yang sama, ambil payment_id dari respons 409, lalu lanjutkan dengan Cek Status. Jangan pernah menerbitkan order_id baru untuk order yang sama.

Mengecek status pembayaran terkini berdasarkan id invoice Aulaa — yaitu field id yang Anda terima saat membuat transaksi, bukan order_id Anda sendiri. Simpan id itu bersama order Anda. Webhook tetap merupakan sumber kebenaran utama; gunakan endpoint ini untuk rekonsiliasi atau verifikasi berkala. Satu pembayaran boleh dicek paling banyak 30 kali per menit (rata-rata sekali per 2 detik); lebih dari itu dijawab 429 dengan header Retry-After.

Contoh Request

curl https://api.aulaa.co/v1/payments/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "Authorization: Bearer pgw_id_xxxxxxxxxxxxxxxx"

Response (200 OK)

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "order_id": "INV-20260627-001",
  "status": "paid",
  "amount": 50000,
  "fee_amount": 350,
  "charged_amount": 50000,
  "currency": "IDR",
  "country_code": "ID",
  "payment_method": "qris",
  "payment_number": "00020101021226670016COM.NOBUBANK...",
  "redirect_url": "https://toko-anda.com/checkout/sukses",
  "is_test": false,
  "expired_at": "2026-06-27T08:00:00Z",
  "paid_at": "2026-06-27T07:15:32Z",
  "created_at": "2026-06-27T07:00:00Z"
}

Nilai Status Transaksi

Membatalkan pembayaran yang masih berstatus pending. Pembayaran yang sudah paid, expired, atau cancelled akan menghasilkan 409 Conflict.

Contoh Request

curl -X POST \
  https://api.aulaa.co/v1/payments/f47ac10b-58cc-4372-a567-0e02b2c3d479/cancel \
  -H "Authorization: Bearer pgw_id_xxxxxxxxxxxxxxxx"

Alternatif bagi Anda yang ingin membuat link pembayaran instan tanpa memanggil REST API pembayaran dari backend server. Tautan ini ditandatangani secara offline (*cryptographic HMAC-SHA256 signature*) menggunakan Webhook Secret project Anda agar parameter nominal tidak bisa dimanipulasi oleh pembeli.

https://payment.aulaa.co/checkout/{ProjectID}/{Amount}?order_id={OrderID}&sig={Signature}&redirect_url={RedirectURL}

• ProjectID — ID project Anda (lihat di Dashboard → Projects).
• Amount — Nominal tagihan dalam angka bulat tanpa titik/koma (mis. 50000).
• order_id — Wajib. ID invoice unik di sistem Anda. Transaksi dengan order_id yang sama akan melanjutkan sesi pembayaran yang sama.
• sig — Wajib. Signature HMAC-SHA256 (hex) dari data checkout:v1:ProjectID:Amount:OrderID ditandatangani dengan Webhook Secret project Anda.
• redirect_url — Opsional. URL website Anda untuk redirect otomatis setelah pembayaran berhasil.

Contoh Pembuatan Signed URL (Node.js)

const crypto = require('crypto');

const projectID = 'b2c3d4e5-f6a7-8901-bcde-f12345678901';
const amount = 50000;
const orderID = 'INV-20260627-001';
const secret = 'YOUR_WEBHOOK_SECRET'; // Diambil dari Dashboard -> Projects
const redirectURL = encodeURIComponent('https://toko-anda.com/checkout/sukses');

// Format string: checkout:v1:{ProjectID}:{Amount}:{OrderID}
const payload = `checkout:v1:${projectID}:${amount}:${orderID}`;
const signature = crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');

const checkoutURL = `https://payment.aulaa.co/checkout/${projectID}/${amount}?order_id=${orderID}&sig=${signature}&redirect_url=${redirectURL}`;
console.log(checkoutURL);

Saat status pembayaran berubah, Aulaa mengirim HTTP POST ke callback_url project Anda — diatur sekali di Dashboard → Projects dan berlaku untuk semua transaksi project itu (tidak bisa diganti per-transaksi, demi keamanan). Payload bersifat flat (tanpa pembungkus event); bedakan jenis notifikasi dari field status — biasanya paid atau expired.

Contoh Webhook Payload

{
  "order_id": "INV-20260627-001",
  "amount": 50000,
  "currency": "IDR",
  "country_code": "ID",
  "status": "paid",
  "payment_method": "qris",
  "formatted_amount": "Rp 50.000",
  "paid_at": "2026-06-27T07:15:32Z"
}

Verifikasi Signature (Node.js)

Setiap request menyertakan header X-Webhook-Signature berisi HMAC-SHA256 (hex, tanpa prefix) dari raw body, ditandatangani dengan Webhook Secret project Anda. Selalu verifikasi sebelum memproses.

const crypto = require('crypto');
const express = require('express');
const app = express();

// PENTING: signature dihitung dari RAW body (byte mentah), jadi
// gunakan express.raw — bukan express.json — di endpoint webhook.
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'];

  const expected = crypto
    .createHmac('sha256', process.env.AULAA_WEBHOOK_SECRET)
    .update(req.body)            // req.body = Buffer (raw)
    .digest('hex');             // hex, TANPA prefix "sha256="

  const valid = signature && crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );

  if (!valid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(req.body.toString());
  if (event.status === 'paid') {
    // Verifikasi order_id & amount sesuai data Anda, lalu update order
    console.log('Pembayaran lunas:', event.order_id);
  }

  res.status(200).json({ received: true });
});

Aulaa menggunakan HTTP status code standar. Body error berformat sederhana — satu field error berisi pesan:

{
  "error": "amount must be between 1000 and 500000000 IDR"
}