API · SDK

외부 연동 허브

Merchant API · embed · SDK로 기존 제품에 결제를 붙입니다. 아래 15분 온보딩으로 파일럿을 시작하세요.

외부 결합 가능 (파일럿)

Merchant API + iframe embed + webhook HMAC + @softpay/agent-sdk(MerchantClient) — 프로덕션에서 데모·파일럿 연동 가능. Execute는 Mock(실카드 아님).

연동 준비도 문서 →postMessage 계약 가맹 포털 · Get embed code Webhook HMAC

Embed playground

Express · returnUrl · 상품을 바꿔 라이브 iframe과 스니펫(HTML/JS/curl/SDK)을 바로 복사하세요.

ProductreturnUrlSoftPay Express

Live preview

postMessage log

대기 중 — iframe에서 결제하거나 READY 이벤트를 기다립니다.

<iframe id="softpay" src="https://softpay-dapp.vercel.app/embed/checkout/claude-api-credit?returnUrl=https%3A%2F%2Fexample.com%2Fthanks&express=1" width="100%" height="560" style="border:0;border-radius:12px" allow="payment *"></iframe>
<script>
window.addEventListener("message", (e) => {
  if (e.origin !== "https://softpay-dapp.vercel.app") return;
  if (e.data?.type === "SOFTPAY_CHECKOUT" && e.data.status === "SETTLED") {
    console.log("paid", e.data.intentId);
  }
  if (e.data?.type === "SOFTPAY_EMBED_RESIZE") {
    document.getElementById("softpay").style.height = e.data.height + "px";
  }
  if (e.data?.type === "SOFTPAY_EMBED_ERROR") {
    console.error("softpay", e.data.message, e.data.code);
  }
});
</script>

URL: https://softpay-dapp.vercel.app/embed/checkout/claude-api-credit?returnUrl=https%3A%2F%2Fexample.com%2Fthanks&express=1

15분 온보딩

API 키 확인

GET /v1/me — 데모 키 sk_demo_* 또는 파일럿 전용 키

청구 생성

POST /v1/charges → paymentPageUrl 받기

embed 연결

iframe + postMessage 또는 checkout-widget

Webhook

PUT /v1/webhooks/url · HMAC 검증

SDK

MerchantClient로 백엔드 연동

Intent거래 의도 생성

Mandate위임·권한 검증

Policy한도·리스크 평가

Execute결제 실행

Clearing결과 검증·지급 확정

Receipt증빙·감사 기록

Runtime API — Intent 파이프라인

Base URL: https://runtime-api-production-5bc8.up.railway.app

Method	Path	설명
POST	/v1/intents	결제 요청 생성
POST	/v1/checkout	상품 결제 (중복 방지 키 지원)
POST	/v1/checkout/store	Smart Checkout
GET	/v1/approvals/pending	승인 대기 목록
POST	/v1/intents/:id/approve	승인 후 실행
POST	/v1/demo/agent/purchase	AI·에이전트 구매
POST	/v1/demo/qr/create	QR 결제 세션
POST	/v1/sandbox/simulate	규칙·경로만 검증 (결제 없음)
POST	/v1/sandbox/execute	검증 통과 시 Intent 생성
POST	/v1/intents/run	생성 + 즉시 실행

Merchant API — 가맹점 BFF (권장)

Runtime을 X-Api-Key로 감쌉니다. 외부 SaaS·쇼핑몰 연동은 여기서 시작하세요. https://merchant-api-production-a575.up.railway.app

Method	Path	설명
GET	/v1/me	가맹점 프로필
GET	/v1/products	내 상품·SKU
POST	/v1/charges	청구 + paymentPageUrl
GET	/v1/intents	내 결제 내역
GET	/v1/keys	API 키 목록
POST	/v1/keys/rotate	키 회전
PUT	/v1/webhooks/url	Webhook URL 등록
POST	/v1/intents/:id/refund	환불

OpenAPI: https://merchant-api-production-a575.up.railway.app /v1/openapi.json

가맹점 포털 열기

iframe Embed Checkout

헤더 없는 결제 UI · postMessage · returnUrl — 파트너 사이트에 그대로 삽입

Merchant charges에 embed:true → paymentPageUrl — 라이브 미리보기·스니펫은 위 Embed playground에서 복사하세요. 계약 문서: EMBED_POSTMESSAGE.md

embed 체크아웃 열기

TypeScript SDK

SoftPayClient(Runtime) · MerchantClient(가맹점 BFF)

import { MerchantClient, SoftPayClient } from "@softpay/agent-sdk";

const merchant = new MerchantClient({
  baseUrl: "https://merchant-api-production-a575.up.railway.app
",
  apiKey: process.env.SOFTPAY_API_KEY!,
});

const { paymentPageUrl } = await merchant.createCharge({
  productId: "claude-api-credit",
  embed: true,
  returnUrl: "https://your-app.com/thanks",
});

에이전트 구매 예시 (curl)

curl -X POST https://runtime-api-production-5bc8.up.railway.app
/v1/demo/agent/purchase \
  -H "Content-Type: application/json" \
  -d '{"agentId":"marketing-agent-001","productId":"enterprise-api-pack"}'

라이브 데모 운영 콘솔 외부 결합 가이드 (GitHub)

데모를 불러오는 중…