Charge Credit Card API

An API that submits card information directly from the server without a checkout page. Billkey (recurring payment token) issuance is also available.

Test Key Information

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

Payment Method Guide

NOTE

Required parameters by payment method

legacy-authenticated: Payment request using card number, expiration date (yyMM), identification number, and card password / non-authenticated: Payment request using card number and expiration date (yyMM)

Billkey (recurring payment token) issuance: A billkey is returned in the response based on merchant ID settings. Store the billkey separately and use billkey payment when a charge is needed.
Requires separate service activation. Contact your account manager to enable billkey issuance for your merchant ID.

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

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

Message version

*Fixed value

└methodA(2)Alphabetic, up to 2 bytes*Payment method

Payment method

*Fixed value

└bizTypeAN(2)Alphanumeric, up to 2 bytes*Business type code

Business type code

*Fixed value

└encCdN(2)Numeric, up to 2 bytes*Encryption type code

Encryption type code

*Fixed value

└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*Unique transaction number generated by the merchant

Unique transaction number generated by the merchant

└trdDtN(8)Numeric, up to 8 bytes*Date the message is transmitted (YYYYMMDD)

Date the message is transmitted (YYYYMMDD)

└trdTmN(6)Numeric, up to 6 bytes*Time the message is transmitted (HHMMSS)

Time the message is transmitted (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: Other Blank: Unknown

data Object

└pktHashAN(200)Alphanumeric, up to 200 bytes*SHA-256Hash value generated using SHA256(실시간 생성)

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

Product name for payment

└mchtCustNmAHN(30)Alphanumeric + Korean, up to 30 bytes*Merchant customer name

Merchant customer name

└mchtCustIdAHN(50)Alphanumeric + Korean, up to 50 bytes*Merchant customer ID

Merchant customer ID

└emailAN(60)Alphanumeric, up to 60 bytesMerchant customer email address

Merchant customer email address

└cardNoN(16)Numeric, up to 16 bytes*AES-256AES-256/ECB/PKCS5Padding + Base64Card number

Card number

└vldDtMonN(2)Numeric, up to 2 bytes*AES-256AES-256/ECB/PKCS5Padding + Base64Expiration date (month) MM

Expiration date (month) MM

└vldDtYearN(2)Numeric, up to 2 bytes*AES-256AES-256/ECB/PKCS5Padding + Base64Expiration date (year) YY

Expiration date (year) YY

└idntNoN(10)Numeric, up to 10 bytes*AES-256AES-256/ECB/PKCS5Padding + Base64Identification number. 6-digit date of birth or 10-digit business registration number

Identification number. 6-digit date of birth or 10-digit business registration number

*Used only for legacy-authenticated payment

└cardPwdN(2)Numeric, up to 2 bytes*AES-256AES-256/ECB/PKCS5Padding + Base64First 2 digits of card password

First 2 digits of card password

*Used only for legacy-authenticated payment

└instmtMonN(2)Numeric, up to 2 bytes*Installment months (2 digits)

Installment months (2 digits)

00: Full payment 02~12: Corresponding number of months

└crcCdA(3)Alphabetic, up to 3 bytes*Currency type

Currency type

KRW: Domestic payment USD: International payment

└taxTypeCdA(1)Alphabetic, up to 1 bytesTax type. If blank, follows merchant configuration

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 + Base64Transaction amount

Transaction amount

*KRW: 1000 / USD: ex) $1.50 → 150

└taxAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64Taxable amount within the transaction amount (required for mixed taxation)

Taxable amount within the transaction amount (required for mixed taxation)

└vatAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64VAT amount within the transaction amount (required for mixed taxation)

VAT amount within the transaction amount (required for mixed taxation)

└taxFreeAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64Tax-free amount within the transaction amount (required for mixed taxation)

Tax-free amount within the transaction amount (required for mixed taxation)

└svcAmtN(12)Numeric, up to 12 bytesAES-256AES-256/ECB/PKCS5Padding + Base64Credit card service charge

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

Webhook URL to receive the payment result sent from Hecto Financial to your server after payment completion

└mchtParamAHN(4000)Alphanumeric + Korean, up to 4000 bytesMerchant reserved field for entering additional order information

Merchant reserved field for entering additional order information

Response Parameters

타입 표기법

N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자

예: AN(10) = 영문+숫자, 최대 10byte

params Object

└mchtIdAN(12)Alphanumeric, up to 12 bytes*Unique merchant ID assigned by Hecto Financialnxca_jt_bi

Unique merchant ID assigned by Hecto Financial

└verAN(4)Alphanumeric, up to 4 bytes*Message version0A19

Message version

*Fixed value

└methodA(2)Alphabetic, up to 2 bytes*Payment methodCA

Payment method

*Fixed value

└bizTypeAN(2)Alphanumeric, up to 2 bytes*Business type codeB0

Business type code

*Fixed value

└encCdN(2)Numeric, up to 2 bytes*Encryption type code23

Encryption type code

*Fixed value

└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*Unique order number generated by the merchantORDER20211231100000

Unique order number generated by the merchant

└trdNoAN(40)Alphanumeric, up to 40 bytes*Unique transaction number issued by Hecto FinancialSTFP_PGCAnxca_jt_il0211129135810M1494620

Unique transaction number issued by Hecto Financial

└trdDtN(8)Numeric, up to 8 bytes*Date the message is transmitted (YYYYMMDD)20211231

Date the message is transmitted (YYYYMMDD)

└trdTmN(6)Numeric, up to 6 bytes*Time the message is transmitted (HHMMSS)100000

Time the message is transmitted (HHMMSS)

└outStatCdAN(4)Alphanumeric, up to 4 bytes*Transaction status code (success/failure)0021

Transaction status code (success/failure)

0021: Success 0031: Failure

└outRsltCdAN(4)Alphanumeric, up to 4 bytes*Decline code. Detailed code provided when transaction status is '0031'0000

Decline code. Detailed code provided when transaction status is '0031'

*Refer to the decline code table

└outRsltMsgAHN(200)Alphanumeric + Korean, up to 200 bytes*Result message (URL Encoding, UTF-8)Processed successfully.

Result message (URL Encoding, UTF-8)

data Object

└pktHashAN(64)Alphanumeric, up to 64 bytes*Hash value from request returned as-is

Hash value from request returned as-is

└trdAmtN(12)Numeric, up to 12 bytes*AES-256AES-256/ECB/PKCS5PaddingTransaction amount1000

Transaction amount

*KRW: 1000 / USD: ex) $1.50 → 150

*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.

└billKeyAN(50)Alphanumeric, up to 50 bytesBillkey used for subsequent chargesSBILL_0123456789

Billkey used for subsequent charges

*Provided only for merchants using the Billkey (tokenized recurring payment) service

└cardNoN(16)Numeric, up to 16 bytesMasked card number111122xxxxxx4444

Masked card number

*Not provided by default; available only for specific merchants. Contact the business department.

└vldDtMonN(2)Numeric, up to 2 bytesExpiration date (month) MM12

Expiration date (month) MM

*Provided only for merchants using the Billkey (tokenized recurring payment) service

└vldDtYearN(2)Numeric, up to 2 bytesExpiration date (year) YY24

Expiration date (year) YY

*Provided only for merchants using the Billkey (tokenized recurring payment) service

└issrIdAN(4)Alphanumeric, up to 4 bytes*Card issuer code (refer to credit card identifier)NHC

Card issuer code (refer to credit card identifier)

└cardNmAHN(20)Alphanumeric + Korean, up to 20 bytes*Card company name (refer to credit card identifier)NH NongHyup

Card company name (refer to credit card identifier)

└cardKindAHN(50)Alphanumeric + Korean, up to 50 bytes*Card type (refer to credit card identifier)NH Check Card

Card type (refer to credit card identifier)

└ninstmtTypeCdA(1)Alphabetic, up to 1 bytes*Interest-free installment typeN

Interest-free installment type

Y: Interest-free (partial, merchant) N: Regular installment, full payment

└instmtMonN(2)Numeric, up to 2 bytesValue from request returned as-is00

Value from request returned as-is

└apprNoN(15)Numeric, up to 15 bytes*Card approval number30001234

Card approval number

Request Example

{
  "params": {
    "mchtId": "nxca_jt_bi",
    "ver": "0A19",
    "method": "CA",
    "bizType": "B0",
    "encCd": "23",
    "mchtTrdNo": "ORDER20211231100000",
    "trdDt": "20211231",
    "trdTm": "100000",
    "mobileYn": "N",
    "osType": "W"
  },
  "data": {
    "pktHash": "f395b6725a9a18f2563ce34f8bc76698051d27c05e5ba815f463f00429061c0c",
    "pmtprdNm": "Test Product",
    "mchtCustNm": "Hong Gil-dong",
    "mchtCustId": "HongGilDong",
    "email": "HongGilDong@example.com",
    "cardNo": "AES-encrypted card number",
    "vldDtMon": "AES-encrypted month",
    "vldDtYear": "AES-encrypted year",
    "instmtMon": "00",
    "crcCd": "KRW",
    "taxTypeCd": "N",
    "trdAmt": "AES-encrypted amount"
  }
}

Response Examples

Success Response

{
  "params": {
    "mchtId": "nxca_jt_bi",
    "ver": "0A19",
    "method": "CA",
    "bizType": "B0",
    "encCd": "23",
    "mchtTrdNo": "ORDER20211231100000",
    "trdNo": "STFP_PGCAnxca_jt_il0211129135810M1494620",
    "trdDt": "20211231",
    "trdTm": "100000",
    "outStatCd": "0021",
    "outRsltCd": "0000",
    "outRsltMsg": "Processed successfully."
  },
  "data": {
    "pktHash": "f395b6725a9a18f2563ce34f8bc76698051d27c05e5ba815f463f00429061c0c",
    "trdAmt": "AES-encrypted amount",
    "billKey": "SBILL_0123456789",
    "issrId": "NHC",
    "cardNm": "NH NongHyup",
    "cardKind": "NH Check Card",
    "ninstmtTypeCd": "N",
    "instmtMon": "00",
    "apprNo": "30001234"
  }
}

Failure Response

{
  "params": {
    "mchtId": "nxca_jt_bi",
    "ver": "0A19",
    "method": "CA",
    "bizType": "B0",
    "encCd": "23",
    "mchtTrdNo": "ORDER20211231100000",
    "trdNo": "",
    "trdDt": "20211231",
    "trdTm": "100000",
    "outStatCd": "0031",
    "outRsltCd": "1001",
    "outRsltMsg": "Missing payment request information"
  },
  "data": {
    "pktHash": "f395b6725a9a18f2563ce34f8bc76698051d27c05e5ba815f463f00429061c0c"
  }
}

Need technical support?

Code Samples

HectoFinancial GitHub