KCP BRpay
This page provides an overview of the payments methods provided by the KCP BRpay adapter in the IXOPAY platform. It also includes a full list of all configuration options available to you when integrating KCP BRpay within your payments landscape, as well as an overview of the parameters required when submitting a transaction via IXOPAY's API.
KCP BRpay is NHN KCP's unified hosted redirect flow. One connector serves both PC
and mobile payers (selected through reg_type) and supports Credit Card, Bank
Transfer and Korean Carrier Billing.
Supported Payment Methods
| Payment Method | Transaction Flows | Transaction Types |
|---|---|---|
| Credit Card | Full-Page Redirect | Debit, Preauthorize, Capture, Void, Refund, Partial-Refund |
| Bank Transfer | Full-Page Redirect | Debit, Refund, Partial-Refund |
| Carrier Billing | Full-Page Redirect | Debit, Refund, Partial-Refund |
Carrier Billing (Korean mobile carriers SKT / KTF / LGT and MVNOs) is only available for South Korea (KR) in KRW.
Capture Mode
Whether KCP captures an authorization immediately or holds it for a later capture
is configured by NHN KCP on the merchant ID (MID), not per request. Every MID uses
auto capture unless KCP has enabled manual capture on it. For Credit Card
connectors, the captureMode connector option is required and has to match that
MID setting:
captureMode | Allowed transactions | Rejected transactions |
|---|---|---|
manual | Card: Preauthorize, Capture, Void, Refund. Bank Transfer / Carrier Billing: Debit, Refund | Card Debit |
auto | Debit, Refund | Preauthorize |
A rejected transaction fails before anything is sent to KCP, with error code
1007 and adapter code CAPTURE_MODE_MISMATCH.
captureMode has no default. If it is not set on a Credit Card connector, card
debits and preauthorizations are rejected with error code 1007 and adapter code
CAPTURE_MODE_NOT_CONFIGURED. Bank Transfer and Carrier Billing connectors do not
use it and can leave it unset.
KCP does not report a mismatch. On an auto-capture MID, a "preauthorization" is captured on approval. On a manual-capture MID, a debit is held and never settles. Set
captureModetomanualonly after KCP has confirmed that manual capture is enabled on the MID.
Preauthorize is only available for Credit Card: bank transfer and carrier billing settle on approval, so they are processed as debits in either mode.
Connector Configuration
| Option | Mandatory | Description |
|---|---|---|
certKey | Yes | KCP PG-API service certificate (PEM), issued in the KCP merchant portal. |
privateKey | Yes | Private key paired with the service certificate. Used to sign requests (kcp_sign_data). |
sslPrivatePassword | Yes | Password of the private key. |
merchantId | Yes | KCP merchant identifier (site code, site_cd). |
captureMode | Credit Card connectors | manual or auto, no default. Must match the capture setting on the KCP MID, see Capture Mode. Not used by Bank Transfer or Carrier Billing connectors. |
regTypeDefault | No | Payment-window type when a transaction does not send extraData.reg_type: web (PC) or mobile. Falls back to web. |
carrierFilter | No | Carriers offered for Carrier Billing, colon-separated, e.g. SKT:KTF:LGT. |
siteLogo | No | Not used by BRpay (shared KCP option, used by KCP PC). |
skinIndx | No | Not used by BRpay (shared KCP option, used by KCP PC). |
engFlag | No | Not used by BRpay (shared KCP option, used by KCP PC). |
siteName | No | Not used by BRpay (shared KCP option, used by KCP PC). Send extraData.shop_name instead. |
kcp_pay_title | No | Not used by BRpay (shared KCP option, used by KCP PC and KCP Mobile). |
use_tno_for_adaptertxid | No | Not used by BRpay (shared KCP option, used by KCP PC). BRpay always uses the KCP tno as adapter transaction id. |
Mandatory Debit & Preauthorize parameters
| Parameter | Type | Description |
|---|---|---|
description | String | Description of the transaction, shown as the product name (good_name). |
extraData.shop_user_id | String | Shop user id. Must not be empty: the KCP payment window rejects it. |
Optional Debit & Preauthorize parameters
| Parameter | Type | Description |
|---|---|---|
customer.firstName | String | Customer's first name (sent as buyr_name together with the last name). |
customer.lastName | String | Customer's last name. |
customer.email | String | Customer's email address. |
customer.billingPhone | String | Customer's billing phone number. |
extraData.reg_type | String | Payment-window type for this transaction: web (PC) or mobile. Overrides regTypeDefault. |
extraData.shop_name | String | Shop/merchant name shown on the payment window. |
extraData.escw_used | String | Escrow used? Possible values: N/Y. |
Capture parameters
| Parameter | Mandatory | Type | Description |
|---|---|---|---|
amount | Yes | Number | Must equal the preauthorized amount. |
description | No | String | Capture reason, sent to KCP as mod_desc. |
KCP captures the full authorization only. A capture for less than the preauthorized amount is rejected with error code
1002.
Void parameters
| Parameter | Mandatory | Type | Description |
|---|---|---|---|
description | No | String | Cancellation reason, sent to KCP as mod_desc. |
A void sends a full cancellation (STSC) for the authorization. Partial voids are
not supported.
Mandatory Refund & Partial-Refund parameters
| Parameter | Type | Description |
|---|---|---|
description | String | Reason or description for the refund. |
amount | Number | Amount to be refunded. |
A refund for less than the original amount is sent as a partial cancellation
(STPC). The KCP partial-cancellation sequence number (mod_pcan_seq_no) is
stored as the refund's second adapter transaction id.
Additional Postback ExtraData
| Key | Values | Description |
|---|---|---|
| acqu_cd | string | Card acquirer code (Credit Card only) |
| card_cd | string | Card issuer code (Credit Card only) |
| pay_method | string | Payment method (Credit Card and Bank Transfer) |
| card_no | string | Truncated PAN (Credit Card only) |
| bank_code | string | Bank code (Bank Transfer only) |
Error Handling
KCP result codes (res_cd) are mapped against the full KCP error catalogue, and
KCP's own message (res_msg / res_en_msg) is passed through. A payer
cancelling in the payment window (3001) maps to a cancelled transaction.
Provider Settlements
KCP settlement files are fetched through the data fetcher and parsed into provider settlements (KRW).
References:
- NHN KCP PG-API LITE Integration Guide (BRpay)
- NHN KCP PG-API Manual Capture API (HTTPS)
- NHN KCP Payment Standard API Cancel (Refund) (HTTPS)
- KCP Developer Documentation