Dokumentasi API ACAPAY

Overview

Semua endpoint merchant di /api/v1/*. Webhook pembayaran internal diproses otomatis (async). Response envelope konsisten. Approval admin wajib sebelum API aktif.

Getting Started

1. Buat akun merchant — Daftar di /register (status pending).
2. Tunggu approval admin — Admin cek data via GET /api/v1/admin/merchants lalu POST /api/v1/admin/merchants/[id]/approve. Jika ditolak → status rejected.
3. Dapatkan API Key — Setelah active, cek GET /api/v1/merchant/api-keys. Subscription 30 hari otomatis aktif (Rp 1.000/bulan).
4. Buat invoice — POST /api/v1/invoices → dapat payment_url.
5. Redirect customer ke payment_url (/pay/inv_xxx) untuk scan QRIS.
6. Terima webhook — ACAPAY POST ke callback_url || merchant.webhook_url saat paid.
7. Verifikasi status — GET /api/v1/invoices/[id] atau GET /api/v1/transactions/[id].
8. Kelola payout & subscription — GET /api/v1/subscription & POST /api/v1/subscription/renew (potong saldo Rp 1.000).

Authentication

curl -X POST https://pay.xiamostore.xyz/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{ "name":"Budi Santoso","email":"budi@toko.com","password":"password123","business_name":"Toko Budi","whatsapp":"6281234567890","store_url":"tokobudi.com","purpose":"Jualan QRIS"}'

curl -X POST https://pay.xiamostore.xyz/api/v1/auth/login -c cookies.txt -H "Content-Type: application/json" -d '{"email":"budi@toko.com","password":"password123"}'

curl https://pay.xiamostore.xyz/api/v1/auth/me -b cookies.txt
# atau
curl https://pay.xiamostore.xyz/api/v1/auth/me -H "Authorization: Bearer acp_sec_xxx"

API Keys

Pasangan kunci: acp_sec_* (secret, hashed) & acp_pub_* (public). Subscription Rp 1.000/30 hari aktif setelah approve.

curl https://pay.xiamostore.xyz/api/v1/subscription -b cookies.txt
curl -X POST https://pay.xiamostore.xyz/api/v1/subscription/renew -b cookies.txt

Projects (1 merchant = max 5 proyek)

1 merchant harus buat proyek dulu untuk dapat API key proyek (prj_sec_xxx / prj_pub_xxx). Semua transaksi masuk ke proyek sesuai apikey-nya. Fee bisa diatur per proyek. Notif ke Nofbox diabaikan (selalu Ya).

curl https://pay.xiamostore.xyz/api/v1/projects -b cookies.txt
curl -X POST https://pay.xiamostore.xyz/api/v1/projects -b cookies.txt -H "Content-Type: application/json" -d '{"name":"acamedia"}'
# → {"public_key":"prj_pub_xxx","secret_key":"prj_sec_xxx"}
curl -X PATCH https://pay.xiamostore.xyz/api/v1/projects/prj_xxx -b cookies.txt -d '{"fee_by_merchant":false}'

Create Invoice

curl -X POST https://pay.xiamostore.xyz/api/v1/invoices \
  -H "Authorization: Bearer acp_sec_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150000,
    "description": "Langganan Pro",
    "customer": {"name":"Budi","email":"budi@acme.id"},
    "callback_url": "https://acme.id/webhook/acapay",
    "fee_bearer": "merchant"
  }'

{
  "success": true,
  "data": {
    "invoice_id": "acp_inv_abc123",
    "transaction_id": "acp_tx_abc123",
    "amount": 150000,
    "fee": 1050,
    "fee_bearer": "merchant",
    "total": 150000,
    "net_amount": 148950,
    "payment_url": "/pay/acp_inv_abc123",
    "expired_at": "2026-01-15T11:30:00Z"
  }
}

Get Invoice

curl https://pay.xiamostore.xyz/api/v1/invoices/acp_inv_abc123
curl https://pay.xiamostore.xyz/api/v1/invoices -b cookies.txt

QRIS Dinamis (Bearer Merchant)

QRIS dinamis butuh Bearer token merchant agar terikat ke merchant Anda — payhook masuk + matching → saldo masuk ke merchant tersebut. QRIS_STATIC_CODE + amount → image_data_url base64. Dipakai di /pay/[invoiceId] (fetch /api/v1/qris?amount=total). Support GoPay • OVO • DANA • ShopeePay • LinkAja • m-Banking.

curl "https://pay.xiamostore.xyz/api/v1/qris?amount=250000" \
  -H "Authorization: Bearer acp_sec_xxx"
# → {"success":true,"data":{"image_data_url":"data:image/png;base64,iVBOR...","amount":250000,"merchant_id":"mch_xxx"}}

# 1. Buat invoice dengan custom ID
curl -X POST https://pay.xiamostore.xyz/api/v1/invoices \
  -H "Authorization: Bearer acp_sec_xxx" \
  -d '{"amount":50000,"description":"Order #123","customer":{"name":"Andi","email":"a@x.id"},"external_id":"ORDER-123"}'
# → {"invoice_id":"acp_inv_xxx","transaction_id":"acp_tx_xxx"}
# 2. Generate QRIS (Bearer agar terikat merchant)
curl "https://pay.xiamostore.xyz/api/v1/qris?amount=50000" -H "Authorization: Bearer acp_sec_xxx"

# Polling status (pakai invoice_id atau external_id)
curl https://pay.xiamostore.xyz/api/v1/invoices/ORDER-123 \
  -H "Authorization: Bearer acp_sec_xxx"
# atau original id
curl https://pay.xiamostore.xyz/api/v1/invoices/acp_inv_xxx

# Response
{"success":true,"data":{"invoice":{"id":"acp_inv_xxx","status":"paid","amount":50000},"transaction":{"status":"paid","external_reference":"ORDER-123"}}}

Transactions

curl https://pay.xiamostore.xyz/api/v1/transactions -b cookies.txt

Payment Status

Cek via GET /api/v1/invoices/[id] atau GET /api/v1/transactions/[id]. Webhook pembayaran akan update otomatis → ledger credit.

{
  "success": true,
  "data": { "invoice": {"id":"acp_inv_xxx","status":"paid","amount":150000,"fee":1050}, "transaction":{"id":"acp_tx_xxx","status":"paid"} }
}

Webhooks

Webhook Pembayaran (Incoming)

GET /api/webhooks/* → 200 health

POST /api/webhooks/* (internal)
Headers: X-Signature, X-Timestamp, X-Nonce: sha256=HMAC(SECRET, timestamp.rawBody)

{ "event_id":"evt_abc123","event_type":"payment.incoming","amount":150000,"source":"BCA","reference":"ACAPAY-7823","timestamp":"2026-01-15T10:30:00Z" }

Merchant Callback

Saat paid, Acapay POST ke merchant dengan header X-Acapay-Signature & X-Acapay-Timestamp.

POST https://toko.com/webhook/acapay
X-Acapay-Signature: sha256=<hex>
X-Acapay-Timestamp: 1705300000
{ "event":"payment.paid","invoice_id":"acp_inv_xxx","transaction_id":"acp_tx_xxx","amount":150000,"reference":"ACAPAY-7823" }

import crypto from "crypto";
function verify(req, secret){
  const sig=req.headers["x-acapay-signature"]; const ts=req.headers["x-acapay-timestamp"];
  const expected="sha256="+crypto.createHmac("sha256",secret).update(ts+"."+JSON.stringify(req.body)).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

Payout — MANUAL 1×24 jam

curl -X POST https://pay.xiamostore.xyz/api/v1/payouts -b cookies.txt -H "Content-Type: application/json" -d '{"amount":500000,"bank_name":"BCA","account_number":"1234567890","account_name":"Budi"}'

Error Codes

Idempotency

Gunakan X-Request-ID (invoice/payout) dan event_id (webhook internal). Duplicate diproses 1x, TTL 24 jam.

• event_id webhook unik → duplicate return 200 tanpa ledger ulang (nonce TTL 10m, drift 5m)
• Retry aman: kirim ulang request sama → hasil identik

Security

• HTTPS — wajib di production
• Jangan expose secret — env vars, jangan commit
• Signature verification — HMAC-SHA256 timestamp.rawBody
• Replay protection — nonce 10m, timestamp 5m
• Webhook verification — X-Acapay-Signature
• API key security — rotate via POST /merchant/api-keys

API Reference

OpenAPI JSON di /openapi.json. Semua endpoint akurat, tidak ada yang dikarang.

Changelog