Gift Card Payment (Checkout Method)
The gift card checkout method allows customers to pay using gift cards they hold (Teencash, CultureCash, Smart Book Gift Card, Book Gift Card).
NOTE
T-money Payment
T-money payment is available as a separate payment method.
Test Key Information
API Information
POST/gift/{giftCardType}/main.do
Content-Type
application/x-www-form-urlencodedSandbox
https://tbnpg.settlebank.co.kr/gift/{giftCardType}/main.doProduction
https://npg.settlebank.co.kr/gift/{giftCardType}/main.doNOTE
API Path by Gift Card Type
The call URL differs depending on the gift card type (method).
| method | Sandbox URL | Production URL |
|---|---|---|
| teencash | https://tbnpg.settlebank.co.kr/gift/teenCash/main.do | https://npg.settlebank.co.kr/gift/teenCash/main.do |
| culturecash | https://tbnpg.settlebank.co.kr/gift/cultureCash/main.do | https://npg.settlebank.co.kr/gift/cultureCash/main.do |
| smartcash | https://tbnpg.settlebank.co.kr/gift/smartCash/main.do | https://npg.settlebank.co.kr/gift/smartCash/main.do |
| booknlife | https://tbnpg.settlebank.co.kr/gift/booknlife/main.do | https://npg.settlebank.co.kr/gift/booknlife/main.do |
Important Notes
Gift Card Payment Important Notes
Available amounts and conditions differ by gift card type. Check whether partial use is available.
- Gift card types: CultureCash, Book Gift Card, Smart Book Gift Card, etc.
- If the gift card balance is less than the payment amount, only the available balance will be used.
- Partial cancellation may not be available for some gift cards.
- Gift card settlement proceeds according to the gift card company's policy.
Request Parameters
Type Notation
NNumericAAlphabeticHKoreanANAlphanumericAHNAlphanumeric + Koreane.g. AN(10) = alphanumeric, up to 10 bytes
Required Parameters
└mchtIdAN(10)Alphanumeric, up to 10 bytes*Unique merchant ID assigned by Hecto Financial
Unique merchant ID assigned by Hecto Financial
nx_mid_il: Gift Card└methodAN(20)Alphanumeric, up to 20 bytes*Payment type code
Payment type code
teencash: Teencash culturecash: CultureCash smartcash: Smart Book Gift Card booknlife: Book Gift Card*Select based on gift card type
└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)
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*Unique order number generated by the merchant (no Korean characters)
Unique order number generated by the merchant (no Korean characters)
└mchtNameAHN(100)Alphanumeric + Korean, up to 100 bytes*Merchant name (Korean)
Merchant name (Korean)
└mchtENameAN(100)Alphanumeric, up to 100 bytes*Merchant name (English)
Merchant name (English)
└pmtPrdtNmAHN(50)Alphanumeric + Korean, up to 50 bytes*Payment product name
Payment product name
└trdAmtN(12)Numeric, up to 12 bytes*
AES-256AES-256/ECB/PKCS5Padding + Base64Transaction amountTransaction amount
└notiUrlAN(250)Alphanumeric, up to 250 bytes*Webhook endpoint URL to receive payment results (server-to-server)
Webhook endpoint URL to receive payment results (server-to-server)
└nextUrlAN(250)Alphanumeric, up to 250 bytes*URL to redirect to the payment result screen
URL to redirect to the payment result screen
*Redirected when a button inside the checkout is clicked. Check outStatCd to confirm payment success (0021) or failure (0031).
└cancUrlAN(250)Alphanumeric, up to 250 bytes*URL to redirect when the customer clicks the X button in the checkout
URL to redirect when the customer clicks the X button in the checkout
*Browser close and back navigation are not detected.
└pktHashAN(200)Alphanumeric, up to 200 bytes*
SHA-256Hash value generated using SHA256(auto-generated)Hash value generated using SHA256
NOTE
Hash Generation Combination
mchtId + method + mchtTrdNo + trdDt + trdTm + trdAmt (plaintext) + hashKey
Optional Parameters
└mchtCustNmAHN(30)Alphanumeric + Korean, up to 30 bytes
AES-256AES-256/ECB/PKCS5Padding + Base64Customer nameCustomer name
└mchtCustIdAN(50)Alphanumeric, up to 50 bytes
AES-256AES-256/ECB/PKCS5Padding + Base64Merchant customer IDMerchant customer ID
*Required for CultureLand gift card (CultureCash, culturecash)
└custIpAN(15)Alphanumeric, up to 15 bytesCustomer IP address (the customer device's IP, not the merchant server IP). Must be in IPv4 format (IPv6 not supported).
Customer IP address (the customer device's IP, not the merchant server IP). Must be in IPv4 format (IPv6 not supported).
*Required for CultureLand gift card (CultureCash, culturecash)
└mchtParamAHN(4000)Alphanumeric + Korean, up to 4000 bytesMerchant reserved field (returned as-is when results are delivered)
Merchant reserved field (returned as-is when results are delivered)
└prdtTermN(14)Numeric, up to 14 bytesProduct provision period (yyyyMMddHHmmss; if empty, displayed as a regular payment)
Product provision period (yyyyMMddHHmmss; if empty, displayed as a regular payment)
Response Parameters
Upon payment completion or failure, a redirect to nextUrl occurs; when the customer clicks the X button inside the checkout, a redirect to cancUrl occurs, and the following parameters are passed. Browser close and back navigation are not detected.
Type Notation
NNumericAAlphabeticHKoreanANAlphanumericAHNAlphanumeric + Koreane.g. AN(10) = alphanumeric, up to 10 bytes
Common Response
└mchtIdAN(10)Alphanumeric, up to 10 bytes*Merchant ID
nx_mid_ilMerchant ID
└outStatCdAN(4)Alphanumeric, up to 4 bytes*Transaction status code
0021Transaction status code
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
└methodAN(20)Alphanumeric, up to 20 bytes*Payment method
teencashPayment method
teencash: Teencash culturecash: CultureCash smartcash: Smart Book Gift Card booknlife: Book Gift Card└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*Merchant order number
ORDER20211231100000Merchant order number
└mchtCustIdAN(50)Alphanumeric, up to 50 bytes
AES-256AES-256/ECB/PKCS5PaddingMerchant customer ID (required for CultureCash)HongGilDongMerchant customer ID (required for CultureCash)
*Certain response fields are AES-256 encrypted. Decrypt them before use.
└trdNoAN(40)Alphanumeric, up to 40 bytes*Hecto Financial transaction number
STFP_PGCAnx_mid_il0211129135810M1494620Hecto Financial transaction number
└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.
└mchtParamAHN(4000)Alphanumeric + Korean, up to 4000 bytesMerchant reserved field (the value received in the request is returned as-is)
name=HongGilDong&age=25Merchant reserved field (the value received in the request is returned as-is)
└authDtN(14)Numeric, up to 14 bytesApproval datetime
20211231100000Approval datetime
Webhook (Payment Result)
After payment is completed, Hecto Financial sends a webhook to your server.
NOTE
Webhook Reference
For webhook parameters and processing methods for gift card payment results, see the Webhook document.
