xendit-mcp

Model Context Protocol server for the Xendit payment API. Supports payment links via invoices, payouts/disbursements, balances, and transactions across Indonesia, the Philippines, Thailand, Vietnam, and Malaysia.

Install

npm install -g xendit-mcp

Or run on demand with npx xendit-mcp.

Upgrading from 0.1.x

0.2.0 introduces breaking defaults. If you were on 0.1.x and relied on invoice creation or one-shot payouts working out of the box, those tools are now disabled by default.

To restore the old behavior, set these in your MCP config env:

XENDIT_ENABLE_INVOICE_MUTATIONS=true
XENDIT_ENABLE_DISBURSEMENTS=true
XENDIT_ENABLE_LEGACY_ONE_SHOT_DISBURSEMENT=true

If you enable disbursements, you must also set the four safety gates (XENDIT_MAX_DISBURSEMENT_AMOUNT, XENDIT_MAX_DAILY_AMOUNT, XENDIT_ALLOWED_ACCOUNTS, XENDIT_APPROVAL_CODE) or the server will refuse to start.

The recommended migration is to adopt the new two-step payout flow (prepare_disbursement → confirm_disbursement with an approval code) instead of re-enabling the legacy one-shot. See Safety for details.

User-facing modes

Think about the product in 3 modes:

• read-only: balances, invoices read, transactions read
• invoices: read-only plus create_invoice and expire_invoice
• guarded-payouts: invoices mode plus prepare_disbursement and confirm_disbursement

For non-technical users, the easiest helpers are:

npx xendit-mcp doctor
npx xendit-mcp setup

• doctor prints the current mode, enabled capabilities, and what is still blocked.
• setup generates a Claude Code or Claude Desktop snippet for the mode you want.

Configuration

1. Sign up at the Xendit Dashboard.
2. Go to Settings → API Keys and generate a key.
3. Use a test key (xnd_development_...) for development or a live key for production.

Variable	Required	Description
XENDIT_API_KEY	yes	Test or live API key
XENDIT_ENABLE_INVOICE_MUTATIONS	no	Set to true to enable create_invoice, expire_invoice, and the create_payment_link prompt. Disabled by default for safer read-only behavior.
XENDIT_ENABLE_DISBURSEMENTS	no	Set to true to enable disbursement tools (money-movement). Disabled by default.
XENDIT_ALLOW_LIVE	no	Set to true to allow live/production keys (prefixes xnd_production_, iluma_production_, sk_live_). Refused by default.
XENDIT_MAX_DISBURSEMENT_AMOUNT	no	Hard cap for one money-out call. Set to 0 or omit to disable.
XENDIT_MAX_DAILY_AMOUNT	no	Rolling 24-hour cap across money-out calls. Set to 0 or omit to disable.
XENDIT_ALLOWED_ACCOUNTS	no	Comma-separated allowlist in CHANNEL_CODE:ACCOUNT_NUMBER format, e.g. ID_BCA:1234567890.
XENDIT_PREPARE_TTL_SECONDS	no	How long a prepared disbursement token stays valid. Defaults to 300, max 86400.
XENDIT_APPROVAL_CODE	no	Required when XENDIT_ENABLE_DISBURSEMENTS=true. Human approval code required by confirm_disbursement and legacy one-shot payouts. Keep it out of untrusted prompt context.
XENDIT_ENABLE_LEGACY_ONE_SHOT_DISBURSEMENT	no	Set to true only if you intentionally want the old create_disbursement one-shot tool. Disabled by default.

Guided setup

If you do not want to hand-edit env vars, run:

npx xendit-mcp setup

It will ask which client you use and which mode you want, then output a ready-to-paste Claude config snippet with placeholders for secrets.

If the MCP is already connected in Claude, you can also ask Claude to use:

• get_workspace_mode
• guided_setup

guided_setup uses MCP elicitation in Claude Code when available, so the user sees a form instead of raw config details.

Claude Desktop

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "xendit": {
      "command": "npx",
      "args": ["-y", "xendit-mcp"],
      "env": {
        "XENDIT_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

claude mcp add xendit --env XENDIT_API_KEY=your-api-key -- npx -y xendit-mcp

Cursor

Add to ~/.cursor/mcp.json with the same shape as Claude Desktop.

Tools

Tool	Description
get_workspace_mode	Explain which Xendit mode is active, what is enabled, and the safest next step to unlock more features.
guided_setup	Generate a Claude Code or Claude Desktop config snippet for read-only, invoices, or guarded-payouts.
get_balance	Account balance by type (CASH, HOLDING, TAX).
list_invoices	List invoices filtered by status, date range, or currency.
get_invoice	Retrieve a single invoice.
create_invoice	Create a payment invoice and return a payment link. Disabled unless XENDIT_ENABLE_INVOICE_MUTATIONS=true.
expire_invoice	Expire an active invoice. Disabled unless XENDIT_ENABLE_INVOICE_MUTATIONS=true.
list_transactions	List payments, payouts, refunds, transfers, and balance adjustments.
prepare_disbursement	Stage a money-out call and return a short-lived confirmation token. Disabled unless XENDIT_ENABLE_DISBURSEMENTS=true.
confirm_disbursement	Execute a previously prepared money-out token. Requires approvalCode. Disabled unless XENDIT_ENABLE_DISBURSEMENTS=true.
cancel_disbursement	Cancel a prepared money-out token. Disabled unless XENDIT_ENABLE_DISBURSEMENTS=true.
create_disbursement	Legacy one-shot payout/disbursement. Requires approvalCode and explicit legacy opt-in. Disabled unless both XENDIT_ENABLE_DISBURSEMENTS=true and XENDIT_ENABLE_LEGACY_ONE_SHOT_DISBURSEMENT=true.
get_disbursement	Check payout/disbursement status. Disabled unless XENDIT_ENABLE_DISBURSEMENTS=true.
list_disbursement_banks	List payout channels such as ID_BCA and PH_BPI. Disabled unless XENDIT_ENABLE_DISBURSEMENTS=true.

Prompts

Prompt	Description
check_balance	Report account balance.
recent_payments	Payments received in the last N days.
create_payment_link	Generate a payment link for a customer. Disabled unless XENDIT_ENABLE_INVOICE_MUTATIONS=true.
unpaid_invoices	List pending invoices.
daily_summary	Today's payment activity.

Resources

Resource	URI	Description
Supported Banks	xendit://banks	Common payout channel aliases for Indonesia and the Philippines.
Setup Guide	xendit://setup	Current mode, setup commands, and plain-English mode explanations.
API Info	xendit://info	Xendit API overview and doc links.

Example queries

What's my current Xendit balance?
Saldo Xendit saya berapa?

With `XENDIT_ENABLE_INVOICE_MUTATIONS=true`:
Create an invoice for Rp 500,000 for "Website design deposit".
Buatkan invoice Rp 500.000 untuk "Deposit desain website".

Show me all unpaid invoices.
Tampilkan semua invoice yang belum dibayar.

With XENDIT_ENABLE_DISBURSEMENTS=true:

Prepare a Rp 1,000,000 payout to Ahmad at BCA, then wait for my confirmation.
Siapkan payout Rp 1.000.000 ke Ahmad di BCA, lalu tunggu konfirmasi saya.

List available payout channels in the Philippines.

Environments

Xendit issues separate test and live API keys. Test keys operate against the Xendit sandbox, so no real funds move. Live keys (xnd_production_..., iluma_production_..., sk_live_...) operate against production.

Safety

This server can move real money through the Xendit API. Key safeguards:

• Read-only by default. Invoice write tools are disabled unless XENDIT_ENABLE_INVOICE_MUTATIONS=true. Money-moving tools are disabled unless XENDIT_ENABLE_DISBURSEMENTS=true.
• Live keys are refused by default. Keys with the prefixes xnd_production_, iluma_production_, or sk_live_ are rejected at startup unless XENDIT_ALLOW_LIVE=true. Always test with a development key (xnd_development_...) first.
• Fail-closed money movement. If you enable disbursements, the server refuses to start unless XENDIT_MAX_DISBURSEMENT_AMOUNT, XENDIT_MAX_DAILY_AMOUNT, XENDIT_ALLOWED_ACCOUNTS, and XENDIT_APPROVAL_CODE are configured.
• Human-in-the-loop flow. confirm_disbursement requires both the staged token and a separate approvalCode.
• Legacy one-shot payouts stay off by default. create_disbursement is not even registered unless XENDIT_ENABLE_LEGACY_ONE_SHOT_DISBURSEMENT=true.
• Hard caps and allowlists. XENDIT_MAX_DISBURSEMENT_AMOUNT, XENDIT_MAX_DAILY_AMOUNT, and XENDIT_ALLOWED_ACCOUNTS let you fail closed before a payout is sent.
• Idempotency. Payout calls use your externalId as the Idempotency-Key, so safe retries do not create duplicate transfers.
• Setup helpers are always available. get_workspace_mode and guided_setup are exposed even in read-only mode so users can understand what is blocked and how to enable the next mode safely.
• Important limitation. No MCP server can be fully immune to prompt injection if you expose sensitive read or write tools to an untrusted model context. These defaults reduce risk, but you should still only connect this server to trusted agent workflows.

Even with these gates on, review any money-moving request before approving the tool call. Treat tool inputs derived from model output as untrusted.

Payout lifecycle

A confirmed payout does not always succeed or fail immediately. Xendit returns one of these statuses, and the terminal state may arrive seconds or minutes later:

• ACCEPTED — accepted by Xendit, channel processing in progress
• REQUESTED — submitted to the destination channel, waiting for the channel's response
• SUCCEEDED — funds delivered
• FAILED — final failure (e.g. INVALID_DESTINATION, REJECTED_BY_CHANNEL, INSUFFICIENT_BALANCE)

Some destinations (observed in PHP sandbox testing) sit in REQUESTED for a while before transitioning to FAILED. Always re-fetch with get_disbursement before assuming the final state. Do not treat the initial response from confirm_disbursement as proof of delivery.

Sandbox verification scope

0.2.0 was verified against the Xendit sandbox using IDR and PHP development keys (May 25, 2026). Verified flows:

• Invoice create / get / list / expire (IDR + PHP)
• Payout channel discovery (PHP)
• Guarded payout prepare → confirm → get (IDR + PHP)
• Negative payout reasons INVALID_DESTINATION and REJECTED_BY_CHANNEL (PHP only — the IDR sandbox key had balance: 0, so negative IDR cases surfaced as INSUFFICIENT_BALANCE rather than destination-specific failures)

Thailand, Vietnam, and Malaysia behavior is not yet verified against real sandbox keys. Behavior should be similar but cannot be claimed as tested.

Optional Claude Code hardening

Claude Code supports PreToolUse hooks that can force an extra approval dialog for sensitive tools such as confirm_disbursement. That gives you a second control outside the model context.

Example .claude/settings.json snippet:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__xendit__confirm_disbursement",
        "hooks": [
          {
            "type": "command",
            "command": "printf '%s' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"Human review required before confirm_disbursement.\"}}'"
          }
        ]
      }
    ]
  }
}

Disclaimer

This is an unofficial, community-built MCP server. Not affiliated with, endorsed by, or sponsored by Xendit. Xendit is a trademark of its respective owners. Use at your own risk. The author accepts no liability for funds lost through misuse, prompt injection, or bugs.

License

MIT