Documentation API

Introduction

L'API Payman est une REST API JSON. Toutes les requêtes sont envoyées à https://payman33.com/v1 via HTTPS.

Authentification

Envoyez le jeton d'accès reçu lors de la création de votre compte en tant que jeton Bearer. Il n'est affiché qu'une seule fois et ne peut pas être réémis : gardez-le secret et ne le placez jamais dans du code côté client.

Authorization: Bearer pm_live_xxxxxxxxxxxxxxxx

Envoyer un message

POST /messages

Champ	Type	Description
`to`	string[]	Destinataires au format E.164. Jusqu'à 10,000 par requête.
`text`	string	Corps du message : un SMS, jusqu'à 160 caractères (GSM-7), ou 70 s'il contient d'autres lettres ou des emojis. Un texte plus long est rejeté.
`schedule_at`	string	Heure ISO-8601 facultative pour un envoi différé, jusqu'à 30 jours à l'avance.
`callback_url`	string	URL HTTPS facultative qui reçoit les rapports de livraison.

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

Ajoutez un en-tête Idempotency-Key pour réessayer sans risque : la même clé dans un délai de 24 heures renvoie la réponse d'origine au lieu de renvoyer le message.

Statut des messages

GET /messages/{id}

Statuts : d'abord queued, puis sent, puis delivered ou failed. Un message planifié reste scheduled jusqu'à son envoi ; annulez-le (et récupérez le montant débité) avec POST /messages/{id}/cancel.

Webhooks

Lorsqu'un rapport de livraison arrive, nous l'envoyons en POST à votre callback_url. Chaque requête comporte un en-tête X-Payman-Signature : le HMAC-SHA256 du corps calculé avec votre secret de webhook (tableau de bord, onglet API), afin que vous puissiez la vérifier. Les livraisons échouées sont retentées jusqu'à 3 fois.

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

Solde

GET /balance

Renvoie votre solde actuel en USDT. Les prix sont indiqués en USD ; 1 USDT = 1 USD.

Erreurs

HTTP	Code	Signification
400	`invalid_request`	Champ manquant ou mal formé.
401	`unauthorized`	Clé API manquante ou invalide.
402	`insufficient_balance`	Rechargez votre solde pour continuer à envoyer.
403	`verification_required`	Les comptes non vérifiés ont atteint la limite de destinataires du jour.
404	`not_found`	Aucun message correspondant sur votre compte.
429	`rate_limited`	Trop de requêtes. Réessayez après le délai indiqué par l'en-tête `Retry-After`.

Limites de débit

La limite par défaut est de 50 requêtes par seconde et par compte. Utilisez les envois groupés (plusieurs numéros dans to) pour les grandes campagnes. Les comptes non vérifiés peuvent envoyer à 500 destinataires maximum par jour.