헥토파이낸셜 개발자센터

Top-up API

Tops up (credits) Money or Points to a member.

API Information

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

Top-up Types

Division CodeTypeDescription
MPMoney top-upCash-equivalent prepaid balance top-up (withdrawal available)
PPPoints issuanceEvent/promotion points (withdrawal not available)

Top-up Method Codes

CodeTop-up Method
CACredit card
ZOZ010 virtual account
EZMy account payment
RAAccount transfer
PINPIN
RPSimple cash payment
MMMoney transfer
PMPoints transfer

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).
└divCdAN(2)Alphanumeric, up to 2 bytes*
Division code.
MP: Money top-up PP: Points issuance
└trdDivDtlCdAN(10)Alphanumeric, up to 10 bytes
Transaction division detail code.
*Only pre-registered transaction division detail codes can be used.
└chrgMeanCdAN(2)Alphanumeric, up to 2 bytes*
Top-up method code.
CA: Credit card ZOZ: 010 virtual account EZ: My account payment RA: Account transfer PIN: PIN RP: Simple cash payment MM: Money transfer PM: Points transfer
*For white-label top-up, enter the payMethod value (CA or RP) from the white-label payment API response.
└trdAmtAN(7)Alphanumeric, up to 7 bytes*AES-256AES-256/ECB/PKCS5Padding + Base64
Requested top-up amount.
*AES-256/ECB/PKCS5Padding encryption required. Minimum top-up amount for Money is KRW 10,000.
└blcAmtAN(7)Alphanumeric, up to 7 bytes*AES-256AES-256/ECB/PKCS5Padding + Base64
Current balance.
*Money or Points balance. AES-256/ECB/PKCS5Padding encryption required. For Money top-up, provide the Money balance.
└pntVldPdAN(8)Alphanumeric, up to 8 bytes*
Points expiry date.
*yyyyMMdd format. Maximum validity period is 10 years.
└custBdnFeeAmtN(7)Numeric, up to 7 bytesAES-256AES-256/ECB/PKCS5Padding + Base64
Customer-borne fee amount.
*AES-256/ECB/PKCS5Padding encryption required.
└chrgTrdNoAN(50)Alphanumeric, up to 50 bytes
Top-up transaction reference number.
*Transaction reference number generated during Hecto Financial PG processing. Enter '00000' for external PG; enter the PG transaction number for internal PG.
└reqDtAN(8)Alphanumeric, up to 8 bytes
Request date.
*yyyyMMdd format. If omitted, the server date is used automatically.
└reqTmAN(6)Alphanumeric, up to 6 bytes
Request time.
*HHmmss format. If omitted, the server time is used automatically.
└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.
└trdSumryAN(50)Alphanumeric, up to 50 bytes
Transaction summary.
*Reason for issuance.
└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.
*Transaction approval number issued by Hecto Financial.
└trdDivDtlCdAN(10)Alphanumeric, up to 10 bytes
Transaction division detail code.
*Only pre-registered transaction division detail codes are used.
└trdAmtN(7)Numeric, up to 7 bytes*10000
Transaction amount.
└custBdnFeeAmtN(7)Numeric, up to 7 bytes*0
Customer-borne fee amount.
└mnyBlcN(7)Numeric, up to 7 bytes*25000
Money balance.
*Money balance after the transaction.
└pntBlcN(7)Numeric, up to 7 bytes*1000
Points balance.
*Points balance after the transaction.
└trdDtAN(8)Alphanumeric, up to 8 bytes*20241212
Transaction date.
*yyyyMMdd format.
└trdTmAN(6)Alphanumeric, up to 6 bytes*192035
Transaction time.
*HHmmss format.
└pktHashAN(200)Alphanumeric, up to 200 bytes*
SHA-256 hash value.
*Signature composition: prepaid member number + merchant ID + merchant transaction reference number + Hecto Financial transaction approval number + transaction amount + hash key.

Request Examples

Money Top-up

{
  "custNo": "2400001605",
  "mTrdNo": "ORDER20240716",
  "divCd": "MP",
  "chrgMeanCd": "CA",
  "trdAmt": "AES-encrypted amount",
  "blcAmt": "AES-encrypted balance",
  "pntVldPd": "20340716",
  "reqDt": "20241212",
  "reqTm": "192035",
  "pktHash": "hash value"
}

Points Issuance

{
  "custNo": "2400001605",
  "mTrdNo": "ORDER20240716",
  "divCd": "PP",
  "chrgMeanCd": "PIN",
  "trdAmt": "AES-encrypted amount",
  "blcAmt": "AES-encrypted balance",
  "pntVldPd": "20340716",
  "trdSumry": "Event points issuance",
  "pktHash": "hash value"
}

Response Examples

Success

{
  "rsltCd": "0000",
  "rsltMsg": "Success",
  "rsltObj": {
    "custNo": "2400001605",
    "mtrdNo": "ORDER20240716",
    "trdNo": "24071616270200002193",
    "trdAmt": "10000",
    "custBdnFeeAmt": "0",
    "mnyBlc": "25000",
    "pntBlc": "1000",
    "trdDt": "20241212",
    "trdTm": "192035",
    "pktHash": "f395b6725a9a18f2563ce34f8bc76698051d27c05de5ba815f463f00429061c"
  }
}

Failure

{
  "rsltCd": "1001",
  "rsltMsg": "Member information does not exist."
}

Important Notes

  • The minimum top-up amount for Money is KRW 10,000.
  • Points cannot be withdrawn.
  • The maximum validity period for Points is 10 years.
  • The transaction reference number (mTrdNo) must be unique.
💬

Need technical support?