AA Digital Payment Docs

Central Payment Gateway

Dokumentasi ringkas untuk QRIS dinamis, payment notification dari APK AA Payment Gateway, matching invoice, callback ke project, dan service payment lama yang masih terkait.

Project buat invoice -> Central Gateway bikin QRIS -> AA Payment Gateway APK kirim notif DANA -> Gateway match amount -> Callback order paid
Production

Base URL

https://gateway.aadigitalz.my.id

Central gateway sekarang berjalan di root subdomain. Router legacy tersedia di https://router.aadigitalz.my.id.

Secrets redacted

Auth

Semua token di docs ini memakai placeholder. Secret asli hanya ada di .env service.

Migration

Status Migrasi

Kopken, Mekdi, TMR, dan fee antrean Fore sudah membuat invoice ke central gateway dan menerima callback signed. QRIS order merchant Fore tetap berasal dari API Fore resmi. Router lama masih aktif untuk compatibility/mirror.

Service Map

Service Path VPS Port Peran Status desain
central-payment-gateway /root/central-payment-gateway 127.0.0.1:3040 Otak payment baru: create invoice, QRIS, match payment, callback, audit log. utama
payment-router /root/payment-router 127.0.0.1:3020 Router lama untuk forward notifikasi DANA ke service lama dan mirror ke gateway. legacy/mirror
kopken-payment /root/kopken-payment 127.0.0.1:3017 Payment/order handler Kopken Dor/Jasdor. Checkout membuat invoice central, status menampilkan QRIS central, callback paid ditandatangani gateway. gateway
kopken-dor-api /root/kopken-dor-server 127.0.0.1:3030 Web/API Kopken Dor/Jasdor: menu, checkout, status, Telegram bot command. app backend
mekdi-payment /root/mekdi-payment 127.0.0.1:3031 Project pilot yang membuat invoice ke central gateway dan menerima callback paid. pilot gateway
tmr-license /opt/tmr-license 127.0.0.1:3175 Service TMR license/account. Membuat invoice ke central gateway dan menerima callback signed. pilot gateway
fore-web-tool /opt/fore-web-tool 127.0.0.1:3180 Service Fore. Fee antrean sudah gateway-ready dan menerima callback signed; QRIS order Fore tetap dari API Fore resmi. fee gateway

Central Gateway Endpoints

Public APK

POST /payment-notify

Dipakai APK AA Payment Gateway untuk mengirim notifikasi DANA resmi ke server.

Header auth:

Authorization: Bearer <PAYMENT_NOTIFY_TOKEN>
X-Gateway-Token: <PAYMENT_NOTIFY_TOKEN>
X-Payment-Token: <PAYMENT_NOTIFY_TOKEN>

Payload minimal:

{
  "amount": 5036,
  "title": "Pembayaran Masuk",
  "body": "Rp5.036 dari DANA berhasil diterima",
  "raw_text": "Pembayaran Masuk Rp5.036 dari DANA berhasil diterima",
  "source_package": "id.dana",
  "received_at": 1780000000000
}
Health

GET /health

Cek service gateway tanpa membuka secret.

curl https://gateway.aadigitalz.my.id/health

Response contoh:

{
  "ok": true,
  "service": "central-payment-gateway",
  "pending": 0,
  "qris_configured": true,
  "telegram_configured": true,
  "telegram_polling": true
}
Internal

POST /internal/invoices

Dipakai project seperti Kopken, Mekdi, dan TMR untuk membuat invoice QRIS dinamis. Endpoint ini wajib pakai internal auth.

Header auth, pilih salah satu mode:

x-gateway-secret: <INTERNAL_API_SECRET>
x-app-id: <APP_ID>
x-app-secret: <APP_SECRET>

Request:

{
  "app": "mekdi",
  "merchant_order_id": "MEKDI-1780000000000-ABC123",
  "idempotency_key": "MEKDI-1780000000000-ABC123",
  "base_amount": 5000,
  "callback_url": "http://127.0.0.1:3031/internal/payment-paid",
  "expires_in_seconds": 900,
  "metadata": {
    "customer": "masked",
    "notes": "optional"
  }
}

Response penting:

{
  "ok": true,
  "invoice": {
    "id": "PAY-1780000000000-A1B2C3",
    "app": "mekdi",
    "merchant_order_id": "MEKDI-1780000000000-ABC123",
    "base_amount": 5000,
    "unique_code": 36,
    "payable_amount": 5036,
    "status": "pending",
    "expires_at": "2026-07-13T05:00:00.000Z",
    "qris_image": "data:image/png;base64,..."
  }
}
Internal

GET /internal/invoices/:id

Cek invoice berdasarkan invoice id. Perlu internal auth.

curl -H "x-gateway-secret: <INTERNAL_API_SECRET>" \
  https://gateway.aadigitalz.my.id/internal/invoices/PAY-...
Internal

POST /internal/invoices/:id/cancel

Cancel invoice pending, misalnya order dibatalkan atau smoke test selesai.

curl -X POST \
  -H "content-type: application/json" \
  -H "x-gateway-secret: <INTERNAL_API_SECRET>" \
  --data '{"reason":"customer_cancel"}' \
  https://gateway.aadigitalz.my.id/internal/invoices/PAY-.../cancel
Manual

GET /internal/manual/pending

Lihat invoice pending untuk debugging delay payment.

curl -H "x-gateway-secret: <INTERNAL_API_SECRET>" \
  https://gateway.aadigitalz.my.id/internal/manual/pending
Manual

POST /internal/manual/process

Proses amount manual jika DANA sudah masuk tapi event listener delay.

curl -X POST \
  -H "content-type: application/json" \
  -H "x-gateway-secret: <INTERNAL_API_SECRET>" \
  --data '{"amount":5036}' \
  https://gateway.aadigitalz.my.id/internal/manual/process

Callback Ke Project

Setelah invoice cocok dengan notifikasi DANA, gateway mengirim callback ke callback_url milik project.

Header callback:

x-gateway-timestamp: <unix_ms>
x-gateway-signature: sha256=<hmac_sha256>
x-gateway-invoice-id: PAY-...

Rumus signature:

sha256 = HMAC_SHA256(callback_secret, timestamp + "." + raw_json_body)

Project wajib verifikasi signature, cek invoice/order id, cek amount, lalu baru ubah order menjadi paid.

Payload callback contoh:

{
  "event": "invoice.paid",
  "invoice_id": "PAY-1780000000000-A1B2C3",
  "app": "mekdi",
  "merchant_order_id": "MEKDI-1780000000000-ABC123",
  "base_amount": 5000,
  "unique_code": 36,
  "payable_amount": 5036,
  "paid_at": "2026-07-13T05:00:00.000Z",
  "metadata": {}
}

Legacy Router

Legacy

POST /payment-notify

Endpoint lama yang forward payload DANA ke target internal lama seperti Kopken dan Mekdi lama. Saat ini juga mirror ke central gateway.

curl -X POST \
  -H "content-type: application/json" \
  -H "Authorization: Bearer <ROUTER_AUTH_TOKEN>" \
  --data '{"amount":5036,"title":"Pembayaran Masuk"}' \
  https://router.aadigitalz.my.id/payment-notify
Disabled

POST /payment-notify

Direct root payment notify sengaja ditutup dari publik.

https://pay.thisisntmy.shop/payment-notify
HTTP 404

Telegram Gateway Commands

Command Fungsi
/gwhelpMenampilkan command gateway.
/gwstatusCek status central payment gateway.
/gwcekdelayLihat invoice pending yang menunggu payment.
/gwproses <amount>Proses amount manual ke matching engine gateway.
/gwinvoice <invoice/order>Cek invoice berdasarkan invoice id atau order id.
/gwretrycb <invoice>Retry callback invoice yang sudah paid/callback failed.

Catatan Operasional

Jangan taruh secret asli di docs publik. Simpan token di .env service atau local.properties APK. Kalau token pernah bocor, rotate PAYMENT_NOTIFY_TOKEN dan rebuild APK.

Untuk migrasi project baru: project harus membuat invoice ke central gateway, menampilkan QRIS dari response, lalu menerima callback signed. Jangan lagi match paid langsung dari input user.