Welcome to Zuora Product Documentation

Explore our rich library of product information

Configure the KCP gateway integration with the Payment Form SDK

Learn how to configure the NHN KCP gateway integration in the Payment Form SDK to accept credit card payments, KakaoPay, and PAYCO.

  • A KCP gateway instance must be configured in your Zuora tenant before you initialize the Payment Form SDK.
  • Your integration must implement the createPaymentSession callback. This callback is required for the gateway-hosted card form and the PAYCO button component. The Payment Form SDK returns a configuration error if this callback is absent when either component is initialized.
  • Your integration must implement the onComplete callback to receive the payment result.

The KCP gateway integration supports three payment method types in the Payment Form SDK: credit card, KakaoPay, and PAYCO. Each type uses KCP's hosted payment window to collect payment details. For credit card payments, the Payment Form renders a single button instead of card input fields. When a customer clicks the button, KCP's hosted payment window opens and collects the card details directly. KakaoPay and PAYCO each render as branded button components that follow the same hosted-component pattern.

Card data is collected and encrypted entirely within KCP's hosted window. The Payment Form SDK does not receive or transmit raw card numbers.

  1. Configure a KCP gateway instance in your Zuora tenant.

    Enable the KCP payment gateway integration for your tenant before proceeding. See your Zuora administrator for the gateway configuration steps, including merchant credentials and test environment settings.

  2. Initialize the Payment Form SDK and include the KCP payment method type or types you want to support.

    The supported payment method type identifiers for KCP are creditcard, kakaopay, and payco. Set the type field in each PaymentMethodSetting entry to the appropriate identifier.

    For credit card, also set isGatewayHostedCard: true in the payment method setting. This flag causes the Payment Form to render a single button instead of card input fields and routes the payment flow through KCP's hosted window.

  3. Implement the createPaymentSession callback in your Payment Form configuration.

    The createPaymentSession callback is called by the SDK when a customer initiates a payment. Your implementation must create a payment session and return the session data required by KCP's hosted window. This callback is required for all three KCP payment method types. If the callback is not provided, the SDK returns a configuration error when the payment is initiated.

  4. Implement the onComplete callback to handle the payment result.

    The onComplete callback receives the outcome of the payment flow. On success, it receives the paymentMethodId and paymentId. On failure, it receives the error details. This callback is required for the PAYCO button component.

  5. (Optional) Configure display options for the PAYCO button component.

    When using the PAYCO payment method type, you can customize the button appearance with the following options in the payment method setting:

    • buttonWidth: Sets the width of the PAYCO button.
    • buttonHeight: Sets the height of the PAYCO button.
    • buttonRadius: Sets the border radius of the PAYCO button.
    • buttonColor: Sets the background color of the PAYCO button.

    When no button options are specified, the PAYCO button renders using the default dimensions from the Payment Form theme.

  6. Test your integration using the KCP test environment.

    To use the KCP test environment, configure your KCP gateway instance to point to the test endpoint. The KCP SDK loads kcp_spay_hub.js dynamically from either the test URL (testspay.kcp.co.kr) or the production URL (spay.kcp.co.kr) based on the gateway instance configuration. Verify that your Content Security Policy allows both URLs if you manage CSP headers in your environment.

    Use the test card details and testing scenarios provided by NHN KCP to validate the hosted payment window flow for each payment method type.

When configuration is complete, the Payment Form SDK renders the appropriate component for each KCP payment method type. The credit card form displays a single button that opens KCP's hosted payment window. The KakaoPay and PAYCO components display their respective branded buttons. On successful payment, the onComplete callback receives the payment method ID and payment ID.

If the KCP SDK does not load within 10 seconds, the SDK logs a warning and reports the failure through onComplete. Verify that the KCP SDK URLs are reachable from your environment and that no network or CSP policy blocks the script load.