본문으로 건너뛰기
VPawn

API v1

결제 API

VPawn 결제 창으로 회원을 보내고, 결과를 웹훅이나 조회 API로 받아요. 서명·로그인·결제는 모두 www.vpawn.io에서 일어나요. 파트너 페이지는 이동(redirect) 또는 팝업으로만 열 수 있고, iframe은 막혀 있어요.

시작하기

  1. VPawn 운영자에게 허용 출처(https), 웹훅 URL(https, 443, 공인 IP), 팔 컬렉션 목록 등록을 요청해요.
  2. 운영자가 API 키(vb_test_… = Amoy 테스트, vb_live_… = Polygon 실서비스)와 모드별 웹훅 비밀값(whsec_…)을 발급해요. 원문은 발급할 때 한 번만 보여요.
  3. 키는 서버에만 두세요. 브라우저나 앱에 넣지 않아요.

API 주소는 api.vpawn.io 하나예요. 키 접두어가 환경을 정해요. vb_test_ 키는 테스트 사이트(www.vpawn.io, Amoy)에서, vb_live_ 키는 https://www.vpawn.io 에서 처리돼요. 테스트 결제 창과 사용 화면은 www.vpawn.io에서 열려요.

공통

  • 기본 주소: https://api.vpawn.io/api/v1 (테스트·실서비스 키 모두 같은 주소)
  • 인증: Authorization: Bearer vb_live_…
  • 요청·응답은 JSON이고 응답에는 Cache-Control: no-store가 붙어요.
  • 금액은 정수 문자열, USDT 최소 단위(6자리). "125000000" = 125 USDT.
  • 주소·해시는 소문자 0x…, 시각은 UTC ISO 8601(초 단위).
  • 레이트 리밋: 키마다 분당 120회, IP마다 분당 600회. 넘으면 429 RATE_LIMITED.
  • 오류: {"error": "<코드>", "message": "<설명>"}

오류 코드

400 INVALID_REQUEST
본문 형식 오류(message에 필드)
400 INVALID_JSON / INVALID_IDEMPOTENCY_KEY
JSON이 아님 / 키 형식 오류
400 INVALID_URL / URL_NOT_ALLOWED
success/cancel URL이 https가 아니거나 등록한 출처와 다름
401 INVALID_API_KEY
키 없음·틀림·폐기됨
403 MODE_NOT_SERVED
이 환경이 받지 않는 모드의 키
403 PARTNER_SUSPENDED
파트너 정지. 새 세션만 막아요
403 COLLECTION_NOT_ALLOWED
허용 컬렉션 밖의 상품
404 ITEM_NOT_FOUND / SESSION_NOT_FOUND
상품·세션 없음. 다른 파트너의 item_id도 ITEM_NOT_FOUND로 답해요
409 ITEM_UNAVAILABLE / SOLD_OUT
판매 시작 전·종료, 주문 만료, (PARTNER_ITEM) 판매 중이 아니거나 파트너가 판매를 일시중지한 아이템 / 남은 수량 부족
409 IDEMPOTENCY_KEY_REUSED
같은 Idempotency-Key를 다른 본문에 사용
404 TOKEN_NOT_FOUND / 409 ALREADY_USED
사용 세션: 토큰이 없거나 내 것이 아님 / 이미 사용됨
409 SESSION_PROCESSING / SESSION_FINAL
결제 진행 중이거나 이미 끝나 취소할 수 없음
413 TOO_LARGE
본문 16KB 초과
422 QUANTITY_LIMIT
지갑당 구매 한도 초과(LAUNCHPAD, PARTNER_ITEM)
429 RATE_LIMITED
레이트 리밋

세션 만들기

Idempotency-Key 헤더(선택): 같은 키와 같은 본문이면 처음 결과를 돌려줘요. 본문이 다르면 409. 같은 partner_order_id도 기존 세션을 돌려줘요(새로 만들면 201, 기존이면 200).

POST /checkout/sessions
{
  "kind": "LAUNCHPAD",
  "event_id": "12",
  "quantity": 1,
  "partner_order_id": "ORD-2026-000123",
  "success_url": "https://partner.example/orders/123/done",
  "cancel_url": "https://partner.example/orders/123",
  "locale": "ko",
  "metadata": { "campaign": "fall" }
}

필드

kind
LAUNCHPAD(런치패드 이벤트), PARTNER_ITEM(파트너 디지털 자산) 또는 MARKET(마켓 판매 주문)
event_id, quantity
LAUNCHPAD. event_id는 정수 문자열, quantity는 1–1000(지갑당 한도 이하)
item_id, quantity
PARTNER_ITEM. item_id는 파트너 화면의 아이템 ID(양의 정수 문자열), quantity는 1–100(지갑당 한도 이하). 내 파트너의 판매 중인 아이템이어야 해요
customer_email
선택, 모든 kind. 이메일 형식, 254자까지, 소문자로 저장해요. 넣으면 손님은 그 이메일로 받은 코드로만 결제할 수 있고 다른 계정은 결제할 수 없어요. 빼면 로그인한 어떤 회원이든 결제할 수 있어요
order_hash
MARKET. 살아 있는 판매 주문의 해시(0x + 64자)
partner_order_id
파트너 안에서 유일. A–Z a–z 0–9 . _ : -, 1–64자
success_url, cancel_url
https, 등록한 출처와 정확히 일치(경로는 자유). 새 출처는 VPawn 운영자에게 등록을 요청하세요
locale
ko(기본) 또는 en
metadata
선택. 문자열 값만, 키 20개까지. 개인정보는 넣지 않아요
{
  "id": "cs_5f0c…",
  "url": "https://www.vpawn.io/checkout/cs_5f0c…",
  "status": "OPEN",
  "currency": "USDT",
  "total_minor": "125000000",
  "expires_at": "2026-11-01T03:30:00Z",
  "mode": "live"
}
  • 알 수 없는 필드가 있으면 400 INVALID_REQUEST.
  • 가격은 만들 때 체인 또는 주문 서명에서 읽어 고정해요. total_minor는 회원이 낼 수 있는 최대 금액이에요. 등급 할인이 있으면 실제 결제액(paid_minor)은 더 작을 수 있어요.
  • 세션은 30분 유효해요. MARKET은 주문 만료가 더 빠르면 그때까지예요.
  • 회원을 url로 보내요(이동 또는 팝업).
  • PARTNER_ITEM의 가격은 아이템의 현재 단가 × quantity로 고정해요.
  • PARTNER_ITEM 결제 흐름: (1) customer_email을 넣었다면 손님에게 마스킹된 이메일이 보이고 그 주소로 온 코드로 로그인해요. 넣지 않았다면 로그인한 회원이면 돼요. (2) 맞지 않는 계정이면 계정을 바꾸라는 안내가 나와요. (3) 지갑이 없으면 결제 창에서 비밀번호로 만들고(복구 코드는 나중에 저장해도 돼요). (4) 지갑 USDT 또는 카드(Wert)로 결제해요. Wert 카드 수수료는 손님이 결제 금액에 더해 내고 파트너 몫은 같아요. 실서비스(Polygon) 카드 결제는 VPawn가 열 때까지 꺼져 있어요. (5) 체인에서 확정되면 세션이 PAID가 되고 웹훅이 가요.

세션 조회

만들기 응답의 필드에 아래가 더 붙어요. item_id는 PARTNER_ITEM에서만, customer_email은 보냈을 때만 값이 있고(없으면 null) 다른 kind의 event_id·order_hash는 null이에요. collection은 이 응답과 웹훅에만 있고 만들기 응답에는 없어요.

GET /checkout/sessions/{id}
{
  …,
  "partner_order_id": "ORD-2026-000123",
  "kind": "LAUNCHPAD", "event_id": "12", "quantity": 1, "order_hash": null,
  "collection": "0x…", "token_ids": ["101"],
  "paid_minor": "112500000", "failure_reason": null,
  "tx_hash": "0x…", "recipient_wallet": "0x…", "chain_id": 137,
  "paid_at": "2026-11-01T03:12:44Z", "created_at": "2026-11-01T03:00:00Z",
  "locale": "ko", "metadata": { "campaign": "fall" }
}

status

OPEN
결제 대기
PROCESSING
서명을 받아 전송함, 체인 확정 대기
PAID
체인 이벤트로 확정(최종)
FAILED
실패(최종). failure_reason: PRICE_CHANGED, ITEM_UNAVAILABLE, SOLD_OUT, LIMIT, TX_REVERTED
EXPIRED
시간 초과 또는 파트너 취소

파트너가 보낸 customer_email 말고는 회원 이메일·이름이 어떤 응답에도 없어요. recipient_wallet은 체인에 공개된 받는 지갑 주소예요.

세션 취소

POST /checkout/sessions/{id}/expire

결제 전(OPEN, 진행 중인 전송 없음)에만 돼요. 이미 EXPIRED이면 그대로 돌려줘요. checkout.session.expired 웹훅이 가요.

취소와 거의 같은 순간에 회원의 거래가 이미 전송됐다면, 그 거래가 확정될 때 세션이 EXPIRED에서 PAID로 바뀌고 completed 웹훅이 뒤따라요. 주문 처리는 항상 마지막 상태를 기준으로 하세요.

상품 목록

GET /catalog/items?collection=0x…

허용 컬렉션의 판매 중인 상품이에요. collection을 빼면 허용 컬렉션 전체, 허용 밖이면 403.

표시용이에요(인덱서 기준이라 몇 초 늦을 수 있어요). 가격은 세션을 만들 때 체인에서 다시 확인해요.

웹훅

checkout.session.completed
PAID
checkout.session.failed
FAILED
checkout.session.expired
EXPIRED
item.used
디지털 자산 사용(소각)이 체인에서 확정됨(아이템 사용 참고)
  • POST <웹훅 URL>, Content-Type: application/json.
  • VBank-Signature: t=<unix초>,v1=<hex> — HMAC-SHA256(웹훅 비밀값, "<t>.<원문 본문>").
  • VBank-Event-Id: evt_… — 이벤트마다 고유하고 재전송에도 같아요. 중복을 거르는 데 써요.
  • data.total_minor는 실제 결제액(paid_minor)이에요. failed에는 data.failure_reason이 더 붙어요.
  • data.item_id(10진 문자열)는 kind가 PARTNER_ITEM일 때만 들어가요. data.customer_email은 세션을 만들 때 보낸 경우에만 들어가요(모든 kind).
  • 10초 안에 2xx로 답하세요. 3xx는 따라가지 않고 실패로 봐요.
  • 실패하면 1분, 5분, 30분, 2시간, 6시간, 24시간 뒤에 다시 보내요(최대 7번). 그래도 실패하면 운영자가 확인해요.
  • 최소 한 번(at least once) 보내고, 순서는 보장하지 않아요. 처리 전에 조회 API로 현재 상태를 확인해도 돼요.
{
  "id": "evt_…",
  "type": "checkout.session.completed",
  "created_at": "2026-11-01T03:12:44Z",
  "mode": "live",
  "data": {
    "session_id": "cs_…",
    "partner_order_id": "ORD-2026-000123",
    "kind": "LAUNCHPAD",
    "collection": "0x…",
    "token_ids": ["101"],
    "total_minor": "112500000",
    "currency": "USDT",
    "recipient_wallet": "0x…",
    "tx_hash": "0x…",
    "chain_id": 137
  }
}

서명 검증 (Node.js)

받은 원문 그대로(파싱 전 문자열)로 검증하고, 5분보다 오래된 t는 버리세요.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyVPawnWebhook(secret, rawBody, header, nowSec = Math.floor(Date.now() / 1000)) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(nowSec - t) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

아이템 사용

디지털 자산을 사용하면 NFT가 소각되고, 파트너가 자기 서비스에서 혜택을 지급해요. 시작점은 두 가지예요. 회원이 VPawn 내 자산에서 직접 쓰거나, 파트너 서비스가 사용 세션을 만들어 회원을 url로 보내요. 어느 쪽이든 같은 디지털 자산이에요.

POST /use-sessions
{
  "token_id": "101",
  "customer_email": "player@example.com",
  "success_url": "https://partner.example/inventory/done",
  "cancel_url": "https://partner.example/inventory",
  "locale": "en"
}

POST /use-sessions

token_id
필수. 10진 정수 문자열
collection
선택. 컨트랙트 주소(0x + 40자). 생략하면 등록된 내 컬렉션
customer_email
선택. 올바른 이메일, 254자까지, 소문자로 저장. 있으면 회원은 그 이메일로 온 코드로 로그인해요
success_url, cancel_url
필수. https이고 등록된 출처 중 하나와 정확히 일치(경로는 자유), 결제와 같아요
locale
ko(기본) 또는 en
{
  "id": "us_5f0c…",
  "url": "https://www.vpawn.io/use/us_5f0c…",
  "status": "OPEN",
  "mode": "live",
  "collection": "0x…",
  "token_id": "101",
  "item_id": "34",
  "customer_email": "player@example.com",
  "tx_hash": null,
  "used_at": null,
  "expires_at": "2026-11-02T06:11:05Z",
  "created_at": "2026-11-02T05:41:05Z"
}
  • 알 수 없는 필드는 400 INVALID_REQUEST예요. 세션은 30분 동안 유효해요. 응답(201)에는 id(us_…), url, status, mode, collection, token_id, item_id, customer_email, tx_hash, used_at, expires_at, created_at이 있어요.
  • GET /use-sessions/{id}는 같은 모양으로 답해요(토큰 정보를 아직 못 읽으면 item_id가 null일 수 있어요). 같은 모드의 내 세션만 조회돼요.
  • 돌아올 때 success_url에 ?use_session_id=us_…가 붙어요. 사용의 증거는 아니에요. item.used 웹훅이나 조회 API의 USED로 확정하세요.

status

OPEN
사용 대기
USED
어느 경로로 썼든(이 세션, 내 자산) 그 토큰이 소각·확정됨. tx_hash, used_at이 채워져요
EXPIRED
시간이 지남

오류

404 TOKEN_NOT_FOUND
토큰이 없거나 내 컬렉션 것이 아님(다른 파트너의 토큰도 이렇게 답해요)
409 ALREADY_USED
이미 소각·사용된 토큰
404 SESSION_NOT_FOUND
세션 없음(조회)

회원이 보는 흐름

  • customer_email이 있으면 가려진 이메일로 온 코드로 로그인하고, 없으면 VPawn에 로그인해요.
  • 그 계정의 지갑에 토큰이 있어야 해요.
  • 사용하면 NFT가 소각되어 되돌릴 수 없고 파트너가 혜택을 지급한다는 경고가 나와요. 회원이 동의해야 해요.
  • 전달 이메일: 파트너 결제 세션에 customer_email이 있었고 구매자가 아직 그 토큰을 가지고 있을 때만 구매 때의 이메일이고, 그 밖에는 회원이 입력해요. VPawn 밖에서 소각돼도 같은 규칙으로 구매 때의 이메일이고, 아니면 없어요(null).
  • 체인이 소각을 확정하면 item.used가 가고, 회원은 success_url로 돌아가요.

item.used 웹훅

소각이 체인에서 확정된 뒤 한 번 보내요. 서명·헤더·재시도는 위와 같아요.

{
  "id": "evt_…",
  "type": "item.used",
  "created_at": "2026-11-02T05:41:09Z",
  "mode": "live",
  "data": {
    "use_id": "…",
    "use_session_id": "us_…",
    "item_id": "34",
    "item_name": "Dragon Sword",
    "collection": "0x…",
    "token_id": "101",
    "wallet": "0x…",
    "customer_email": "player@example.com",
    "tx_hash": "0x…",
    "chain_id": 137,
    "used_at": "2026-11-02T05:41:05Z"
  }
}
use_id
이 사용의 ID
use_session_id
파트너 서비스의 사용 세션(us_…). 내 자산에서 썼거나 VPawn 밖에서 소각됐거나 토큰이 옮겨진 뒤 썼으면 null
item_id
아이템 ID(10진 문자열)
item_name
영문 아이템 이름. 빈 문자열일 수 있으니 item_id로 구분하세요
collection, token_id
소각된 토큰
wallet
소각한 지갑
customer_email
전달 이메일: 파트너 결제 세션에 customer_email이 있었고 구매자가 아직 그 토큰을 가지고 있으면 구매 때의 이메일, 아니면 회원이 입력한 이메일. VPawn 밖 소각은 같은 규칙으로 구매 때의 이메일, 아니면 null
tx_hash, chain_id
소각 거래
used_at
소각 시각(UTC)
  • 이벤트 ID로 중복을 거르세요. 같은 사용은 같은 ID로만 다시 와요.
  • 혜택은 item.used를 받았을 때만 지급하세요. success_url 복귀만으로는 지급하지 마세요.
  • 회원 이름·계정 ID는 들어가지 않아요.
  • 7번 모두 실패한 전송(FAILED)은 파트너 개발자 화면(최근 웹훅 전송)에서 직접, 또는 VPawn 운영자가 다시 보낼 수 있어요. 이벤트 ID는 그대로예요.
  • 아이템을 등록하려면 먼저 웹훅 URL을 등록하세요(NO_WEBHOOK). 체인에 올라간 아이템이 있으면 URL을 바꿀 수는 있지만 비울 수는 없어요(WEBHOOK_REQUIRED). URL이 없으면 VPawn가 사용을 시작하지 않아요(NO_WEBHOOK). URL이 없을 때 VPawn 밖에서 소각된 건은 실패한 전송(FAILED, NO_WEBHOOK_URL)으로 남으니, URL을 등록한 뒤 다시 보내세요. 다시 보내면 그때 등록된 URL로 가요.

결제 확정 규칙

  • success_url로 돌아온 것은 결제 증거가 아니에요. 주문은 웹훅 또는 조회 API의 PAID로만 확정하세요.
  • 인덱서가 본 체인 이벤트의 거래 해시가 이 세션으로 보낸 거래와 같고 상품·수량·금액이 맞을 때만 PAID가 돼요.
  • 그 블록 위로 블록이 몇 개(운영 설정) 쌓인 뒤에 확정해요. Polygon에서는 대개 10–15초 걸려요.
  • 맞지 않으면 확정하지 않고 운영자가 확인해요. 15분이 지나도 맞는 이벤트가 없으면 결제가 아닌 것으로 봐요.

테스트 모드

  • vb_test_ 키 = Polygon Amoy(80002) + TestUSDT0. 결제 창 위에 "테스트"가 표시돼요.
  • 테스트 세션과 실서비스 세션은 서로 보이지 않아요. 웹훅 비밀값도 모드별로 따로예요.