API documentation

Introduction

The Payman API is a JSON REST API. All requests go to https://payman33.com/v1 over HTTPS.

Authentication

Send the access token you received when you created your account as a bearer token. It is shown only once and can't be reissued, so keep it secret and never put it in client-side code.

Authorization: Bearer pm_live_xxxxxxxxxxxxxxxx

Send a message

POST /messages

Field	Type	Description
`to`	string[]	Recipients in E.164 format. Up to 10,000 per request.
`text`	string	Message body: one SMS, up to 160 characters (GSM-7), or 70 if it contains any other letters or emoji. Longer text is rejected.
`schedule_at`	string	Optional ISO-8601 time to send later, up to 30 days ahead.
`callback_url`	string	Optional HTTPS URL that receives delivery reports.

{
  "id": "msg_01J9Z3K8V2",
  "status": "queued",
  "recipients": 1,
  "segments": 1,
  "cost": 0.0063
}

Add an Idempotency-Key header to retry safely: the same key within 24 hours returns the original response instead of sending again.

Message status

GET /messages/{id}

Statuses: queued, then sent, then delivered or failed. A scheduled message stays scheduled until it goes out; cancel it (and get the charge back) with POST /messages/{id}/cancel.

Webhooks

When a delivery report arrives we POST it to your callback_url. Each request carries an X-Payman-Signature header: the HMAC-SHA256 of the body with your webhook secret (Dashboard, API tab), so you can verify it. Failed deliveries are retried up to 3 times.

{
  "id": "msg_01J9Z3K8V2",
  "to": "+14155550123",
  "status": "delivered",
  "delivered_at": "2026-10-09T08:12:03Z"
}

Balance

GET /balance

Returns your current balance in USDT. Prices are listed in USD; 1 USDT = 1 USD.

Errors

HTTP	Code	Meaning
400	`invalid_request`	Missing or malformed field.
401	`unauthorized`	Missing or invalid API key.
402	`insufficient_balance`	Top up to continue sending.
403	`verification_required`	Unverified accounts have reached today's recipient limit.
404	`not_found`	No such message on your account.
429	`rate_limited`	Too many requests. Retry after the `Retry-After` header.

Rate limits

Default limit is 50 requests per second per account. Use bulk sends (multiple numbers in to) for large campaigns. Unverified accounts can send to up to 500 recipients per day.