인보이스로 결제하기

이 가이드는 인보이스 메타데이터에서 파생된 결정적 nonce를 사용하여 ERC-3009로 온체인에서 인보이스를 정산하는 과정을 안내합니다. nonce는 각 결제를 해당 인보이스에 연결하고 이중 결제를 방지합니다.

무엇을 만들게 되나요

전체 인보이스 라이프사이클: 구매자가 오프체인에서 ERC-3009 인가에 서명하고, 공급업체가 이를 온체인에 제출하며, 대사 처리는 결과로 생성된 AuthorizationUsed 이벤트를 결정적 nonce로 인보이스에 다시 매칭합니다.

데모

step 1. Invoice issued
        number:  INV-2026-001234
        amount:  5000 USDT0
        dueDate: 2026-04-30

step 2. Buyer signs authorization (off-chain, no gas)
        nonce:     0xa1b2...c3d4 (from invoice metadata)
        signature: 0xf0e9...1234

step 3. Vendor submits transferWithAuthorization
        tx:     0x8f3a...2d41
        amount: 5000 USDT0 transferred to vendor

step 4. Reconciliation
        AuthorizationUsed(nonce=0xa1b2...) → invoice INV-2026-001234
        Transfer event verified for correct amount and parties
        ERP: marked PAID at block 1284371

개요

구매자:

─── Buyer ───────────────────────────────────────────
nonce = getInvoiceNonce(invoice)
authorization = { from: buyer, to: vendor, value: amount, nonce, ... }
signature = signTypedData(authorization)
 
// Option A: Buyer submits the transaction directly.
usdt0.transferWithAuthorization(authorization, signature)
 
// Option B: Buyer sends {authorization, signature} to the vendor.
//           The vendor (or a facilitator) submits on the buyer's behalf.

공급업체:

─── Vendor ──────────────────────────────────────────
// If Option B: submit transferWithAuthorization using the buyer's signature
 
// Reconcile via AuthorizationUsed event
on AuthorizationUsed(authorizer, nonce):
    invoice = nonceToInvoice.get(nonce)
    transferLog = receipt.logs.find(Transfer matching invoice.buyer, invoice.vendor, invoice.amount)
    if transferLog:
        erpSystem.markPaid(invoice.id, txHash, settledAt)

구성

// config.ts
import { ethers } from "ethers";
 
export const STABLE_TESTNET_RPC = "https://rpc.testnet.stable.xyz";
export const CHAIN_ID = 2201;
export const USDT0_ADDRESS = "0x78Cf24370174180738C5B8E352B6D14c83a6c9A9";
 
export const provider = new ethers.JsonRpcProvider(STABLE_TESTNET_RPC);
 
export const EIP712_DOMAIN = {
  name: "USDT0",
  version: "1",
  chainId: CHAIN_ID,
  verifyingContract: USDT0_ADDRESS,
};
 
export const TRANSFER_WITH_AUTHORIZATION_TYPE = {
  TransferWithAuthorization: [
    { name: "from", type: "address" },
    { name: "to", type: "address" },
    { name: "value", type: "uint256" },
    { name: "validAfter", type: "uint256" },
    { name: "validBefore", type: "uint256" },
    { name: "nonce", type: "bytes32" },
  ],
};
 
export interface Invoice {
  number: string;   // e.g. "INV-2026-001234"
  vendor: string;   // vendor wallet address
  buyer: string;    // buyer wallet address
  amount: bigint;   // amount in USDT0 atomic units (6 decimals)
  dueDate: number;  // Unix timestamp
}

1단계: 결정적 nonce 생성

구매자와 공급업체 모두 인보이스 메타데이터로부터 동일한 nonce를 독립적으로 계산할 수 있습니다. 외부 레지스트리가 필요하지 않습니다.

// nonce.ts
import { ethers } from "ethers";
import { Invoice } from "./config";
 
export function getInvoiceNonce(invoice: Invoice): string {
  return ethers.solidityPackedKeccak256(
    ["string", "address", "address", "uint256", "uint256"],
    [
      invoice.number,
      invoice.vendor,
      invoice.buyer,
      invoice.amount,
      invoice.dueDate,
    ]
  );
}
 
// Example
const invoice: Invoice = {
  number: "INV-2026-001234",
  vendor: "0xVendorAddress",
  buyer: "0xBuyerAddress",
  amount: ethers.parseUnits("5000", 6), // 5,000 USDT0
  dueDate: Math.floor(new Date("2026-04-30").getTime() / 1000),
};
 
const nonce = getInvoiceNonce(invoice);
// Same input always produces the same nonce.
// This nonce is consumed on-chain upon payment, preventing double payment.

2단계: 인가에 서명 (구매자)

구매자는 1단계의 결정적 nonce를 사용하여 ERC-3009 transferWithAuthorization에 서명합니다.

// sign-invoice.ts
import { ethers } from "ethers";
import {
  provider,
  EIP712_DOMAIN,
  TRANSFER_WITH_AUTHORIZATION_TYPE,
  Invoice,
} from "./config";
import { getInvoiceNonce } from "./nonce";
 
const buyerWallet = new ethers.Wallet(process.env.BUYER_KEY!, provider);
 
async function signInvoiceAuthorization(invoice: Invoice) {
  const nonce = getInvoiceNonce(invoice);
  const gracePeriod = 30 * 24 * 60 * 60; // 30 days after due date
 
  const authorization = {
    from: invoice.buyer,
    to: invoice.vendor,
    value: invoice.amount,
    validAfter: 0,
    validBefore: invoice.dueDate + gracePeriod,
    nonce,
  };
 
  const signature = await buyerWallet.signTypedData(
    EIP712_DOMAIN,
    TRANSFER_WITH_AUTHORIZATION_TYPE,
    authorization
  );
 
  return { authorization, signature };
}

3단계: 트랜잭션 제출

제출하는 주체에 따라 두 가지 옵션이 있습니다.

옵션 A: 구매자가 제출

구매자가 transferWithAuthorization 트랜잭션을 직접 제출하고 가스를 지불합니다. 구매자가 결제 실행 시점과 방법을 제어할 때 사용합니다. 예를 들어 구매자의 회계 시스템이 내부 승인 흐름에 연결된 tx 해시를 필요로 하는 경우입니다.

// pay.ts
import { ethers } from "ethers";
import { provider, USDT0_ADDRESS } from "./config";
 
const buyerWallet = new ethers.Wallet(process.env.BUYER_KEY!, provider);
 
const usdt0 = new ethers.Contract(
  USDT0_ADDRESS,
  [
    "function transferWithAuthorization(address from, address to, uint256 value, uint256 validAfter, uint256 validBefore, bytes32 nonce, uint8 v, bytes32 r, bytes32 s)",
  ],
  buyerWallet,
);
 
async function payInvoice(
  authorization: { from: string; to: string; value: bigint; validAfter: number; validBefore: number; nonce: string },
  signature: string,
) {
  const { v, r, s } = ethers.Signature.from(signature);
 
  const tx = await usdt0.transferWithAuthorization(
    authorization.from,
    authorization.to,
    authorization.value,
    authorization.validAfter,
    authorization.validBefore,
    authorization.nonce,
    v, r, s,
  );
 
  const receipt = await tx.wait(1);
  console.log("Invoice paid, tx:", receipt.hash);
  // The nonce is now consumed; the same invoice cannot be paid twice.
  return { txHash: receipt.hash, blockNumber: receipt.blockNumber };
}

옵션 B: 공급업체가 제출

구매자는 API, 이메일 또는 어떤 채널을 통해서든 {authorization, signature}를 공급업체에 보냅니다. 공급업체(또는 퍼실리테이터)가 구매자를 대신하여 트랜잭션을 제출하므로 구매자는 가스를 관리할 필요가 없습니다. 공급업체가 동일한 요청 흐름 내에서 동기 확인을 필요로 할 때 사용합니다.

// settle.ts
import { ethers } from "ethers";
import { provider, USDT0_ADDRESS } from "./config";
 
const vendorWallet = new ethers.Wallet(process.env.VENDOR_KEY!, provider);
 
const usdt0 = new ethers.Contract(
  USDT0_ADDRESS,
  [
    "function transferWithAuthorization(address from, address to, uint256 value, uint256 validAfter, uint256 validBefore, bytes32 nonce, uint8 v, bytes32 r, bytes32 s)",
  ],
  vendorWallet,
);
 
async function settleInvoice(
  authorization: { from: string; to: string; value: bigint; validAfter: number; validBefore: number; nonce: string },
  signature: string,
) {
  const { v, r, s } = ethers.Signature.from(signature);
 
  const tx = await usdt0.transferWithAuthorization(
    authorization.from,
    authorization.to,
    authorization.value,
    authorization.validAfter,
    authorization.validBefore,
    authorization.nonce,
    v, r, s,
  );
 
  const receipt = await tx.wait(1);
  console.log("Invoice settled, tx:", receipt.hash);
  return { txHash: receipt.hash, blockNumber: receipt.blockNumber };
}

4단계: 온체인 이벤트를 통한 대사 처리 (공급업체)

누가 트랜잭션을 제출했든 관계없이, 모든 인보이스 결제는 결정적 nonce를 담은 AuthorizationUsed 이벤트를 발생시킵니다. 공급업체는 이 이벤트를 수신하고 nonce로 대기 중인 인보이스에 매칭합니다. nonce가 인보이스 메타데이터에서 파생되므로 매칭은 정확합니다.

// reconcile.ts
import { ethers } from "ethers";
import { provider, USDT0_ADDRESS, Invoice } from "./config";
import { getInvoiceNonce } from "./nonce";
 
const usdt0 = new ethers.Contract(
  USDT0_ADDRESS,
  [
    "event AuthorizationUsed(address indexed authorizer, bytes32 indexed nonce)",
    "event Transfer(address indexed from, address indexed to, uint256 value)",
  ],
  provider,
);
 
// Build a lookup map: nonce -> invoice.
// In production, this comes from your invoice database.
const invoices: Invoice[] = [
  {
    number: "INV-2026-001234",
    vendor: "0xVendorAddress",
    buyer: "0xBuyerAddress",
    amount: ethers.parseUnits("5000", 6),
    dueDate: Math.floor(new Date("2026-04-30").getTime() / 1000),
  },
];
 
const nonceToInvoice = new Map<string, Invoice>();
for (const inv of invoices) {
  nonceToInvoice.set(getInvoiceNonce(inv), inv);
}
 
usdt0.on("AuthorizationUsed", async (authorizer: string, nonce: string, event: any) => {
  const invoice = nonceToInvoice.get(nonce);
  if (!invoice) return; // not one of our invoices
 
  const receipt = await event.getTransactionReceipt();
 
  const transferLog = receipt.logs
    .map((log: any) => {
      try { return usdt0.interface.parseLog(log); } catch { return null; }
    })
    .find(
      (parsed: any) =>
        parsed?.name === "Transfer" &&
        parsed.args[0].toLowerCase() === invoice.buyer.toLowerCase() &&
        parsed.args[1].toLowerCase() === invoice.vendor.toLowerCase() &&
        parsed.args[2] === invoice.amount
    );
 
  if (!transferLog) {
    console.error("No matching Transfer event for invoice:", invoice.number);
    return;
  }
 
  // All checks passed
  console.log(`Invoice ${invoice.number} PAID`);
  console.log("  tx:", receipt.hash);
  console.log("  settled at block:", receipt.blockNumber);
 
  // In production: update your ERP/accounting system here
  // erpSystem.markPaid(invoice.number, receipt.hash, receipt.blockNumber);
});
 
console.log("Listening for invoice settlements...");

npx tsx reconcile.ts

Listening for invoice settlements...
Invoice INV-2026-001234 PAID
  tx: 0x8f3a...2d41
  settled at block: 1284371

실패한 결제 처리

제출된 transferWithAuthorization은 여러 가지 이유로 되돌려질(revert) 수 있습니다. 각각을 감지하여 공급업체나 구매자에게 표시함으로써 인보이스를 재시도하거나 마감할 수 있도록 합니다.

Revert 사유	원인	복구 방법
`FiatTokenV2: invalid signature`	서명이 인가 필드와 일치하지 않습니다.	인보이스 데이터를 변경하지 않은 상태로 구매자에게 재서명을 요청하세요.
`FiatTokenV2: authorization is used or canceled`	nonce가 이미 소비되었거나(이중 제출) 구매자가 취소했습니다.	인보이스를 이미 결제됨으로 표시하고, nonce로 원래 tx를 조회하세요.
`FiatTokenV2: authorization is not yet valid`	`validAfter` 이전에 제출되었습니다.	`validAfter`까지 기다리거나 새 인가를 발급하세요.
`FiatTokenV2: authorization is expired`	`validBefore` 이후에 제출되었습니다.	확장된 기간으로 새 인가를 발급하세요.
`FiatTokenV2: transfer amount exceeds balance`	구매자의 USDT0 잔액이 부족합니다.	구매자에게 지갑에 자금을 채우도록 알린 후 동일한 서명으로 재시도하세요.

revert를 포착하고 재시도하기 전에 분류하세요.

// retry.ts
import { ethers } from "ethers";
 
async function submitWithRetry(
  submit: () => Promise<ethers.ContractTransactionResponse>,
): Promise<string> {
  try {
    const tx = await submit();
    const receipt = await tx.wait(1);
    return receipt!.hash;
  } catch (err: any) {
    const reason = err?.info?.error?.message || err?.reason || err?.message || "";
 
    if (reason.includes("authorization is used or canceled")) {
      // Lookup the original tx by AuthorizationUsed event; mark invoice paid.
      throw new Error("ALREADY_PAID");
    }
    if (reason.includes("authorization is expired")) {
      throw new Error("AUTHORIZATION_EXPIRED");
    }
    if (reason.includes("invalid signature")) {
      throw new Error("INVALID_SIGNATURE");
    }
    if (reason.includes("transfer amount exceeds balance")) {
      throw new Error("INSUFFICIENT_BALANCE");
    }
    throw err;
  }
}

다음 추천

인보이스 정산 개념 — 결정적 nonce 대사 처리 모델을 이해하세요.
ERC-3009 — 이 흐름의 기반이 되는 서명된 인가 표준을 검토하세요.
가스 없는 트랜잭션 활성화 — Gas Waiver와 결합하여 정산 경로에서 가스를 제거하세요.