Documentación de la API

Introducción

La API de Payman es una API REST en JSON. Todas las solicitudes van a https://payman33.com/v1 por HTTPS.

Autenticación

Envía como token bearer el token de acceso que recibiste al crear tu cuenta. Se muestra una sola vez y no se puede volver a emitir, así que mantenlo en secreto y nunca lo pongas en código del lado del cliente.

Authorization: Bearer pm_live_xxxxxxxxxxxxxxxx

Enviar un mensaje

POST /messages

Campo	Tipo	Descripción
`to`	string[]	Destinatarios en formato E.164. Hasta 10,000 por petición.
`text`	string	Cuerpo del mensaje: un SMS, hasta 160 caracteres (GSM-7), o 70 si contiene cualquier otra letra o emojis. Un texto más largo se rechaza.
`schedule_at`	string	Opcional. Hora ISO-8601 para enviar más tarde, hasta con 30 días de antelación.
`callback_url`	string	URL HTTPS opcional que recibe los informes de entrega.

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

Añade un encabezado Idempotency-Key para reintentar de forma segura: la misma clave en un plazo de 24 horas devuelve la respuesta original en lugar de volver a enviar.

Estado del mensaje

GET /messages/{id}

Estados: queued, luego sent y después delivered o failed. Un mensaje programado permanece en scheduled hasta que se envía; puedes cancelarlo (y recuperar el cargo) con POST /messages/{id}/cancel.

Webhooks

Cuando llega un informe de entrega, lo enviamos con POST a tu callback_url. Cada solicitud lleva una cabecera X-Payman-Signature: el HMAC-SHA256 del cuerpo con tu secreto de webhook (Panel, pestaña API), para que puedas verificarla. Las entregas fallidas se reintentan hasta 3 veces.

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

Saldo

GET /balance

Devuelve tu saldo actual en USDT. Los precios se indican en USD; 1 USDT = 1 USD.

Errores

HTTP	Código	Significado
400	`invalid_request`	Falta un campo o tiene un formato incorrecto.
401	`unauthorized`	Clave API ausente o no válida.
402	`insufficient_balance`	Recarga saldo para seguir enviando.
403	`verification_required`	Las cuentas no verificadas han alcanzado el límite de destinatarios de hoy.
404	`not_found`	No existe ese mensaje en tu cuenta.
429	`rate_limited`	Demasiadas solicitudes. Vuelve a intentarlo cuando indique la cabecera `Retry-After`.

Límites de peticiones

El límite predeterminado es de 50 solicitudes por segundo por cuenta. Usa envíos masivos (varios números en to) para campañas grandes. Las cuentas no verificadas pueden enviar a hasta 500 destinatarios al día.