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.