API · SDK

외부 연동 허브

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

외부 결합 가능 (파일럿)

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

연동 준비도 문서 →

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결제 의도 생성

Policy한도·권한 검증

Route최적 경로 선택

Execute결제 실행

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	환불

가맹점 포털 열기

iframe Embed Checkout

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

<iframe
  src="https://softpay-dapp.vercel.app/embed/checkout/claude-api-credit"
  width="420" height="640"
  style="border:0;border-radius:12px"
></iframe>

window.addEventListener("message", (e) => {
  if (e.data?.type === "SOFTPAY_CHECKOUT") {
    console.log(e.data.status, e.data.intentId);
  }
});

Merchant charges에 embed:true → paymentPageUrl

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)

데모를 불러오는 중…