개발자 문서 — 결제 연동 API

퓨인소프트 주식회사가 운영하는 서비스(SaaS)를 pay.fuinsoft.com 결제 허브에 연동하기 위한 서버 간 API·웹훅 계약입니다. 연동은 운영자가 테넌트를 등록해 드린 뒤 시작합니다.

개요

연동은 세 가지 요소로 이뤄집니다.

기본 주소는 https://pay.fuinsoft.com 이며, 모든 API 는 /v1 접두사를 씁니다.

인증 · livemode

모든 요청에 테넌트 API 키를 Bearer 토큰으로 담습니다.

Authorization: Bearer fpay_test_xxxxxxxxxxxxxxxx

• 키는 test / live 두 종류이며, 접두사로 구분됩니다(fpay_test_ · fpay_live_).
• 키의 모드가 생성되는 모든 리소스에 전파됩니다. test 키로 만든 결제는 test 원장에만 기록되고 실 매출에 섞이지 않습니다.
• 조회도 같은 모드로만 됩니다. live 이벤트를 test 키로 재조회하면 404 not_found 가 납니다 — 리소스가 없는 게 아니라 키 모드가 틀린 것입니다.
• 키는 발급 시 1회만 표시되며 다시 확인할 수 없습니다. 분실 시 재발급합니다.
• 키는 서버 환경변수로 보관하고 브라우저·모바일 앱에 넣지 않습니다.

멱등성

생성 계열 5개 엔드포인트는 Idempotency-Key 헤더가 필수입니다(누락 시 400 idempotency_key_required).

• 키 범위는 (테넌트, 모드, 키) 입니다. test·live 는 서로 간섭하지 않습니다.
• 구독은 card·invoice 저장소가 분리돼 있어 모드를 바꿔 같은 키를 재사용해도 409 입니다.
• 주문번호처럼 업무적으로 유일한 값을 키로 쓰는 것을 권장합니다.

에러 · 레이트리밋

에러 응답은 { "error": "<code>", "detail"?: ... } 형태입니다.

detail(zod 검증 상세)은 엔드포인트마다 다릅니다. invalid_body 에 detail 이 있는 곳: 결제 세션 생성 · 구독 생성. 없는 곳: 구독 변경(PATCH) · 카드 교체(billing-key) · 환불. 결제 목록의 쿼리 오류는 invalid_body 가 아니라 invalid_query(detail 포함)입니다. detail 유무에 의존하는 코드를 쓰지 마세요.

레이트리밋: 클라이언트 IP 당 분당 300회. 초과 시 429 와 retry-after 헤더를 반환합니다. 같은 IP 에서 나가는 요청은 테넌트·엔드포인트 구분 없이 한 버킷을 공유합니다. retry-after 를 존중해 지수 백오프로 재시도하세요.

API 엔드포인트

타입 규약

• 금액(amount·supplyAmount·taxAmount·totalAmount·totalRefunded) = 정수, 원 단위. 소수점 없음.
• 시각(*At·periodStart/End·dueAt) = ISO8601 UTC 문자열. 한국 시각 해석은 수신측에서 하세요.
• writeDate(세금계산서 작성일)만 예외로 yyyy-MM-dd 문자열입니다.
• null 이 올 수 있는 필드: 세션 amount(카드 등록 전용 세션), payment·payment.paidAt, 구독 기간 필드(개시 전), 결제 paidAt·failedReason, 인보이스의 가상계좌·납기·세금계산서 연계 필드, 세금계산서의 issuedAt·providerStatus 등.

주요 enum

필수 조건 · 제약

• 리다이렉트 URL 화이트리스트: successUrl·failUrl 의 오리진이 테넌트에 등록된 목록에 없으면 422 redirect_url_not_allowed. 도메인이 바뀌면 운영자에게 등록을 요청하세요.
• 결제 세션 유효기간 30분 — 만료 후 재시도는 새 Idempotency-Key 로.
• 일회성 결제의 customer 는 선택입니다(구독과 달리 없어도 결제창이 열립니다).
• 정기 인보이스(billingMode: invoice) 구독은 test 모드 전용입니다. live 요청은 422 invoice_billing_gated 로 막힙니다.

결제 · 구독 플로우

일회성 결제

세션 생성 → 결제창 → 웹훅 또는 재조회로 확정.

# 1) 결제 세션 생성 (서버 → 허브)
curl -X POST https://pay.fuinsoft.com/v1/checkout-sessions \
  -H "Authorization: Bearer fpay_test_xxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: order-2026-0823-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 33000,
    "orderName": "MassCurve 단건 이용료",
    "customer": { "id": "user_1024", "email": "buyer@example.com" },
    "successUrl": "https://myapp.example.com/pay/done",
    "failUrl": "https://myapp.example.com/pay/fail"
  }'

# → 201 { "id": "...", "checkoutUrl": "https://pay.fuinsoft.com/checkout/<token>", ... }
# 2) 사용자를 checkoutUrl 로 보낸다(결제창)
# 3) 이행 확정은 successUrl 리다이렉트가 아니라 웹훅 수신 또는 아래 재조회로만 한다
curl https://pay.fuinsoft.com/v1/checkout-sessions/<id> \
  -H "Authorization: Bearer fpay_test_xxxxxxxxxxxxxxxx"
# → { "paid": true, "payment": { "id": "...", "status": "paid", "paidAt": "..." } }

카드 구독

구독 생성 → 카드 등록(빌링키 발급) → 개시 → 주기마다 자동 청구.

# 카드 구독 — customer 의 email·name·phone 을 반드시 포함한다(카드등록 페이지가 요구)
curl -X POST https://pay.fuinsoft.com/v1/subscriptions \
  -H "Authorization: Bearer fpay_test_xxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: sub-user_1024-pro" \
  -H "Content-Type: application/json" \
  -d '{
    "planCode": "pro-monthly",
    "customer": {
      "id": "user_1024",
      "email": "buyer@example.com",
      "name": "홍길동",
      "phone": "01012345678"
    },
    "successUrl": "https://myapp.example.com/billing/done",
    "failUrl": "https://myapp.example.com/billing/fail"
  }'

# → 201 { "id": "...", "billingUrl": "https://pay.fuinsoft.com/billing/<token>" }
#
# ⚠️ 이 응답의 "id" 는 **구독 ID 가 아니다** — 빌링키 발급 세션의 ID 다.
#    이 값으로 GET /v1/subscriptions/{id} 를 호출하면 404 가 난다.
#    구독은 카드 등록이 끝난 시점에 만들어지고, 그 구독 ID 는
#    subscription.activated 이벤트의 data.subscriptionId 로 전달된다. 그 값을 저장해서
#    이후 조회(GET)·해지(PATCH)·카드 교체(billing-key)에 사용한다.
#
# 사용자를 billingUrl 로 보내 카드를 등록시키면 구독이 개시되고 subscription.activated 가 발송된다.

결제 실패와 연체(dunning)

• 청구 실패 시 구독은 past_due 가 되고 subscription.payment_failed 가 발송됩니다. 연체 중 서비스 이용을 막을지 유예할지는 각 서비스가 정하는 정책이며 허브는 관여하지 않습니다.
• 재시도는 원 납기 기준 +1일 · +3일 · +5일 로 진행됩니다.
• 재시도를 모두 소진하면 구독이 자동 해지되고 subscription.canceled(reason: dunning_exhausted) 가 발송됩니다.
• 재청구가 성공해 연체에서 벗어나면 subscription.renewed 가 아니라 subscription.recovered 가 옵니다.
• 카드 교체는 POST /v1/subscriptions/{id}/billing-key 로 새 등록 URL 을 발급합니다. past_due 상태에서 등록이 성공하면 즉시 재청구되어 복귀합니다.

해지

PATCH /v1/subscriptions/{id} 에 cancelAtPeriodEnd: true(기간말 해지 예약) 또는 cancelImmediately: true(즉시 해지)를 보냅니다. 예약은 cancelAtPeriodEnd: false 로 취소할 수 있습니다.

웹훅(팬아웃)

허브가 테넌트의 webhook_url 로 POST 합니다. 전송 헤더는 다음과 같습니다.

본문(envelope)은 다음 구조입니다.

{
  "id": "01J...",             // 이벤트 id — 멱등 키로 사용
  "type": "payment.paid",
  "livemode": false,
  "seq": 42,                   // 테넌트별 단조 증가 — 순서 "힌트"일 뿐
  "occurredAt": "2026-08-23T04:05:06.000Z",
  "data": { }                  // 이벤트별 페이로드(아래 카탈로그)
}

검증 코드 (Node / TypeScript)

// Node 22 / TypeScript — 팬아웃 웹훅 수신 (Fastify 예시)
import { createHmac, timingSafeEqual } from 'node:crypto'

const SECRET = process.env.FUINPAY_WEBHOOK_SECRET!   // 허브에서 발급받은 테넌트 webhook_secret
const BASE = 'https://pay.fuinsoft.com'

// ⚠️ 원문(raw body)으로 검증해야 한다. JSON 을 파싱했다가 다시 문자열로 만들면 서명이 어긋난다.
app.addContentTypeParser('application/json', { parseAs: 'string' }, (req, body, done) => {
  req.rawBody = body as string
  done(null, JSON.parse(body as string))
})

/** 우리가 실제로 처리하는 이벤트만 나열한다. 나머지는 "의도적 무시"로 기록만 한다. */
const HANDLED = new Set(['payment.paid', 'refund.completed', 'subscription.activated'])

app.post('/webhooks/fuinpay', async (req, reply) => {
  const header = req.headers['x-pay-signature'] as string | undefined
  const eventId = req.headers['x-pay-event-id'] as string | undefined
  const livemodeHeader = req.headers['x-pay-livemode'] === 'true'

  // ── 검증 실패는 전부 비-2xx. 200 을 주면 허브가 delivered 로 확정해 이벤트가 영구 유실된다. ──
  if (!header || !eventId) return reply.code(400).send()

  // 1) 서명 파싱 — t=<unix>,v1=<hex>
  const parts = new Map(header.split(',').map((kv) => {
    const i = kv.indexOf('=')
    return [kv.slice(0, i).trim(), kv.slice(i + 1).trim()] as const
  }))
  const t = Number(parts.get('t'))
  const v1 = parts.get('v1')
  if (!Number.isFinite(t) || !v1) return reply.code(400).send()

  // 2) 리플레이 방지 — 5분 skew
  if (Math.abs(Date.now() - t * 1000) > 5 * 60 * 1000) return reply.code(400).send()

  // 3) 상수시간 비교
  const expected = createHmac('sha256', SECRET).update(t + '.' + req.rawBody).digest('hex')
  const a = Buffer.from(expected), b = Buffer.from(v1)
  if (a.length !== b.length || !timingSafeEqual(a, b)) return reply.code(400).send()

  // 4) 헤더와 본문 일치 확인(변조 신호)
  const ev = req.body as { id: string; type: string; livemode: boolean; data: Record<string, any> }
  if (ev.id !== eventId || ev.livemode !== livemodeHeader) return reply.code(400).send()

  // 5) 멱등 — 같은 id 가 **동시에** 중복 도착할 수 있다. "조회 후 처리" 는 경합에 안전하지 않으므로
  //    UNIQUE(event_id) inbox 에 원자적으로 선점한다. 이때 **반드시 lease(만료)** 를 함께 둔다 —
  //    선점 직후 프로세스가 죽으면 lease 없이는 그 이벤트가 영원히 'processing' 으로 고착되고,
  //    이후 재시도가 전부 409 로 돌아가 결국 허브에서 dead 처리된다.
  //      INSERT INTO webhook_inbox (event_id, status, owner, lease_until)
  //        VALUES ($1, 'processing', $2, now() + interval '5 minutes')
  //      ON CONFLICT (event_id) DO UPDATE
  //        SET owner = excluded.owner, lease_until = excluded.lease_until
  //        WHERE webhook_inbox.status = 'processing'
  //          AND webhook_inbox.lease_until < now()        -- 만료된 선점만 회수(CAS)
  //      RETURNING status
  //    → 행이 반환되면 내가 소유자('claimed'). 아니면 기존 status 를 읽어 판단한다.
  const owner = crypto.randomUUID()                        // fencing token
  const claim = await claimEvent(ev.id, owner)             // 'claimed' | 'processing' | 'completed'
  if (claim === 'completed') return reply.code(200).send()   // 이미 끝남 → 조용히 성공
  if (claim === 'processing') return reply.code(409).send()  // 다른 워커가 lease 보유 중 → 재시도 받기
  // ⚠️ 완료·해제는 **현재 owner 일 때만** 수행한다(WHERE owner = $2). 그래야 lease 를 회수해 간
  //    다른 워커의 처리 결과를 뒤늦게 깨어난 이전 워커가 덮어쓰지 않는다.

  // 6) 처리하지 않는 이벤트도 **완료로 전이**한 뒤 200. (비-2xx 를 주면 33시간 재시도 후 dead 가 되어
  //    운영 알림만 쌓인다. 단 "처리 대상인데 실패한" 경우와 반드시 구분해야 한다.)
  //    ⚠️ 여기서 completed 로 넘기지 않고 200 만 반환하면 inbox 행이 'processing' 으로 남아
  //       같은 id 의 후속 중복이 영원히 409 가 된다("완료된 중복만 200" 규칙과도 모순).
  if (!HANDLED.has(ev.type)) {
    try {
      // 기록과 완료 전이는 한 트랜잭션으로 묶는 것이 안전하다.
      await logIgnoredEventAndComplete(ev, owner)
    } catch {
      await releaseEvent(ev.id, owner)                      // 기록 실패 → 선점 풀고 재시도 받기
      return reply.code(500).send()
    }
    return reply.code(200).send()
  }

  // 7) 상태는 반드시 재조회로 확정한다. 순서는 보장되지 않는다.
  //    이벤트의 livemode 와 같은 모드의 키를 써야 한다(다르면 404).
  const key = ev.livemode ? process.env.FUINPAY_LIVE_KEY! : process.env.FUINPAY_TEST_KEY!
  const auth = { authorization: 'Bearer ' + key }

  // 아래 실패 경로에서는 선점을 반드시 풀어야 재시도가 실제로 처리된다.
  const giveUp = async (code: number) => {
    // DELETE FROM webhook_inbox WHERE event_id = $1 AND owner = $2
    await releaseEvent(ev.id, owner)
    return reply.code(code).send()
  }

  // ⚠️ lease 는 만료될 수 있다. 재조회·처리에 시간이 걸린 사이 다른 워커가 회수했을 수 있으므로
  //    **부수효과 직전에 소유권을 재확인**한다(UPDATE … SET lease_until = now() + interval '5 minutes'
  //    WHERE event_id = $1 AND owner = $2 AND status = 'processing' RETURNING 1).
  //    0행이면 내 것이 아니므로 아무것도 실행하지 않고 물러난다 — 이중 이행 방지의 핵심이다.
  const stillMine = async (): Promise<boolean> => renewLease(ev.id, owner)

  try {
    if (ev.type === 'payment.paid' || ev.type === 'refund.completed') {
      const res = await fetch(BASE + '/v1/payments/' + ev.data.paymentId, { headers: auth })
      if (!res.ok) return giveUp(502)                     // 재조회 실패 → 재시도 받기
      const payment = await res.json()
      if (!(await stillMine())) return reply.code(409).send()   // lease 상실 → 실행하지 않고 물러남
      // ⚠️ 가능한 status 를 전부 처리한다. 빠뜨린 상태를 조용히 넘기면 그 이벤트는 유실된다.
      // 부수효과 자체도 event id 로 멱등화한다(재시도가 두 번 적용되지 않도록).
      // ⚠️ lease 재확인은 창을 좁힐 뿐 완전한 배제가 아니다. 확실한 방지는 **부수효과 저장소에서**
      //    event_id UNIQUE 로 한 번 더 막는 것이다 — 아래 함수들은 그렇게 구현한다.
      switch (payment.status) {
        case 'paid':               await fulfill(payment, ev.id); break
        case 'partial_cancelled':  await syncPartialRefund(payment, ev.id); break  // 부분 환불
        case 'cancelled':          await revoke(payment, ev.id); break             // 전액 환불
        case 'failed':             await markFailed(payment, ev.id); break
        case 'ready':              return giveUp(409)            // 아직 확정 전 → 재시도
        default:                   return giveUp(500)            // 모르는 상태 → 재시도+점검
      }
    } else if (ev.type === 'subscription.activated') {
      const res = await fetch(BASE + '/v1/subscriptions/' + ev.data.subscriptionId, { headers: auth })
      if (!res.ok) return giveUp(502)
      const sub = await res.json()
      if (!(await stillMine())) return reply.code(409).send()   // lease 상실 → 실행하지 않고 물러남
      switch (sub.status) {
        case 'active':
        case 'trialing':           await grantAccess(sub, ev.id); break  // 체험도 접근 부여 대상이다
        case 'past_due':
          // 연체 중 이용을 막을지 유예할지는 **각 서비스가 정할 정책**이며 허브는 관여하지 않는다.
          // (순서 무보장이라, 늦게 도착한 activated 를 재조회하면 이미 past_due 일 수 있다.)
          // 정책을 결정하지 못하면 완료 처리하지 말고 재시도를 받아야 한다.
          if (!(await applyPastDuePolicy(sub, ev.id))) return giveUp(500)
          break
        case 'suspended':
        case 'canceled':           await revokeAccess(sub, ev.id); break
        default:                   return giveUp(500)
      }
    }
  } catch {
    return giveUp(502)                                     // 처리 실패 → 재시도 받기
  }

  // 8) 여기까지 왔을 때만 completed 로 확정한다(내가 소유자일 때만).
  //      UPDATE webhook_inbox SET status = 'completed' WHERE event_id = $1 AND owner = $2 RETURNING 1
  const completed = await completeEvent(ev.id, owner)
  if (!completed) {
    // lease 를 뺏긴 뒤 완료했다는 뜻이다. **상태를 확인하지 않고 200 을 주면 안 된다** —
    // 다른 워커가 아직 처리 중일 수 있고, 그때 200 을 주면 허브가 전달 완료로 확정해 유실된다.
    const status = await readEventStatus(ev.id)   // 'completed' | 'processing' | null
    if (status !== 'completed') return reply.code(409).send()   // 아직 미완 → 재시도 받기
  }
  return reply.code(200).send()   // 5초 안에 2xx — 무거운 후속 작업은 큐로
})

수신측 필수 계약

• 순서는 보장되지 않습니다. seq·occurredAt 는 힌트일 뿐이며, 정본은 수신 시점의 재조회 결과입니다.
• 리플레이 방지: 서명의 t 와 현재 시각 차이가 5분을 넘으면 거부하세요.
• 원문(raw body)으로 검증하세요. JSON 을 파싱한 뒤 다시 문자열로 만들면 서명이 어긋납니다.
• 응답은 5초 안에 반환하세요(타임아웃 = 실패). 무거운 처리는 큐에 넣고 먼저 응답합니다.
• 재시도 간격: 1분 → 5분 → 30분 → 2시간 → 6시간 → 24시간(6회, 약 33시간).

webhook secret 회전

이벤트 카탈로그

현재 발송되는 이벤트는 다음 15종입니다.

중복 억제 열은 허브 내부에서 같은 이벤트를 중복 생성하지 않기 위한 장치이며, 전달이 한 번만 된다는 보장이 아닙니다. 수신측 멱등 처리는 어느 이벤트에서든 필수입니다.

온보딩 절차

테넌트 등록은 운영자가 직접 진행합니다(셀프 가입은 제공하지 않습니다).

1. 연동 요청 — ydnam@fuinsoft.com 로 서비스명·도메인·결제 형태(일회성/구독)를 알려주세요.
2. 테넌트 등록 · API 키 발급 — test 키를 먼저 발급합니다(1회 표시).
3. 설정 등록 — 웹훅 수신 URL, 리다이렉트 허용 오리진(successUrl·failUrl 도메인)을 전달해 주세요. 오리진이 등록되지 않으면 결제 세션 생성이 전부 422 로 막힙니다.
4. 요금제 등록 — test 모드는 POST /v1/plans 로 직접 등록·변경·보관할 수 있습니다. live 요금제만 운영자 승인 대상입니다 — 상품명·금액·주기를 전달해 주시면 운영자가 등록 후 planCode 를 알려드립니다 (실청구 금액을 단독으로 정하지 못하게 하는 게이트입니다 — 조회(GET /v1/plans)는 두 모드 모두 가능). 미등록 상태로 구독을 생성하면 404 plan_not_found 입니다.
   · 금액 변경은 신규 구독부터 적용됩니다 — 진행 중 구독과 열린 결제 세션은 개시 시점 금액을 그대로 유지합니다.
   · interval·trialDays 는 변경할 수 없습니다 — 주기나 체험기간이 다르면 새 요금제를 만드세요.
   · 체험기간(trial)은 카드 구독에만 적용됩니다 — billingMode: invoice 구독은 체험을 무시하고 즉시 첫 청구합니다.
   · 요금제 금액 상한은 1,818,182원입니다(결제대행사 계약상 건당 승인한도 200만원 · 정기 인보이스는 부가세를 더한 금액이 승인 대상이라 공급가 상한이 더 낮습니다).
5. test 모드 연동·검증 — 결제·웹훅·재조회까지 확인합니다.
6. live 전환 — 검증 완료 후 live 키를 발급합니다.

현재 미제공

설계에는 있으나 아직 제공되지 않는 항목입니다. 연동 설계 시 참고하세요.

이 문서는 구현 코드에서 직접 생성됩니다 · 기준 a1b06c9 · 갱신 2026-08-23 · 문의 ydnam@fuinsoft.com