ASone API v1

Integrasikan pembayaran QRIS dan Virtual Account.

Panduan ini menjelaskan alur dasar untuk membuat transaksi, memeriksa status, menerima webhook, dan mengamankan komunikasi antara sistem merchant dengan ASone.

Catatan lingkungan

API v1 berjalan pada host aplikasi ini. Secret key sandbox menghasilkan instrumen simulasi. Secret key production hanya dapat memproses uang nyata setelah adapter provider resmi dikonfigurasi dan merchant diaktifkan untuk production.

Quick start

Alur minimal untuk membuat pembayaran pertama.

Ambil API key

Buka menu API Keys pada dashboard merchant dan gunakan secret key sandbox.

Kirim request

Buat transaksi QRIS atau Virtual Account dengan reference ID unik.

Simpan invoice

Simpan invoice_no dari response untuk rekonsiliasi internal.

Terima webhook

Verifikasi signature lalu perbarui status order pada sistem merchant.

Environment dan base URL

Gunakan sandbox selama proses development dan pengujian.

Sandboxhttps://funnytesting.biz.id/v1Pengujian integrasi

Productionhttps://funnytesting.biz.id/v1Transaksi nyata

Semua request dan response menggunakan format application/json, encoding UTF-8, dan koneksi HTTPS.

Autentikasi

Kirim secret key pada header Authorization di setiap request.

Authorization: Bearer asone_sandbox_sk_xxxxxxxxx
Content-Type: application/json
Accept: application/json
X-Idempotency-Key: order-10001

Jangan tampilkan secret key di frontend

Simpan secret key hanya di server. Jangan menaruhnya di JavaScript, aplikasi mobile, repository publik, atau screenshot.

Idempotency

Cegah transaksi ganda ketika request mengalami timeout atau dikirim ulang.

Kirim nilai unik melalui header X-Idempotency-Key. Gunakan nilai yang sama hanya untuk pengulangan request transaksi yang sama.

Disarankanpayment-order-10001

Tidak disarankan12345

Buat transaksi QRIS

Menghasilkan QRIS dinamis sesuai nominal pembayaran.

POST/payments/qris

Request body

Parameter	Tipe	Wajib	Keterangan
`reference_id`	string	Ya	Referensi unik dari sistem merchant.
`amount`	integer	Ya	Nominal dalam Rupiah tanpa pemisah.
`customer`	object	Tidak	Nama dan email pelanggan.
`expired_in`	integer	Tidak	Masa berlaku dalam detik.

{
  "reference_id": "ORDER-10001",
  "amount": 150000,
  "customer": {
    "name": "Budi Santoso",
    "email": "budi@example.com"
  },
  "expired_in": 900
}

Response sukses

{
  "success": true,
  "data": {
    "invoice_no": "INV-20260726-001",
    "reference_id": "ORDER-10001",
    "status": "pending",
    "amount": 150000,
    "qr_string": "000201010212...",
    "qr_image_url": null,
    "expires_at": "2026-07-26T07:30:00+07:00"
  }
}

Buat Virtual Account

Menghasilkan nomor Virtual Account untuk pembayaran pelanggan.

POST/payments/virtual-accounts

{
  "reference_id": "ORDER-10002",
  "bank_code": "BCA",
  "amount": 250000,
  "customer_name": "Budi Santoso",
  "expired_in": 86400
}

{
  "success": true,
  "data": {
    "invoice_no": "INV-20260726-002",
    "status": "pending",
    "bank_code": "BCA",
    "va_number": "1234567890123456",
    "amount": 250000,
    "expires_at": "2026-07-27T07:00:00+07:00"
  }
}

Cek status transaksi

Gunakan pengecekan API sebagai fallback apabila webhook terlambat.

GET/payments/{invoice_no}

curl --request GET \
  --url https://funnytesting.biz.id/v1/payments/INV-20260726-001 \
  --header 'Authorization: Bearer asone_sandbox_sk_xxxxxxxxx' \
  --header 'Accept: application/json'

Webhook

ASone mengirim event pembayaran dan operasional yang dipilih merchant. Event ID tetap sama saat delivery di-retry.

Contoh payload

{
  "event": "payment.paid",
  "event_id": "evt_01J2ASONE001",
  "created_at": "2026-07-26T07:05:12+07:00",
  "resource_type": "transaction",
  "data": {
    "invoice_no": "INV-20260726-001",
    "reference_id": "ORDER-10001",
    "status": "paid",
    "amount": 150000,
    "paid_at": "2026-07-26T07:05:10+07:00"
  }
}

Event yang tersedia meliputi payment.paid, payment.failed, payment.expired, settlement.completed, payout.success, payout.failed, dan refund.completed.

Respons endpoint merchant

Balas dengan HTTP 200 secepat mungkin setelah payload diterima dan divalidasi. Proses berat sebaiknya dijalankan melalui queue internal merchant.

Validasi signature webhook

Hitung HMAC SHA-256 dari raw request body menggunakan webhook secret.

<?php
$rawBody = file_get_contents('php://input');
$receivedSignature = isset($_SERVER['HTTP_X_ASONE_SIGNATURE'])
    ? $_SERVER['HTTP_X_ASONE_SIGNATURE']
    : '';
$expectedSignature = hash_hmac('sha256', $rawBody, $webhookSecret);

if (!$receivedSignature || !hash_equals($expectedSignature, $receivedSignature)) {
    http_response_code(401);
    exit('Invalid signature');
}

$payload = json_decode($rawBody, true);
http_response_code(200);

Praktik yang disarankan

Validasi signature, simpan event_id untuk mencegah proses ganda, cocokkan nominal dan reference ID, serta jangan hanya mempercayai status dari browser pelanggan.

Status transaksi

Gunakan nilai berikut untuk memetakan status pembayaran.

pending

Menunggu pembayaran pelanggan.

paid

Pembayaran telah diterima.

expired

Masa berlaku transaksi berakhir.

failed

Transaksi gagal diproses.

refunded

Dana telah dikembalikan.

Error codes

Semua error menggunakan format JSON yang konsisten.

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Field amount wajib berupa integer positif.",
    "request_id": "req_01J2ASONE999"
  }
}

HTTP	Kode	Keterangan	Tindakan
400	`INVALID_REQUEST`	Payload atau parameter tidak valid.	Periksa field pada pesan error.
401	`UNAUTHORIZED`	API key salah, tidak aktif, atau environment tidak sesuai.	Periksa Authorization header.
404	`NOT_FOUND`	Invoice atau resource tidak ditemukan.	Periksa invoice number.
409	`DUPLICATE_REFERENCE`	Reference ID sudah digunakan.	Gunakan referensi unik atau ambil transaksi lama.
422	`PAYMENT_CHANNEL_ERROR`	Kanal pembayaran tidak dapat memproses transaksi.	Coba kanal lain atau hubungi support.
429	`RATE_LIMITED`	Terlalu banyak request.	Terapkan exponential backoff.
500	`INTERNAL_ERROR`	Kesalahan internal.	Simpan request ID dan hubungi support.

Checklist sebelum production

Pastikan seluruh alur berikut sudah berhasil diuji.

Langkah berikutnya

Siapkan akun merchant dan mulai pengujian.

Daftar Merchant Buka Dashboard