@adocommercekit/midtrans

Midtrans Core API v2 deferred-payment driver for Adocommerce Kit. Supports QRIS, BCA/BNI/BRI virtual accounts, Mandiri bill-key, Permata VA, GoPay, Indomaret, and Alfamart.

Configure one factory per checkout method so the selected channel stays explicit.

Requirements

• Node.js 24+
• AdonisJS 7
• @adocommercekit/core ^1.1.0 (install matching lockstep versions)

Install

pnpm add @adocommercekit/midtrans
node ace configure @adocommercekit/midtrans

Configure adds:

• MIDTRANS_SERVER_KEY
• MIDTRANS_CLIENT_KEY
• MIDTRANS_ENVIRONMENT (sandbox | production)

Webhook URL expected by the package: <APP_URL>/commerce/webhooks/midtrans.

Usage

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",
    }),
  },
}

Notable exports

• midtrans() / MidtransPaymentProvider
• MidtransChannel, MidtransOptions
• MIDTRANS_REFUND_CAPABILITIES
• MidtransManualRefundRequiredError
• midtransWebhookUrl()
• MIDTRANS_API_FAMILY

Automatic refunds are offered only for QRIS and GoPay. Other channels require an operator-recorded manual-transfer reference. Notifications verify Midtrans’s SHA-512 signature, then re-query current transaction status before returning a normalized event.

Refund reconciliation

refund() returns state: 'pending' | 'succeeded' | 'failed'. A response with transaction_status: 'refund' | 'partial_refund' confirms success; an accepted request without a confirmed refund status remains pending. Provider error status codes map to failed.

The documented refund notifications include refund_key in each refunds[] entry. Normalized refund.succeeded events echo that key as both providerRefundId and idempotencyKey, with the transaction ID as providerChargeId. Notifications select the notified key from the re-fetched status, not an unrelated newer refund. If status omits a correlatable key, the event is unhandled rather than inventing a refund ID. Midtrans's documented notification/status schema exposes successful refund and partial_refund states, but does not specify distinct pending/failed refund notifications; the driver does not invent those webhook types.

retrieveRefund({ providerChargeId, idempotencyKey?, providerRefundId? }) uses GET /v2/{transaction_id}/status and selects the exact refund key. It returns null if the charge/key is missing, the refund is absent, or status cannot confirm that refund. The transaction's aggregate refunded amount is never used as an individual refund amount when multiple refunds exist.

Documentation

• Package map
• Configuration reference

License

MIT