API 레퍼런스: 송금과 송금 링크

대금을 지급하는 메서드예요. 송금은 앱 잔액에서 Telegram 사용자의 지갑으로 바로 보내고, 송금 링크는 미리 돈을 채워 두고 받아 가게 하는 링크예요. 공통 규칙(인증, 응답 형식, 금액, spend_id)은 Merchant API 레퍼런스에 있어요.

transfer

POST /pay/api/transfer — payouts 권한, 분당 30회. 바로, 한 번에 끝나요. 대기 상태 같은 건 없어요.

파라미터	타입	필수	설명
user_id	integer	예	받는 사람의 Telegram 사용자 id. 이미 앱을 쓰고 있는 사람이어야 해요 — 모르는 id로 보내면 돈이 붕 뜨는 대신 오류가 나요
asset	string	예	자산 코드
amount	string	예	양수 소수점 문자열. 플랫폼이 정한, 한 번에 보낼 수 있는 최소·최대 금액(현재 시세로 환산한 미국 달러 추정치)에도 걸려요
spend_id	string	예	멱등키, 1~64자, 지급 건마다 달라야 해요
comment	string	아니요	1024자까지, 받는 사람에게 보여요
disable_send_notification	boolean	아니요	true면 받는 사람에게 Telegram 알림을 보내지 않아요

결과는 송금 객체예요. transfer_id, hash, user_id, asset, amount, amount_minor, spend_id, comment, status(항상 completed), created_at, completed_at이 들어 있어요.

오류: 404 user_not_found(받는 사람이 앱을 한 번도 쓴 적 없을 때), 409 recipient_blocked, 400 amount_too_small / 400 amount_too_big(보낼 수 있는 범위를 벗어났을 때), 409 insufficient_funds, 404 unknown_asset, 400 invalid_amount, 그리고 spend_id 짝인 409 idempotency_conflict / 409 idempotency_in_progress.

transferBatch

POST /pay/api/transferBatch — payouts 권한, 분당 10회. 대량 지급용 확장 기능이에요. 한 번에 송금 100건까지 보낼 수 있어요.

파라미터는 items 하나예요. 배열이고, 항목마다 transfer의 파라미터를 한 벌씩 담아요(user_id, asset, amount, spend_id, 그리고 선택인 comment와 disable_send_notification). 배치 안에서 spend_id는 서로 달라야 하고, 겹치면 아무것도 실행되기 전에 400 duplicate_spend_id로 전체가 실패해요.

항목은 순서대로, 따로따로 처리돼요. 하나가 실패해도 나머지가 되돌려지지 않아요. 일부가 실패해도 호출 자체는 HTTP 200에 ok: true로 돌아오니까, 항목마다 꼭 확인해 주세요.

• 성공: {"ok": true, "spend_id": "…", "result": <transfer object>}
• 실패: {"ok": false, "spend_id": "…", "error": {"code": …, "name": "…"}} — 오류 이름은 단건 transfer와 같아요.

배치 항목은 단건 송금과 멱등 공간을 같이 써요. 배치 전체를 다시 보내거나, 항목 하나를 같은 spend_id로 단건 transfer에 다시 보내도 두 번 나가지 않고 원래 결과가 돌아와요.

getTransfers

GET /pay/api/getTransfers — read 권한. 필터: asset, transfer_ids(쉼표로 구분), spend_id(정확히 일치 — 내 키로 지급 건을 찾을 때 써요), 그리고 offset / count. {"items": [transfer, …]}를 최신순으로 돌려줘요.

createCheck

POST /pay/api/createCheck — checks 권한, 분당 60회. 앱 잔액에서 돈을 채운, 한 번만 쓸 수 있는 송금 링크를 만들어요. 링크를 가진 사람이면 누구나, 또는 지정한 사람만 자기 지갑으로 받아 갈 수 있어요. 금액은 만드는 순간 잠겨요(getBalance에서 available에서 onhold로 옮겨 가요).

파라미터	타입	필수	설명
asset	string	예	자산 코드
amount	string	예	양수 소수점 문자열
pin_to_user_id	integer	아니요	이 Telegram 사용자 id만 받아 갈 수 있어요
pin_to_username	string	아니요	이 @username만 받아 갈 수 있어요(@는 붙여도 되고 안 붙여도 돼요. pin_to_user_id도 함께 넣으면 무시돼요). 앱을 쓰고 있는 사람의 username이어야 해요
spend_id	string	아니요	멱등키(확장 기능) — 하나 넣어 주세요

결과는 송금 링크 객체예요. check_id, hash, asset, amount, amount_minor, bot_check_url(받아 가는 t.me 링크), status(active / activated), pin_to_user_id, created_at, activated_at이 들어 있어요. 누가 받아 가면 원할 때만 켜는 check_activated webhook이 발생해요.

오류: 404 unknown_asset, 400 invalid_amount, 404 user_not_found(지정한 username을 가진 사람이 없을 때), 409 insufficient_funds, 그리고 spend_id 짝이에요.

deleteCheck

POST /pay/api/deleteCheck — checks 권한. 파라미터는 check_id 하나예요. 아직 받아 가지 않은 송금 링크를 취소하고 잠겨 있던 금액을 앱 잔액으로 돌려줘요. true를 돌려줘요. 오류: 404 check_not_found, 409 check_not_active(이미 받아 갔거나 지운 경우).

getChecks

GET /pay/api/getChecks — read 권한. 필터: asset, check_ids(쉼표로 구분), status(active / activated), 그리고 offset / count. {"items": [check, …]}를 최신순으로 돌려줘요. 지운 송금 링크는 나오지 않아요.