Merchants API

Provision merchants programmatically. Create, list, and get merchants under your partner.

Overview

The Merchants API lets your server provision merchants programmatically instead of routing every user through JoPay's interactive onboarding. It opens Stripe-Connect-style integrations — PSPs, marketplaces, Shopify-class plugins — where a merchant exists in your system before they've touched JoPay at all.

Creating a merchant via the API produces a shell merchantwith onboarding_status: "incomplete". The response includes an onboarding_url you redirect the user to; they finish wallet setup and TOS acceptance there.

Create a merchant

POST /api/v1/merchants

Required scope: merchants:write. Rate limit: 30 requests per minute per API key.

curl -X POST https://<partner-slug>.jopay.app/api/v1/merchants \
  -H "Authorization: Bearer jo_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@acmecafe.example",
    "display_name": "Alice",
    "business_name": "Alice'\''s Cafe",
    "country": "NL",
    "account_type": "business",
    "display_currency": "EUR"
  }'

Request body

Every field is optional. What your partner policy requires of merchants at onboarding is separate from what this endpoint accepts.

Response

{
  "ok": true,
  "merchant_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "email": "alice@acmecafe.example",
  "display_name": "Alice",
  "business_name": "Alice's Cafe",
  "country": "NL",
  "phone": null,
  "website": null,
  "instagram": null,
  "industry": null,
  "account_type": "business",
  "onboarding_status": "incomplete",
  "wallet_address": null,
  "display_currency": "EUR",
  "home_portal": "<partner-slug>",
  "disabled": false,
  "created_at": "2026-04-17T12:00:00.000Z",
  "test_mode": false,
  "onboarding_url": "https://app.jopay.app/merchant/onboarding"
}

Onboarding handoff

The returned onboarding_url is the deep-link your user needs to open in a browser to finish setup (wallet, TOS). Typical flow:

1. Your server creates a shell merchant via this endpoint, gets a merchant_id and onboarding_url.
2. You redirect the user's browser to onboarding_url(or email them the link).
3. They complete wallet connection and TOS acceptance in JoPay. On success, onboarding_status flips to "complete" and onboarding_url on subsequent reads is null.
4. You can now create payment requests for that merchant via POST /api/v1/requests/create. Creating a request for a merchant still in onboarding_status: "incomplete" returns 400 merchant_onboarding_incomplete.

Idempotency

Create is idempotent on wallet_address. If you POST a merchant with a wallet_address that already belongs to a merchant on your partner and matches your key's mode, the existing merchant is returned with idempotent_replay: true instead of a duplicate being created.

If the wallet belongs to a merchant on a different partner, or to a merchant in a different mode (live vs test), you get 409 wallet_address_conflict — wallet addresses are globally unique across the platform.

Get a merchant

GET /api/v1/merchants/:id

Required scope: merchants:read. Rate limit: 60 requests per minute per API key.

curl https://<partner-slug>.jopay.app/api/v1/merchants/aaaaaaaa-... \
  -H "Authorization: Bearer jo_live_xxx"

Returns the same shape as Create response. Returns 404 not_found if the merchant doesn't exist, isn't assigned to your partner, or is in a different mode than your key (live vs test). JoPay never discloses cross-tenant or cross-mode existence — a 404 from another partner's id looks identical to a 404 from a typo.

List merchants

GET /api/v1/merchants

Required scope: merchants:read. Rate limit: 60 requests per minute per API key.

Query parameters

Response

{
  "ok": true,
  "merchants": [ /* array of merchant objects, same shape as get */ ],
  "has_more": true,
  "limit": 50,
  "offset": 0
}

Response field reference

Every Merchants API endpoint returns the same shape.

What next?