API 문서 | Payman

소개

Payman API는 JSON REST API입니다. 모든 요청은 HTTPS를 통해 https://payman33.com/v1로 전송됩니다.

인증

계정을 만들 때 받은 액세스 토큰을 Bearer 토큰으로 보내세요. 토큰은 한 번만 표시되며 다시 발급할 수 없으니, 비밀로 유지하고 클라이언트 코드에는 절대 넣지 마세요.

Authorization: Bearer pm_live_xxxxxxxxxxxxxxxx

메시지 발송

POST /messages

필드	유형	설명
`to`	string[]	E.164 형식의 수신자. 요청당 최대 10,000개.
`text`	string	메시지 본문: 문자 1건, 최대 160자(GSM-7), 그 밖의 글자나 이모지가 들어가면 70자예요. 더 긴 글은 거부돼요.
`schedule_at`	string	선택 사항. 나중에 보낼 ISO-8601 시각 (최대 30일 이후까지).
`callback_url`	string	선택 사항. 전달 리포트를 받을 HTTPS URL.

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

Idempotency-Key 헤더를 붙이면 안전하게 재시도할 수 있습니다: 24시간 안에 같은 키로 보내면 다시 발송하지 않고 처음 응답을 돌려줍니다.

메시지 상태

GET /messages/{id}

상태는 queued, 그다음 sent, 그다음 delivered 또는 failed 순서로 바뀝니다. 예약 메시지는 나가기 전까지 scheduled 상태이며, POST /messages/{id}/cancel로 취소하면 비용이 환불됩니다.

웹훅

전송 리포트가 도착하면 callback_url로 POST합니다. 각 요청에는 X-Payman-Signature 헤더가 붙습니다. 본문을 웹훅 시크릿(대시보드의 API 탭)으로 HMAC-SHA256 한 값이므로 이것으로 검증할 수 있습니다. 전달에 실패하면 최대 3번 다시 보냅니다.

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

잔액

GET /balance

현재 잔액을 USDT로 반환합니다. 요금은 USD로 표시되며 1 USDT = 1 USD입니다.

오류

HTTP	코드	의미
400	`invalid_request`	필드가 없거나 형식이 잘못되었습니다.
401	`unauthorized`	API 키가 없거나 유효하지 않습니다.
402	`insufficient_balance`	계속 발송하려면 잔액을 충전하세요.
403	`verification_required`	미인증 계정의 오늘 수신자 한도에 도달했습니다.
404	`not_found`	계정에 해당 메시지가 없습니다.
429	`rate_limited`	요청이 너무 많습니다. `Retry-After` 헤더에 표시된 시간 후 다시 시도하세요.

요청 한도

기본 한도는 계정당 초당 50건입니다. 대규모 캠페인에는 대량 발송(to에 여러 번호 지정)을 사용하세요. 미인증 계정은 하루 500명까지 보낼 수 있습니다.