Documentação da API

Introdução

A API do Payman é uma API REST em JSON. Todas as solicitações vão para https://payman33.com/v1 via HTTPS.

Autenticação

Envie como token bearer o token de acesso que você recebeu ao criar sua conta. Ele é exibido apenas uma vez e não pode ser emitido novamente, então mantenha-o em segredo e nunca o coloque em código do lado do cliente.

Authorization: Bearer pm_live_xxxxxxxxxxxxxxxx

Enviar uma mensagem

POST /messages

Campo	Tipo	Descrição
`to`	string[]	Destinatários no formato E.164. Até 10.000 por requisição.
`text`	string	Corpo da mensagem: um SMS, até 160 caracteres (GSM-7), ou 70 se contiver quaisquer outras letras ou emojis. Textos mais longos são rejeitados.
`schedule_at`	string	Opcional. Horário ISO-8601 para envio posterior, até 30 dias à frente.
`callback_url`	string	Opcional. URL HTTPS que recebe os relatórios de entrega.

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

Adicione um header Idempotency-Key para repetir com segurança: a mesma chave em até 24 horas retorna a resposta original em vez de enviar novamente.

Status da mensagem

GET /messages/{id}

Status: queued, depois sent e então delivered ou failed. Uma mensagem agendada fica em scheduled até ser enviada; cancele-a (e receba o valor de volta) com POST /messages/{id}/cancel.

Webhooks

Quando chega um relatório de entrega, nós o enviamos com POST para a sua callback_url. Cada solicitação traz um cabeçalho X-Payman-Signature: o HMAC-SHA256 do corpo com o seu segredo de webhook (Painel, aba API), para que você possa verificá-la. Entregas com falha são reenviadas até 3 vezes.

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

Saldo

GET /balance

Retorna seu saldo atual em USDT. Os preços são informados em USD; 1 USDT = 1 USD.

Erros

HTTP	Código	Significado
400	`invalid_request`	Campo ausente ou malformado.
401	`unauthorized`	Chave de API ausente ou inválida.
402	`insufficient_balance`	Recarregue para continuar enviando.
403	`verification_required`	A conta não verificada atingiu o limite de destinatários de hoje.
404	`not_found`	Mensagem não encontrada na sua conta.
429	`rate_limited`	Muitas solicitações. Tente novamente após o tempo indicado no cabeçalho `Retry-After`.

Limites de requisição

O limite padrão é de 50 requisições por segundo por conta. Use envios em massa (vários números em to) para campanhas grandes. Contas não verificadas podem enviar para até 500 destinatários por dia.