Skip to content

Payments for Indonesia

Configure Midtrans, Xendit, and kode unik as explicit deferred-payment methods with verified callbacks and operator-safe settlement.

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/midtrans

Set 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/xendit

Set 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 a data.id beginning with rfd- carry providerRefundId from data.id, idempotencyKey from data.reference_id, and providerChargeId from the available payment request/payment ID. retrieveRefund({ providerRefundId }) queries GET /refunds/{id} and returns provider state and an optional IDR amount. Missing IDs or missing refunds return null; the driver does not infer a refund from a merchant reference.
  • Midtrans: confirmed refund/partial_refund status means success; acceptance without confirmation remains pending and provider error status codes mean failed. Documented refund notifications provide refund_key in refunds[]. The normalized refund.succeeded event uses that key as both providerRefundId and idempotencyKey, and the transaction ID as providerChargeId. 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 (idempotencyKey takes precedence). Missing charge/key, absent refund, or unconfirmed status returns null. 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,reference

Rows 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

Navigation

Type to search…

↑↓ navigate↵ selectEsc close