Card Payment & Settlement

— CARD (USD) · DEX V2 FIAT LEDGER · ON-CHAIN PAYOUT PROOF —

How a credit card payment for your app is processed off-chain, how it is recorded on-chain as a USD ledger, how the platform pays you, and how you can verify every step yourself. 내 앱의 신용카드 결제가 오프체인에서 어떻게 처리되고, 온체인 달러 원장에 어떻게 기록되며, 플랫폼이 어떻게 정산하고, 개발자가 각 단계를 어떻게 직접 확인하는지 설명합니다.

1 Overview 개요

A card payment moves no coins. The money stays in the card network and the platform's bank account. The blockchain is used only as a USD settlement ledger: every sale, refund and payout is written to the dex v2 contract so that neither side can change the numbers later. 카드 결제는 코인을 송금하지 않습니다. 돈은 카드망과 플랫폼 은행 계좌에서만 움직입니다. 블록체인은 달러 정산 원장으로만 쓰입니다. 판매·환불·정산이 모두 dex v2 컨트랙트에 기록되므로 어느 쪽도 나중에 숫자를 바꿀 수 없습니다.

  • The currency is fixed to USD cents (integers). $10.00 is stored as 1000. 통화는 USD 센트(정수)로 고정입니다. $10.00 은 1000 으로 저장됩니다.
  • Each app has a monetization type: FREE, XOTN, CARD or BOTH. A free app has no ledger entries, so there is nothing to settle. 앱마다 수익화 방식이 있습니다. FREE·XOTN·CARD·BOTH 중 하나입니다. 무료 앱은 원장 기록이 없으므로 정산할 것도 없습니다.
  • Only the platform key can write to the ledger. You read it on the Settlements page. 원장에는 플랫폼 키만 쓸 수 있습니다. 개발자는 Settlements 메뉴에서 읽습니다.

2 Before you can receive card revenue 카드 매출을 받기 위한 전제 조건

  1. Set Monetization to CARD or BOTH in Register App or in My Applications. Register App 또는 My Applications 에서 수익화 방식을 CARD 또는 BOTH 로 지정합니다.
  2. In My Applications, click 🔑 Verify Ownership and enter your wallet PIN. The app shows the ✓ OWNER VERIFIED (AA) badge. My Applications 에서 🔑 Verify Ownership 을 누르고 지갑 PIN 을 입력합니다. 앱에 ✓ OWNER VERIFIED (AA) 배지가 붙습니다.
  3. Click ⛓ Register on-chain and enter the PIN again. The platform key registers your app's provider on the dex v2 contract with your AA wallet address as the owner. You do not pay gas or sign a transaction. The app then shows the ⛓ ON-CHAIN badge. ⛓ Register on-chain 을 누르고 PIN 을 한 번 더 입력합니다. 플랫폼 키가 대신 호출해 dex v2 컨트랙트에 앱의 provider 를 등록하고, owner 는 개발자 AA 지갑 주소가 됩니다. 개발자가 가스비를 내거나 트랜잭션에 서명할 필요는 없습니다. 등록 뒤에는 ⛓ ON-CHAIN 배지가 붙습니다.

If the app is not registered on-chain, a sale cannot be recorded. The contract reverts with Provider not registered (code PROVIDER_NOT_REGISTERED). 온체인 등록을 하지 않은 앱은 판매를 기록할 수 없습니다. 컨트랙트가 Provider not registered(코드 PROVIDER_NOT_REGISTERED)로 revert 합니다.

3 Off-chain flow: payment to record 오프체인 흐름. 결제에서 기록까지

1
Card payment카드 결제
The user pays in USD through the PG (payment gateway). 사용자가 PG(결제 대행사)로 달러 결제합니다.
→
2
A serverA 서버
Checks that the slot belongs to the app and the PG fee does not exceed the gross. 슬롯이 그 앱 소속인지, PG 수수료가 결제액을 넘지 않는지 확인합니다.
→
3
B serverB 서버
Signs with the platform key. orderId = keccak256(PG transaction no.). 플랫폼 키로 서명합니다. orderId = keccak256(PG 거래번호).
→
4
dex v2dex v2
record_fiat_sale updates the ledger and emits FiatSale. record_fiat_sale 가 원장을 갱신하고 FiatSale 이벤트를 남깁니다.
→
  • The on-chain order key is keccak256(utf8(PG transaction number)). The same PG number always gives the same key, so one payment can be recorded only once (FIAT_ORDER_EXISTS). 온체인 주문 키는 keccak256(utf8(PG 거래번호)) 입니다. 같은 PG 거래번호는 항상 같은 키가 되므로 결제 1건은 한 번만 기록됩니다(FIAT_ORDER_EXISTS).
  • The PG webhook is not connected yet. For now an operator enters each sale by hand in the admin screen (gross and PG fee in USD). PG 웹훅은 아직 연결되지 않았습니다. 지금은 운영자가 운영자 화면에서 판매를 1건씩 수동으로 입력합니다(결제액·PG 수수료는 달러 단위).

Refund and payout timing. Refunds are accepted for 15 days after payment. Payouts are made 30 days after payment. So a refund always happens before the payout. The contract does not count days. It enforces the rule by rejecting a refund when the remaining pending balance is smaller than that order's share (FIAT_ALREADY_SETTLED). Such a case is handled manually by the platform. 환불과 정산 시점. 환불은 결제 후 15일 안에만 받습니다. 정산은 결제 30일 후에 합니다. 그래서 환불은 항상 정산 전에 일어납니다. 컨트랙트가 날짜를 세지는 않습니다. 대신 남은 미지급액이 그 주문의 개발자 몫보다 작으면 환불을 거부(FIAT_ALREADY_SETTLED)하는 방식으로 이 규칙을 강제합니다. 이런 경우는 플랫폼이 수동으로 처리합니다.

4 On-chain ledger 온체인 원장

The dex v2 contract keeps one FiatLedger per app (keyed by the app's on-chain cuid). All values are cumulative USD cents. dex v2 컨트랙트는 앱마다(온체인 cuid 기준) FiatLedger 하나를 둡니다. 모든 값은 누적 USD 센트입니다.

Field필드Settlements label정산 화면 표시Meaning의미
grossCents Gross sales Total amount paid by card카드 결제 총액
pgFeeCents PG fees Total PG feesPG 수수료 합계
shareCents Developer share Your share of every recorded sale기록된 판매 전체의 개발자 몫
refundedShareCents Refunded Share cancelled by refunds환불로 취소된 몫
settledCents Settled Amount already paid out to you이미 지급된 금액
pending Pending payout share − refundedShare − settled. Never negative.share − refundedShare − settled. 음수가 될 수 없습니다.

How your share is calculated 개발자 몫 계산 

share = floor( (gross − pgFee) × rateBps / 10000 )     // rateBps default 8500 = 85%
  • The share is based on the net amount after the PG fee. Integer division rounds down to the cent. 개발자 몫은 PG 수수료를 뺀 순액 기준입니다. 정수 나눗셈이라 센트 미만은 버립니다.
  • The rate is stored in the contract and only the platform can change it (set_share_rate_bps). Each order keeps a snapshot of the rate at the time it was recorded, so a rate change applies only to later orders. 비율은 컨트랙트에 저장되며 플랫폼만 바꿀 수 있습니다(set_share_rate_bps). 주문마다 기록 시점의 비율을 스냅샷으로 저장하므로, 비율을 바꿔도 이후 주문에만 적용됩니다.
  • On a sale, the app's content tokens move from the provider to the buyer's slot. On a refund, tokens come back only up to the slot's unused balance. 판매 시 앱의 콘텐츠 토큰이 provider 에서 구매자 슬롯으로 이동합니다. 환불 시 토큰은 슬롯의 미사용분 한도에서만 회수됩니다.

Example: one $10.00 sale 예시. $10.00 판매 1건 

gross   = 1000 cents ($10.00)
pgFee   =   30 cents ($0.30)
net     = 1000 − 30           = 970 cents
share   = floor(970 × 8500 / 10000)
        = floor(824.5)        = 824 cents
pending = 824 − 0 − 0         → Pending payout shows $8.24

Events 이벤트

Event이벤트Fields필드
FiatSale cuid, orderId, slot, grossCents, pgFeeCents, shareCents, rateBps, tokenAmount
FiatRefund cuid, orderId, shareCents, tokenReturned
FiatSettled cuid, amountCents, settlementRef, receiptHash, periodStart, periodEnd
ShareRateChanged oldBps, newBps

5 Payout (done by the operator) 정산 실행(운영자)

The platform operator pays you by bank transfer outside the chain, then records the payout on-chain with proof of the transfer. 플랫폼 운영자가 체인 밖에서 은행 송금으로 지급한 뒤, 송금 증빙과 함께 정산을 온체인에 기록합니다.

1
Bank transfer은행 송금
The operator pays an app with Pending payout above $0. 운영자가 미지급액이 $0 보다 큰 앱에 송금합니다.
→
2
Settle form정산 입력
Amount, reference, period and the transfer receipt. 금액·참조번호·기간·송금 영수증을 입력합니다.
→
3
A serverA 서버
Stores the file and computes its sha256. 파일을 보관하고 sha256 을 계산합니다.
→
4
dex v2dex v2
settle_fiat adds to Settled and emits FiatSettled with a tx_hash. settle_fiat 이 정산 완료액을 늘리고 FiatSettled 를 남깁니다(tx_hash 발급).
→
Input입력Rule규칙
Amount Greater than 0 and not more than Pending payout. The contract rejects anything else (INVALID_SETTLE_AMOUNT).0 보다 크고 미지급액 이하여야 합니다. 그 밖의 값은 컨트랙트가 거부합니다(INVALID_SETTLE_AMOUNT).
Settlement reference UTF-8, 31 bytes or less, stored on-chain as bytes32. It cannot be reused for the same app (SETTLEMENT_REF_EXISTS).UTF-8 31바이트 이하이며 온체인에 bytes32 로 저장됩니다. 같은 앱에서 다시 쓸 수 없습니다(SETTLEMENT_REF_EXISTS).
Period from / to The sales period this payout covers, entered by the operator.이번 정산이 다루는 판매 기간이며 운영자가 입력합니다.
Receipt pdf, png or jpg, up to 10MB.pdf·png·jpg, 최대 10MB.

The receipt file itself is kept on the A server. Only its sha256 hash goes on-chain. Anyone who has the file can prove it is the same file the operator recorded. 영수증 파일 자체는 A 서버에 보관하고, 체인에는 sha256 해시만 올라갑니다. 파일을 가진 사람은 누구나 운영자가 기록한 파일과 같은 파일인지 증명할 수 있습니다.

6 How to check your settlements 개발자의 정산 확인 방법

Open Settlements in the sidebar. You need to be signed in. 사이드바의 Settlements 를 엽니다. 로그인이 필요합니다.

App cards 앱 카드

  • One card per app, with the monetization badge (FREE, XOTN, CARD, BOTH) and ⛓ ON-CHAIN or NOT ON-CHAIN. 앱마다 카드 1장이 있고, 수익화 배지(FREE·XOTN·CARD·BOTH)와 ⛓ ON-CHAIN 또는 NOT ON-CHAIN 배지가 붙습니다.
  • A free app, or a paid app with no card sales yet, shows Not subject to settlement. 무료 앱이나 아직 카드 매출이 없는 유료 앱은 정산 대상 아님으로 표시됩니다.
  • Otherwise six cells are shown: Gross sales, PG fees, Developer share, Refunded, Settled and Pending payout. These are read live from the contract each time the page loads. 그 밖에는 누적 매출·PG 수수료·개발자 몫·환불·정산 완료·미지급 6칸이 보입니다. 이 값은 페이지를 열 때마다 컨트랙트에서 라이브로 읽습니다.

Timeline 타임라인

Filter by app, type (Sale, Refund, Settled) and date range, then click Apply. The timeline is built from the platform's index of contract events, so a new record can take a short moment to appear. 앱·종류(Sale·Refund·Settled)·기간을 고르고 Apply 를 누릅니다. 타임라인은 플랫폼이 컨트랙트 이벤트를 색인한 결과라서 새 기록이 보이기까지 잠시 걸릴 수 있습니다.

Column열Content내용
Date Block time. Hover to see the block number.블록 시각. 마우스를 올리면 블록 번호가 보입니다.
Amount / Your share Sale: gross and your share. Refund: your share as a negative value. Settled: the paid amount.Sale 은 결제액과 개발자 몫, Refund 는 음수로 표시한 개발자 몫, Settled 는 지급액입니다.
Order / Ref Sale and Refund: the on-chain orderId. Settled: the settlement reference and period. Hover a Settled row to see the receipt hash.Sale·Refund 는 온체인 orderId, Settled 는 정산 참조번호와 기간입니다. Settled 행에 마우스를 올리면 영수증 해시가 보입니다.
Tx Shortened tx_hash. Hover to see the full value.줄인 tx_hash. 마우스를 올리면 전체 값이 보입니다.
Receipt Settled rows only. Download gets the transfer receipt. Its tooltip shows sha256 0x….Settled 행에만 있습니다. Download 로 송금 영수증을 받습니다. 툴팁에 sha256 0x… 가 표시됩니다.

Verify a payout receipt 정산 영수증 검증

  1. Click Download on the Settled row. Settled 행의 Download 를 누릅니다.
  2. Compute the file's sha256. 파일의 sha256 을 계산합니다.
  3. Compare it with the on-chain receipt hash in the tooltip, ignoring the 0x prefix. If they match, the file is exactly the one recorded on-chain. 툴팁의 온체인 영수증 해시와 비교합니다. 0x 접두어는 빼고 비교합니다. 같으면 체인에 기록된 바로 그 파일입니다. 
# macOS / Linux
shasum -a 256 receipt.pdf

# Windows (PowerShell)
Get-FileHash receipt.pdf -Algorithm SHA256

If you disagree with a number 숫자에 이의가 있을 때

Every Sale, Refund and Settled row has a tx_hash. Look it up on the XOTN chain with a block explorer or with JSON-RPC eth_getTransactionReceipt, and read the event fields directly. Contact the platform with the tx_hash. Sale·Refund·Settled 행마다 tx_hash 가 있습니다. XOTN 체인에서 블록 탐색기나 JSON-RPC eth_getTransactionReceipt 로 조회해 이벤트 필드를 직접 확인하세요. 문의할 때는 tx_hash 를 함께 보내 주세요.

7 Not yet supported 아직 지원하지 않는 것

  • Automatic recording from the PG webhook. Sales are entered by an operator for now. PG 웹훅 자동 기록. 지금은 운영자가 판매를 입력합니다.
  • A developer signature confirming receipt of a payout. Only the platform key records payouts. 개발자의 입금 확인 서명. 지금은 플랫폼 키만 정산을 기록합니다.
  • Currencies other than USD. USD 이외의 통화.