Documentazione API

Introduzione

L'API di Payman è un'API REST in JSON. Tutte le richieste vanno a https://payman33.com/v1 tramite HTTPS.

Autenticazione

Invia come bearer token il token di accesso ricevuto alla creazione dell'account. Viene mostrato una sola volta e non può essere emesso di nuovo, quindi tienilo segreto e non inserirlo mai nel codice lato client.

Authorization: Bearer pm_live_xxxxxxxxxxxxxxxx

Inviare un messaggio

POST /messages

Campo	Tipo	Descrizione
`to`	string[]	Destinatari in formato E.164. Fino a 10,000 per richiesta.
`text`	string	Corpo del messaggio: un SMS, fino a 160 caratteri (GSM-7), o 70 se contiene altre lettere o emoji. Un testo più lungo viene rifiutato.
`schedule_at`	string	Facoltativo. Orario ISO-8601 per l'invio differito, fino a 30 giorni in anticipo.
`callback_url`	string	Facoltativo. URL HTTPS che riceve i report di consegna.

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

Aggiungi un header Idempotency-Key per ritentare in sicurezza: la stessa chiave entro 24 ore restituisce la risposta originale invece di inviare di nuovo.

Stato del messaggio

GET /messages/{id}

Stati: queued, poi sent, quindi delivered o failed. Un messaggio programmato resta scheduled finché non viene inviato; puoi annullarlo (e riavere l'addebito) con POST /messages/{id}/cancel.

Webhook

Quando arriva un report di consegna, lo inviamo con POST alla tua callback_url. Ogni richiesta contiene un header X-Payman-Signature: l'HMAC-SHA256 del corpo con il tuo segreto webhook (Dashboard, scheda API), così puoi verificarla. Le consegne non riuscite vengono ritentate fino a 3 volte.

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

Credito

GET /balance

Restituisce il tuo credito attuale in USDT. I prezzi sono espressi in USD; 1 USDT = 1 USD.

Errori

HTTP	Codice	Significato
400	`invalid_request`	Campo mancante o non valido.
401	`unauthorized`	Chiave API mancante o non valida.
402	`insufficient_balance`	Ricarica il credito per continuare a inviare.
403	`verification_required`	L'account non verificato ha raggiunto il limite di destinatari di oggi.
404	`not_found`	Messaggio non trovato nel tuo account.
429	`rate_limited`	Troppe richieste. Riprova dopo il tempo indicato nell'header `Retry-After`.

Limiti di richieste

Il limite predefinito è di 50 richieste al secondo per account. Per campagne di grandi dimensioni usa gli invii multipli (più numeri in to). Gli account non verificati possono inviare fino a 500 destinatari al giorno.