헥토파이낸셜 개발자센터

Charge with Billkey API

An API for making payments using a billkey received from the credit card payment API or billkey issuance API.

Test Key Information

Important Notes

NOTE

Billkey Service Activation

The Billkey (tokenized recurring payment) service requires separate service activation. Contact your account manager.
  • Use the billkey issued during the initial charge to process subsequent charges.
  • Billkey payment is processed via server-to-server communication without any UI.

API Information

POST/spay/APICardActionPay.do
Content-Typeapplication/json
테스트https://tbgw.settlebank.co.kr/spay/APICardActionPay.do
운영https://gw.settlebank.co.kr/spay/APICardActionPay.do

Request Parameters

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

params Object

└mchtIdAN(12)Alphanumeric, up to 12 bytes*
Unique merchant ID assigned by Hecto Financial
nxca_ks_gu: legacy-authenticated nxca_jt_bi: non-authenticated
└verAN(4)Alphanumeric, up to 4 bytes*
Message version
*Fixed value
└methodA(2)Alphabetic, up to 2 bytes*
Payment method
*Fixed value
└bizTypeAN(2)Alphanumeric, up to 2 bytes*
Business type code
*Fixed value
└encCdN(2)Numeric, up to 2 bytes*
Encryption type code
*Fixed value
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*
Unique order number generated by the merchant
└trdDtN(8)Numeric, up to 8 bytes*
Date the message is transmitted (YYYYMMDD)
└trdTmN(6)Numeric, up to 6 bytes*
Time the message is transmitted (HHMMSS)
└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(200)Alphanumeric, up to 200 bytes*SHA-256(실시간 생성)
Hash value generated using SHA256
NOTE

Hash Generation Combination

trdDt + trdTm + mchtId + mchtTrdNo + trdAmt (plaintext) + hashKey
└pmtprdNmAHN(128)Alphanumeric + Korean, up to 128 bytes*
Product name for payment
└mchtCustNmAHN(30)Alphanumeric + Korean, up to 30 bytes*
Merchant customer name
└mchtCustIdAHN(50)Alphanumeric + Korean, up to 50 bytes*
Merchant customer ID
└emailAN(60)Alphanumeric, up to 60 bytes
Merchant customer email address
└billKeyAN(50)Alphanumeric, up to 50 bytes*
Billkey issued during the initial charge
└instmtMonN(2)Numeric, up to 2 bytes*
Installment months (2 digits)
00: Full payment 02~12: Corresponding number of months
└crcCdA(3)Alphabetic, up to 3 bytes*
Currency type
KRW: Domestic payment USD: International payment
└taxTypeCdA(1)Alphabetic, up to 1 bytes
Tax type. If blank, follows merchant configuration
N: Taxable Y: Tax-exempt G: Mixed taxation
└trdAmtN(12)Numeric, up to 12 bytes*AES-256AES-256/ECB/PKCS5Padding + Base64
Transaction amount
*Domestic payment: 1000, International payment: 150 (ex [$1.50] => integer representation [150])
└taxAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Taxable amount within the transaction amount (required for mixed taxation)
└vatAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
VAT amount within the transaction amount (required for mixed taxation)
└taxFreeAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Tax-free amount within the transaction amount (required for mixed taxation)
└svcAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Credit card service charge
└notiUrlAN(250)Alphanumeric, up to 250 bytes*
Webhook URL to receive the payment result sent from Hecto Financial to your server after payment completion
└mchtParamAHN(4000)Alphanumeric + Korean, up to 4000 bytes
Merchant reserved field for entering additional order information

Response Parameters

params Object

└mchtIdAN(12)Alphanumeric, up to 12 bytes*nxca_jt_bi
Unique merchant ID assigned by Hecto Financial
└verAN(4)Alphanumeric, up to 4 bytes*0A19
Message version
*Fixed value
└methodA(2)Alphabetic, up to 2 bytes*CA
Payment method
*Fixed value
└bizTypeAN(2)Alphanumeric, up to 2 bytes*B0
Business type code
*Fixed value
└encCdN(2)Numeric, up to 2 bytes*23
Encryption type code
*Fixed value
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*ORDER20211231100000
Unique order number generated by the merchant
└trdNoAN(40)Alphanumeric, up to 40 bytes*STFP_PGCAnxca_jt_il0211129135810M1494620
Unique transaction number issued by Hecto Financial
└trdDtN(8)Numeric, up to 8 bytes*20211231
Request date (YYYYMMDD)
└trdTmN(6)Numeric, up to 6 bytes*100000
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
Decline code. Detailed code provided when transaction status is '0031'
└outRsltMsgAHN(200)Alphanumeric + Korean, up to 200 bytes*Processed successfully.
Result message (URL Encoding, UTF-8)

data Object

└pktHashAN(64)Alphanumeric, up to 64 bytes*
Hash value from request returned as-is
└trdAmtN(12)Numeric, up to 12 bytes*AES-256AES-256/ECB/PKCS5Padding1000
Transaction amount
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└billKeyAN(50)Alphanumeric, up to 50 bytes*SBILL_0123456789
Value from request returned as-is
└cardNoN(16)Numeric, up to 16 bytes111122xxxxxx4444
Masked card number. Not provided by default; available only for specific merchants.
└vldDtMonN(2)Numeric, up to 2 bytes12
Expiration date MM. Provided only for merchants using the Billkey (tokenized recurring payment) service.
└vldDtYearN(2)Numeric, up to 2 bytes24
Expiration date YY. Provided only for merchants using the Billkey (tokenized recurring payment) service.
└issrIdAN(4)Alphanumeric, up to 4 bytes*NHC
Card issuer identifier
└cardNmAHN(20)Alphanumeric + Korean, up to 20 bytes*NH NongHyup
Card company name
└cardKindAHN(50)Alphanumeric + Korean, up to 50 bytes*NH Check Card
Card type
└ninstmtTypeCdA(1)Alphabetic, up to 1 bytes*N
Interest-free installment type
Y: Interest-free (partial, merchant) N: Regular installment, full payment
└instmtMonN(2)Numeric, up to 2 bytes00
Value from request returned as-is
└apprNoN(15)Numeric, up to 15 bytes*30001234
Card approval number
💬

Need technical support?