결제 링크 활용하기

NICE링크결제 서비스는 가맹점에서 고객의 정보를 나이스정보통신으로 전달하면 나이스페이 결제 모듈이 적용된 링크를 고객에게 문자(SMS), 이메일, 카카오톡 등으로 전송하는 서비스입니다. 필요 시, 링크를 가맹점에서 받은 후 고객에게 직접 전송하는 방법도 가능합니다.

1. 전체 Flow

고객께서 원하는 방법에 따라 결제 링크를 문자, 이메일, 카카오톡으로 발송하는 API와 발송된 결제 링크의 결과를 조회하는 API로 구성되어 있습니다.
결제 링크를 통해 고객이 결제하는 시점(가상계좌의 경우 입금 시)에 결과를 받고자 하는 경우 결제통보 페이지를 참고하시기 바랍니다.

2. 연동 전 준비 사항

2.1. 방화벽 설정

프로토콜: HTTPS
연결대상(IP): 121.133.126.56
포트(PORT): 443
연결방향: OUTBOUND
도메인 허용 목록: webapi.nicepay.co.kr

2.2. 주의 사항

NICE링크결제는 테스트 계정을 제공하지 않으며, 영업담당자와 협의된 이후 사용 가능합니다.
인코딩은 utf-8로 설정하여 요청하되 euc-kr에서 지원하지 않는 문자를 보내는 경우 해당 문자가 깨질 수 있습니다.
모든 API호출은 server-side에서 처리 될 수 있도록 하고 민감정보가 외부에 노출되지 않도록 주의해야 합니다. API 로깅에 따른 정보 노출의 모든 책임은 가맹점에 있습니다.
PG사의 기능 추가 및 서비스 개선에 따라 응답 필드는 사전 고지 없이 추가될 수 있습니다.
가맹점에서는 아래 표에 기재되지 않은 응답 필드가 추가될 수 있음을 고려하여 연동해야 하며, 추가 필드로 인해 파싱 오류 또는 결과 처리 오류가 발생하지 않도록 구현해야 합니다.

3. API 목록 및 구성

3.1. HTTP Request

Method: POST
URL: https://webapi.nicepay.co.kr/webapi/smslink/api.jsp
Content-Type: application/json
Encoding: UTF-8

3.2. 요청 전문 구성

API 데이터 포맷은 요청 전문을 정의한 header와 전달 파라미터를 정의한 body를 조합한 JSON 데이터입니다.
header는 요청 전문ID(sid) 및 결과 코드를 정의합니다.
- 서비스별 sid는 아래 "전문ID(sid) 목록"을 참고하시기 바랍니다.
body는 각 전문ID에 대한 요청/응답 값을 정의합니다.
- body 전문 내에는 가맹점 검증 및 요청 데이터 위변조 방지를 위한 encKey 값이 필수로 존재합니다.
  (encKey 생성 규칙은 아래 "가맹점 인증키(encKey) 생성 규칙" 항목을 참고하시기 바랍니다.)

필드명	크기(byte)	필수	설명
sid	10	O	전문 ID, 업무별 정의된 ID 입력
trDtm	14	O	요청 전문 생성 일시(YYYYMMDDHHMISS)
gubun	1	O	전문 구분 (S: 요청, R: 응답)
resCode	4	O	결과 코드, 빈 값으로 요청 후 결과 코드 반환 (0000: 성공 / 이외 실패)
resMsg	255	O	결과 메세지, 빈 값으로 요청 후 결과 메세지 반환

전문ID(sid) 목록

sid	API
0501001	NICE링크결제 등록
0501002	NICE링크결제 내역 조회

가맹점 인증키(encKey) 생성 규칙

규칙: hex(sha256(sid + usrId + trDtm + 가맹점 Key))
- sid: 전문ID (7자리)
- usrId: 상점 로그인 ID (최대 20자리)
- trDtm: 요청 전문 생성 일시 (14자리)
- 가맹점 Key: 가맹점관리자페이지(https://npg.nicepay.co.kr) 접속 후 가맹점정보->Key관리 매뉴를 통해 확인하실 수 있습니다.

4. NICE링크결제 등록 (0501001)

4.1. 요청 파라미터

필드명	크기(byte)	필수	설명
usrId	20	O	상점 로그인 ID
encKey	255	O	암호화 Key, 생성 규칙: `hex(sha256(sid + usrId + trDtm + MerchantKey))`
mid	10	O	가맹점 ID
goodsNm	100	O	상품명
goodsAmt	14	O	상품가격
moid	64	O	상품 주문번호
ordNm	30	O	구매자명
ordEmail	60		구매자 이메일 (`sendType`이 `1`인 경우 필수)
ordHpNo	15	O	구매자 휴대폰 번호 (`-` 기호 없이 입력)
type	1	O	발송 내용 구분 (`0`: 기본, `1`: 추가). `sendType=2`이거나 09~21시 외 시간대에 등록 요청하는 경우 반드시 `0`으로 설정
logoImageUrl	200		NICE링크결제 페이지 내 로고 CI 이미지 URL (`https` 프로토콜만 허용, 최대 길이 255)
skinType	10		NICE링크결제 페이지 색상 타입 (`blue`(default), `green`, `purple`, `darkgray`, `red`)
ordBusType	1		사업자 유형 (`0`: 개인, `1`: 법인)
ordBusNo	10		사업자 유형에 따른 구매자 정보 (개인: 생년월일 `YYMMDD`, 법인: 사업자번호 10자리)
sendType	2		결제 링크 발송 수단 (`0`: SMS(default), `1`: Email, `2`: KAKAO, `4`: 가맹점 결제 URL 응답)
payLimitDt	8		결제링크 유효기간 (`YYYYMMDD`). 요청 당일부터 최대 7일까지 설정 가능하며, 미입력 시 요청 당일로 설정
payMethod	10		결제수단 (`CARD`: 신용카드, `BANK`: 계좌이체, `VBANK`: 가상계좌, `CELLPHONE`: 휴대폰)
multiSelectQuota	2		카드 할부개월 (`00`: 일시불, `02`: 2개월, `03`: 3개월 등). 사용 시 결제수단은 카드로 고정되므로 `payMethod`는 `CARD`로 설정
transType	1		에스크로 결제 여부 (`0`: 일반 결제(default), `1`: 에스크로 결제)
langType	1		언어 설정 (`1`: 국문(default), `2`: 영문)
mallReserved	400		가맹점 여분필드 (결제통보 응답 시 `MallReserved` 필드로 값 변경 없이 전달)

기능별 옵션 파라미터

아래 내용은 가맹점 MID 설정에 따라 추가로 사용 가능한 파라미터들을 항목별로 정리하였습니다. 영업담당자와 사전 협의 후 사용하시기 바랍니다. (사전협의 없이 사용하는 경우 결제 혹은 취소 시 실패가 발생할 수 있습니다.)

과세 및 면세 지정 옵션 (사용 시 4개 필드의 합이 Amt 값과 일치해야 합니다.)

필드명	크기(byte)	설명
supplyAmt	12	공급가액
goodsVat	12	부가세
serviceAmt	12	봉사료
taxFreeAmt	12	면세 금액

4.2. 응답 파라미터

필드명	크기(byte)	설명
reqDt	14	요청일시 (YYYYMMDDHHMISS)
authCl	2	사용자 ID별 조회 권한 (2: MID, 3: GID, 4: AID)
dataCnt	-	데이터 Count
data	-	조회 데이터 (data 하위 파라미터 상세 항목 참조)

data 하위 파라미터 상세

필드명	크기(byte)	설명
reqId	30	요청 ID (NICE링크결제 내역 조회 시 사용)
payUrl	74	결제 요청 URL (요청 시 `sendType`이 `4`인 경우에만 응답)

4.3. 예시

요청 예시

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

POST /webapi/smslink/api.jsp HTTP/1.1
Host: webapi.nicepay.co.kr
Content-Type: application/json

{
  "header": {
    "sid": "0501001",
    "trDtm": "20200602142641",
    "gubun": "S",
    "resCode": "",
    "resMsg": ""
  },
  "body": {
    "usrId": "nictest00",
    "encKey": "4fed0e11d260344ebb15021701a47a83c8030755edd6c6ba772835cfd1f8059c",
    "type": "0",
    "mid": "nictest00m",
    "goodsNm": "테스트 상품",
    "goodsAmt": "1004",
    "moid": "TEST000001",
    "ordNm": "홍길동",
    "ordEmail": "test@test.co.kr",
    "ordHpNo": "01012341234"
  }
}

응답 예시

{
  "header": {
    "sid": "0501001",
    "trDtm": "20200602144636",
    "gubun": "R",
    "resCode": "0000",
    "resMsg": "SUCCESS"
  },
  "body": {
    "reqDt": "20200602144636",
    "authCl": "3",
    "dataCnt": 1,
    "data": [
      {
        "reqId": "gyooqn5o"
      }
    ],
    "reqInfo": {
      "header": {
        "sid": "0501001",
        "trDtm": "20200602142641",
        "gubun": "S",
        "resCode": "",
        "resMsg": ""
      },
      "body": {
        "usrId": "nictest00",
        "encKey": "4fed0e11d260344ebb15021701a47a83c8030755edd6c6ba772835cfd1f8059c",
        "type": "0",
        "mid": "nictest00m",
        "goodsNm": "테스트 상품",
        "goodsAmt": "1004",
        "moid": "TEST000001",
        "ordNm": "홍길동",
        "ordEmail": "test@test.co.kr",
        "ordHpNo": "01012341234"
      }
    }
  }
}

5. NICE링크결제 내역 조회 (0501002)

5.1. 요청 파라미터

필드명	크기(byte)	필수	설명
usrId	20	O	가맹점관리자페이지 로그인 ID
encKey	255	O	암호화 Key, 생성 규칙: `hex(sha256(sid + usrId + trDtm + MerchantKey))`
mid	10	O	가맹점 ID
reqId	30	O	NICE링크결제 등록 시 응답으로 받은 `reqId`

5.2. 응답 파라미터

필드명	크기(byte)	설명
reqDt	14	요청일시 (YYYYMMDDHHMISS)
authCl	2	사용자 ID별 조회 권한 (2: MID, 3: GID, 4: AID)
dataCnt	-	데이터 Count
data	-	조회 데이터 (data 하위 파라미터 상세 항목 참조)

data 하위 파라미터 상세

필드명	크기(byte)	설명
coNm	30	가맹점 상호
mid	10	가맹점 ID
svcNm	30	결제수단 (신용카드, 계좌이체, 가상계좌, 휴대폰)
payStatus	10	결제내역 (미완료, 결제완료, 결제실패, 결제중지)
sendDt	8	발송일자 (YYYYMMDD)
payDt	8	결제일자 (YYYYMMDD)
amt	14	거래금액
ordNm	30	구매자명
moid	64	상품 주문번호
ordEmail	60	구매자 이메일
ordHpNo	15	구매자 전화번호
sendStatus	10	전송 결과 (성공, 실패)
tid	30	거래 아이디 (Transaction ID)
goodsNm	100	상품명

5.3. 예시

요청 예시

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

POST /webapi/smslink/api.jsp HTTP/1.1
Host: webapi.nicepay.co.kr
Content-Type: application/json

{
  "header": {
    "sid": "0501002",
    "trDtm": "20200602142641",
    "gubun": "S",
    "resCode": "",
    "resMsg": ""
  },
  "body": {
    "usrId": "nictest00",
    "encKey": "5431a36e6eb963f73ef2f8fa8202f29f2edbd4595c4751ed7ef4064e78dbb547",
    "mid": "nictest00m",
    "reqId": "gyooqn5o"
  }
}

응답 예시

{
  "header": {
    "sid": "0501002",
    "trDtm": "20200602145003",
    "gubun": "R",
    "resCode": "0000",
    "resMsg": "SUCCESS"
  },
  "body": {
    "reqDt": "20200602145003",
    "authCl": "3",
    "dataCnt": 1,
    "data": [
      {
        "coNm": "나이스정보통신(주)",
        "mid": "nictest00m",
        "svcNm": "",
        "payStatus": "미완료",
        "sendDt": "20200602",
        "payDt": "",
        "amt": 1004,
        "ordNm": "홍길동",
        "moid": "TEST000001",
        "ordEmail": "te**@test.co.kr",
        "ordHpNo": "0101234****",
        "sendStatus": "성공",
        "tid": "",
        "goodsNm": "테스트 상품"
      }
    ],
    "reqInfo": {
      "header": {
        "sid": "0501002",
        "trDtm": "20200602142641",
        "gubun": "S",
        "resCode": "",
        "resMsg": ""
      },
      "body": {
        "usrId": "nictest00",
        "encKey": "5431a36e6eb963f73ef2f8fa8202f29f2edbd4595c4751ed7ef4064e78dbb547",
        "mid": "nictest00m",
        "reqId": "gyooqn5o"
      }
    }
  }
}

6. NICE링크결제 비활성화

6.1. HTTP Request

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

6.2. 요청 파라미터

필드명	크기(byte)	필수	설명
ReqId	14	O	NICE링크결제 등록 시 응답으로 받은 `reqId`
MID	10	O	가맹점 아이디
EdiDate	14	O	요청 전문 생성 일시(YYYYMMDDHHMISS)
SignData	256	O	위변조 검증 데이터, 생성규칙: hex(sha256(ReqId + EdiDate + MerchantKey))
CharSet	10		응답 인코딩 (euc-kr(default) / utf-8)

6.3. 응답 파라미터

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

필드명	크기(byte)	설명
ResultCode	4	결과코드 (0000: 성공, 이외 실패)
ResultMsg	100	결과 메세지
ReqId	14	가맹점이 요청 시 입력한 ReqId 값 그대로 전달
MID	10	가맹점 아이디
EdiDate	14	요청 전문 생성 일시(YYYYMMDDHHMISS)
Signature	500	위변조 검증 데이터, 생성 규칙: hex(sha256(ReqId + MID + MerchantKey))

6.4. 예시

요청 예시

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

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

ReqId=urix2609039271&MID=nictest00m&EdiDate=20260903200529&SignData=ba511c2828c4538508eacb2e5bb7a5058699b2e669a1f477035cfd944782753c&CharSet=utf-8

응답 예시

{
  "ResultCode": "0000",
  "ResultMsg": "정상 처리되었습니다.",
  "ReqId": "urix2609039271",
  "MID": "nictest00m",
  "EdiDate": "20260903200529",
  "Signature": "f225a56735ac4003908693e998070e065693808b3aba0c5e9e8944c777901297"
}

1. 전체 Flow​

2. 연동 전 준비 사항​

2.1. 방화벽 설정​

2.2. 주의 사항​

3. API 목록 및 구성​

3.1. HTTP Request​

3.2. 요청 전문 구성​

header 파라미터 명세​

전문ID(sid) 목록​

가맹점 인증키(encKey) 생성 규칙​

4. NICE링크결제 등록 (0501001)​

4.1. 요청 파라미터​

기능별 옵션 파라미터​

4.2. 응답 파라미터​

data 하위 파라미터 상세​

4.3. 예시​

요청 예시​

응답 예시​

5. NICE링크결제 내역 조회 (0501002)​

5.1. 요청 파라미터​

5.2. 응답 파라미터​

data 하위 파라미터 상세​

5.3. 예시​

요청 예시​

응답 예시​

6. NICE링크결제 비활성화​

6.1. HTTP Request​

6.2. 요청 파라미터​

6.3. 응답 파라미터​

6.4. 예시​

요청 예시​

응답 예시​

1. 전체 Flow

2. 연동 전 준비 사항

2.1. 방화벽 설정

2.2. 주의 사항

3. API 목록 및 구성

3.1. HTTP Request

3.2. 요청 전문 구성

header 파라미터 명세

전문ID(sid) 목록

가맹점 인증키(encKey) 생성 규칙

4. NICE링크결제 등록 (0501001)

4.1. 요청 파라미터

기능별 옵션 파라미터

4.2. 응답 파라미터

data 하위 파라미터 상세

4.3. 예시

요청 예시

응답 예시

5. NICE링크결제 내역 조회 (0501002)

5.1. 요청 파라미터

5.2. 응답 파라미터

data 하위 파라미터 상세

5.3. 예시

요청 예시

응답 예시

6. NICE링크결제 비활성화

6.1. HTTP Request

6.2. 요청 파라미터

6.3. 응답 파라미터

6.4. 예시

요청 예시

응답 예시