Account Enrollment API
Enroll or deregister a customer's debit account for direct debit withdrawal.
Account Enrollment (Direct Debit Registration)
Submit a direct debit enrollment request using a transaction reference number obtained via ARS verification or another supported verification method (PASS, written consent, etc.).
API Information
POST/v1/api/acnt/reg
Content-Type
application/json; charset=UTF-8테스트
https://tbnpay.settlebank.co.kr/v1/api/acnt/reg운영
https://npay.settlebank.co.kr/v1/api/acnt/regRequest Parameters
타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자예: AN(10) = 영문+숫자, 최대 10byte
└hdInfoAN(50)Alphanumeric, up to 50 bytes*Message information code.
Message information code.
*Fixed value
└mchtIdAN(8)Alphanumeric, up to 8 bytes*Merchant ID.
Merchant ID.
└mchtTrdNoAN(100)Alphanumeric, up to 100 bytes*Merchant order number (no Korean characters).
Merchant order number (no Korean characters).
└trdNoAN(50)Alphanumeric, up to 50 bytesTransaction reference number issued during authentication confirmation.
Transaction reference number issued during authentication confirmation.
*Required when authMthdCd is ARS
└mchtCustIdAN(100)Alphanumeric, up to 100 bytes*
AES-256AES-256/ECB/PKCS5Padding + Base64 (Standard)Customer ID.Customer ID.
└reqDtAN(8)Alphanumeric, up to 8 bytes*Request date (yyyyMMdd).
Request date (yyyyMMdd).
└reqTmAN(6)Alphanumeric, up to 6 bytes*Request time (HH24MISS).
Request time (HH24MISS).
└mchtCustNmAN(60)Alphanumeric, up to 60 bytes*
AES-256AES-256/ECB/PKCS5Padding + Base64 (Standard)Account holder name (Korean: 3 bytes per character).Account holder name (Korean: 3 bytes per character).
└uiiAN(10)Alphanumeric, up to 10 bytes*
AES-256AES-256/ECB/PKCS5Padding + Base64 (Standard)Date of birth (yyMMdd) or business registration number (10 digits).Date of birth (yyMMdd) or business registration number (10 digits).
└bankCdAN(3)Alphanumeric, up to 3 bytes*Financial institution code.
Financial institution code.
└custAcntNoAN(15)Alphanumeric, up to 15 bytes*
AES-256AES-256/ECB/PKCS5Padding + Base64 (Standard)Account number (no hyphens, minimum 9 digits, maximum 15 digits).Account number (no hyphens, minimum 9 digits, maximum 15 digits).
└authMthdCdAN(5)Alphanumeric, up to 5 bytesAuthentication method code.
Authentication method code.
ARS: ARS verification WR: Written consent PASS: PASS verification└custIpAN(15)Alphanumeric, up to 15 bytesCustomer IP address.
Customer IP address.
└pktHashAN(200)Alphanumeric, up to 200 bytes*
SHA-256SHA-256 HMAC signature.(실시간 생성)SHA-256 HMAC signature.
NOTE
Signature composition
mchtId + mchtCustId + reqDt + reqTm + custAcntNo + hashKey
Response Parameters
└outStatCdAN(4)Alphanumeric, up to 4 bytes*Transaction status code.
0021Transaction status code.
0021: Success 0031: Failure└outRsltCdAN(4)Alphanumeric, up to 4 bytes*Decline code.
0000Decline code.
*ST08: If the account is already enrolled, existing account information is returned
└outRsltMsgAN(300)Alphanumeric, up to 300 bytes*Result message.
Processed successfully.Result message.
└mchtCustIdAN(100)Alphanumeric, up to 100 bytes*
AES-256AES-256/ECB/PKCS5PaddingCustomer ID.kimhectoCustomer ID.
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└bankCdAN(3)Alphanumeric, up to 3 bytes*Bank code.
004Bank code.
└custAcntNoAN(15)Alphanumeric, up to 15 bytes*Account number (masked).
234*******123Account number (masked).
└custAcntKeyAN(50)Alphanumeric, up to 50 bytes*Account key — unique identifier for the enrolled direct debit account.
d894kjd93kd9Account key — unique identifier for the enrolled direct debit account.
└svcDivCdN(1)Numeric, up to 1 bytes*Account enrollment service type.
1Account enrollment service type.
1: Firm Banking└mchtTrdNoAN(100)Alphanumeric, up to 100 bytesMerchant order number.
OID201902210001Merchant order number.
└trdNoAN(40)Alphanumeric, up to 40 bytes*Transaction reference number.
STFP_FIRM12345678901234567890Transaction reference number.
└payerNoAN(20)Alphanumeric, up to 20 bytes*Payer number.
TESTMCHT00000001Payer number.
Request Example
{
"hdInfo": "SPAY_RE0W_1.0",
"mchtId": "midtest",
"mchtTrdNo": "T2026022100001",
"mchtCustId": "AES-encrypted customer ID",
"trdNo": "STFP_FIRM12345678901234567890",
"reqDt": "20260211",
"reqTm": "095000",
"mchtCustNm": "AES-encrypted account holder name",
"uii": "AES-encrypted date of birth",
"bankCd": "004",
"custAcntNo": "AES-encrypted account number",
"authMthdCd": "ARS",
"pktHash": "hash value"
}
Response Example
{
"outStatCd": "0021",
"outRsltCd": "0000",
"outRsltMsg": "Processed successfully.",
"mchtCustId": "AES-encrypted customer ID",
"bankCd": "004",
"custAcntNo": "234*******123",
"custAcntKey": "d894kjd93kd9",
"svcDivCd": "1",
"mchtTrdNo": "T2026022100001",
"trdNo": "STFP_FIRM12345678901234567890",
"payerNo": "TESTMCHT00000001"
}
Need technical support?
Code Samples
HectoFinancial GitHub