Indonesian channels are deferred payments: checkout creates an order and returns provider instructions while the order remains pending_payment. A verified provider callback—or an authorized kode-unik operator—settles the payment later.
Pick a provider by channel and operation
| Provider | Supported checkout channels | Settlement signal | Refund boundary |
|---|---|---|---|
| Midtrans Core API v2 | QRIS, BCA/BNI/BRI VA, Mandiri bill-key, Permata VA, GoPay, Indomaret, Alfamart | SHA-512 notification plus a fresh transaction-status query | Automatic for QRIS and GoPay; other channels require a recorded manual transfer |
Xendit Payment Requests 2024-11-11 |
QRIS, BCA/BNI/BRI/Mandiri VA, OVO, DANA-compatible redirects | Constant-time x-callback-token verification |
Automatic for QRIS, OVO, and DANA; virtual accounts require a recorded manual transfer |
| Kode unik | IDR bank transfer with a visible 001–999 adjustment |
Authorized operator confirmation | Manual bank transfer with an operator-recorded reference |
Expose each channel as a separate payment method. This keeps eligibility, labels, instructions, and operational reporting explicit.
Configure Midtrans
pnpm add @adocommercekit/midtrans
node ace configure @adocommercekit/midtransSet MIDTRANS_SERVER_KEY, MIDTRANS_CLIENT_KEY, and MIDTRANS_ENVIRONMENT, then register each channel:
import { midtrans } from "@adocommercekit/midtrans"
payments: {
default: "midtrans_qris",
methods: {
midtrans_qris: midtrans({
serverKey: env.get("MIDTRANS_SERVER_KEY"),
clientKey: env.get("MIDTRANS_CLIENT_KEY"),
environment: env.get("MIDTRANS_ENVIRONMENT"),
channel: "qris",
}),
midtrans_bca_va: midtrans({
serverKey: env.get("MIDTRANS_SERVER_KEY"),
clientKey: env.get("MIDTRANS_CLIENT_KEY"),
environment: env.get("MIDTRANS_ENVIRONMENT"),
channel: "bca_va",
}),
},
}The configure hook recommends <APP_URL>/commerce/webhooks/midtrans but does not publish a controller or route. Mount that host-owned raw-body endpoint through core’s payment webhook ingestion. Do not reproduce the signature check in a controller: the driver verifies the notification and re-queries Midtrans before producing a normalized event.
Configure Xendit
pnpm add @adocommercekit/xendit
node ace configure @adocommercekit/xenditSet XENDIT_SECRET_KEY and XENDIT_WEBHOOK_TOKEN:
import { xendit } from "@adocommercekit/xendit"
payments: {
default: "xendit_qris",
methods: {
xendit_qris: xendit({
secretKey: env.get("XENDIT_SECRET_KEY"),
webhookToken: env.get("XENDIT_WEBHOOK_TOKEN"),
channel: "QRIS",
}),
},
}The configure hook recommends <APP_URL>/commerce/webhooks/xendit but does not publish a controller or route. Mount that host-owned raw-body endpoint through core’s payment webhook ingestion. Xendit uses Basic secret-key API authentication and the callback token; Midtrans signature rules do not apply. Channel codes are QRIS, BCA_VIRTUAL_ACCOUNT, BNI_VIRTUAL_ACCOUNT, BRI_VIRTUAL_ACCOUNT, MANDIRI_VIRTUAL_ACCOUNT, OVO, and DANA.
Refund state and correlation
Both drivers return state: "pending" | "succeeded" | "failed" from refund(). An accepted request may still be pending; do not mark the refund complete or initiate a replacement merely because the provider has not completed it yet.
- Xendit: callbacks identified by
refund.*events or adata.idbeginning withrfd-carryproviderRefundIdfromdata.id,idempotencyKeyfromdata.reference_id, andproviderChargeIdfrom the available payment request/payment ID.retrieveRefund({ providerRefundId })queriesGET /refunds/{id}and returns provider state and an optional IDR amount. Missing IDs or missing refunds returnnull; the driver does not infer a refund from a merchant reference. - Midtrans: confirmed
refund/partial_refundstatus means success; acceptance without confirmation remains pending and provider error status codes mean failed. Documented refund notifications providerefund_keyinrefunds[]. The normalizedrefund.succeededevent uses that key as bothproviderRefundIdandidempotencyKey, and the transaction ID asproviderChargeId. The driver selects the notified key from re-fetched status, not an unrelated newer refund; missing correlation is unhandled. The documented schema does not specify distinct pending/failed refund notifications, so the driver does not invent them. - Midtrans retrieval:
retrieveRefund({ providerChargeId, idempotencyKey?, providerRefundId? })queries transaction status and selects the exact refund key (idempotencyKeytakes precedence). Missing charge/key, absent refund, or unconfirmed status returnsnull. An aggregate refunded amount is never substituted for one individual refund when multiple refunds exist.
Persist refund keys and provider identities with the operator case. Retrieval is an optional provider reconciliation capability, not a guarantee that every provider can discover a refund without its identity.
Configure kode unik
Kode unik adds a small positive adjustment so incoming bank transfers can be distinguished on one receiving account.
import { kodeUnik } from "@adocommercekit/id"
payments: {
methods: {
kode_unik: kodeUnik({
receivingAccount: {
id: "bca-main",
bankName: "BCA",
accountNumber: env.get("COMMERCE_ID_BANK_ACCOUNT_NUMBER"),
accountName: "PT Example",
},
expiresAfterMinutes: 60,
}),
},
}The driver requires IDR, allocates one active code per receiving account, adds that code to the amount due, and returns bank-transfer instructions. Settlement is never inferred from browser input. An operator must pass host authorization to KodeUnikAdminService.confirm() and record the bank statement reference. Rejection and manual refunds also require auditable operator actions.
Match bank statements
Call KodeUnikAdminService.matchBankStatement(contents, { actor, actorId }) from a trusted operator workflow. CSV imports accept a leading UTF-8 BOM; the exact header is:
receiving_account,amount_amount,currency,referenceRows match unexpired active leases by receiving-account ID, exact integer amount (including kode unik), and IDR currency. The reference records the bank-statement evidence, not a browser claim. Each result reports settled, review, unmatched, ambiguous, or invalid; ambiguous rows must not be auto-assigned. Matching still calls the authorized confirmation path. A confirmation returning review_required or a review reason does not archive its lease as settled: resolve the review with the payment evidence before freeing that code.
Checkout and operations contract
- Return every instruction and expiry supplied by the payment intent. QR payloads, VA numbers, redirect URLs, and exact transfer amounts are not interchangeable.
- Make pending, paid, expired, rejected, and review-required states visible to the customer.
- Dispatch expiry and asynchronous work through a durable queue in production.
- Treat callback bodies, payment instructions, account numbers, tokens, and provider payloads as sensitive. Keep them out of general logs and issue trackers.
- Make callback handling idempotent. Retries and out-of-order delivery are normal provider behavior.
- Test one controlled production purchase per enabled channel and every claimed refund path before launch.
Continue
- Add Indonesian shipping and regions.
- Review IDR and PPN evidence.
- Configure the full engine in the configuration reference.
- Diagnose provider boot and capability errors with troubleshooting.