Overview

The Merchant API lets your service create users, record the USDC payouts you send them, and hear back from Zay through webhooks.

New to the API? Start with Get started.

Base URLs

Environment	Merchant API	Onboarding
Staging	https://api-connect.zay.me	https://privy-stag.zay.me
Production	https://api.zay.me	https://privy.zay.me

Staging and production have separate credentials. Every example in these docs uses staging.

Requests

• All endpoints are versioned under /merchants/v1.
• Use HTTPS for every call — unencrypted traffic is rejected at the edge.
• Request and response bodies are JSON (content-type: application/json).
• Every request is signed — see Authentication.

Endpoints

Endpoint	Operation
POST /merchants/v1/users	Create user
GET /merchants/v1/users/{id}	Retrieve user
GET /merchants/v1/users	List users
GET /merchants/v1/users/by_wallet_address	Look up user by wallet address
GET /merchants/v1/users/{id}/balance	Retrieve user balance
POST /merchants/v1/payouts/report	Report a payout
GET /merchants/v1/payouts	List payouts
GET /merchants/v1/payouts/{id}	Retrieve payout
POST /merchants/v1/events	Submit events
POST /merchants/v1/webhook_endpoints	Register webhook endpoint
GET /merchants/v1/webhook_endpoints	List webhook endpoints
GET /merchants/v1/webhook_endpoints/{id}	Retrieve webhook endpoint
PATCH /merchants/v1/webhook_endpoints/{id}	Update webhook endpoint
DELETE /merchants/v1/webhook_endpoints/{id}	Delete webhook endpoint
POST /merchants/v1/webhook_endpoints/{id}/test_delivery	Trigger test delivery

Zay also sends events to you — see the Event catalog.