Developers

Build on JoPay. REST API, webhooks, scopes, and integration patterns.

Overview

JoPay exposes a small REST API for partners and partner-side developers to create payment requests, manage merchants, and receive webhook notifications. Every call is authenticated with a partner API key; there is no OAuth, no client secrets, no callback URLs — just a bearer token and JSON over HTTPS.

The API is versioned under /api/v1. It is stable — breaking changes ship as a new major version with overlap periods. This section covers the v1 surface end to end.

Generating your first API key takes one click in the partner portal (or in admin for partners who manage keys there). Both jo_live_and jo_test_ prefixes are available.

Start here

Quickstart

Create your first payment request with a single curl call.

Authentication

Bearer tokens, scopes, live vs test mode, and key rotation.

Integration patterns

E-commerce checkout, invoicing, subscriptions, reconciliation.

API surface

Requests API

Create, get, list, and cancel payment requests. Idempotency keys.

Merchants API

Provision merchants programmatically. Onboarding handoff via onboarding_url.

Webhooks

HMAC-signed event deliveries for payment.proof_verified and payment.proof_attached. Retry schedule, deduplication.

Limits and errors

Rate limits

60 requests per minute per API key. Per-endpoint limits for FX and webhooks.

Errors

Full error-code table with HTTP status and remediation per code.

Conventions

  • JSON everywhere. Every request and response body is JSON. Error responses include { "ok": false, "error": "<error_code>" } and a matching HTTP status.
  • Idempotency is supported per-endpoint via idempotency_key. See Requests API → Idempotency.
  • Minor units for fiat. fiat_amount_int is always in minor units (cents for EUR/USD/GBP, paise for INR, whole yens for JPY). Never send a decimal.
  • Tenant isolation. An API key can only read and write its own partner's resources. A 404 never leaks the existence of another partner's data.
  • Test mode is fully isolated. jo_test_ keys see sandbox data only. See Authentication → Live and test mode.

SDKs

No official SDK is published yet. Every example in these pages uses plain curl or fetch against the REST surface. When an SDK ships, this page will list it.