Wallet Recurring Payment API
This is a Charge Subscription API using a KakaoPay Subscription Key. You can use a Subscription Key issued through KakaoPay digital wallet payment to make recurring charges.
Test Key Information
API Information
POST/spay/APIPZSubsTrd.do
Content-Type
application/jsonSandbox
https://tbgw.settlebank.co.kr/spay/APIPZSubsTrd.doProduction
https://gw.settlebank.co.kr/spay/APIPZSubsTrd.doImportant Notes
A separate merchant ID is required for each purpose
A Subscription Key is not issued with a general payment merchant ID. Get a separate merchant ID for subscription or sequential payments through your sales representative.
- KakaoPay and Naver Pay are supported.
Merchant ID by purpose
A single merchant ID cannot be used for both general payments and subscription or sequential payments. You need a separate merchant ID for each purpose. Request them through your sales representative.
| Purpose | autoPayType | Test merchant ID |
|---|---|---|
| General payment (KakaoPay, Naver Pay) | Not used | hecto_test |
| KakaoPay subscription | A | nxkkp_auto |
| KakaoPay sequential payment | S | nxkkp_seq |
| Naver Pay subscription | A | nxnvp_auto |
- Subscription Key issuance procedure:
- Use the merchant ID for the purpose when calling the checkout (see the table above)
- Set the
autoPayTypeparameter (KakaoPay:AorS/ Naver Pay:A) and the customer IDmchtCustId - Receive the
billKeyfrom the response upon successful payment
- The issued Subscription Key is used in the
billKeyparameter when calling the Charge Subscription API. mUserIdin the Charge Subscription API must match themchtCustIdsent in the key issuance checkout (the original value before encryption). Always sendmchtCustIdin the key issuance checkout.
KRW 0 Subscription Key issuance by provider
| Provider | Checkout trdAmt = 0 | Description |
|---|---|---|
| KakaoPay | Supported | A Subscription Key can be issued without a charge. |
| Naver Pay | Not supported | A Subscription Key is issued only after an actual payment. |
NOTE
Subscription Key issuance checkout
For how to call the checkout to issue a Subscription Key, see the KakaoPay checkout document.
Request Parameters
Type Notation
NNumericAAlphabeticHKoreanANAlphanumericAHNAlphanumeric + Koreane.g. AN(10) = alphanumeric, up to 10 bytes
params Object
└mchtIdAN(10)Alphanumeric, up to 10 bytes*Unique merchant ID assigned by Hecto Financial
Unique merchant ID assigned by Hecto Financial
nxkkp_auto: KakaoPay subscription (automatic payment)└verAN(4)Alphanumeric, up to 4 bytes*Message version
Message version
*Fixed value
└methodA(2)Alphabetic, up to 2 bytes*Payment method
Payment method
*Fixed value (PZ: Digital Wallet)
└bizTypeAN(2)Alphanumeric, up to 2 bytes*Business type code
Business type code
*Fixed value (B3: Subscription charge)
└encCdN(2)Numeric, up to 2 bytes*Encryption classification code
Encryption classification code
*Fixed value
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*Unique order number generated by the merchant
Unique order number generated by the merchant
└trdDtN(8)Numeric, up to 8 bytes*Request date (yyyyMMdd)
Request date (yyyyMMdd)
└trdTmN(6)Numeric, up to 6 bytes*Request time (HH24MISS)
Request time (HH24MISS)
└mobileYnA(1)Alphabetic, up to 1 bytesMobile indicator
Mobile indicator
Y: Mobile web/app N: PC or other└osTypeA(1)Alphabetic, up to 1 bytesOS type
OS type
A: Android I: iOS W: Windows M: Mac E: Otherdata Object
└pktHashAN(64)Alphanumeric, up to 64 bytes*
SHA-256Hash value generated using SHA256(auto-generated)Hash value generated using SHA256
NOTE
Hash generation combination
trdDt + trdTm + mchtId + mchtTrdNo + trdAmtEnc (plaintext) + hashKey
└corpPayCodeAN(40)Alphanumeric, up to 40 bytes*Digital wallet provider ID
Digital wallet provider ID
KKP: KakaoPay NVP: NaverPay└mUserIdAHN(50)Alphanumeric + Korean, up to 50 bytes*Merchant customer ID used at the time of Subscription Key issuance
Merchant customer ID used at the time of Subscription Key issuance
*Must match the mchtCustId sent in the key issuance checkout (the original value before encryption).
└ordNmAHN(30)Alphanumeric + Korean, up to 30 bytes*Order name
Order name
└crcCdA(3)Alphabetic, up to 3 bytes*Currency classification value
Currency classification value
*Fixed value
└taxTypeA(1)Alphabetic, up to 1 bytesTax type
Tax type
N: Taxable Y: Tax-exempt G: Mixed tax└trdAmtEncN(12)Numeric, up to 12 bytes*
AES-256AES-256/ECB/PKCS5Padding + Base64Transaction amountTransaction amount
└taxAmtEncN(12)Numeric, up to 12 bytes
AES-256AES-256/ECB/PKCS5Padding + Base64Taxable amount (required for mixed tax)Taxable amount (required for mixed tax)
└vatAmtEncN(12)Numeric, up to 12 bytes
AES-256AES-256/ECB/PKCS5Padding + Base64VAT amount (required for mixed tax)VAT amount (required for mixed tax)
└taxFreeAmtEncN(12)Numeric, up to 12 bytes
AES-256AES-256/ECB/PKCS5Padding + Base64Tax-exempt amount (required for mixed tax)Tax-exempt amount (required for mixed tax)
└svcAmtEncN(12)Numeric, up to 12 bytes
AES-256AES-256/ECB/PKCS5Padding + Base64Service chargeService charge
└billKeyAN(50)Alphanumeric, up to 50 bytes*Subscription Key issued by Hecto Financial
Subscription Key issued by Hecto Financial
└prdtNmAHN(128)Alphanumeric + Korean, up to 128 bytes*Product name
Product name
└etcOrdInfoAHN(4000)Alphanumeric + Korean, up to 4000 bytesMerchant reserved field for entering additional order information
Merchant reserved field for entering additional order information
└csrcIssReqYnA(1)Alphabetic, up to 1 bytesCash receipt issuance flag
Cash receipt issuance flag
Y: Issue N: Do not issue*NaverPay only
└cashRcptPrposDivCdN(1)Numeric, up to 1 bytesCash receipt purpose classification
Cash receipt purpose classification
0: Income deduction 1: Expense proof*Required when using cash receipt. NaverPay only
└csrcRegNoDivCdN(1)Numeric, up to 1 bytesRegistration number type code
Registration number type code
1: Card 2: Resident registration number 3: Business registration number 4: Mobile phone number*Required when using cash receipt. NaverPay only
└csrcRegNoAN(64)Alphanumeric, up to 64 bytes
AES-256AES-256/ECB/PKCS5Padding + Base64Unique identification informationUnique identification information
*Required when using cash receipt. NaverPay only
Response Parameters
Type Notation
NNumericAAlphabeticHKoreanANAlphanumericAHNAlphanumeric + Koreane.g. AN(10) = alphanumeric, up to 10 bytes
params Object
└mchtIdAN(10)Alphanumeric, up to 10 bytes*Merchant ID
nxkkp_autoMerchant ID
└verAN(4)Alphanumeric, up to 4 bytesMessage version
0A19Message version
└methodA(2)Alphabetic, up to 2 bytesPayment method
PZPayment method
└bizTypeAN(2)Alphanumeric, up to 2 bytesBusiness type code
B3Business type code
└encCdN(2)Numeric, up to 2 bytes*Encryption classification code
23Encryption classification code
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*Merchant order number
ORDER20211231100000Merchant order number
└trdNoAN(40)Alphanumeric, up to 40 bytes*Hecto Financial transaction number
STFP_PGPZnx_mid_hd0230315153232M1196602Hecto Financial transaction number
└trdDtN(8)Numeric, up to 8 bytes*Approval request date (YYYYMMDD)
20211231Approval request date (YYYYMMDD)
└trdTmN(6)Numeric, up to 6 bytes*Approval request time (HHMMSS)
100000Approval request time (HHMMSS)
└outStatCdAN(4)Alphanumeric, up to 4 bytes*Transaction status code (success/failure)
0021Transaction status code (success/failure)
0021: Success 0031: Failure└outRsltCdAN(4)Alphanumeric, up to 4 bytes*Result code
0000Result code
└outRsltMsgAHN(200)Alphanumeric + Korean, up to 200 bytes*Result message
Processed successfully.Result message
data Object
└pktHashAN(64)Alphanumeric, up to 64 bytes*Hash value generated using SHA256
f395b6725a9a18...Hash value generated using SHA256
NOTE
Hash Generation Combination
outStatCd + trdDt + trdTm + mchtId + mchtTrdNo + trdAmtEnc (plaintext) + hashKey
└AuthTrdNoAN(40)Alphanumeric, up to 40 bytes*Transaction number issued by Hecto Financial at the time of payment
STFP_PGCAnxca_jt_il0211129135810M1494620Transaction number issued by Hecto Financial at the time of payment
└TrdAmtEncN(12)Numeric, up to 12 bytes*
AES-256AES-256/ECB/PKCS5PaddingTransaction amount1000Transaction amount
*Certain response fields are AES-256 encrypted. Decrypt them before use.
└csrcIssNoAN(9)Alphanumeric, up to 9 bytesCash receipt approval number
0123456789Cash receipt approval number
*NaverPay only
Webhook
NOTE
No webhook
The Charge Subscription API does not send a webhook. Please confirm the result from the response message.
