# Setup Xendit

> Set up, build, debug, and explain Xendit payment gateway integrations, including Payments API v3, payment requests, payment tokens, webhooks, refunds, and xenPlatform sub-account routing. Use when implementing checkout, server-side payment collection, saved payment methods, webhook handling, payment status reconciliation, or platform marketplace flows with Xendit.

- Skill: `afu-it/setup-xendit` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add afu-it/setup-xendit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/afu-it/setup-xendit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: afu-it (https://skillmd.com/u/afu-it)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/afu-it/setup-xendit

---


# Xendit Payment Gateway

## Quick Start

Use this skill for Xendit integration work. Start with the task shape, then load only the relevant reference:

- Payments API or checkout flow: read [payments-api.md](references/payments-api.md).
- Webhook receiver, retries, duplicate events, or callback-token validation: read [webhooks.md](references/webhooks.md).
- Marketplace/platform, sub-accounts, split fees, balance transfer, or `for-user-id` routing: read [xenplatform.md](references/xenplatform.md).
- First-time project setup, API keys, dashboard prerequisites, or channel activation: read [setup-checklist.md](references/setup-checklist.md).
- Registration, credentials, env vars, and dashboard setup summary: read [account-setup.md](references/account-setup.md).
- Endpoint/category lookup and live documentation links: read [source-map.md](references/source-map.md).

## Integration Rules

- Use server-side code for secret-key requests and webhook handling.
- Authenticate Xendit API calls with HTTP Basic Auth where username is the secret API key and password is empty.
- Preserve trailing colon before Base64 encoding when manually building `Authorization: Basic ...`.
- Treat `reference_id` as merchant idempotency/correlation key; store Xendit IDs returned by the API.
- Never trust client-side payment completion alone. Fulfill orders from verified server-side state or webhook state.
- Make webhook handlers idempotent by Xendit object/event identifiers such as `payment_id`, `capture_id`, or product-specific IDs.
- Return a 2xx response quickly from webhook endpoints, then process heavier work asynchronously.
- Do not assume webhook order. Reconcile from current object state when events arrive out of sequence.

## Current API Shape

Prefer Payments API v3 for new payment collection:

- `POST /v3/payment_requests`: create payment intent/request.
- `POST /v3/payment_tokens`: save payment information for later reuse.
- `/refunds`: refund payment funds.

Common payment request types:

- `PAY`: collect one payment.
- `PAY_AND_SAVE`: collect one payment and save reusable payment information.
- `PAY` with token: collect using previously saved payment token.
- `REUSABLE_PAYMENT_CODES`: collect multiple payments from reusable code or static channel setup.

## Measure Twice

Before coding against Xendit:

1. Decide product path: Payment Sessions/Components, Payments API v3, Payment Links, Subscriptions, Payouts, or xenPlatform.
2. Confirm country, currency, channel, and channel properties.
3. Confirm live vs test API key, key permissions, and callback/webhook URLs.
4. Confirm whether flow requires customer action via returned `actions` or hosted/embedded checkout.
5. Confirm status mapping and order-fulfillment state machine.
6. Confirm webhook token verification and idempotency storage.
7. For xenPlatform, confirm master account vs sub-account ownership and routing header/body fields.

## Verification

For production-facing answers, verify live docs if exact field names, enum values, or endpoint schemas matter. Xendit docs are active and may change; this skill carries stable workflow rules plus source links, not a complete frozen OpenAPI copy.