Bank Submission Notice
This documentation set is being maintained for merchant onboarding, bank review, and production-readiness assessment, with emphasis on sandbox separation, key control, signed webhooks, auditability, and replay-safe transaction handling.
Merchant Setup Guide
This guide is written for merchants and technical teams who need a complete onboarding path for PaynPlus, from sandbox setup to production go-live.
이 문서는 PaynPlus를 연동해야 하는 가맹점과 기술 담당자를 위한 전체 온보딩 가이드입니다. 샌드박스 환경 구성부터 운영 전환까지 단계별로 설명합니다.
For bank review, security clarification, or production activation support, contact support@paynplus.com.
A merchant should be able to finish these steps before requesting production activation.
Receive your merchant profile
가맹점 프로필 수령
Request your merchant ID, sandbox keys, live keys, webhook secret, and whitelisting requirements from PaynPlus.
PaynPlus로부터 merchant ID, sandbox key, live key, webhook secret, 그리고 화이트리스트 요구사항을 전달받습니다.
Configure your sandbox environment
샌드박스 환경 구성
Store your test keys in server-side environment variables and register your success, cancel, and webhook URLs.
테스트 키를 서버 환경변수에 저장하고 success, cancel, webhook URL을 등록합니다.
Run your first payment test
첫 결제 테스트 실행
Create a sandbox Checkout Session or Payment Intent, redirect the customer, and confirm the dashboard and webhook result.
샌드박스 Checkout Session 또는 Payment Intent를 생성하고, 고객 리다이렉트 후 대시보드와 웹훅 결과를 확인합니다.
Validate failure and retry scenarios
실패 및 재시도 시나리오 검증
Test cancellation, expired session, failed payment, and webhook retry handling before moving to production.
운영 전 사용자 취소, 세션 만료, 결제 실패, 웹훅 재전송 처리까지 검증합니다.
Switch to live credentials
운영 키로 전환
Replace all test credentials, verify webhook security again, and confirm your production callback domains.
모든 테스트 자격증명을 운영용으로 교체하고, 웹훅 보안과 운영 콜백 도메인을 다시 점검합니다.
This guide has been structured to reflect current global documentation expectations around API security, payment data protection, zero-trust validation, and replay-safe transaction processing.
OWASP API Security Top 10 (2023)
The integration should enforce strong authentication, authorization checks, secure webhook handling, and proper inventory of exposed endpoints.
연동 구조는 강한 인증, 권한 검증, 안전한 웹훅 처리, 외부 노출 엔드포인트 관리 체계를 포함해야 합니다.
PCI DSS-aligned card handling
Cardholder data should stay out of merchant systems whenever possible by using hosted checkout or tokenization-first flows.
가능한 경우 hosted checkout 또는 tokenization 우선 구조를 사용하여 카드 데이터가 가맹점 시스템에 남지 않도록 해야 합니다.
Zero Trust operating posture
Do not rely on network location alone. Validate identity, keys, signatures, and environment boundaries for every sensitive interaction.
네트워크 위치만 신뢰하지 말고, 민감한 요청마다 신원, 키, 서명, 환경 경계를 검증해야 합니다.
Idempotency and replay safety
Use stable order references, event logging, and duplicate-event protection so retries do not create duplicate fulfillment or settlement errors.
고정 주문번호, 이벤트 로깅, 중복 이벤트 차단을 적용하여 재시도가 중복 처리나 정산 오류로 이어지지 않도록 해야 합니다.
Prepare these items first so your sandbox and production rollout stay predictable.
| Item | English | Korean |
|---|---|---|
| Merchant account | An approved PaynPlus merchant account with your merchant ID and settlement profile. | 승인된 PaynPlus 가맹점 계정과 merchant ID, 정산 프로필이 필요합니다. |
| Server environment | A backend or secure server where your secret key can be stored safely. | 시크릿 키를 안전하게 보관할 수 있는 백엔드 또는 보안 서버가 필요합니다. |
| Callback URLs | A success URL, cancel URL, and webhook endpoint reachable from the internet. | 인터넷에서 접근 가능한 success URL, cancel URL, webhook endpoint가 필요합니다. |
| Order system | Your own order or invoice reference so every payment can be matched to a business transaction. | 각 결제를 실제 주문과 매칭할 수 있도록 주문번호 또는 청구 reference가 필요합니다. |
| Operational owner | A technical contact who can monitor failed payments, webhook retries, and go-live issues. | 실패 결제, 웹훅 재시도, 운영 전환 이슈를 모니터링할 기술 담당자가 필요합니다. |
Use sandbox first for all functional, UI, webhook, and operational validation.
English Instructions
- 1. Request sandbox keys, merchant ID, and webhook secret.
- 2. Register your callback URLs and confirm if backend IP whitelisting is required.
- 3. Store the keys only on the server side and never expose the secret key in frontend code.
- 4. Create a sandbox checkout session, redirect the customer, and verify the redirect result.
- 5. Confirm the final status with the webhook before marking the order as paid.
한글 안내
- 1. sandbox key, merchant ID, webhook secret를 발급받습니다.
- 2. callback URL을 등록하고, 백엔드 IP 화이트리스트 필요 여부를 확인합니다.
- 3. 키는 반드시 서버 환경변수에만 저장하고 frontend 코드에 secret key를 노출하지 않습니다.
- 4. sandbox checkout session을 생성하고 고객을 리다이렉트한 뒤 결과를 확인합니다.
- 5. 결제 완료 처리는 반드시 webhook 기준으로 수행합니다.
Suggested Environment Variables
Use your own variable names if you prefer, but keep sandbox and live values separated.
PAYNPLUS_BASE_URL=https://api-sandbox.paynplus.com PAYNPLUS_PUBLIC_KEY=pk_test_xxxxxxxxxxxx PAYNPLUS_SECRET_KEY=sk_test_xxxxxxxxxxxx PAYNPLUS_WEBHOOK_SECRET=whsec_test_xxxxxxxxxxxx PAYNPLUS_MERCHANT_ID=merc_test_xxxxxxxxxxxx
Sandbox Safety Rules
- Use only test keys in sandbox and live keys only in production.
- Do not ship fulfillment logic based only on the success redirect.
- Log webhook event IDs so retries and duplicate events can be ignored safely.
- Keep merchant support and engineering aligned on test order references for reconciliation.
Example Sandbox Checkout Request
For most merchants, PaynPlus Checkout is the fastest and lowest-risk integration path.
const response = await fetch("https://api-sandbox.paynplus.com/v1/checkout/sessions", {
method: "POST",
headers: {
"Authorization": "Bearer sk_test_your_secret_key",
"Content-Type": "application/json"
},
body: JSON.stringify({
amount: 2500.00,
currency: "PHP",
reference_id: "ORDER-10021",
description: "Hotel room reservation",
success_url: "https://merchant.example/success?ref=ORDER-10021",
cancel_url: "https://merchant.example/cancel?ref=ORDER-10021"
})
});
const session = await response.json();
// Redirect your customer to session.checkout_urlFinish these test cases before you ask PaynPlus to switch your merchant profile to production readiness.
Card payment success
카드 결제 성공
Complete a successful card payment and verify that your order stays pending until the webhook confirms success.
카드 결제를 성공시킨 뒤 웹훅 성공 이벤트 전까지 주문이 보류 상태인지 확인합니다.
E-wallet authorization
E-wallet 인증
Redirect to the sandbox wallet page, finish the flow, and confirm that the customer returns to your success page.
샌드박스 지갑 페이지로 리다이렉트한 뒤 결제를 완료하고 고객이 success 페이지로 돌아오는지 확인합니다.
QR payment confirmation
QR 결제 확인
Test a QR payment and confirm that your system receives the same final status through the webhook channel.
QR 결제를 테스트하고 최종 상태가 웹훅으로 동일하게 수신되는지 확인합니다.
Cancellation and expiry
취소 및 만료
Validate customer cancellation, invalid session handling, and a clear retry path in your checkout UI.
고객 취소, 세션 만료, 그리고 재시도 흐름이 체크아웃 UI에서 명확히 처리되는지 검증합니다.
Webhook idempotency
웹훅 멱등 처리
Return a non-200 response once and verify that duplicate webhook deliveries do not create duplicate orders or double fulfillment.
한 번은 200이 아닌 응답을 반환해 보고, 웹훅 재전송이 중복 주문이나 중복 처리로 이어지지 않는지 확인합니다.
Webhook Verification Flow
The sandbox phase is where you prove that your backend handles async events correctly. This must be completed before go-live.
1. Log the raw request body. 2. Read the X-PaynPlus-Signature header. 3. Recompute the HMAC using your webhook secret. 4. Reject the request if the signature does not match. 5. Store the event ID and ignore duplicates. 6. Mark the order as paid only after a verified success event.
Where to find method-specific sandbox credentials
Use the payment-method guides for the latest sandbox credentials and UX behavior. Each method may have a different redirect or authorization experience.
Use this final review before you accept real funds and customer traffic.
Replace all test keys with live keys and confirm that no sandbox domain remains in production code.
모든 테스트 키를 운영 키로 교체하고, 운영 코드에 샌드박스 도메인이 남아 있지 않은지 확인합니다.
Verify that your webhook endpoint checks signatures and logs every event ID for auditing.
웹훅 엔드포인트가 서명을 검증하고 모든 event ID를 감사용으로 기록하는지 확인합니다.
Confirm that your success page does not mark an order as paid until the webhook arrives.
success 페이지가 뜨더라도 웹훅 전까지 주문을 결제 완료로 처리하지 않는지 확인합니다.
Review timeout, retry, refund, and support escalation procedures with your operations team.
타임아웃, 재시도, 환불, 고객지원 이관 절차를 운영팀과 함께 점검합니다.
Perform a small real payment in production and confirm dashboard, webhook, and reconciliation records.
운영 환경에서 소액 실결제를 수행하고 대시보드, 웹훅, 정산 기록이 모두 일치하는지 확인합니다.
Next Documents to Review
Once the merchant setup is complete, review the specific API and security pages below so your integration is ready for live traffic.
Sandbox and production domains, key prefixes, and rollout notes.
Secret key usage, public key scope, and request examples.
Signature checks, retries, and payment confirmation rules.