POP Protocol API 개발 문서
파이 네트워크 기반 암호화폐 및 법정화폐 하이브리드 결제를 가맹점 dApp 쇼핑몰에 손쉽게 연동하세요.
개요 및 API 인증
POP Protocol은 가맹점의 쇼핑몰과 파이 네트워크 블록체인을 연결하는 B2B 결제 게이트웨이입니다. 모든 백엔드 REST API 요청은 Authorization 헤더에 발급받은 비밀 키(Secret Key)를 포함해야 합니다. 클라이언트 코드에 비밀 키를 노출하지 마세요.
http://localhost:8080/v1Authorization: Bearer <YOUR_SECRET_KEY>각 HTTP 요청에 Bearer 토큰 형식으로 전달합니다.
- pop_test_sec_...파이 테스트넷 연동 및 로컬 개발용 샌드박스 키입니다.
- pop_live_sec_...실제 상용 결제 및 파이 메인넷 연동용 운영 키입니다.
# 1. Authenticate with Bearer API Secret Key
curl -X GET http://localhost:8080/v1/oracle/rates \
-H "Authorization: Bearer pop_test_sec_99a8b1c2e4f5a6b7c8d9e0f1" \
-H "Content-Type: application/json"프론트엔드 위젯 연동 (pop-widget.js)
가장 간편한 연동 방식은 경량화된 pop-widget.js를 로드하는 것입니다. 고객이 결제 버튼을 클릭할 때 PopCheckout.open()을 호출하면 모바일 및 데스크톱에 최적화된 결제 팝업창이 실행됩니다.
HTML 문서의 <head> 태그 내부 또는 <body> 태그 직전에 스크립트를 추가합니다.
가맹점 백엔드에서 생성한 sessionId를 파라미터로 넘겨 결제창을 실행합니다.
위젯 호출 파라미터 규격
필수. POST /v1/checkout/sessions API를 통해 발급받은 고유 세션 ID입니다.
선택. 고객의 결제가 승인 및 완료되었을 때 실행되는 콜백 함수입니다.
선택. 고객이 결제창을 닫거나 취소했을 때 실행되는 콜백 함수입니다.
<!-- 1. Load POP Checkout Widget in your HTML shop -->
<script src="http://localhost:3000/pop-widget.js"></script>
<!-- 2. Attach trigger to your checkout button -->
<button onclick="openPiPaymentModal()">Pay with Pi Network</button>
<script>
function openPiPaymentModal() {
// 3. Obtain sessionId from your backend (POST /v1/checkout/sessions)
const activeSessionId = "sess_99a8b1c2-3d4e-5f6a-7b8c-9d0e1f2a3b4c";
// 4. PopCheckout modal automatically renders centered modal
PopCheckout.open({
sessionId: activeSessionId,
onCompleted: function(payload) {
console.log("Payment Confirmed:", payload);
window.location.href = "/order/success?order_id=" + payload.dapp_order_id;
},
onClosed: function() {
console.log("User closed payment window.");
}
});
}
</script>백엔드 결제 세션 발급 API
고객에게 결제창을 띄우기 전, 가맹점 서버는 POST /v1/checkout/sessions를 호출하여 결제 세션을 생성해야 합니다. POP 엔진은 실시간 탈중앙 오라클 환율을 고정하고 결제 세션 ID를 발급합니다.
요청 바디 파라미터
가맹점 포털에 등록된 고유 식별자 (예: 11111111-1111-1111-1111-111111111111).
가맹점 쇼핑몰 고유 주문번호 (예: ORD-2026-98101).
법정화폐 기준 청구 금액 (예: 120.00).
3자리 ISO 통화 코드. 현재 USD를 기본 통화로 지원합니다.
선택. 결제 완료 후 이동할 고객 리디렉트 URL.
# Issue a new checkout session via cURL
curl -X POST http://localhost:8080/v1/checkout/sessions \
-H "Authorization: Bearer pop_test_sec_99a8b1c2e4f5a6b7c8d9e0f1" \
-H "Content-Type: application/json" \
-d '{
"merchant_id": "11111111-1111-1111-1111-111111111111",
"dapp_order_id": "ORD-2026-98101",
"amount": 120.00,
"currency": "USD",
"redirect_url": "https://mystore.com/order/98101"
}'웹훅 수신 및 서명 검증
고객이 온체인 파이 결제를 완료하면, POP Protocol은 가맹점이 등록한 웹훅 엔드포인트로 payment.completed 이벤트를 즉시 비동기 발송합니다.
위변조 공격 및 리플레이 공격을 방지하기 위해 주문 상태를 업데이트하기 전 X-POP-Signature 헤더의 서명을 가맹점 Webhook Secret Key로 반드시 검증하세요.
X-POP-Signature: hex(hmac_sha256(raw_body, webhook_secret))// Express.js Webhook Receiver & Signature Verifier
import express from 'express';
import crypto from 'crypto';
const app = express();
// Note: Use raw body buffer to compute exact HMAC signature
app.use(express.json({
verify: (req: any, res, buf) => {
req.rawBody = buf;
}
}));
const WEBHOOK_SECRET = 'whsec_99a8b1c2e4f5a6b7c8d9e0f1a2b3c4d577';
app.post('/api/webhook', (req: any, res) => {
const signature = req.headers['x-pop-signature'];
// Compute expected HMAC SHA-256
const hmac = crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(req.rawBody || JSON.stringify(req.body))
.digest('hex');
if (signature !== hmac) {
console.error('Invalid signature detected! Rejecting webhook.');
return res.status(401).send('Signature verification failed');
}
const { event_type, payload } = req.body;
if (event_type === 'payment.completed') {
console.log('Payment Completed for Order:', payload.merchant_uid || payload.dapp_order_id);
console.log('Pi TxID:', payload.pi_txid);
// TODO: Update your internal database order status to PAID
}
// Acknowledge receipt to POP Protocol
res.status(200).json({ received: true });
});