헥토파이낸셜 개발자센터

Spend API

Processes a spend (payment) using the member's Money and Points.

API Information

POST/v1/wallet/use
Content-Typeapplication/json
테스트https://tb-mps-api.hectofinancial.co.kr/v1/wallet/use
운영https://mps-api.hectofinancial.co.kr/v1/wallet/use

Integration Process

Customer
Merchant
Hecto Financial
11. Payment request
22. Balance inquiry API
33. Balance response
44. Spend API (PIN authentication)
55. Spend complete response
66. Payment complete

Request Parameters

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte
└custNoAN(20)Alphanumeric, up to 20 bytes*
Prepaid member number.
*Unique prepaid member number assigned by Hecto Financial.
└mTrdNoAN(50)Alphanumeric, up to 50 bytes*
Merchant transaction reference number.
*Transaction reference number generated by the merchant (no Korean characters).
└trdAmtN(7)Numeric, up to 7 bytes*AES-256AES-256/ECB/PKCS5Padding + Base64
Transaction amount (requested spend amount).
*AES-256/ECB/PKCS5Padding encryption, then Base64 encoding.
└mnyBlcN(7)Numeric, up to 7 bytes*AES-256AES-256/ECB/PKCS5Padding + Base64
Money balance.
*Member's Money balance. AES-256/ECB/PKCS5Padding encryption required.
└pntBlcN(7)Numeric, up to 7 bytes*AES-256AES-256/ECB/PKCS5Padding + Base64
Points balance.
*Member's Points balance. AES-256/ECB/PKCS5Padding encryption required.
└blcUseOrdAN(1)Alphanumeric, up to 1 bytes
Balance usage priority.
M: Money first P: Points first (default)
└reqDtAN(8)Alphanumeric, up to 8 bytes
Request date.
*yyyyMMdd format.
└reqTmAN(6)Alphanumeric, up to 6 bytes
Request time.
*HHmmss format.
└csrcIssReqYnAN(1)Alphanumeric, up to 1 bytes
Cash receipt issuance request flag.
Y: Request issuance N: Do not issue
*Request to issue a cash receipt for the Money amount spent.
└stlMIdAN(20)Alphanumeric, up to 20 bytes*AES-256AES-256/ECB/PKCS5Padding + Base64
Settlement merchant ID.
*Merchant ID for settlement target. AES-256/ECB/PKCS5Padding encryption required.
└storCdAN(20)Alphanumeric, up to 20 bytes
Store code.
└storNmAN(128)Alphanumeric, up to 128 bytes
Store name.
*Used in spend notification emails when sent to the customer.
└pinNoAN(6)Alphanumeric, up to 6 bytes*AES-256AES-256/ECB/PKCS5Padding + Base64
Payment PIN.
*AES-256/ECB/PKCS5Padding encryption required.
└mResrvField1AN(255)Alphanumeric, up to 255 bytes
Merchant reserve field 1.
*Transmitted in plaintext. Do not include sensitive personal information.
└mResrvField2AN(255)Alphanumeric, up to 255 bytes
Merchant reserve field 2.
*Transmitted in plaintext. Do not include sensitive personal information.
└mResrvField3AN(255)Alphanumeric, up to 255 bytes
Merchant reserve field 3.
*Transmitted in plaintext. Do not include sensitive personal information.
└pktHashAN(200)Alphanumeric, up to 200 bytes*SHA-256(실시간 생성)
SHA-256 hash value.
*Signature composition: prepaid member number + merchant ID + merchant transaction reference number + transaction amount (plaintext) + hash key.

Response Parameters

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte
└rsltCdAN(4)Alphanumeric, up to 4 bytes*0000
Result code.
0000: Success Other: Failure
└rsltMsgAN(255)Alphanumeric, up to 255 bytes*Success
Result message.

rsltObj (Response Object)

└custNoAN(20)Alphanumeric, up to 20 bytes*2400001605
Prepaid member number.
└mtrdNoAN(50)Alphanumeric, up to 50 bytes*ORDER20240716
Merchant transaction reference number.
*No Korean characters.
└trdNoAN(50)Alphanumeric, up to 50 bytes*24071616270200002193
Transaction approval number.
*Unique transaction number assigned by Hecto Financial. Required for void.
└trdDtAN(8)Alphanumeric, up to 8 bytes*20240716
Transaction date.
*yyyyMMdd format.
└trdTmAN(6)Alphanumeric, up to 6 bytes*164101
Transaction time.
*HHmmss format.
└trdAmtN(7)Numeric, up to 7 bytes*10000
Transaction amount.
*Total amount spent (Money + Points).
└mnyAmtN(7)Numeric, up to 7 bytes*9000
Money amount spent.
└pntAmtN(7)Numeric, up to 7 bytes*1000
Points amount spent.
└mnyBlcN(7)Numeric, up to 7 bytes*11000
Money balance after spend.
└pntBlcN(7)Numeric, up to 7 bytes*0
Points balance after spend.
└pktHashAN(200)Alphanumeric, up to 200 bytes*
SHA-256 hash value.
*Signature composition: prepaid member number + merchant ID + merchant transaction reference number + transaction approval number + transaction amount + Money amount + Points amount + hash key.

Request Example

{
  "custNo": "2400001605",
  "mTrdNo": "NSTEST20240715000006",
  "trdAmt": "OtHHsG793ox9XewbvX21Lw==",
  "mnyBlc": "2fISihtRzzKJZZay2s8LFQ==",
  "pntBlc": "ceBxI7xbssp9mlz9hRzTJw==",
  "blcUseOrd": "M",
  "reqDt": "20240826",
  "reqTm": "160010",
  "csrcIssReqYn": "Y",
  "stlMId": "R0L4ColX2RqUDQyo5lWTPQ==",
  "storCd": "HF0001",
  "storNm": "Hecto Financial",
  "pinNo": "6NykSPILA01QdAh6sTGaBA==",
  "pktHash": "eb19306c05c1fd19c0fb185358243512d0ffad44ab299e629d89428ad6134f46"
}

Response Examples

Success

{
  "rsltCd": "0000",
  "rsltMsg": "Success",
  "rsltObj": {
    "custNo": "2400001605",
    "mtrdNo": "ORDER20240716",
    "trdNo": "24071616270200002193",
    "trdDt": "20240716",
    "trdTm": "164101",
    "trdAmt": "10000",
    "mnyAmt": "9000",
    "pntAmt": "1000",
    "mnyBlc": "11000",
    "pntBlc": "0",
    "pktHash": "f395b6725a9a18f2563ce34f8bc76698051d27c05de5ba815f463f00429061c"
  }
}

Failure (Insufficient Balance)

{
  "rsltCd": "T-009",
  "rsltMsg": "Please verify the original transaction amount or requested amount."
}

Failure (Incorrect PIN)

{
  "rsltCd": "T-010",
  "rsltMsg": "Incorrect payment PIN. (2 attempts)"
}

Important Notes

Payment PIN Attempt Limit

The account will be locked after 5 consecutive incorrect PIN entries. The PIN must be reset from the My Information page.
  • Call the Balance Inquiry API first to confirm the mnyBlc and pntBlc values before processing a spend.
  • Use blcUseOrd to set the spend priority between Money and Points.
  • The transaction reference number (mTrdNo) must be unique.
  • All amount parameters are plaintext values; use decoded values when encrypting.
💬

Need technical support?