API Quick Reference

Quick-scan catalog of every 3PAY merchant API endpoint.

Base URLs

Environment	Base URL
Production	`https://pay.3pa-y.com/api/v1`
Sandbox	Available in your sandbox dashboard

All endpoints require the apikey header. Some require x-api-secret. See Authentication & Security for full details.

Method	Path	Rate Limit	Description
`POST`	`/transaction/create`	Wallet Gen (20/15min)	Create a payment link with unique wallet address
`GET`	`/public/transaction/verify`	Standard (100/15min)	Check transaction status by ID
`GET`	`/public/transaction/list`	Standard (100/15min)	List merchant transactions (max 100/page)
`POST`	`/public/transaction/cancel`	Standard (100/15min)	Cancel an initiated transaction

Method	Path	Rate Limit	Description
`POST`	`/public/wallet/generate`	Wallet Gen (20/15min)	Generate persistent wallet for a user
`GET`	`/public/wallet/view/{userId}`	Standard (100/15min)	Get wallet details and addresses
`GET`	`/public/wallet/balance/{userId}`	Standard (100/15min)	Check user's current balance
`POST`	`/public/wallet/updateBalance`	Financial (30/15min)	Manually adjust user balance
`GET`	`/public/user/transaction/list`	Standard (100/15min)	List transactions for a specific user

Method	Path	Auth	Rate Limit	Description
`POST`	`/public/user/withdrawal/create`	API Key	Financial (30/15min)	Create user withdrawal (auto-approved)
`GET`	`/public/withdrawal-requests`	API Key	Standard (100/15min)	List pending withdrawal requests
`POST`	`/public/withdrawal-requests/{id}/approve`	API Key + Secret	Financial (30/15min)	Approve pending withdrawal
`POST`	`/public/withdrawal-requests/{id}/reject`	API Key + Secret	Financial (30/15min)	Reject pending withdrawal
`GET`	`/public/payout/get`	API Key	Standard (100/15min)	Query payout details (read-only)
~~`POST`~~	~~`/public/payout/create`~~	—	—	DISABLED — use dashboard with 2FA

These use JWT authentication (dashboard session), not API Key.

Method	Path	Description
`PUT`	`/webhook/url`	Update your webhook URL
`POST`	`/webhook/test`	Send a test webhook to your endpoint
`GET`	`/webhook/events`	View webhook delivery history (max 100/page)
`POST`	`/webhook/retry/{webhookEventId}`	Manually retry a failed webhook
`GET`	`/webhook/secret`	View your webhook secret (masked)
`POST`	`/webhook/secret/rotate`	Generate a new webhook secret

Method	Path	Rate Limit	Description
`GET`	`/public/getMerchantDetails`	Standard (100/15min)	Get your merchant profile info

These endpoints return 404:

Endpoint	Reason
`POST /public/payout/create`	Payouts moved to dashboard-only with 2FA
`/refund/*`	Refund feature disabled
`/token/mint`, `/token/burn`	Goldy tokenization archived
`/test-notifications/*`	Debug endpoints removed

Status	Meaning	Example Message
`400`	Validation error	`Missing required field: amount`
`401`	Missing/invalid API key or secret	`API key required`
`404`	Invalid ID or disabled endpoint	`Resource not found`
`429`	Rate limit exceeded	`API rate limit exceeded. Try again in 15 minutes.`
`500`	Server error	`Internal server error`

All errors follow the format:

{ "success": false, "message": "Error description here" }

All list endpoints accept these query parameters:

Parameter	Type	Default	Max	Description
`page`	integer	1	—	Page number
`limit`	integer	10–50	100	Results per page (capped server-side)
`status`	string	—	—	Filter by status
`search`	string	—	—	Search by relevant fields
`sortBy`	string	`createdAt`	—	Sort field: `createdAt`, `updatedAt`, `amount`, `status`, `confirmedAt`
`sortOrder`	string	`desc`	—	`asc` or `desc`

Invalid sortBy values silently fall back to createdAt.