Mobile Recurring Payment API
Mobile Recurring Payment is a service that uses the bill key (billKey) issued after the first payment approval to charge for subsequent payments.
Test Key Information
API Information
POST/spay/APIService.do
Content-Type
application/jsonSandbox
https://tbgw.settlebank.co.kr/spay/APIService.doProduction
https://gw.settlebank.co.kr/spay/APIService.doImportant Notes
NOTE
Monthly Recurring Payment Flow
1) First payment checkout request (autoPayType='M') → 2) billKey issued → 3) Use this API for subsequent payments
- For the first payment, set
autoPayTypetoMin the request parameters to receive abillKey. - For subsequent payments, set the issued
billKeyin the request parameters. - The transaction amount and product name for subsequent payments must be the same as the first payment.
- Operating rules apply — billing cycle (once a month, prior-month record required, ±5 days from the previous payment date, month-end caution), amount changes, and payment failure handling. Be sure to review the guide below.
Webhooks are not sent for subsequent payments by default
This API returns the result directly in its response, so webhooks are not sent by default for the second and later payments. Handle the result using outStatCd in the API response. If you need webhooks, contact your sales representative or technical support (pgsupport@hecto.co.kr).
NOTE
Mobile Monthly Recurring Payment — Operations Guide
A guide covering the operating rules you need: billing cycle, amount changes, and payment failure handling. View the Mobile Recurring Payment operations guide
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
nxhp_sb_ma: Monthly recurring payment sandbox└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 (MP: Mobile Payment)
└bizTypeAN(2)Alphanumeric, up to 2 bytes*Business type code
Business type code
*Fixed value (B1: Recurring renewal)
└encCdN(2)Numeric, up to 2 bytes*Encryption type code
Encryption type 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 (HHMMSS)
Request time (HHMMSS)
└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 + trdAmt (plaintext) + hashKey
└emailAN(60)Alphanumeric, up to 60 bytes*Customer email address
Customer email address
└mUserIdAHN(50)Alphanumeric + Korean, up to 50 bytes*Merchant customer ID
Merchant customer ID
└crcCdA(3)Alphabetic, up to 3 bytes*Currency code
Currency code
*Fixed value
└trdAmtN(12)Numeric, up to 12 bytes*
AES-256AES-256/ECB/PKCS5Padding + Base64Transaction amount (must match the first payment)Transaction amount (must match the first payment)
└prdtNmAHN(128)Alphanumeric + Korean, up to 128 bytes*Product name (must match the first payment)
Product name (must match the first payment)
└sellerNmAHN(50)Alphanumeric + Korean, up to 50 bytesSeller name
Seller name
└ordNmAHN(50)Alphanumeric + Korean, up to 50 bytes*Orderer name
Orderer name
└billKeyAN(50)Alphanumeric, up to 50 bytes*Bill key issued by Hecto Financial
Bill key issued by Hecto Financial
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
nxhp_sb_maMerchant ID
└verAN(4)Alphanumeric, up to 4 bytes*Message version
0A19Message version
└methodA(2)Alphabetic, up to 2 bytes*Payment method
MPPayment method
└bizTypeAN(2)Alphanumeric, up to 2 bytes*Business type code
B1Business type code
└encCdN(2)Numeric, up to 2 bytes*Encryption type code
23Encryption type 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_PGMPnxhp_sb_ma0211129135810M1494620Hecto Financial transaction number
└trdDtN(8)Numeric, up to 8 bytes*Request date (YYYYMMDD)
20211231Request date (YYYYMMDD)
└trdTmN(6)Numeric, up to 6 bytes*Request time (HHMMSS)
100000Request 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 + trdAmt (plaintext) + hashKey
└telCoA(3)Alphabetic, up to 3 bytes
AES-256AES-256/ECB/PKCS5PaddingCarrierSKTCarrier
*Certain response fields are AES-256 encrypted. Decrypt them before use.
└trdAmtN(12)Numeric, up to 12 bytes*
AES-256AES-256/ECB/PKCS5PaddingTransaction amount1000Transaction amount
*Certain response fields are AES-256 encrypted. Decrypt them before use.
└billKeyAN(50)Alphanumeric, up to 50 bytes*Value from the request, returned as-is
MO0123456789Value from the request, returned as-is
