# Poketo

> Poketo is an Indonesian payment platform (aggregator) for payment links and a payments API. Buyers pay with QRIS, a bank Virtual Account (10 banks), PayLater, or a Visa/Mastercard debit card; transactions are processed by DOKU (PT Nusa Satu Inti Artha), a Payment Service Provider licensed by Bank Indonesia. A service fee is added on top for the buyer, so the seller receives the full invoice amount. Amounts are whole rupiah (IDR).

Poketo is not a bank or a licensed PJP and takes no deposits. A seller's balance records what they are owed; QRIS and Virtual Account funds become withdrawable the next working day (09:00 WIB), PayLater after 2 working days, debit cards after 7 days, and withdrawals go out the working day after they are requested.

## Product (no code, from the dashboard)

- Invoices: itemised invoices with a payment link to share on WhatsApp, email, or DM; buyers pick QRIS, VA, PayLater, or debit card.
- Payment links: one reusable link for many buyers, with fixed or buyer-entered amounts, quantity, stock limits, custom fields, promo codes, and a QR to print.
- Recurring invoices: weekly or monthly schedules; each invoice is created automatically at 09:00 WIB.
- Memberships: tiers of 1, 3, 6, or 12 months with email reminders 7, 3, and 1 day before the end, on the day, and 3 days after, each with a renewal link. No automatic debit.
- Customers and reports: buyers grouped by email with what they paid, unpaid invoices by age, and CSV exports of transactions and the balance ledger.
- Withdrawals: to a bank or e-wallet account in the verified owner's name, minimum Rp 50.000, fee Rp 5.000 taken out of the amount (withdraw Rp 50.000, receive Rp 45.000), optional 2FA, processed on working days.
- Security: [poketo.id/security](https://poketo.id/security) covers payments, balance protection, API key handling, signed webhooks, and how to report a vulnerability.

## Docs

- [API reference (Indonesian)](https://poketo.id/docs): full documentation with examples
- [Pricing](https://poketo.id/pricing): fees per method
- [Help center](https://poketo.id/help)
- [Service status](https://poketo.id/status): live status and 90-day uptime; JSON at `GET https://poketo.id/api/public/status` (no key)
- [Changelog](https://poketo.id/changelog)
- [Solutions](https://poketo.id/solutions), [comparisons](https://poketo.id/compare), [blog](https://poketo.id/blog), [glossary of Indonesian payment terms](https://poketo.id/glossary), [about](https://poketo.id/about)
- [Security](https://poketo.id/security): how payments, balances, and API integrations are protected
- [Terms](https://poketo.id/terms), [Privacy](https://poketo.id/privacy), [Acceptable use](https://poketo.id/acceptable-use)

## Authentication

- Base URL: `https://poketo.id/api/v1`, JSON over HTTPS.
- Header `Authorization: Bearer <key>`. Keys belong to a project, shown as a merchant in the dashboard (dashboard → Merchants → API settings).
- `sk_test_…` = sandbox (no money moves, use simulate), `sk_live_…` = live (needs identity verification). The response header `Poketo-Environment` says which one you used.
- Errors: `{ "error": { "code": "invalid_request", "message": "…" } }`. Codes are English and stable; messages are Indonesian. 429 comes with `Retry-After`.
- `POST /v1/invoices` accepts `Idempotency-Key`; `referenceId` also dedupes (same referenceId returns the first invoice).

## Endpoints

- `GET /v1/payment-methods?amount=50000`: QRIS, VA (with its banks), AKULAKU and CARD with fee rules, limits, settlement days, and the buyer's total for that amount. Service fee (paid by the buyer) = 0.3% of the amount (min Rp 200, max Rp 1.000) + a method part on the total paid: QRIS 0.777% (flat Rp 1.110 for totals up to Rp 100.000; max Rp 10.000.000), VA Rp 4.440 (max Rp 50.000.000), PayLater 1.665% + Rp 2.220, card 3.108% + Rp 2.220.
- `POST /v1/invoices`: create an invoice. Body: `amount` (integer ≥ 10000, required), `title`, `description`, `customer` {`name`, `email`, `phone`}, `items` [{`name`, `quantity`, `price`}] (must add up to amount), `expiresInMinutes` (5–43200, default 1440), `referenceId` (your order id, ≤ 64 chars), `redirectUrl` (https), `metadata` (≤ 20 keys). Returns the invoice with `paymentUrl` (`https://pay.poketo.id/inv/…`) to send to the buyer.
- `GET /v1/invoices?status=&limit=&offset=&createdFrom=&createdTo=&paymentLinkId=`: list (status: pending, paid, expired, cancelled, refunded).
- `GET /v1/invoices/:id`: one invoice (id is the invoice number, e.g. `INV-PKT-20261022-12345`).
- `POST /v1/invoices/:id/cancel`: cancel a pending invoice.
- `POST /v1/invoices/:id/check-status`: ask the payment provider now and settle if paid.
- `POST /v1/invoices/:id/simulate` (sandbox only): `{ "result": "paid" | "expired", "paymentMethod": "QRIS" | "VA" | "AKULAKU" | "CARD" }`.
- `POST /v1/payment-links`: reusable link many people can pay. Body: `title` (required), `amount` (fixed) or `minAmount`/`maxAmount` (payer enters the amount), `description`, `askEmail`, `redirectUrl`. Selling options: `allowQuantity` + `maxQuantity` (fixed amount only), `stockLimit` (null = unlimited), `customFields` (≤ 5 `{ label, type: text|phone|select, required, options }`), `afterPaymentMessage`. Returns `url` (`https://pay.poketo.id/l/…`). Invoices from a link carry `quantity`, `discountAmount` and `customFields` (buyer answers).
- `GET /v1/payment-links`, `GET /v1/payment-links/:id`, `PATCH /v1/payment-links/:id` (same fields plus `active`), `DELETE /v1/payment-links/:id` (archive).
- Memberships (subscriptions of 1, 3, 6 or 12 months; products belong to the key's project, members are per environment: a sandbox key only sees sandbox members): `POST /v1/memberships` `{ title, tiers: [{ name, price, periodMonths }], description?, benefits?, customFields?, maxMembers? }` → join page `url` (`https://pay.poketo.id/m/…`); `GET /v1/memberships`, `GET|PATCH|DELETE /v1/memberships/:id`.
- `POST /v1/memberships/:id/checkout` `{ tierId?, customer: { name, email, phone? }, answers?, expiresInMinutes?, redirectUrl?, metadata? }` → `{ member, invoice }` (invoice carries `memberId`; pay it, or simulate it in sandbox). Paying extends the member from their end date.
- `GET /v1/memberships/:id/members?status=&q=&limit=&offset=`, `POST /v1/memberships/:id/members` (add a member paid elsewhere), `GET /v1/members/:id`, `PATCH /v1/members/:id` `{ months? | expiresAt?, tierId?, note?, status?: "cancelled" | "active" }`, `POST /v1/members/:id/renewal` `{ tierId?, sendEmail? }` → renewal invoice. Webhooks: `membership.activated|renewed|updated|cancelled|expired`.

## Connect (platforms charging for their users)

For platforms that take payments on behalf of their users (e.g. creators). Each user has their own Poketo account, approves the link, passes KYC and withdraws their own balance; the platform never holds the money. Connect must be enabled for the project by the Poketo team.
- `POST /v1/connect/accounts` `{ referenceId, email?, name? }` → `{ id: "acct_…", status: "pending", onboardingUrl }`. Send the user to `onboardingUrl` (single use, 7 days). Same `referenceId` returns the same account; while pending each call issues a new link.
- `GET /v1/connect/accounts` (`status`, `limit`, `offset`), `GET /v1/connect/accounts/:id` (`status`: pending | active | revoked, `kycVerified`), `DELETE /v1/connect/accounts/:id` (unlink).
- Charge for a user: `POST /v1/invoices` with header `Poketo-Account: acct_…`. The invoice and money belong to that user; webhooks go to the platform. Live invoices need `kycVerified: true`.
- `purpose: "donation"` on an invoice makes the payment page say "Dukungan untuk" / "Dari".
- `applicationFeeAmount` (integer, 0 ≤ fee < amount, only with `Poketo-Account`): the platform's commission. The user receives `amount − applicationFeeAmount`, the project owner's balance gets the fee; a refund reverses both.
- Errors: `connect_not_enabled` (403), `account_not_found` (404), `account_pending` / `account_revoked` (409), `account_kyc_required` (403).

## Embedded checkout

Open a payment page as a pop-up on your site: load `https://poketo.id/js/checkout.js`, then `Poketo.checkout.open(paymentUrl, { onPaid, onStatus, onClose })`, or add `data-poketo-checkout` to an `<a href="https://pay.poketo.id/…">`. Still confirm payment from the webhook or `GET /v1/invoices/:id`.

## Invoice statuses

`pending` → `paid` | `expired` | `cancelled`; `paid` → `refunded` (refund or chargeback). A buyer who still pays an expired or cancelled invoice makes it `paid`.

## Webhooks

Poketo POSTs JSON to the project's webhook URL on `invoice.paid`, `invoice.expired`, `invoice.cancelled`, `invoice.refunded`, Connect's `account.updated` and `account.revoked` (data is the account object), and `ping` from "Send test".

- `Poketo-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(whsec_secret, "<t>.<raw body>")>`: verify over the raw body, reject t older than 5 minutes.
- `Poketo-Event-Id` (same on retries, use it to dedupe), `Poketo-Event`, `Poketo-Delivery`.
- Answer 2xx within 10 seconds. Retries up to 6 times (30 s, 2 min, 10 min, 1 h, 6 h) on 5xx, 408, 429, timeouts.

## Example

```bash
curl -X POST https://poketo.id/api/v1/invoices \
  -H "Authorization: Bearer $POKETO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 150000, "title": "Pesanan #1042", "customer": {"name": "Rina", "email": "rina@example.com"}, "referenceId": "order-1042"}'
```

## Integration prompt

Paste into a coding agent (Claude Code, Cursor, Codex) in your project:

```text
Integrate Poketo payments into this project.

1. Read https://poketo.id/llms.txt first; it describes the whole API.
2. Use a sandbox secret key (sk_test_…) from the POKETO_SECRET_KEY environment variable. Never hard-code keys.
3. Create invoices with POST https://poketo.id/api/v1/invoices (Authorization: Bearer <key>). Send my order id as referenceId and an Idempotency-Key header, then redirect the buyer to the returned paymentUrl.
4. Mark orders paid only from the invoice.paid webhook: verify Poketo-Signature (HMAC-SHA256 over "<t>.<raw body>" with the whsec_ secret), reject timestamps older than 5 minutes, and dedupe by Poketo-Event-Id.
5. Test the whole flow with POST /api/v1/invoices/:id/simulate in sandbox.
6. If you support MCP, the Poketo MCP server is https://poketo.id/api/mcp with the same key.
```

## MCP server (for AI agents)

Remote MCP server, Streamable HTTP: `https://poketo.id/api/mcp`, authenticated with the same project API key (`Authorization: Bearer sk_test_…`). Start with a sandbox key.

Tools: get_payment_methods, create_invoice, list_invoices, get_invoice, check_invoice_status, cancel_invoice, simulate_payment (sandbox), create_payment_link, list_payment_links, get_payment_link, update_payment_link, archive_payment_link.

Claude Code:

```bash
claude mcp add --transport http poketo https://poketo.id/api/mcp --header "Authorization: Bearer sk_test_..."
```

Other clients (Cursor, Claude Desktop, VS Code and others with remote MCP):

```json
{ "mcpServers": { "poketo": { "type": "http", "url": "https://poketo.id/api/mcp", "headers": { "Authorization": "Bearer sk_test_..." } } } }
```

## SDK

Node.js 18+, no dependencies: `npm install poketo-node`, then `const poketo = new Poketo(process.env.POKETO_SECRET_KEY)` and `poketo.invoices.create`, `poketo.invoices.list`, `poketo.paymentLinks.create`, `poketo.webhooks.verify(rawBody, signatureHeader, whsecSecret)`.
