카드키인 API 연동하기

1. 카드 Key-in API Flow

2. 설명 (Description)

• 카드키인 서비스는 카드번호, 유효기간 등의 카드 정보로 별도의 인증 절차 없이 결제를 처리하는 서비스입니다.
• 결제를 시도하려는 카드가 유효기간 만료, 분실/정지된 카드 등 유효성 문제가 있는 경우 카드사에서 오류 메세지를 그대로 전달합니다.
  이 경우, 결제를 시도한 카드의 소유주께서 직접 카드사를 통해 오류 상세 확인이 필요합니다.
• 해당 문서에서는 카드 키인 서비스 요청 시 필요한 기본적인 파라미터 위주로 기재하고 있습니다.
  이외 부가적인 기능을 원하시는 경우 영업담당자를 통해 가능 여부를 협의하시기 바랍니다.

3. 요청 (Request)

3.1. HTTP Request

• Method: POST
• URL: https://webapi.nicepay.co.kr/webapi/card_keyin.jsp
• Content-Type: application/x-www-form-urlencoded
• Encoding: EUC-KR

3.2. 요청 파라미터

필드명	크기(byte)	필수	설명
TID	30	O	거래 아이디, TID 생성규칙 항목 참고
MID	10	O	가맹점 아이디
EdiDate	14	O	전문생성일시 (YYYYMMDDHHMISS)
Moid	64	O	가맹점 주문번호 (고유한 값으로 설정, 나이스페이 가공 없음)
Amt	12	O	결제 금액
GoodsName	40	O	상품명
EncData	512	O	결제정보 암호화 데이터, EncData 생성 규칙 및 하위 파라미터 상세 항목 참고
CardInterest	1	O	가맹점 분담 무이자 할부 이벤트 사용 여부 (0: 미사용, 1: 사용(무이자))
CardQuota	2	O	할부 개월 (00: 일시불, 02: 2개월, 03: 3개월, ...)
SignData	256	O	위변조 검증 데이터, 생성 규칙: hex(sha256(MID + Amt + EdiDate + Moid + MerchantKey))
BuyerEmail	60		구매자 이메일 주소
BuyerTel	20		구매자 전화번호
BuyerName	30		구매자명
CharSet	10		인증 응답 인코딩 (euc-kr(default) / utf-8)
EdiType	10		응답전문 유형 (JSON(default) / KV) *KV:Key=value
MallReserved	500		가맹점 여분필드 (나이스페이 가공 없음)

TID 생성규칙

생성 규칙

• MID(10) + 지불수단(2) + 매체구분(2) + 시간정보(12) + 랜덤(4)
• 크기: 30 byte
• 설명:
  • MID: 가맹점 아이디 (문자열 끝은 소문자 m으로 기재되어야 함.)
  • 지불수단: 결제수단별 코드 (01: 신용카드)
  • 매체구분: 거래 형태 (01: 일반)
  • 시간정보: 결제 요청 일시 (YYMMDDHHMISS)
  • 랜덤: 거래를 식별하기 위한 임의의 값 4자리
• TID 생성 예시: nictest00m01012605061948280471

EncData 생성 규칙 및 하위 파라미터 상세

생성 규칙

• 암호화 알고리즘: AES128/ECB/PKCS5padding
• 암호화 결과 인코딩: Hex Encoding
• 암호 Key: 가맹점에 부여된 MerchantKey 앞 16자리

결제정보 암호화 생성 규칙: Hex(AES(CardNo=value&CardExpire=YYMM&BuyerAuthNum=value&CardPwd=value))

필드명	크기(byte)	필수	설명
CardNo	16	O	카드번호
CardExpire	4	O	카드 유효기간 (YYMM)
BuyerAuthNum	13		생년월일 6자리 또는 사업자등록번호 10자리
CardPwd	2		카드 비밀번호 앞 2자리

주의사항

• 입력된 카드 정보가 외부로 노출되지 않도록 주의해야 합니다.
• BuyerAuthNum, CardPwd 필드는 계약 현황에 따라 필수 여부가 결정되므로 계약 시 영업담당자와 협의가 필요합니다.

---

4. 응답 (Response)

4.1. 응답 파라미터

PG사의 기능 추가 및 서비스 개선에 따라 응답 필드는 사전 고지 없이 추가될 수 있습니다.
가맹점에서는 아래 표에 기재되지 않은 응답 필드가 추가될 수 있음을 고려하여 연동해야 하며, 추가 필드로 인해 파싱 오류 또는 결과 처리 오류가 발생하지 않도록 구현해야 합니다.

필드명	크기(byte)	설명
ResultCode	4	결과코드 (3001: 성공, 이외 실패)
ResultMsg	100	결과 메세지
TID	30	거래 아이디
Moid	64	가맹점 주문번호
Amt	12	결제 금액
AuthCode	30	승인번호
AuthDate	12	승인 일시 (YYMMDDHHMISS)
AcquCardCode	4	매입 카드사 코드
AcquCardName	20	매입 카드사명
CardNo	20	카드번호, 예) 12345678****1234
CardCode	4	카드사 코드
CardName	20	카드사명
CardQuota	2	할부개월
CardCl	1	카드타입 (0: 신용카드, 1: 체크카드)
CcPartCl	1	부분취소 가능 여부 (0: 불가능, 1: 가능)
CardInterest	1	무이자 결제 여부 (0: 이자, 1: 무이자)
MallReserved	500	가맹점 여분필드 (요청 시 Data 그대로 전달)

---

5. 예시

아래 예시는 테스트 시 이해를 돕기 위해 임의로 만든 데이터로 요청 및 응답 규격을 확인하기 위한 용도입니다.
예시 데이터를 실제 API 요청에 사용하지 않도록 주의해주세요.

5.1. 요청 예시

POST /webapi/card_keyin.jsp HTTP/1.1
Host: webapi.nicepay.co.kr
Content-Type: application/x-www-form-urlencoded

TID=nictest00m01012605061948280471&MID=nictest00m&EdiDate=20260506194828&Moid=MOID_260506194748&Amt=1004&GoodsName=TEST&EncData=a1a8b8db9e921ac45c57213e22f7a5f249f2fa74099eeaa301befac20f49d35feae72075bcd0c9e38370f2025f78e51e27afb91f4c04f697bb030d2227536a3fa706dfdf64cc8505dedfb7fa9b131714&SignData=5c80a192a75b5c91a399a8b0630eda67b4be6140b94d09a90d22f0943ec4e5cd&CardInterest=0&CardQuota=00

5.2. 응답 예시

{
  "ResultCode":"3001",
  "ResultMsg":"카드 결제 성공",
  "TID":"nictest00m01012605061948280471",
  "Moid":"MOID_260506194748",
  "Amt":"000000001004",
  "AuthCode":"15215812",
  "AuthDate":"260506194829",
  "AcquCardCode":"04",
  "AcquCardName":"삼성",
  "CardNo":"12345678****9012",
  "CardCode":"04",
  "CardName":"삼성",
  "CardQuota":"00",
  "CardCl":"0",
  "CcPartCl":"1",
  "CardInterest":"0",
  "MallReserved":""
}

---