| name | setup-xendit |
| description | 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. |
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.
- Webhook receiver, retries, duplicate events, or callback-token validation: read webhooks.md.
- Marketplace/platform, sub-accounts, split fees, balance transfer, or
for-user-id routing: read xenplatform.md.
- First-time project setup, API keys, dashboard prerequisites, or channel activation: read setup-checklist.md.
- Registration, credentials, env vars, and dashboard setup summary: read account-setup.md.
- Endpoint/category lookup and live documentation links: read 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:
- Decide product path: Payment Sessions/Components, Payments API v3, Payment Links, Subscriptions, Payouts, or xenPlatform.
- Confirm country, currency, channel, and channel properties.
- Confirm live vs test API key, key permissions, and callback/webhook URLs.
- Confirm whether flow requires customer action via returned
actions or hosted/embedded checkout.
- Confirm status mapping and order-fulfillment state machine.
- Confirm webhook token verification and idempotency storage.
- 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.
