Merchant API 수수료와 한도

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

청구서 수수료

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

수수료율은 **1.5%**예요. 모든 청구서에 같은 요율이 적용되고, 거래액에 따른 할인은 없어요.

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

• 수수료는 결제하는 시점에 정해져서 그대로 굳어요. 나중에 요율이 바뀌어도 이미 결제된 청구서는 건드리지 않아요.
• 수수료는 자산의 최소 단위로 내림해요. 그래서 아주 작은 청구서에는 수수료가 붙지 않을 수도 있어요.

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

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

구독 요금이 청구될 때도 가맹점 수수료가 붙을 수 있어요. 현재 수수료는 0%예요. 각 청구의 수수료는 subscription_charged 웹훅의 charge.fee 필드에 나와요.

송금 한도

transfer의 건별 송금 상한은 $25,000예요. 자산마다 별도 금액을 정하는 대신 미국 달러 환산액으로 적용해요. 건별 하한도 설정할 수 있지만 현재는 없어요. 이 한도로 금액이 거절되면 연동 코드에서 amount_too_big을 처리하세요. 나중에 하한이 생기면 amount_too_small도 처리해야 해요(둘 다 400이에요). 지금 미국 달러 시세가 없는 자산에는 상한이 적용되지 않아요.

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

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

• 그 자산의 앱 잔액이 부족할 때,
• 받는 사람이 TgPay Crypto를 한 번도 연 적이 없을 때 — 모르는 Telegram ID나 잘못 적은 ID로 보내면 아무도 열지 않을 지갑에 넣는 대신 오류가 나요,
• 받는 사람의 계정이 차단됐을 때 — 똑같이 404 user_not_found로 알려 줘요.

일일 지급 한도

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

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

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