South Korea Payment API

About 1246 wordsAbout 4 min

Warning

Before reading this API documentation, make sure to review the API Description Guide

Limits

Transaction Type	Limit
Collection	USD: 0.99-499.99; KRW: 1500~1000000
Payout	KRW: 1500~1500000

Collection API

Collection Application

Description:

Create a collection order

URL:

KRW: /krw/collect/apply
Note: appId KRW, amount KRW, settlement KRW

USD: /usd/collect/apply
Note: appId USD, amount USD, settlement USD

Parameters:

Parameter	Required	Type	Description
appId	Yes	Long	Business ID (obtained from the backend, needs to pass the corresponding business ID based on the currency in the URL)
orderId	Yes	String	Merchant order number (must be unique, max length 48)
name	Yes	String	User's full name, recommended to use the real name, format: firstName lastName, example: Donald John Trump
phone	Yes	String	Real phone number (format reference: Phone Number Format)
email	Yes	String	Real email address
amount	Yes	String	Transaction amount (rounded to two decimal places, no punctuation allowed, e.g., "50.00")
payType	Yes	String	Transaction type
inBankCode	Yes	String	Payment Methods
callBackUrl	Yes	String	URL to redirect after successful payment
callBackFailUrl	Yes	String	URL to redirect after failed payment
notifyUrl	No	String	Callback URL
subject	No	String	Payment description
body	No	String	Detailed description
partnerUserId	Yes	String	Unique identifier for the user (such as userID), used for risk control system, must be valid and accurate. Format: numbers, letters, or common symbols -~!@#$%&*()_
sign	Yes	String	Signature

Returned data parameters description

Parameter	Type	Description
orderId	String	Merchant order number (must be unique)
orderNo	String	Platform order number
payUrl	String	Payment link
sign	String	Signature

Collection Query

Description:

Query a collection order

URL:

KRW: /krw/collect/query

USD: /usd/collect/query

Parameters:

Parameter	Required	Type	Description
appId	Yes	Long	Business ID (obtained from backend, must be passed based on the currency in the URL)
orderId	Yes	String	Merchant order number
orderNo	No	String	Platform order number (faster response)
sign	Yes	String	Signature

Request Example:

request

{
  "appId": 1054,
  "orderId": "M22222000028",
  "sign": "EmyJGm3ELzG4FsOd0Krs9ncbSjo4oTGuXWML+7djYla3+VAwd9wS17z38p/7U2ZAjroO04XrE7YXcB1o76Dtyipj3h3bJzs7FYma1QNkMUdt9hh7m8U6hMsMQX7vIWHtXNwz4pbTSC75+kQWXaCew7KoE6LXECdJU8AISgNgeki2TK9R0pCfshr0Z2SZBPeuT6OvIH5LdmqgdZhuqnffGU2qnXk4KMkO848e6/WALLBR+LE1wyKHfPnYVcuKSMVYxkvKyyIL5JIPEgW0o5bh4RCbaUn3NZtyYwrU1uQ3ZDFRThm9j6XAQP+LBlmq3nOePqBtp/VDVarRaV+7FbQg3A=="
}

response

{
  "status": "1",
  "error": "00000000",
  "msg": "",
  "data": {
    "orderId": "M22222000028",
    "orderNo": "6023042811314347",
    "amount": "50.00",
    "actualAmount": "0.00",
    "fee": "0.00",
    "status": 1,
    "sign": "fP433ygWVDLVGxYkVnIJj7riGq0U3vyVX+MbBAImxfGLZkZcEAHVEoVYuULZSmXAAXKRSyd67WlDNm+24pougM54ofAoH4HMtCL2tfCoBReFyz3z02AGKkrKE2xWhSpWoqfQoBvzwuN5iGMMu0s9Q1YvqiwJ8WDVIENnmiIyD8qDJN7caHTW2US14/faG+69AvnuIgJ/nu7/jogOlgEYdZdVYU7gcRDE+d47KjlFGswQkJ/h/uzV7cWtUqrtOO7ZnZ3/z33Xx8awokX36QoYcPSWAU0h+Ij9O9402HNhm1eTbYcLU0uI/z8xCAtyAI/tTyiFijpiNlxUKQj+zKsILw=="
  }
}

Returned data parameters description

Parameter	Type	Description
orderId	String	Merchant order number (must be unique)
orderNo	String	Platform order number
amount	String	Transaction amount
actualAmount	String	Amount received
fee	String	Service fee
status	Integer	Status (0 not started, 1 in progress, 2 success (final), 3 failed (final), -1 exception awaiting confirmation)
payTime	String	Payment success time (when status=2, there is a value) (local time), format: yyyy-MM-dd HH:mm:ss
errorMsg	String	Payment failure reason (when status=3, there is a value)
sign	String	Signature

Payment Methods

1. Local Cashier Mode:

payType	inBankCode
CASHIER	CASHIER

2. Non-Cashier Mode:

payType	inBankCode	Limit	Description	Local Cashier
BANK_TRANSFER	KAKAOPAY_USD	0.99-1000	USD order, Korea Kakao	Supported
BANK_TRANSFER	TOSS_USD	0.99-1000	USD order, Korea Toss	Supported
BANK_TRANSFER	NAVERPAY_USD	0.99-1000	USD order, Korea Naverpay	Supported
BANK_TRANSFER	KR_BANK_USD	0.99-1000	USD order, input bank card details	Supported
EWALLET	SAMSUNGPAY_USD	0.99-1000	USD order, Samsung Pay	Supported
BANK_TRANSFER	KAKAOPAY_KRW	1500-1000000	KRW order, Korea Kakao	Supported
BANK_TRANSFER	TOSS_KRW	1500-1000000	KRW order, Korea Toss	Supported
BANK_TRANSFER	NAVERPAY_KRW	1500-1000000	KRW order, Korea Naverpay	Supported
BANK_TRANSFER	BANK_KRW	1500-1000000	KRW order, input bank card details	Supported
EWALLET	SAMSUNGPAY_KRW	1500-1000000	KRW order, Samsung Pay	Supported
EWALLET	GOOGLE_PAY	0.99-1000	USD order, Google Pay	Supported
EWALLET	APPLE_PAY	0.99-1000	USD order, Apple Pay	Supported

Payout API

Payout Application

Description:

Create a payout order

URL: /krw/pay/apply

Parameters:

Parameter	Required	Type	Description
appId	Yes	Long	Business ID (obtained from the backend, needs to pass the corresponding business ID based on the currency in the URL)
orderId	Yes	String	Merchant order number (must be unique, max length 48)
amount	Yes	String	Transaction amount (in ₩, rounded to two decimal places, no punctuation, e.g., “,”)
accountType	Yes	String	Account type: BANK_ACCOUNT (bank account)
bankCode	Yes	String	Bank code (see Appendix: Payout Bank Codes)
accountNo	Yes	String	User's bank account number
name	Yes	String	Recipient's name (format: uppercase letters with spaces allowed, 1-30 characters, "firstName middleName lastName" (middleName is optional, special characters supported: .-))
phone	Yes	String	Phone number
email	Yes	String	Email address
notifyUrl	No	String	Callback URL
subject	No	String	Payment description
body	No	String	Detailed description
partnerUserId	Yes	String	Unique identifier for the user (e.g., userID), used for the risk control system, must be valid and accurate. Format: numbers, uppercase/lowercase letters, or common symbols -~!@#$%&*()_
sign	Yes	String	Signature

request（When accountType = BANK_ACCOUNT）

{
  "appId": 1054,
  "orderId": "M100000450012",
  "amount": "2000",
  "accountType": "BANK_ACCOUNT",
  "bankCode": "KYNAKR22",
  "accountNo": "09876543210",
  "name": "john doe",
  "phone": "09876543210",
  "email": "johndoe@cashfree.com",
  "subject": "iphone13",
  "body": "ProMotion technology with adaptive refresh rates up to 120Hz",
  "partnerUserId": "149597870",
  "sign": "I1PeK3eJOVsFFNowxVRqMXpeWm1lr/BcRpBi8WsW4wVo1+5CC3JsrFq/m/L2O69NzKHvtDWi4zia3DL3dPut0yMyUyqL91LNCSaeISbGsQPlhEsQpyTOryS/RKOfsrn2Xo37SCF/phAvndOk2jwwGwqM5xLz1ms9Ukl85wv27QFNrXIMxK2p18oe7MpMYrgf+xvEBE/VqCtKMtN9pO449wWwXzHWNPbZ76s4pAvKwRE9yXQDr7Iw14Dktcnl1FoLM4gWM/obkO+mz6SyAGDuXhVh/+OD/IGNiCyTCNq6ciQY28UnCFV6ZIP40gxsFhfBJKbK+Raw7y1Bh912ifYfug=="
}

response

{
  "status": "1",
  "error": "00000000",
  "msg": "",
  "data": {
    "orderId": "M100000450013",
    "orderNo": "3023062014149637",
    "sign": "LmhUnkw5j0pMiimsG8rKwdNNZGvXH5MpSmD6mdHZwq1SQwuK5BohmdEoqKB/jkMk28o3da4Cxh6Q+tW97+yTCemRrF+dMaHA73rpOeUuujKQl/UcFvJuMhfLBa2tp09L71NzoBqpPD6aXf37mYAz8E1HmERwFPpac5FVxIYanHG8cqmMLJYsVmHTSxWavgWU03ys9UczBePkBiR8sl2FSOhFABB0wAP28lswrV/ABS68IsLKtyd1fyI3GBfSbIK5nDEEnlE+EdElFdLs9taAxJImeVF1x4eT47+bkPJ2qS8z3K8QGzKLF3W+8SiRZGfSwDTsLKH+2Vycvy5auRl+ag=="
  }
}

Returned data parameters description

Parameter	Required	Type	Description
orderId	Yes	String	Merchant order number (must be unique)
orderNo	Yes	String	Platform order number
sign	Yes	String	Signature

Payout Query

Description:

Create a payout order

URL: /krw/pay/query

Parameters:

Parameter	Required	Type	Description
appId	Yes	Long	Business ID (obtained from the backend, needs to pass the corresponding business ID based on the currency in the URL)
orderId	Yes	String	Merchant order number
orderNo	No	String	Platform order number (faster response)
sign	Yes	String	Signature

request

{
  "appId": 1000,
  "orderId": "M1234567111",
  "orderNo": "3022111516571436",
  "sign": "ZxkVZL+GAyv0VhvWn4IvuYahTzxgQuthkuV2ONWiqIfIDb2avvHlFOUJVzqZi1q8CPHXZm1ltanRTRVTxfsuftLvGeDioUHglWt46/RU6c1OPznpLGsZ35Q3n5tW2y1EnOsxPynXBFLuDQy+aZ3l9u6AQ30T0zQexMGT+IxuFkmUp02g/6juaHa5ZgNMv7lN67ixIp162wrM7OJuaOif872QijSceRdZhzaMGImAwB0D4MosRV4WMBOKkwgPdmS7GuZN66YUidXk3wTGqX3MYRw6M0kj4eNegSUwPXvp4q4p0KO8Y3xUMld54GY2ApX3WN3CBtC/vpJqEszjGBbbGg=="
}

response — Order Failed

{
  "status": "1",
  "error": "00000000",
  "msg": "",
  "data": {
    "orderId": "M1234567111",
    "orderNo": "3022111516571436",
    "amount": "2000.00",
    "fee": "0.00",
    "status": 3,
    "errorMsg": "Đơn hàng không tồn tại",
    "sign": "KKuvCl0SuNANJs+l2ogDaJm8pmV+Hi+Xa7q27vJ6D1Ehs4aOp13kRbITfJAhczh3T81BE9qwHeJaYwf+r0EypKM9TL6pMwfG8Az4gRy1D57wiUaVjl2PWcvbEqrn1hL0b+btkjvAM9I+CcSv+wuOW3/uku17Ws3FhgJLj9sFsQUBAPjDO+758VnwBytCOLBmljLBXyKgNgpmFQ1/DNkqWl0UNzyLK45Zw3yf5NiwhEFbvW0jlOWlfu/ql4hluISUQG573jEoFCBEnQLb2tQoRZj1QYNRCXPf5lbej0vzqbEwvR9h+ZOf255t1MocJkdIe463DTV5U3KZdVT87HMagw=="
  }
}

response — Order Successful

{
  "status": "1",
  "error": "00000000",
  "msg": "",
  "data": {
    "orderId": "M1234567112",
    "orderNo": "3022111517401574",
    "amount": "2000.00",
    "fee": "1003.00",
    "status": 2,
    "payTime": "2024-03-01 23:59:59",
    "sign": "khPtOmGq+cpKX0HFAI/lbP0dx4oVyNAnL5oLsdmhDJdASlQm0yg5I3o+MhImYggEsL6c2bo5fP29t54OZFqSdQDfIuNDvGbAMAr4mRBxc0hoHLkBLyyagfVPBLyQA1JY8XV3ZL4ySzQ3ZQnMCfrh2K39ueUuz6HpZ03Hj0KYijVRCXAZaio/L5jfLBT12QXmvIfAHa8s/k9flhK05ENHPep3zjj/MZGOEaX7jkEJLfjK0duypDCa61BRQjM+oePOdVsgleIl1Yf98UAxMDZ/A3912KFHEb+/jvmdnulNbiJFyuT1fEe+j2teUgw3vFsZAtwNWAgxhC7UO+N0Q5z4EA=="
  }
}

Returned data parameters description

Parameter	Type	Description
orderId	String	Merchant order number (must be unique)
orderNo	String	Platform order number
amount	String	Transaction amount
fee	String	Transaction fee
status	Integer	Status (0 not started, 1 in progress, 2 success (final state), 3 failure (final state), -1 pending confirmation)
payTime	String	Payment success time (when status=2) (Korean time), format: yyyy-MM-dd HH:mm:ss
errorMsg	String	Payment failure reason (when status=3)
sign	String	Signature

Appendix - Payout Bank Codes

bankCode	bankName
SAMCKRSL	Samsung Securities
KOPOKRS1	Korea Post(Epost)
KWABKRSE	Kwangju Bank(KJ)
KYBOKRSE	Kyobo Securities
KYNAKR22	Kyongnam Bank
MHCBKRSE	Mirae Asset Daewoo
NACFKRSE	Nonghyup Bank(NH)
NFFCKRSE	Suhyup Local Cooperatives
PUSBKR2P	Busan Bank(BNK)
KODBKRSE	Korea Development Bank(KDB)
SCBLKRSE	Standard Chartered Korea(SC First)
SECDKRS1	Daishin Securities
SEOSKRS1	Eugene Investment and Securities
SHBKKRSE	Shinhan Bank
SHHEKRS1	Hyundai Motor Securities
SKSEKRS1	SK Securities
SSISKRSS	Shinhan Investment
WISHKRSE	NH Investment and Securities
HVBKKRSE	Woori Bank
CITIKRSXKAK	K Bank
CZNBKRSE	Kookmin-Bank(KB)
DAEBKR22	Daegu Bank(DGB)
DEUTKRSE	Deutsche Bank
ETSIKRS1	eBEST Investment and Securities
HNBNKRSE	KEB Hana Bank
HNWSKRSS	Hanhwa Investment and Securities
HSBCKRSE	HSBC
CITIKRSX	Citibank Korea
HYSEKRSE	KB Securities
IBKOKRSE	Industrial Bank of Korea(IBK)
JEONKRSE	Jeonbuk Bank(JB)
JJBKKR22	Jeju Bank
KAKOKR22	KAKAO Bank
KFBCKRSE	Meritz Securities
KISEKRSE	Korea Investment and Securities
KIWCKRSE	Kiwoom Securities