Midtrans CLI

Public preview · Sandbox only.

Skill reasons; CLI proves. The CLI works independently or as the deterministic execution and verification layer for the official Midtrans Agent Skill. It may write .midtrans/ configuration and evidence but never writes application code. v0.1 is Sandbox only: it rejects production Midtrans hosts and classic server keys without the SB- prefix. Merchants must still provide and use a Sandbox client key.

Install the public preview

The public preview requires Git, Go 1.26 or later, Python 3, and a POSIX shell.

git clone https://github.com/veritrans/midtrans-cli.git
cd midtrans-cli
tools/install-local.sh
midtrans version

The installer builds and verifies a regular binary under ${MIDTRANS_INSTALL_DIR:-$HOME/.local/bin}. It does not require sudo or edit your shell profile.

Choose your path

CLI independently

Use deterministic commands directly while keeping application-code changes under merchant control.

CLI + Midtrans Agent Skill

Give a coding agent a machine-readable execution and evidence layer while it handles application-code changes.

Path	Best for	Ownership	Start with
CLI independently	Merchants who want direct, deterministic commands	The merchant edits application code; the CLI inspects, tests, executes reviewed Sandbox journeys, and verifies proof	midtrans init
CLI + Midtrans Agent Skill	Merchants using Codex, Claude Code, Copilot, Cursor, OpenCode, or another coding agent	The Skill reasons and the agent edits code; the CLI supplies machine-readable policy, execution, and evidence	midtrans agent capabilities --json --non-interactive

For the paired path, read the official AI integration guidance and use the Midtrans Agent Skill.

How it works

Two operating modes

flowchart LR
    M["Merchant"]

    subgraph Standalone["CLI independently"]
        CLI1["Midtrans CLI"]
        Repo1["Merchant repository"]
        SBX1["Midtrans Sandbox"]
        Proof1["Redacted evidence"]
        CLI1 --> Repo1
        CLI1 --> SBX1
        CLI1 --> Proof1
    end

    subgraph Paired["CLI + AI Agent Skill"]
        Agent["AI coding agent"]
        Skill["Midtrans Agent Skill"]
        CLI2["Midtrans CLI"]
        Repo2["Merchant repository"]
        SBX2["Midtrans Sandbox"]
        Proof2["Redacted evidence"]
        Agent <--> Skill
        Agent --> Repo2
        Agent <--> CLI2
        CLI2 --> SBX2
        CLI2 --> Proof2
    end

    M --> CLI1
    M --> Agent

Loading

Standalone interaction

sequenceDiagram
    actor Merchant
    participant CLI as Midtrans CLI
    participant Repo as Merchant repository
    participant Sandbox as Midtrans Sandbox
    participant Evidence as Evidence files

    Merchant->>CLI: init and setup
    CLI->>Repo: Create .midtrans configuration
    Merchant->>CLI: status and test
    CLI->>Repo: Inspect integration
    CLI->>Sandbox: Execute approved Sandbox operation
    Sandbox-->>CLI: Provider result
    CLI->>Evidence: Write redacted, checksummed proof
    Merchant->>CLI: verify
    CLI-->>Merchant: Verified, provider-confirmed, or blocked

Loading

AI-assisted interaction

sequenceDiagram
    actor Merchant
    participant Agent as AI coding agent + Skill
    participant CLI as Midtrans CLI
    participant Repo as Merchant repository
    participant Sandbox as Midtrans Sandbox

    Merchant->>Agent: Describe the payment integration
    Agent->>CLI: capabilities, inspect, check
    CLI-->>Agent: Machine-readable readiness
    Agent->>Repo: Implement or repair application code
    Agent->>CLI: plan journey
    CLI-->>Agent: Dry-run and missing prerequisites
    Agent->>CLI: run --execute
    CLI->>Sandbox: Approved Sandbox request
    Sandbox-->>CLI: Provider result
    Agent->>CLI: resume and verify
    CLI-->>Agent: Redacted evidence and proof level
    Agent-->>Merchant: Result and remaining merchant actions

Loading

Get your first Sandbox proof

Standalone CLI

Start in the merchant project. The plan output shows what would happen; review it before adding --execute to make a Sandbox request.

cd /path/to/merchant-project
midtrans init
midtrans setup
midtrans status
midtrans test checkout --amount 10000
midtrans test checkout --amount 10000 --execute
midtrans test webhook --order-id <order-id> --amount 10000
midtrans test webhook --order-id <order-id> --amount 10000 --execute
midtrans verify

CLI + Midtrans Agent Skill

First complete the compatibility handshake and produce a non-mutating journey plan.

midtrans agent capabilities --json --non-interactive
midtrans agent inspect --json --non-interactive
midtrans agent check --product snap --json --non-interactive
midtrans agent plan --journey snap.checkout --amount 10000 --json --non-interactive

After the merchant reviews the plan, execution and recovery stay explicit:

midtrans agent run --journey snap.checkout --amount 10000 --execute --json --non-interactive
midtrans agent resume --operation <operation-id> --json --non-interactive
midtrans verify --product snap --json --non-interactive

Supported Midtrans products

Product	Merchant use case	Representative journeys
Snap	Hosted checkout and mobile WebView readiness	snap.checkout, snap.mobile-webview
Core API	Custom card, VA, OTC, recurring, saved-card, installment, and refund flows	core-api.card-3ds, core-api.virtual-account, core-api.refund
Payment Link	Dashboard or API-created links, including reusable links	payment-link.create, payment-link.reusable, payment-link.verify
BI-SNAP	QRIS, VA, direct debit, recurring, refund, and status flows	bisnap.qris-payment, bisnap.virtual-account, bisnap.status
GoPay tokenization	Linking, Binding Inquiry, wallet payment, GoPayLater, recurring, and unlinking	gopay-tokenization.account-linking, gopay-tokenization.wallet-payment, gopay-tokenization.unlink
Subscription	Create, verify, enable, disable, and cancel subscriptions	subscription.create, subscription.verify, subscription.cancel

See the Agent Skill compatibility matrix for the exhaustive capability and journey matrix.

Complete command interface

Command	Purpose	Important input
midtrans	Show welcome or current repository readiness	Global flags
midtrans init	Initialize neutral Sandbox-only .midtrans/ configuration	Global flags
midtrans setup	Configure initial Sandbox checkout readiness	Global flags
midtrans status	Inspect merchant integration readiness	Global flags
midtrans test [intent]	Plan or execute a Sandbox payment journey such as checkout	Journey inputs, --execute
midtrans test webhook	Plan or execute local webhook verification	--order-id, --amount, --execute
midtrans verify	Evaluate required evidence for a product or configured integration	--product, --evidence
midtrans version	Report CLI build identity	Global flags
midtrans update check	Check whether an update is available without silently installing it	Global flags
midtrans agent capabilities	Report machine-readable schemas, packs, capabilities, and journeys	--json --non-interactive
midtrans agent inspect	Inspect repository and manifest state for an agent	--json --non-interactive
midtrans agent check	Diagnose one product pack	--product
midtrans agent pack list	List installed capabilities and journeys	Agent output flags
midtrans agent pack info <pack>	Show one installed pack descriptor	Pack ID
midtrans agent plan	Plan an exact journey without mutating	Required --journey, journey inputs
midtrans agent run	Preview or execute an exact journey	Required --journey, optional --execute
midtrans agent resume	Resume an existing operation after interaction or reconciliation	Required --operation, optional --evidence

Global flags

Flag	Use
--project-dir	Set the merchant repository root instead of auto-detection.
--json	Write the stable JSON result contract.
--non-interactive	Reject prompts so an agent can run deterministically.
--verbose	Write additional redacted diagnostics.

Journey flags

Group inputs deliberately: routing uses --product, --journey, and --method; transaction uses --amount, --order-id, --reusable, and --usage-limit; proof uses --evidence and --operation; safe references use --customer-reference, --subscription-id, --payment-token-reference, and --mobile-number-reference; schedule uses --schedule-interval, --schedule-unit, and --schedule-start. Add --execute only after reviewing a plan.

Common command sequences

Use midtrans status before a direct journey, or midtrans agent check --product <product> before an agent plans one. Use midtrans verify after collecting evidence, and retain the operation ID for midtrans agent resume when provider interaction continues outside the terminal.

Tips for difficult integrations

Webhooks

With midtrans test webhook and midtrans verify, verify authenticity, use idempotent and monotonic state updates, replay safely, and reconcile through the Status API. Dashboard notification configuration, an HTTPS endpoint, and delivered Sandbox evidence can remain blocked until the merchant provides them.

Hybrid routing

Assign exactly one product owner per payment method and run midtrans agent check --product <product> before midtrans agent plan. Merchant routing configuration or product activation can remain blocked.

Snap WebView/mobile

Use midtrans test checkout or midtrans agent plan --journey snap.mobile-webview to model the flow. Browser and deeplink returns are UX signals; device return and provider state are separate proof, so device and Sandbox evidence can remain blocked.

BI-SNAP

Use midtrans agent check --product bisnap before midtrans agent plan. Keep access-token, transaction, and notification signature logic and credentials separate; operator confirmation, dashboard activation, and Sandbox credentials can remain blocked.

GoPay tokenization

Use midtrans agent check --product gopay-tokenization and plan each journey independently. Keep linking, Binding Inquiry, wallet payment, PayLater, recurring, and unlinking separate journeys with activation gates; device approval, merchant activation, and Sandbox evidence can remain blocked.

Ambiguous operations

Retain the operation ID and use midtrans agent resume; never blindly create a replacement payment. Merchant reconciliation or provider status evidence can remain blocked.

Browser/provider disagreement

Use midtrans verify after midtrans agent resume or midtrans test webhook. Fulfill only from authenticated webhook or backend provider-status proof; browser callbacks and missing provider evidence remain blocked.

Best practices and security

• Use Sandbox credentials only. BI-SNAP credentials require operator confirmation because their format does not reveal environment.
• Manifests contain env:NAME or owner-only project-relative file:./path references, never resolved secret values.
• Server keys, private keys, tokens, and signatures stay backend-only and out of AI prompts, logs, public issues, and chats.
• Notification URLs use HTTPS, verify authenticity, process duplicates idempotently, reject stale regressions, and recover with provider status lookup.
• Browser callbacks are not payment or fulfillment proof.
• Evidence must be redacted, checksummed, inspected again, and shared only through an approved private channel.
• Agents complete the compatibility handshake and never silently install or update the CLI.

Read SECURITY.md, payment security, HTTPS notifications, notification handling, and Sandbox testing.

Troubleshooting and proof levels

blocked means a required merchant, dashboard, device, activation, callback, or Sandbox proof is still missing; follow midtrans status, midtrans agent check, or midtrans agent resume to see the next action. provider_confirmed means Midtrans returned provider state, but all local or merchant-side evidence required for completion is not yet verified. verified means midtrans verify validated the required redacted, checksummed evidence for the configured journey.

Further reading

• Official AI guidance
• Midtrans product documentation
• Midtrans Agent Skill
• Security guidance
• Agent Skill compatibility
• Public capability contract, result schema, manifest schema, and evidence schema