NHN KCP gateway integration
The NHN KCP gateway integration enables merchants to accept credit card payments, KakaoPay, and PAYCO through KCP's hosted payment window.
NHN KCP is a South Korean payment gateway. The Zuora integration with NHN KCP supports three payment methods: hosted credit card, KakaoPay, and PAYCO. All three methods use KCP's own hosted payment window to collect and process payment information, so card data never passes through Zuora's Payment Form or Payment SDK.
Supported payment methods
The KCP gateway integration supports the following payment methods:
- Credit card — Card details are collected entirely in KCP's hosted payment window. The Payment Form renders a single button in place of card input fields. When a customer clicks the button, KCP's payment window opens to collect the card number, expiry date, and security code.
- KakaoPay — Processed through the hosted-components pattern. KakaoPay authentication and payment authorization occur inside KCP's hosted window.
- PAYCO — Processed through a dedicated PAYCO button component following the same hosted-components pattern. The PAYCO button renders with PAYCO branding and delegates authorization to KCP's hosted window.
Supported features
| Feature | Support |
|---|---|
| Payment method enrollment and recurring payments | Supported |
| One-time payments | Supported for credit card, KakaoPay, and PAYCO |
| Voids and referenced full or partial refunds | Supported for payments made with an enrolled KCP payment method |
| Gateway reconciliation | Not supported |
| Idempotent retries | Not supported |
| Hosted Payment Pages 2.0 and Hosted Payment Method pages | Not supported |
| Delayed capture and 3D Secure 2.0 | Not supported |
| Non-referenced refunds | Not supported |
How the hosted payment window flow works
When a customer initiates a payment using any of the three KCP payment methods, the Payment SDK follows this sequence:
- The merchant's implementation calls
createPaymentSessionto obtain a payment session. This callback is required for all three KCP payment methods; the SDK returns a configuration error if the callback is absent. - The SDK loads KCP's payment script (
kcp_spay_hub.js) dynamically from KCP's servers. The SDK waits up to 10 seconds for the required KCP globals to become available. If they do not load within that time, the payment attempt fails and the SDK reports the failure through theonCompletecallback. - KCP's payment window opens via
KCP_Pay_Execute_Web. The customer completes payment authentication and authorization inside KCP's window. - When the customer completes the payment, KCP returns an encrypted result containing the order identifier, result code, result message, encrypted payment data, and transaction code. The SDK submits this encrypted result to Zuora to complete the transaction.
- The SDK calls
onCompletewith the payment method ID and payment ID on success, or with an error on failure.
Gateway-hosted card form
When credit card is configured for the KCP gateway, the Payment Form renders a gateway-hosted card form rather than the standard card input form. This form displays a single button with no card number, expiry, or CVV fields. All card data is collected and encrypted within KCP's hosted window and is never transmitted through the Zuora SDK.
The gateway-hosted card form requires the createPaymentSession callback to be provided in the Payment Form configuration. If this callback is not provided, the SDK returns a configuration error when the button is clicked.
PAYCO button component
The PAYCO button component is a dedicated hosted component for the PAYCO payment method. The button renders with PAYCO's branding. In preview mode, the component renders a static button container. In live mode, the component runs inside a hosted-components iframe and delegates the payment flow to KCP's payment window.
The PAYCO button component requires both the createPaymentSession and onComplete callbacks. The following display options are available for the PAYCO button:
buttonWidth— Sets the width of the PAYCO button.buttonHeight— Sets the height of the PAYCO button.buttonRadius— Sets the corner radius of the PAYCO button.buttonColor— Sets the background color of the PAYCO button.
Requirements and limitations
Before using the KCP gateway integration, note the following requirements and limitations:
- The
createPaymentSessioncallback must be implemented and provided for all three KCP payment methods. The SDK returns a configuration error if this callback is absent. - The
onCompletecallback must be implemented and provided for the PAYCO component. - KCP's payment script is loaded dynamically at payment time. The KCP SDK URLs for both test (
testspay.kcp.co.kr) and production (spay.kcp.co.kr) environments are included in the Payment SDK's Content Security Policy allowlist. - The
unmount()anddestroy()operations are not supported for the PAYCO button component or the gateway-hosted card form. - If KCP's payment scripts do not finish loading within 10 seconds, the SDK logs a warning and reports the failure through
onComplete.