지급대행 처리하기

가맹점에서 발생한 매출에 대하여 실제 판매자에게 정산이 필요한 경우, 나이스정보통신에서 가맹점을 대신하여 정산금을 지급하는 서비스입니다.

1. 전체 Flow

서브몰(판매자)의 정보를 먼저 등록하는 과정이 필요합니다.
- 은행 시스템 전환 시간인 23:00~01:00 에는 서브몰 등록이 불가합니다.
지급을 요청하기 전 잔액이 충분한지 확인합니다.
계좌에 남은 잔액 내에서 원하는 서브몰을 설정하여 지급 요청을 진행합니다.
- 지급 요청에 대한 취소 처리도 가능하며 지급 당일(영업일) 기준 오전 10:30 이내로 처리가 완료되어야 합니다.
요청된 내용에 따라 나이스정보통신에서 서브몰로 지급을 대행 처리합니다.
- 지급 처리 시간은 11:00~14:00 이내에 이루어집니다.
지급 요청 후 정상 여부를 확인하기 위해 지급 당일 16:00 이후 결과를 조회할 수 있습니다.

2. 연동 전 준비 사항

2.1. 방화벽 설정

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

2.2. 주의 사항

지급대행 서비스는 테스트 계정을 제공하지 않으며, 영업담당자와 협의된 이후 사용 가능합니다.
지급 처리가 완료된 내역에 대하여 원복은 불가합니다. 지급 요청 시 신중하게 처리하시기 바랍니다.
모든 API호출은 server-side에서 처리 될 수 있도록 하고 민감정보가 외부에 노출되지 않도록 주의해야 합니다. API 로깅에 따른 정보 노출의 모든 책임은 가맹점에 있습니다.
PG사의 기능 추가 및 서비스 개선에 따라 응답 필드는 사전 고지 없이 추가될 수 있습니다.
가맹점에서는 아래 표에 기재되지 않은 응답 필드가 추가될 수 있음을 고려하여 연동해야 하며, 추가 필드로 인해 파싱 오류 또는 결과 처리 오류가 발생하지 않도록 구현해야 합니다.
페이프로 서비스(위챗, 알리페이, 페이팔 등)를 이용하는 MID의 경우 지급 요청을 요청 전일 23시 59분까지 진행해야 합니다.

3. API 목록 및 구성

3.1. HTTP Request

Method: POST
URL: https://data.nicepay.co.kr/om/api
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
0101001	잔액조회
0105001	서브몰 등록/수정
0102001	지급요청
0103001	지급취소
0101002	결과조회

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

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

4. 잔액조회 (0101001)

4.1. 요청 파라미터

필드명	크기(byte)	필수	설명
mid	10	O	가맹점 ID
encKey	255	O	가맹점 인증키, 생성 규칙: hex(sha256(sid + mid + trDtm + 가맹점 Key))

4.2. 응답 파라미터

필드명	크기(byte)	설명
mid	10	가맹점 ID
remainAmt	20	총 잔액
last	-	최근 내역 ("last 하위 파라미터 상세" 항목 참조)

last 하위 파라미터 상세

필드명	크기(byte)	설명
lastcl	2	거래구분 (00: 정산대금, 01: 현금입금, 10: 서브몰 지급)
lastAmt	20	마지막으로 처리한 지급대행 요청 금액
lastDt	8	처리일자 (YYYYMMDD)

4.3. 예시

요청 예시

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

POST /om/api HTTP/1.1
Host: data.nicepay.co.kr
Content-Type: application/json

{
  "header": {
    "sid": "0101001",
    "trDtm": "20190619163525",
    "gubun": "S",
    "resCode": "",
    "resMsg": ""
  },
  "body": {
    "mid": "nictest00m",
    "encKey": "4168f1a95b1b9a765ae67500836416bfbca147c8bc8938cb07cee3b0f86d23f4"
  }
}

응답 예시

{
  "header": {
    "sid": "0101001",
    "trDtm": "20190619163526",
    "gubun": "R",
    "resCode": "0000",
    "resMsg": ""
  },
  "body": {
    "mid": "nictest00m",
    "remainAmt": 77000,
    "last": {
      "lastDt": "20181123",
      "lastAmt": 52000,
      "lastCl": "10"
    },
    "reqInfo": {
      "header": {
        "sid": "0101001",
        "trDtm": "20190619163525",
        "gubun": "S",
        "resCode": "",
        "resMsg": ""
      },
      "body": {
        "mid": "nictest00m",
        "encKey": "4168f1a95b1b9a765ae67500836416bfbca147c8bc8938cb07cee3b0f86d23f4"
      }
    }
  }
}

5. 서브몰 등록/수정 (0105001)

5.1. 요청 파라미터

필드명	크기(byte)	필수	설명
mid	10	O	가맹점 ID
subId	50	O	서브몰 ID
subNm	50	O	서브몰명
subCoNo	30	O	사업자번호 (수정 불가)
bankCd	3	O	정산 은행코드
accntNo	30	O	정산 계좌번호
accntNm	30	O	정산 계좌주명
memo	100		비고
reqType	1	O	요청 구분 (0: 신규 등록, 1: 수정)
encKey	255	O	가맹점 인증키, 생성 규칙: hex(sha256(sid + mid + trDtm + 가맹점 Key))

5.2. 응답 파라미터

필드명	크기(byte)	설명
mid	10	가맹점 ID
subId	50	서브몰 ID
reqType	1	요청 구분 (0: 신규 등록, 1: 수정)

서브몰 신규 등록 시 주의 사항 (reqType: 0)

신규 등록 시 예금주 조회 로직을 이용하여 bankCd, accntNo, accntNm 정보를 검증합니다. 예금주와 계좌 정보가 불일치하는 경우 오류가 발생합니다.
잘못된 계좌를 등록하여 발생하는 책임은 가맹점에 있습니다.
예금주 조회 API가 필요한 경우 영업담당자를 통해 사전 협의 바랍니다.

서브몰 수정 시 주의 사항 (reqType: 1)

서브몰 수정 요청이 인입되는 경우 mid와 subId를 먼저 검증하며 등록되지 않은 mid, subId로 서브몰 정보 수정 요청이 인입되는 경우 오류가 발생합니다.
수정이 가능한 항목에 대해서는 아래 파라미터를 참고하시기 바랍니다.
- subNm(서브몰명), bankCd(정산 은행코드), accntNo(정산 은행계좌), accntNm(계좌주명), memo(비고)
수정이 불가능한 항목에 대해서는 신규 동록 요청 시 입력한 정보와 동일한 값으로 요청합니다.

5.3. 예시

요청 예시

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

POST /om/api HTTP/1.1
Host: data.nicepay.co.kr
Content-Type: application/json

{
  "header": {
    "sid": "0105001",
    "trDtm": "20190619163525",
    "gubun": "S",
    "resCode": "",
    "resMsg": ""
  },
  "body": {
    "mid": "nictest00m",
    "encKey": "b52ccf46cd4335b41073a4dc8a9b5e717b4ad86924f02fc9dad8eedf2a6e617e",
    "subId": "1251216623",
    "subNm": "테스트22",
    "subCoNo": "1268262702",
    "accntNm": "테스트",
    "bankCd": "034",
    "accntNo": "1251252121126",
    "memo": "테스트11",
    "reqType": "0"
  }
}

응답 예시

{
  "header": {
    "sid": "0105001",
    "trDtm": "20190619163528",
    "gubun": "R",
    "resCode": "0000",
    "resMsg": ""
  },
  "body": {
    "mid": "nictest00m",
    "subId": "1251216623",
    "reqType": "0",
    "reqInfo": {
      "header": {
        "sid": "0105001",
        "trDtm": "20190619163525",
        "gubun": "S",
        "resCode": "",
        "resMsg": ""
      },
      "body": {
        "mid": "nictest00m",
        "encKey": "b52ccf46cd4335b41073a4dc8a9b5e717b4ad86924f02fc9dad8eedf2a6e617e",
        "subId": "1251216623",
        "subNm": "테스트22",
        "subCoNo": "1268262702",
        "accntNm": "테스트",
        "bankCd": "034",
        "accntNo": "1251252121126",
        "memo": "테스트11",
        "reqType": "0"
      }
    }
  }
}

6. 지급요청 (0102001)

6.1. 요청 파라미터

필드명	크기(byte)	필수	설명
mid	10	O	가맹점 ID
settlmntDt	8	O	지급일자 (YYYYMMDD), 과거 일자 불가
subId	50	O	서브몰 ID
settlmntAmt	14	O	지급 요청 금액 (숫자만 입력)
dupChkYn	1	O	중복체크여부 (Y: 요청일 기등록건 중복 체크 / N: 중복 허용)
accntDesc	30		수취인 계좌에 표기될 정보, 미설정 시 가입시점에 등록한 값을 기준으로 처리
(등록된 값은 영업담당자 통해 확인 필요)
encKey	255	O	가맹점 인증키, 생성 규칙: hex(sha256(sid + mid + trDtm + 가맹점 Key))

6.2. 응답 파라미터

필드명	크기(byte)	설명
mid	10	가맹점 ID
subId	50	서브몰 ID
settlmntDt	8	지급일자 (YYYYMMDD)
settlmntAmt	14	지급 요청 금액
dupChkYn	1	중복체크여부
seq	20	지급 요청 seq, 취소 및 결과 조회 시 사용

지급 요청 시 주의 사항

지급 요청은 지급처리를 원하는 일자의 오전 10시 30분 전까지 요청이 되어야 합니다. (영업일 기준)
- 오전 10시 30분 이후 당일 일자로 지급 요청 시 오류가 발생합니다.
지급 요청 시 가맹점의 계좌 잔액 검증은 별도로 진행하지 않으므로 실제 지급대행 처리 결과는 결과 조회 API를 활용하여 검증하는 작업이 필요합니다.

6.3. 예시

요청 예시

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

POST /om/api HTTP/1.1
Host: data.nicepay.co.kr
Content-Type: application/json

{
  "header": {
    "sid": "0102001",
    "trDtm": "20190619163525",
    "gubun": "S",
    "resCode": "",
    "resMsg": ""
  },
  "body": {
    "mid": "nictest00m",
    "encKey": "f10478217813ed17e1f55f65ffecd7f3ce5e65ed6c70d1217052bbe10c8302c2",
    "subId": "1251216623",
    "settlmntDt": "20190620",
    "settlmntAmt": "12455555",
    "dupChkYn": "N"
  }
}

응답 예시

{
  "header": {
    "sid": "0102001",
    "trDtm": "20190619163528",
    "gubun": "R",
    "resCode": "0000",
    "resMsg": ""
  },
  "body": {
    "mid": "nictest00m",
    "subId": "1251216623",
    "settlmntDt": "20190620",
    "settlmntAmt": 12455555,
    "dupYn": "N",
    "seq": "296486",
    "reqInfo": {
      "header": {
        "sid": "0102001",
        "trDtm": "20190619163525",
        "gubun": "S",
        "resCode": "",
        "resMsg": ""
      },
      "body": {
        "mid": "nictest00m",
        "encKey": "f10478217813ed17e1f55f65ffecd7f3ce5e65ed6c70d1217052bbe10c8302c2",
        "subId": "1251216623",
        "settlmntDt": "20190620",
        "settlmntAmt": "12455555",
        "dupChkYn": "N"
      }
    }
  }
}

7. 지급취소 (0103001)

7.1. 요청 파라미터

필드명	크기(byte)	필수	설명
mid	10	O	가맹점 ID
settlmntDt	8	O	지급일자 (YYYYMMDD)
subId	50	O	서브몰 ID
seq	20	O	지급 요청 seq, 지급 요청 시 응답된 seq 정보
encKey	255	O	가맹점 인증키, 생성 규칙: hex(sha256(sid + mid + trDtm + 가맹점 Key))

7.2. 응답 파라미터

필드명	크기(byte)	설명
mid	10	가맹점 ID
subId	50	서브몰 ID
settlmntDt	8	지급일자 (YYYYMMDD)
settlmntAmt	14	지급 요청 금액
seq	20	취소된 seq

지급 취소 요청 시 주의 사항

지급요청 취소는 단일 seq에 대해 처리가 가능합니다.
지급처리일 기준 당일 오전 10시 30분 전까지 요청이 가능하며, 그 이후 시간에는 취소가 불가합니다.

7.3. 예시

요청 예시

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

POST /om/api HTTP/1.1
Host: data.nicepay.co.kr
Content-Type: application/json

{
  "header": {
    "sid": "0103001",
    "trDtm": "20190619163525",
    "gubun": "S",
    "resCode": "",
    "resMsg": ""
  },
  "body": {
    "mid": "nictest00m",
    "encKey": "0f5532ee2f39a2f5334bcda177e60f128c7998ed325fca7e30b94639a6f6c199",
    "subId": "1251216623",
    "settlmntDt": "20190620",
    "seq": "296486"
  }
}

응답 예시

{
  "header": {
    "sid": "0103001",
    "trDtm": "20190619163528",
    "gubun": "R",
    "resCode": "0000",
    "resMsg": ""
  },
  "body": {
    "mid": "nictest00m",
    "subId": "1251216623",
    "settlmntDt": "20190620",
    "settlmntAmt": 12455555,
    "seq": "296486",
    "reqInfo": {
      "header": {
        "sid": "0103001",
        "trDtm": "20190619163525",
        "gubun": "S",
        "resCode": "",
        "resMsg": ""
      },
      "body": {
        "mid": "nictest00m",
        "encKey": "0f5532ee2f39a2f5334bcda177e60f128c7998ed325fca7e30b94639a6f6c199",
        "subId": "1251216623",
        "settlmntDt": "20190620",
        "seq": "296486"
      }
    }
  }
}

8. 결과조회 (0101002)

8.1. 요청 파라미터

필드명	크기(byte)	필수	설명
mid	10	O	가맹점 ID
settlmntDt	8	O	지급일자 (YYYYMMDD)
subId	50		서브몰 ID, 미입력 시 mid 지급처리 전체 내역 응답
encKey	255	O	가맹점 인증키, 생성 규칙: hex(sha256(sid + mid + trDtm + 가맹점 Key))

8.2. 응답 파라미터

필드명	크기(byte)	설명
totCnt	10	전체 건수
succCnt	10	성공 건수
failCnt	10	실패 건수
remainAmt	20	잔액
detail	-	결과 상세 ("detail 하위 파라미터 상세" 항목 참조)

detail 하위 파라미터 상세

필드명	크기(byte)	설명
rowNo	10	순번
seq	20	요청 seq
settlmntDt	8	지급일자
subCoNo	10	서브몰 사업자번호
subCoNm	40	서브몰명
subId	50	서브몰 ID
statusNm	10	지급 상태 (요청/성공/실패/재요청 진행중/삭제)
settlmntAmt	20	지급 금액
bankCd	3	은행코드
accntNm	30	예금주명
accntNo	30	계좌번호
errReason	255	실패 사유

8.3. 예시

요청 예시

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

POST /om/api HTTP/1.1
Host: data.nicepay.co.kr
Content-Type: application/json

{
  "header": {
    "sid": "0101002",
    "trDtm": "20190619163525",
    "gubun": "S",
    "resCode": "",
    "resMsg": ""
  },
  "body": {
    "mid": "nictest00m",
    "encKey": "bf5ea7d9cde94ac4646f95ec4c2cae2ce763a4d388f7fda96b6182934b60111a",
    "settlmntDt": "20190625",
    "subId": ""
  }
}

응답 예시

{
  "header": {
    "sid": "0101002",
    "trDtm": "20190619163528",
    "gubun": "R",
    "resCode": "0000",
    "resMsg": ""
  },
  "body": {
    "mid": "nictest00m",
    "totCnt": 4,
    "succCnt": 0,
    "failCnt": 0,
    "remainAmt": 40000000,
    "detail": [
      {
        "rowNo": "1",
        "seq": "296490",
        "settlmntDt": "20190625",
        "subCoNo": "2208115770",
        "subCoNm": "나이스정보통신1",
        "subId": "2302000",
        "statusNm": "요청",
        "settlmntAmt": 14000000,
        "bankCd": "011",
        "accntNm": "나이스",
        "accntNo": "***********",
        "errReason": " "
      },
      {
        "rowNo": "2",
        "seq": "296491",
        "settlmntDt": "20190625",
        "subCoNo": "8158100527",
        "subCoNm": "테스트상점",
        "subId": "HongGilDong",
        "statusNm": "요청",
        "settlmntAmt": 10000,
        "bankCd": "081",
        "accntNm": "홍길동",
        "accntNo": "***********",
        "errReason": " "
      },
      {
        "rowNo": "3",
        "seq": "296498",
        "settlmntDt": "20190625",
        "subCoNo": "2208115770",
        "subCoNm": "나이스정보통신2",
        "subId": "2302005",
        "statusNm": "요청",
        "settlmntAmt": 125666,
        "bankCd": "011",
        "accntNm": "나이스",
        "accntNo": "***********",
        "errReason": " "
      },
      {
        "rowNo": "4",
        "seq": "296499",
        "settlmntDt": "20190625",
        "subCoNo": "8158100527",
        "subCoNm": "테스트상점",
        "subId": "2302230",
        "statusNm": "요청",
        "settlmntAmt": 123456,
        "bankCd": "004",
        "accntNm": "김철수",
        "accntNo": "***********",
        "errReason": " "
      }
    ],
    "reqInfo": {
      "header": {
        "sid": "0101002",
        "trDtm": "20190619163525",
        "gubun": "S",
        "resCode": "",
        "resMsg": ""
      },
      "body": {
        "mid": "nictest00m",
        "encKey": "bf5ea7d9cde94ac4646f95ec4c2cae2ce763a4d388f7fda96b6182934b60111a",
        "settlmntDt": "20190625",
        "subId": ""
      }
    }
  }
}

1. 전체 Flow​

2. 연동 전 준비 사항​

2.1. 방화벽 설정​

2.2. 주의 사항​

3. API 목록 및 구성​

3.1. HTTP Request​

3.2. 요청 전문 구성​

header 파라미터 명세​

전문ID(sid) 목록​

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

4. 잔액조회 (0101001)​

4.1. 요청 파라미터​

4.2. 응답 파라미터​

last 하위 파라미터 상세​

4.3. 예시​

요청 예시​

응답 예시​

5. 서브몰 등록/수정 (0105001)​

5.1. 요청 파라미터​

5.2. 응답 파라미터​

서브몰 신규 등록 시 주의 사항 (reqType: 0)​

서브몰 수정 시 주의 사항 (reqType: 1)​

5.3. 예시​

요청 예시​

응답 예시​

6. 지급요청 (0102001)​

6.1. 요청 파라미터​

6.2. 응답 파라미터​

지급 요청 시 주의 사항​

6.3. 예시​

요청 예시​

응답 예시​

7. 지급취소 (0103001)​

7.1. 요청 파라미터​

7.2. 응답 파라미터​

지급 취소 요청 시 주의 사항​

7.3. 예시​

요청 예시​

응답 예시​

8. 결과조회 (0101002)​

8.1. 요청 파라미터​

8.2. 응답 파라미터​

detail 하위 파라미터 상세​

8.3. 예시​

요청 예시​

응답 예시​

1. 전체 Flow

2. 연동 전 준비 사항

2.1. 방화벽 설정

2.2. 주의 사항

3. API 목록 및 구성

3.1. HTTP Request

3.2. 요청 전문 구성

header 파라미터 명세

전문ID(sid) 목록

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

4. 잔액조회 (0101001)

4.1. 요청 파라미터

4.2. 응답 파라미터

last 하위 파라미터 상세

4.3. 예시

요청 예시

응답 예시

5. 서브몰 등록/수정 (0105001)

5.1. 요청 파라미터

5.2. 응답 파라미터

서브몰 신규 등록 시 주의 사항 (reqType: 0)

서브몰 수정 시 주의 사항 (reqType: 1)

5.3. 예시

요청 예시

응답 예시

6. 지급요청 (0102001)

6.1. 요청 파라미터

6.2. 응답 파라미터

지급 요청 시 주의 사항

6.3. 예시

요청 예시

응답 예시

7. 지급취소 (0103001)

7.1. 요청 파라미터

7.2. 응답 파라미터

지급 취소 요청 시 주의 사항

7.3. 예시

요청 예시

응답 예시

8. 결과조회 (0101002)

8.1. 요청 파라미터

8.2. 응답 파라미터

detail 하위 파라미터 상세

8.3. 예시

요청 예시

응답 예시