API docs by Redocly

PCINS Payment Gateway API (1.0.5)

Download OpenAPI specification:

E-mail: support@pcins.co.kr License: Proprietary - PCINS Payment Gateway Co., Ltd.

PCINS Hosted Payment Interface Service

Overview

PCINS e-Pay Interface Format1 (PeP1) Message Data Protocol This data protocol describes the PCINS API specification.

Change History

v1.0.5
  • Add callbackURL to Credit Card Payment (Non-UI) field
v1.0.4
  • Added an example response when a payment is completed without going through 3DS payment authentication in Direct 3DS Payment (UI)
v1.0.3
  • Added a new payment method. 3DS payments for VAN22(PCINS HR) must be made using the corresponding payment method (Direct 3DS Payment).
v1.0.2
  • Add returnURL to external UI payment field
v1.0.1
  • Add callbackURL to external UI payment field
  • Change the name of ErrorCode -> ResultCode
  • Add Result Code: 200
v1.0.0
  • Added a new payment method. 3DS payments for VAN36 and VAN37 must be made using the corresponding payment method (External UI Payment). All future 3D Secure payments will be processed using this payment method.
  • payEmail, payTel fields changed from O -> M Input Value (for Credit Card, Credit Certification, QR Payment).
  • Add Error Code: 101, 611, 612, 900, 901, 935, 936, 941

Abbreviations and Symbols

Abbreviation Definition
< Variable length data that can be entered up to the written value
a Letter or number such as alphabet
C Conditional required (field created if condition is met)
dp Decimal point
h Hexadecimal
M Required (field created)
n Number
O Optional (field created)
V Variable data with no length limit

Base URLs

  • Production: https://pay.pcins.co.kr/gw

Authentication (Test Account Environment)

NON-3DS:

  • merchantId: M000000187
  • merchantPwd: 1234

3DS:

  • merchantId: M000000413
  • merchantPwd: 1234

Data Format Principles

  • JPY amounts do not allow decimal points. USD amounts allow up to two decimal points.
  • expireM (Card valid month): The request format is MM. If 10 or less, always include 0 (01, 02, 03...).
  • expireY (Card valid year): The request format is YY. If it is less than 10, it must contain 0 (01, 02, 03...).
  • payId: Only letters and numbers are allowed in the data format.
  • transTime: The request format is YYYYMMDDHHMMSS.

Common Parameters

Message Stage (erst)

Value Definition
logon Logon Stage
aures Confirmation stage
logoff Logoff Stage

Transaction Type (tradeGubun)

Value Definition
1 Sale (online approval)
2 Refund
7 Confirmation/Credit Certification
9 Transaction inquiry
11 Register recurring billing
12 Cancel recurring billing

Currency (currType)

Value Definition
JPY Japanese Yen
USD US Dollar
EUR Euro
KRW Korean Won
CNY Chinese Yuan

Card Type (cardType)

Value Definition
AMX American Express
JCB Japanese Credit Bank
MSC MasterCard
VIS VISA

Special CardNo for Speedy Payment

Value Definition
88888888888888 Search for credit card information in merchantId + phone number + payId
88888888888881 Search for credit card information in merchantId + phone number
88888888888882 Search for credit card information in merchantId + payId

Language Code & Language (charset, lang)

Attribute Value Definition
charset UTF-8 Global
SHIFT-JIS Japanese
EUC-KR Korean
lang JP Japanese
EN English
CN Chinese

Transaction Codes

Field Value Definition
transCode (Status) AS Authorization Success
AF Authorization Failed
transStaus (Inquiry) 1 Sale
2 Refund

City Code (cityCode) - 3166-2:JP

Code Prefecture Code Prefecture Code Prefecture
1 HOKKAIDO 17 ISHIKAWA 33 OKAYAMA
2 AOMORI 18 FUKUI 34 HIROSHIMA
3 IWATE 19 YAMANASHI 35 YAMAGUCHI
4 MIYAGI 20 NAGANO 36 TOKUSHIMA
5 AKITA 21 GIFU 37 KAGAWA
6 YAMAGATA 22 SHIZUOKA 38 EHIME
7 FUKUSHIMA 23 AICHI 39 KOCHI
8 IBARAKI 24 MIE 40 FUKUOKA
9 TOCHIGI 25 SHIGA 41 SAGA
10 GUNMA 26 KYOTO 42 NAGASAKI
11 SAITAMA 27 OSAKA 43 KUMAMOTO
12 CHIBA 28 HYOGO 44 OITA
13 TOKYO 29 NARA 45 MIYAZAKI
14 KANAGAWA 30 WAKAYAMA 46 KAGOSHIMA
15 NIIGATA 31 TOTTORI 47 OKINAWA
16 TOYAMA 32 SHIMANE

Result Codes

Code Definition
000 Approval Success
101 Failed to enter continuous billing information.
200 Request Connection
611 Your card exceeds the monthly limit. Contact your administrator.
612 Your card exceeds the number of times you use it per month. Contact your administrator.
711 This card BIN cannot be used.
712 Korean card payment is not possible
713 Risk card registration card, please try again with another card.
900 The message is not long enough.
901 Connection Error.
902 VAN approval failure
909 Payment has already been made.
910 This card number is registered to the risk transaction card. Payment is not possible.
911 The one-time payment limit has been exceeded. Please contact the administrator.
912 The daily payment limit has been exceeded. Please contact the administrator.
913 The one-month payment limit has been exceeded. Please contact the administrator.
914 The password does not match.
915 Merchant Agreement is not Live.
916 Requirements not entered*
917 Transaction information does not exist.
918 Internet access is restricted. Please contact the administrator.
919 There is no payment information.
920 Exceeded limit
921 Insufficient balance
922 Incorrect card holder
923 Incorrect card number
924 Incorrect expiration date
925 Incorrect security code
926 System error
927 Card company approval rejected
928 Invalid card type
929 Stolen card
931 Please contact the card company.
932 Please enter the security code (CVV).
933 Incorrect card type.
934 This card is not eligible for the service.
935 Acquirer decline.
936 The minimum payment amount has not been met.
941 This payment has already been refunded.
999 Continuous charging has already been canceled.
Detailed Error Messages

Code 200

  • Request Connection
  • Mail sent successfully

Code 901

  • VAN login failed (VAN login information is incorrect.)
  • Invalid response data (VAN response data is empty or invalid.)

Code 902

  • The set currency and payment currency are different, so please check the merchant settings. (The VAN line supports only one payment currency.)

Code 916

  • Required not input (merchantID) (M000000187 not entered)
  • Required not input (merchantPW) (Merchant PW not entered)
  • Required not input (age) ()
  • Required not input (tradeGubun) (tradeGubun not entered)
  • Required not input (ref) (ref not entered)
  • Required not input (currType) (currType not entered)
  • Required not input (cardType) (cardType not entered)
  • Card are not supported for payment.
  • Required not input (cardNo) (cardNo not entered)
  • Required not input (expireM, expireY) (expireM or expireY not entered)
  • Required not input (payName) (payName not entered)
  • Required not input (payId) (payId not entered)
  • Required not input (payTel) (payTel not entered)
  • Required not input (productName) (productName not entered)
  • Required not input (price) (price not entered)
  • Required not input (transNo) (transNo not entered)
  • Required not input (regularId) (regularId not entered)
  • The email format is invalid.
  • Please contact the Merchant.

Code 936

  • Minimum payment amount must be ? Yen or more. (The minimum payment amount (Yen) set for the entire account or by store has not been met.)
  • Minimum payment amount must be ? Dollar or more. (The minimum payment amount (Dollar) set for the entire account or by store has not been met.)

Code 941

  • This payment has already been refunded. (There is already a canceled transaction.)
  • This payment is being refunded. (There is already a transaction waiting to be canceled.)

Support

Contact: support@pcins.co.kr

API Endpoints

List of all PCINS Payment Gateway operations

Credit Card Payment & Credit Certification (UI)

Redirects to PCINS payment screen for credit card payment or credit certification.

Flow

  1. Merchant sends form POST to pay_link.jsp
  2. User redirected to PCINS payment page
  3. User enters card info and completes payment/certification
  4. Result sent to callbackURL and returnURL

Return Payment Results (via redirect)

  • Success Callback: callbackURL?merchantId={id}&ref={ref}&payId={payId}&currType={cur}&price={price}&transNo={transNo}&transCode=AS
  • Success Return: returnURL?transCode=AS&transNo={transNo}&ref={ref}
  • Failure Return: returnURL?transCode=AF&transNo={transNo}&ref={ref}&errCode={errCode}

Use tradeGubun=1 for Payment, tradeGubun=7 for Certification

Request Body schema: application/x-www-form-urlencoded
required
One of
merchantId
required
string
merchantPwd
string

Required for 3DS authentication

ref
required
string
tradeGubun
required
string
currType
required
string
price
required
number
payName
string
payId
string
payEmail
required
string
payTel
required
string
productName
required
string
returnURL
required
string
callbackURL
required
string
transNo
string
errCode
string
cardType
string

Required for 3DS authentication

Responses

Request samples 

<!-- Content-Type: application/x-www-form-urlencoded -->
<form method="POST" action="https://pay.pcins.co.kr/gw/pay_link.jsp">
  <input type="hidden" name="merchantId" value="M000000187">
  <input type="hidden" name="ref" value="ORD20240122001">
  <input type="hidden" name="tradeGubun" value="1">
  <input type="hidden" name="currType" value="JPY">
  <input type="hidden" name="price" value="2000">
  <input type="hidden" name="payName" value="John Doe">
  <input type="hidden" name="payId" value="customer123">
  <input type="hidden" name="payEmail" value="john@example.com">
  <input type="hidden" name="payTel" value="090-1234-5678">
  <input type="hidden" name="productName" value="Test Product">
  <input type="hidden" name="returnURL" value="https://your-site.com/return">
  <input type="hidden" name="callbackURL" value="https://your-site.com/callback">
  <button type="submit">Pay Now</button>
</form>

Response samples

Content type
No sample

External UI Payment (3DS)

External payment page with 3D Secure authentication support. This endpoint is required for VAN36 and VAN37 3DS payments.

Return payment results callback

  • Success Callback: callbackURL?merchantId={id}&ref={ref}&payId={payId}&currType={cur}&price={price}&transNo={transNo}&transCode=AS
  • Success Return: returnURL?transCode=AS&transNo={transNo}&ref={ref}
  • Failure Return: returnURL?transCode=AF&transNo={transNo}&ref={ref}&errCode={errCode}
Request Body schema: application/x-www-form-urlencoded
required
merchantId
required
string
merchantPwd
required
string
ref
required
string
tradeGubun
required
string
currType
required
string
cardType
required
string
price
required
number
payName
required
string
payId
required
string
productName
required
string
payEmail
required
string
payTel
required
string
callbackURL
string
returnURL
string

Responses

Request samples 

<!-- Content-Type: application/x-www-form-urlencoded -->
<form method="POST" action="https://pay.pcins.co.kr/gw/pay_external.jsp">
  <input type="hidden" name="merchantId" value="M000000187">
  <input type="hidden" name="merchantPwd" value="1234">
  <input type="hidden" name="ref" value="ORD20240122001">
  <input type="hidden" name="tradeGubun" value="1">
  <input type="hidden" name="currType" value="JPY">
  <input type="hidden" name="cardType" value="VIS">
  <input type="hidden" name="price" value="2000">
  <input type="hidden" name="payName" value="John Doe">
  <input type="hidden" name="payId" value="customer123">
  <input type="hidden" name="productName" value="Test Product">
  <input type="hidden" name="payEmail" value="john@example.com">
  <input type="hidden" name="payTel" value="090-1234-5678">
  <input type="hidden" name="callbackURL" value="https://your-site.com/callback">
  <input type="hidden" name="returnURL" value="https://your-site.com/return">
  <button type="submit">Pay with 3DS</button>
</form>

Response samples

Content type
application/xml
Example
<?xml version="1.0" encoding="UTF-8" ?>
<script>
     window.location.href='External UI Payment URL';
</script>

Direct 3DS Payment (3DS)

Direct 3D Secure payment with card info submitted directly. This endpoint is required for VAN22(PCINS HR).

Return payment results callback

  • Success Callback: callbackURL?merchantId={id}&ref={ref}&payId={payId}&currType={cur}&price={price}&transNo={transNo}&transCode=AS
  • Success Return: returnURL?transCode=AS&transNo={transNo}&ref={ref}
  • Failure Return: returnURL?transCode=AF&transNo={transNo}&ref={ref}&errCode={errCode}

City Code Reference (3166-2:JP)

Use the numeric code for the cityCode parameter:

Code Prefecture Code Prefecture
1 HOKKAIDO 25 SHIGA
2 AOMORI 26 KYOTO
3 IWATE 27 OSAKA
4 MIYAGI 28 HYOGO
5 AKITA 29 NARA
6 YAMAGATA 30 WAKAYAMA
7 FUKUSHIMA 31 TOTTORI
8 IBARAKI 32 SHIMANE
9 TOCHIGI 33 OKAYAMA
10 GUNMA 34 HIROSHIMA
11 SAITAMA 35 YAMAGUCHI
12 CHIBA 36 TOKUSHIMA
13 TOKYO 37 KAGAWA
14 KANAGAWA 38 EHIME
15 NIIGATA 39 KOCHI
16 TOYAMA 40 FUKUOKA
17 ISHIKAWA 41 SAGA
18 FUKUI 42 NAGASAKI
19 YAMANASHI 43 KUMAMOTO
20 NAGANO 44 OITA
21 GIFU 45 MIYAZAKI
22 SHIZUOKA 46 KAGOSHIMA
23 AICHI 47 OKINAWA
24 MIE
Request Body schema: application/x-www-form-urlencoded
required
merchantId
required
string
merchantPwd
required
string
ref
required
string
tradeGubun
required
string
currType
required
string
cardType
required
string
cardNo
required
string
expireM
required
string
expireY
required
string
csc
required
string
price
required
number
payName
required
string
payId
required
string
productName
required
string
payEmail
required
string
payTel
required
string
address
required
string
cityCode
required
string
postCode
required
string
callbackURL
string
returnURL
string

Responses

Request samples 

<!-- Content-Type: application/x-www-form-urlencoded -->
<form method="POST" action="https://pay.pcins.co.kr/gw/pay_direct3ds.jsp">
  <input type="hidden" name="merchantId" value="M000000187">
  <input type="hidden" name="merchantPwd" value="1234">
  <input type="hidden" name="ref" value="ORD20240122001">
  <input type="hidden" name="tradeGubun" value="1">
  <input type="hidden" name="currType" value="JPY">
  <input type="hidden" name="cardType" value="VIS">
  <input type="hidden" name="cardNo" value="4111111111111111">
  <input type="hidden" name="expireM" value="12">
  <input type="hidden" name="expireY" value="25">
  <input type="hidden" name="csc" value="123">
  <input type="hidden" name="price" value="2000">
  <input type="hidden" name="payName" value="John Doe">
  <input type="hidden" name="payId" value="customer123">
  <input type="hidden" name="productName" value="Test Product">
  <input type="hidden" name="payEmail" value="john@example.com">
  <input type="hidden" name="payTel" value="090-1234-5678">
  <input type="hidden" name="address" value="Tokyo Minato-ku">
  <input type="hidden" name="cityCode" value="13">
  <input type="hidden" name="postCode" value="100-0001">
  <input type="hidden" name="callbackURL" value="https://your-site.com/callback">
  <input type="hidden" name="returnURL" value="https://your-site.com/return">
  <button type="submit">Direct 3DS Pay</button>
</form>

Response samples

Content type
application/xml
Example
<?xml version="1.0" encoding="UTF-8" ?>
<script>
     window.location.href='Direct 3DS Payment URL';
</script>

QR Payment (UI)

Generates QR code for Alipay/Wechatpay payment.

Flow

  1. Merchant sends form POST to qr_link.jsp
  2. User redirected to QR payment page
  3. User scans QR code with mobile app
  4. Payment completed and result returned
Request Body schema: application/x-www-form-urlencoded
required
merchantId
required
string
merchantPwd
string
ref
required
string
tradeGubun
required
string
currType
required
string
price
required
number
payName
required
string
payId
required
string
payEmail
required
string
payTel
required
string
productName
required
string
referURL
required
string
returnURL
required
string
lang
string

Responses

Request samples 

<!-- Content-Type: application/x-www-form-urlencoded -->
<form method="POST" action="https://pay.pcins.co.kr/gw/qr_link.jsp">
  <input type="hidden" name="ver" value="100">
  <input type="hidden" name="merchantId" value="M000000187">
  <input type="hidden" name="merchantPwd" value="1234">
  <input type="hidden" name="ref" value="ORD20240122001">
  <input type="hidden" name="tradeGubun" value="1">
  <input type="hidden" name="currType" value="CNY">
  <input type="hidden" name="price" value="2000">
  <input type="hidden" name="payName" value="John Doe">
  <input type="hidden" name="payId" value="customer123">
  <input type="hidden" name="payEmail" value="john@example.com">
  <input type="hidden" name="payTel" value="090-1234-5678">
  <input type="hidden" name="productName" value="Test Product">
  <input type="hidden" name="referURL" value="https://your-site.com/order">
  <input type="hidden" name="returnURL" value="https://your-site.com/return">
  <input type="hidden" name="lang" value="EN">
  <button type="submit">Generate QR</button>
</form>

Credit Card Payment, Speed Payment, Refund & Transaction Inquiry (Non-UI)

Direct API payment processing, speed payment, refunds, and transaction inquiry. Use tradeGubun parameter to specify operation:

  • tradeGubun=1: Credit Card Payment
  • tradeGubun=1 with special cardNo (8888...): Speed Payment
  • tradeGubun=2: Refund
  • tradeGubun=9: Transaction Inquiry
Request Body schema: application/x-www-form-urlencoded
required
One of
ver
required
string
merchantId
required
string
merchantPwd
required
string
ref
required
string
tradeGubun
required
string
cardNo
required
string
expireM
required
string
expireY
required
string
csc
string
currType
required
string
price
required
number
payName
required
string
payId
string
payEmail
required
string
payTel
required
string
productName
string
returnURL
string
callbackURL
string

Responses

Request samples 

curl -X POST https://pay.pcins.co.kr/gw/pay_request.jsp \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "ver=100" \
  -d "merchantId=M000000187" \
  -d "merchantPwd=1234" \
  -d "ref=ORD20240122001" \
  -d "tradeGubun=1" \
  -d "cardNo=4111111111111111" \
  -d "expireM=12" \
  -d "expireY=25" \
  -d "csc=123" \
  -d "currType=JPY" \
  -d "price=2000" \
  -d "payName=John Doe" \
  -d "payEmail=john@example.com"

Response samples

Content type
application/xml
Example
<?xml version="1.0" encoding="UTF-8" ?>
<TransactionResponse>
    <ref>ORD20240122001</ref>
    <transNo>20120815000012</transNo>
    <resultCode>000</resultCode>
    <resultMsg>Success</resultMsg>
    <transTime>20120815095629</transTime>
    <approvalNo>303577</approvalNo>
</TransactionResponse>

Payment Result Notification (Non-UI)

Webhook or API endpoint to receive 3DS payment result notification.

Request Body schema: application/x-www-form-urlencoded
required
ver
required
string
merchantId
required
string
merchantPwd
required
string
transNo
required
string
checkoutId
required
string
cardNo
required
string
expireM
required
string
expireY
required
string
csc
required
string
payName
required
string

Responses

Request samples 

curl -X POST https://pay.pcins.co.kr/gw/pay_3ds_status_check.jsp \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "ver=100" \
  -d "merchantId=M000000187" \
  -d "merchantPwd=1234" \
  -d "transNo=20241115000012" \
  -d "checkoutId=VAN12345" \
  -d "cardNo=4111111111111111" \
  -d "expireM=00" \
  -d "expireY=00" \
  -d "csc=777" \
  -d "payName=John Doe"

Response samples

Content type
application/xml
Example
<?xml version="1.0" encoding="UTF-8" ?> 
<TransactionResponse>
    <transNo>20241115000012</transNo> 
    <resultCode>000</resultCode> 
    <resultMsg>Transaction Successed</resultMsg> 
    <transTime>20241115095629</transTime> 
    <approvalNo>303577</approvalNo> 
</TransactionResponse>