Zeny merchant API

Create payments, pay out money and hear about the result, from your own server.

The API is REST over HTTPS and speaks JSON. Every request goes to https://api.usezeny.com and carries your secret key. The API reference lists every endpoint with its fields; these guides explain the rules that apply to all of them.

Your first payment

1. Create a secret key in the dashboard and keep it on your server only. Use a sk_test_ key while you build. See Authentication.
2. Create a payment with POST /api/merchant/v1/payments. Nothing is charged yet.
3. Start an attempt with POST /api/merchant/v1/payments/{id}/attempts for the method the payer picked (virtual account, QRIS or e-wallet). The answer carries a nextAction that tells you what to show the payer.
4. Wait for the payment.paid webhook, then fulfil the order. You can also read the payment with GET /api/merchant/v1/payments/{id}.

curl https://api.usezeny.com/api/merchant/v1/payments \
  -H "Authorization: Bearer $ZENY_SECRET_KEY" \
  -H "Idempotency-Key: order-1042-create" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order-1042",
    "amount": { "value": "150000.00", "currency": "IDR" },
    "description": "Order 1042"
  }'

Every POST that creates or moves money needs an Idempotency-Key, so a retry never charges twice. See Idempotency.

Conventions

• JSON keys are camelCase. Every documented key of a response is always present: an empty object or time is null, an empty list [], an empty string "".
• Ids carry a prefix for their kind: pay_…, att_…, po_…, evt_…, dsp_…. Treat an id as an opaque string.
• Amounts are Money objects: a decimal string value and a currency. Never send or read an amount as a floating point number.
• Times are UTC, in RFC 3339.
• A field that lists values (a status, an event type) can gain new values in v1. Your code must accept a value it does not know.
• A request field the endpoint does not declare is refused with 400 unknown_field.