Merchant API 수수료와 한도

청구서에는 받는 금액에서 떼는 서비스 수수료가 붙고, 송금과 송금 링크에는 금액 한도가 걸려요. 아래 숫자는 지금 설정된 값이지 계약 조건이 아니에요. 앱 화면과 다르면 앱이 맞고, 가장 믿을 만한 근거는 언제나 결제 완료된 본인의 청구서예요.

청구서 수수료

내는 사람은 언제나 청구서의 액면 금액을 그대로 내요. 수수료는 가맹점 쪽에서 빠져요. 앱 잔액에는 수수료를 뺀 금액이 들어와요.

기본 수수료율: 3%. 설정된 구간과 최근 30일의 결제 완료 청구서 거래액에 따라 실제 요율이 달라져요.

30일 거래량	수수료
$10,000 미만	3%
$10,000 이상	2.9%
$25,000 이상	2.8%
$50,000 이상	2.7%
$75,000 이상	2.6%
$100,000 이상	2.5%

숫자보다 중요한 규칙이 두 가지 있어요.

수수료는 결제하는 시점에 정해져서 그대로 굳어요. 나중에 요율이 바뀌어도 이미 결제된 청구서는 건드리지 않아요.
결제액이 늘면 요율도 달라져요. 최근 30일 결제액이 많아지면 자동으로 낮은 구간으로 옮겨 가요. 신청할 것도, 설정할 것도 없어요.

실제로 얼마가 빠졌는지 보려면 결제된 청구서의 fee_asset과 fee_amount를 읽어 보세요. invoice_paid 웹훅의 페이로드에도, getInvoices 응답에도 들어 있어요. 장부에 쓸 값은 이거예요.

환불해도 수수료는 돌아오지 않아요. refundInvoice로 나가는 돈은 내 잔액에서 빠지고, 수수료는 부분 환불이든 전액 환불이든 돌려주지 않아요.

구독 결제에도 가맹점 쪽 수수료가 붙어요. 건별 금액은 subscription_charged 웹훅의 charge.fee 필드에 들어 있어요.

송금 한도

transfer에는 한 번에 보낼 수 있는 최소·최대 금액이 걸려요. 자산별 숫자가 아니라 USD 환산 금액을 기준으로 해요. 금액이 한도를 벗어나 거절될 경우에 대비해 연동에서 amount_too_small과 amount_too_big을 처리해 주세요.

알 수 없는 username은 지급 모드가 허용하면 대기 중인 지급을 만들어요. 송금과 송금 링크를 참고하세요.

이럴 때도 송금이 실패해요.

그 자산의 앱 잔액이 부족할 때,
받는 사람이 앱을 쓰고 있지 않을 때 — 모르는 Telegram ID나 잘못 적은 ID로 보내면 아무도 열지 않을 지갑에 넣는 대신 오류가 나요,
받는 사람의 계정이 차단됐을 때.

일일 지급 한도

소유자는 앱의 지급 설정에서 최근 24시간 기준 한도를 정할 수 있어요. 송금, 송금 링크, 앱 잔액에서의 지급이 한도를 함께 사용해요. 초과하면 403 daily_cap_exceeded가 반환되며 배치는 첫 지급 전에 검사해요. 환불은 이 한도에 포함되지 않아요. getMe는 daily_payout_max_usd_cents와 daily_payout_spent_usd_cents를 반환해요.

소유자의 계정 제한으로 송금, 송금 링크, 환불이 막힐 수도 있어요(403 verification_required). 일시 중단 상태에는 503 merchant_payouts_paused가 반환돼요.

호출 한도

자산을 이동하는 메서드의 호출 한도는 앱 단위로 적용되며 모든 토큰이 함께 사용해요. 분당 한도는 createInvoice와 createCheck가 60회, refundInvoice가 30회, transfer가 30회, transferBatch가 10회예요. updateApp과 createSubscriptionPlan에도 한도가 있어요. API 레퍼런스를 참고하세요. rate_limited가 반환되면 재시도 간격을 늘리세요.

멱등키

transfer에는 직접 만든 **spend_id**가 꼭 있어야 하고, createCheck와 refundInvoice도 받아 줘요. 같은 값과 같은 파라미터로 다시 요청하면 돈이 한 번 더 나가는 대신 원래 결과가 그대로 돌아와요. 그래서 응답이 늦은 요청은 같은 spend_id로 다시 보내면 안전하고, 진짜 새로운 지급에만 새 값을 주면 돼요.

돈이 안 드는 것

Merchant API에는 네트워크 수수료가 아예 없어요. 청구서도, 송금도, 송금 링크도 체인이 아니라 앱 안에서 끝나거든요. 청구서와 구독 결제에는 플랫폼 수수료가 붙을 수 있어요. 선택 사항인 자동 교환은 교환 가격을 사용해요. 결제자의 지갑을 외부 지갑에서 충전하면 해당 지갑이나 네트워크의 수수료가 발생할 수 있어요.

⚠️ 수수료를 직접 계산하지 마세요

퍼센트를 코드에 박아 두거나, 액면 금액에서 실수령액을 거꾸로 계산하지 마세요. 구간과 요율은 바뀌고, 예전 값을 계속 쓰면 회계 기록이 틀릴 수 있어요. 수수료는 매번 청구서에 기록된 값을 읽어 주세요.