Mobile Payment Hybrid Capture API
The Hybrid Capture method performs authentication only in the checkout, while the capture is requested separately from the merchant server. Authentication and capture can be processed independently.
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
Hybrid Capture Flow
1) Authentication request in the checkout (linkMethod='HBRD') → 2) Authentication success response (outStatCd='0061') → 3) Capture request using this API
- Set the
linkMethodparameter toHBRDwhen making the checkout request. - On authentication success,
outStatCdreturns0061. - Use the
trdNoreturned upon authentication success asauthTrdNowhen requesting capture. - The merchant order number (
mchtTrdNo) must be the same value used in the authentication request.
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_hd: Hybrid Capture 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
B0: Payletter resale approval B2: Hecto Financial original approval*B0: Payletter resale approval, B2: Hecto Financial original approval
└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 (must match the value used in the authentication request)
Unique order number generated by the merchant (must match the value used in the authentication request)
└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
└phoneNoN(11)Numeric, up to 11 bytes
AES-256AES-256/ECB/PKCS5Padding + Base64Customer mobile phone numberCustomer mobile phone number
└telCoA(3)Alphabetic, up to 3 bytes
AES-256AES-256/ECB/PKCS5Padding + Base64CarrierCarrier
SKT: SK Telecom KTF: KT LGT: LG U+ CJH: CJ Hello Mobile KCT: Korea Cable Telecom SKL: SK 7Mobile└emailAN(60)Alphanumeric, up to 60 bytesCustomer email address
Customer email address
└mUserIdAHN(50)Alphanumeric + Korean, up to 50 bytesMerchant 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 amountTransaction amount
└prdtNmAHN(128)Alphanumeric + Korean, up to 128 bytes*Product name
Product name
└sellerNmAHN(128)Alphanumeric + Korean, up to 128 bytesSeller name
Seller name
└ordNmAHN(30)Alphanumeric + Korean, up to 30 bytesOrderer name
Orderer name
└getBillKeyYnA(1)Alphabetic, up to 1 bytesBill key issuance flag
Bill key issuance flag
Y: Issue bill key Other: Do not issue bill key└authTrdNoAN(40)Alphanumeric, up to 40 bytes*Transaction number returned by Hecto Financial upon authentication success
Transaction number returned by Hecto Financial upon authentication success
└linkMethodAN(12)Alphanumeric, up to 12 bytes*Integration method code
Integration method code
*Fixed value
└notiUrlAN(250)Alphanumeric, up to 250 bytes*URL of the endpoint to receive payment results (server-to-server webhook URL)
URL of the endpoint to receive payment results (server-to-server webhook URL)
└mchtParamAHN(4000)Alphanumeric + Korean, up to 4000 bytesMerchant reserved field
Merchant reserved field
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_hdMerchant 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
B0Business 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_hd0211129135810M1494620Hecto 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
└phoneNoN(11)Numeric, up to 11 bytes
AES-256AES-256/ECB/PKCS5PaddingCustomer mobile phone number01012341234Customer mobile phone number
*Certain response fields are AES-256 encrypted. Decrypt them before use.
└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.
└getBillKeyYnA(1)Alphabetic, up to 1 bytesBill key issuance flag
Bill key issuance flag
Y: Bill key issued Other: Bill key not issued└billKeyAN(50)Alphanumeric, up to 50 bytesBill key issued by Hecto Financial (used from the 2nd payment onwards)
MO0123456789Bill key issued by Hecto Financial (used from the 2nd payment onwards)
