Developer platform

개발자 API

멱등성 키, 서명된 웹훅, 호스팅 체크아웃 세션을 포함한 REST 결제 API입니다.

Get Sandbox keys Run a test payment

REST API Signed webhooks Hosted checkout

POST /v1/payments Sandbox

amount128.00 currencyUSD methodhosted_checkout

Merchant→WQN→Provider

✓

payment.succeededReady for webhook delivery

200

01Sandbox firstTest outcomes before live onboarding

02Secure eventsHMAC signatures and replay protection

03Clear operationsTransactions, reports, and settlement visibility

04Regional routingProvider-ready payment orchestration

Start here

Make your first test payment.

Use Sandbox credentials, create a payment intent, send the customer to hosted checkout, and verify the signed webhook before updating your order.

QuickstartFollow the integration sequence

API referenceReview available endpoints

WebhooksVerify signed payment events

Testing guideSimulate payment outcomes

Quickstart

1Create merchant account
2Generate sandbox keys
3Create payment intent
4Redirect to hosted checkout
5Verify webhook signature
6Reconcile settlement report

보안 모델

HMAC

WQN bearer API keys are issued only after document review approval.
Provider credentials remain server-side and are never sent to merchant browsers.
Signed webhooks with timestamp tolerance and replay protection.
Hosted checkout keeps raw card or wallet details outside merchant systems.

Endpoints

REST

WQN Gateway API v1 endpoint overview.
Method	Path	Use
POST	`/api/v1/payments`	Create a live hosted-checkout payment through the WQN key and OneCloudPay provider route
GET	`/api/v1/payments`	List recent payments for the authenticated merchant API key
GET	`/api/v1/payments/{id}`	Read payment state, checkout URL, and provider references
GET	`/api/v1/wallet`	Read merchant wallet balances and recent ledger entries
GET	`/api/v1/bank-accounts`	List masked bank accounts configured for the authenticated merchant
GET	`/api/v1/kyc`	Read merchant KYC/KYB profile status
GET	`/api/v1/withdrawals`	List merchant withdrawal requests
POST	`/api/v1/withdrawals`	Create a withdrawal request and lock wallet balance for operations approval
GET	`/api/v1/settlements`	List merchant settlement batches
GET	`/api/v1/reports/summary`	Read payment, wallet, settlement, and withdrawal totals
GET	`/api/v1/notifications`	List merchant notifications
GET	`/api/v1/support-tickets`	List support tickets opened by the merchant
POST	`/api/v1/support-tickets`	Open a support ticket for integration, settlement, webhook, or payment issues
GET	`/api/v1/payment-links`	List merchant payment links
GET	`/api/v1/qr-codes`	List merchant QR payment codes
GET	`/api/v1/webhooks`	List configured merchant webhook endpoints
POST	`/v1/checkout/sessions`	Planned hosted checkout session abstraction for future provider routing
POST	`/v1/provider-routes/2c2p`	Select 2C2P-style route for card, wallet, QR, BNPL, or counter payment
POST	`/v1/providers/2c2p/payment-token`	Create a provider session token before redirect, direct, or SDK payment
POST	`/v1/providers/2c2p/webhook`	Receive encrypted/signed provider notification and normalize WQN event
POST	`/v1/refunds`	Create full or partial refund
POST	`/v1/payments/{id}/cancel`	Cancel or void eligible pending provider transaction
POST	`/v1/webhooks/test`	Send a signed test webhook to merchant endpoint
GET	`/v1/settlements`	List settlement batches and reconciliation files

요청 예시

curl -X POST "https://gateway.wqnwqn.com/api/v1/payments" \
  -H "Authorization: Bearer wqn_sandbox_your_merchant_key" \
  -H "Idempotency-Key: ORDER-1001-create" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50,
    "currency": "USD",
    "merchant_reference": "ORDER-1001",
    "description": "Order 1001",
    "return_url": "https://merchant.example.com/success",
    "cancel_url": "https://merchant.example.com/cancel"
  }'

응답 예시

{
  "data": {
    "id": "wqn_pay_9a41c20bd1ee4552",
    "object": "payment",
    "status": "pending",
    "amount": 50,
    "currency": "USD",
    "merchant_reference": "ORDER-1001",
    "checkout_url": "https://gateway.wqnwqn.com/sandbox/checkout/...",
    "provider": "sandbox",
    "provider_payment_id": "pay_test_provider_..."
  }
}

Webhook delivery flow

Security guide

1Receive and authenticate the provider event
2Normalize provider status to a WQN event
3Persist the event idempotently
4Sign the merchant webhook payload
5Deliver, record the response, and retry safely

Webhook security notes

Required

Verify the HMAC SHA-256 signature against the raw request body.
Reject stale timestamps and store processed event IDs to prevent replay.
Return a successful response only after durable processing or queueing.
Handle duplicate and out-of-order events without corrupting payment state.
Retry transient failures with bounded exponential backoff.