헥토파이낸셜 개발자센터

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-Typeapplication/json
테스트https://tbgw.settlebank.co.kr/spay/APIPZSubsTrd.do
운영https://gw.settlebank.co.kr/spay/APIPZSubsTrd.do

Important Notes

Subscription Key issuance required

To obtain a Subscription Key, you must use the subscription merchant ID (nxkkp_auto) when calling the KakaoPay checkout. A Subscription Key is not issued with the general payment merchant ID (hecto_test).
  • Currently only KakaoPay is supported.
  • Subscription Key issuance procedure:
    1. Use the subscription merchant ID (nxkkp_auto) when calling the KakaoPay checkout
    2. Set the autoPayType parameter to A (automatic payment) or S (sequential payment)
    3. Receive the billKey from the response upon successful payment
  • The issued Subscription Key is used in the billKey parameter when calling the Charge Subscription API.
NOTE

Subscription Key issuance checkout

For how to call the checkout to issue a Subscription Key, see the KakaoPay checkout document.

Request Parameters

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte

params Object

└mchtIdAN(10)Alphanumeric, up to 10 bytes*
Unique merchant ID assigned by Hecto Financial
nxkkp_auto: KakaoPay subscription (automatic payment)
└verAN(4)Alphanumeric, up to 4 bytes*
Message version
*Fixed value
└methodA(2)Alphabetic, up to 2 bytes*
Payment method
*Fixed value (PZ: Digital Wallet)
└bizTypeAN(2)Alphanumeric, up to 2 bytes*
Business type code
*Fixed value (B3: Subscription charge)
└encCdN(2)Numeric, up to 2 bytes*
Encryption classification code
*Fixed value
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*
Unique order number generated by the merchant
└trdDtN(8)Numeric, up to 8 bytes*
Request date (yyyyMMdd)
└trdTmN(6)Numeric, up to 6 bytes*
Request time (HH24MISS)
└mobileYnA(1)Alphabetic, up to 1 bytes
Mobile indicator
Y: Mobile web/app N: PC or other
└osTypeA(1)Alphabetic, up to 1 bytes
OS type
A: Android I: iOS W: Windows M: Mac E: Other

data Object

└pktHashAN(64)Alphanumeric, up to 64 bytes*SHA-256(실시간 생성)
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
KKP: KakaoPay NVP: NaverPay
└mUserIdAHN(50)Alphanumeric + Korean, up to 50 bytes*
Merchant customer ID used at the time of Subscription Key issuance
└ordNmAHN(30)Alphanumeric + Korean, up to 30 bytes*
Order name
└crcCdA(3)Alphabetic, up to 3 bytes*
Currency classification value
*Fixed value
└taxTypeA(1)Alphabetic, up to 1 bytes
Tax type
N: Taxable Y: Tax-exempt G: Mixed tax
└trdAmtEncN(12)Numeric, up to 12 bytes*AES-256AES-256/ECB/PKCS5Padding + Base64
Transaction amount
└taxAmtEncN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Taxable amount (required for mixed tax)
└vatAmtEncN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
VAT amount (required for mixed tax)
└taxFreeAmtEncN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Tax-exempt amount (required for mixed tax)
└svcAmtEncN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Service charge
└billKeyAN(50)Alphanumeric, up to 50 bytes*
Subscription Key issued by Hecto Financial
└prdtNmAHN(128)Alphanumeric + Korean, up to 128 bytes*
Product name
└etcOrdInfoAHN(4000)Alphanumeric + Korean, up to 4000 bytes
Merchant reserved field for entering additional order information
└csrcIssReqYnA(1)Alphabetic, up to 1 bytes
Cash receipt issuance flag
Y: Issue N: Do not issue
*NaverPay only
└cashRcptPrposDivCdN(1)Numeric, up to 1 bytes
Cash receipt purpose classification
0: Income deduction 1: Expense proof
*Required when using cash receipt. NaverPay only
└csrcRegNoDivCdN(1)Numeric, up to 1 bytes
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 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Unique identification information
*Required when using cash receipt. NaverPay only

Response Parameters

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte

params Object

└mchtIdAN(10)Alphanumeric, up to 10 bytes*nxkkp_auto
Merchant ID
└verAN(4)Alphanumeric, up to 4 bytes0A19
Message version
└methodA(2)Alphabetic, up to 2 bytesPZ
Payment method
└bizTypeAN(2)Alphanumeric, up to 2 bytesB3
Business type code
└encCdN(2)Numeric, up to 2 bytes*23
Encryption classification code
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*ORDER20211231100000
Merchant order number
└trdNoAN(40)Alphanumeric, up to 40 bytes*STFP_PGPZnx_mid_hd0230315153232M1196602
Hecto Financial transaction number
└trdDtN(8)Numeric, up to 8 bytes*20211231
Approval request date (YYYYMMDD)
└trdTmN(6)Numeric, up to 6 bytes*100000
Approval request time (HHMMSS)
└outStatCdAN(4)Alphanumeric, up to 4 bytes*0021
Transaction status code (success/failure)
0021: Success 0031: Failure
└outRsltCdAN(4)Alphanumeric, up to 4 bytes*0000
Result code
└outRsltMsgAHN(200)Alphanumeric + Korean, up to 200 bytes*Processed successfully.
Result message

data Object

└pktHashAN(64)Alphanumeric, up to 64 bytes*f395b6725a9a18...
Hash value from the request returned as-is
└AuthTrdNoAN(40)Alphanumeric, up to 40 bytes*STFP_PGCAnxca_jt_il0211129135810M1494620
Transaction number issued by Hecto Financial at the time of payment
└TrdAmtEncN(12)Numeric, up to 12 bytes*AES-256AES-256/ECB/PKCS5Padding1000
Transaction amount
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└csrcIssNoAN(9)Alphanumeric, up to 9 bytes0123456789
Cash 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.
💬

Need technical support?