Introduction
AntaraPay API v1 integration guide for merchants and companies: quick flow, endpoint overview, and contents.
Draft contract v1
This document is a draft v1 integration contract. Environment URLs, credentials, active channels, amount limits, and the effective fee policy are provided during onboarding. The examples do not mean the endpoints are already available in production. Use the simulator or sandbox provided by AntaraPay before going live.
About this guide
This guide explains how a merchant backend creates payment instructions, fetches a QRIS or VA, submits payouts, reads balances and journals, and receives status notifications from AntaraPay. Your customers keep interacting with your own website or app.
API contract v1 · English · October 15, 2026. Planned production host: https://api.antarapay.com.
Integration flow at a glance
- Keep the API key on your backend. Create an HTTPS webhook endpoint and register it in the integration dashboard.
- Create a payin with a unique order
referenceand anIdempotency-Key. Store the AntaraPay ID you receive. - Fetch the status until the instruction is ready, then show the QR or payment instruction to your customer.
- Receive a verified webhook with status
completed,failed, orexpired. Fulfil the order only on acompletedwebhook or a payin GET showingSUCCEEDED; balance availability is checked separately. - To send funds, submit a payout through the API. AntaraPay holds the balance and processes it after admin approval.
Endpoint overview
The base path of every endpoint is /api/v1. Every POST requires an Idempotency-Key.
| Method | Path | Scope | Purpose |
|---|---|---|---|
| POST | /api/v1/payins | payins:write | Create a payin (202) |
| GET | /api/v1/payins | payins:read | List payins |
| GET | /api/v1/payins/{id} | payins:read | Payin details and instruction |
| GET | /api/v1/payins/{id}/qr | payins:read | QR image (PNG) |
| POST | /api/v1/payouts | payouts:write | Submit a payout (202) |
| GET | /api/v1/payouts | payouts:read | List payouts |
| GET | /api/v1/payouts/{id} | payouts:read | Payout details |
| POST | /api/v1/payouts/{id}/cancel | payouts:write | Cancel a payout |
| GET | /api/v1/balances | balances:read | Active, On Hold, Pending balances |
| GET | /api/v1/journals | journals:read | Debit/credit journal |
| GET | /api/v1/settlements | settlements:read | Settlements |
| GET | /api/v1/channels | channels:read | Channels, limits, and bank codes |
| POST | /api/v1/reports/exports | reports:write | Request a report export |
| GET | /api/v1/reports/exports/{id} | reports:read | Export status and download URL |
Contents
Part 1Environment and authenticationBase URL, required headers, API key scopes, key storage and rotation.Part 2Data formats, idempotency, and errorsData types, pagination, safe retries with Idempotency-Key, and error codes.Part 3–5PayinCreate payins, read QRIS/VA instructions, fetch the QR image, list payins, and handle statuses.Part 6–7PayoutSubmit payouts, read their status, list them, and cancel a payout.Part 8Balances and journalsThe three balance types (Active, On Hold, Pending) and the debit/credit journal.Part 9Settlements, channels, and reportsSettlements, the channel and bank list, and CSV/XLSX report exports.Part 10Receiving webhooksEvent format, event types, and how your endpoint should respond.Part 11Webhook signature and retriesHMAC SHA256 verification, verification steps, code samples, and the retry policy.Part 12Testing checklistTest scenarios, production readiness, and information for investigations.