지급대행
개발 전 확인이 필요한 공통적인 가이드
소개
고객사 API 목록
| API 구분 | API 리소스 경로 |
|---|---|
| 거래 내역 조회 | GET1.0/txlist |
| 정산 내역 조회 | GET1.0/sttllist |
| 지급대행 고객사 서브몰 등록 요청 | POSTv1.0/sttl-prcy/submall |
지급대행 고객사 지급 데이터 등록
|
|
| 지급대행 고객사 서브몰 금액 지급 요청 | POSTv1.0/sttl-prcy/amtsttl |
| 지급대행 환불 요청 | POSTv1.0/sttl-prcy/pybk |
| 지급대행 환불 데이터 확정 요청 | POSTv1.0/sttl-prcy/pybkdcsn |
| 지급대행 환불 취소 요청 | POSTv1.0/sttl-prcy/pybkcncl |
| 지급대행 송금 결과 조회 | POSTv1.0/sttl-prcy/rmtrslt |
| 지급대행 잔액 조회 | POSTv1.0/sttl-prcy/blnc |
*고객사 API의 미디어 타입은 "content-type application/json" 입니다.
통신 규칙
표준 RESTful-API 통신 방식을 따르며, HTTP 1.1 Specification을 준수합니다.
HTTP Method, Resource URL을 요청하면, JSON 데이터를 응답합니다.
지급 대행
개요
판매자와 구매자 모두 참여할 수 있는 온라인 시작을 오픈마켓으로 정의 할 때, 지급 대행은 이런 오픈마켓 형태의 쇼핑몰을 대상으로 쇼핑몰 입점 판매자(서브몰)에게 대금 지급을 대행해주는 서비스이고, 전자상거래, 모다빙 결제, 게임 결제와 항공권 예매 등 여러 분야에서 사용 가능합니다.
지급 대행이 필요한 이유는 판매자가 등록한 상품이 구매되면 발생하는 결제 대금을 판매자가 직접 받는 것이 아니라, 오픈마켓 플랫폼과 연결된 지급대행업체를 통해 받고 결제 대금을 중계하는 과정을 위해 지급대행서비스가 필요합니다.
지급 대행 서브몰 등록
- 고객사는 대금을 지급 할 판매자(서브몰) 등록을 요청합니다.
- 고객사에서 PG로 서브몰 등록 요청을 하면 PG에서 연계시스템(펌뱅킹)에 예금주 계좌조회 API 호출하여 계좌번호를 검증 후 고객사 하위 서브몰 등록합니다.
- 등록 된 서브몰에 대해서는 고객사 관리자 페이지에서 리스트 관리 및 상태를 확인할 수 있다.
지급 대행 지급 데이터 등록 및 지급
- 고객사에서 지급 데이터 등록을 요청하면 고객사별로 등록된 서브몰을 검증하고, 이상 없으면 고객사별로 잔액을 체크하여 지급 데이터를 등록합니다.
- 고객사에서 금액 지급 요청을 하면 등록된 고객사 지급 데이터의 지급처리상태가 고객사관리자 확인으로 변경되어 배치에서 지급을 할 때 해당 상태 값으로 금액을 지급합니다.
고객사 API 정의
거래 내역 조회
고객사 거래 대사용 거래 내역 조회 API 입니다.
API 요청
| URL | HTTP 메서드 | HTTP 헤더 | 키 유형 |
|---|---|---|---|
| /1.0/txlist | GET | Authorization: SPGKEY {API Key} | comparison |
요청 데이터
| 파라미터 | 필수 여부 | 자료형 | 크기 | 설명 |
|---|---|---|---|---|
| client_id | 필수 | string | 10 | 고객사 아이디 |
| req_ymd | 필수 | string | 10 | (조회)요청 일자 (예: 2021-09-29) |
| pgcode | string | 10 |
결제수단 코드 (5. 결제수단 & 오류코드 참조) *결제수단 코드가 없는 경우, 전체 결제수단의 정산 내역을 응답합니다. |
응답 데이터
처리 성공
Content-Type 은 text/csv, charset 은 UTF-8 입니다.
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| 헤더 | |||
| tot_cnt | number | (조회)총 수 | |
| 데이터 | |||
| tx_date | string | 10 |
(PG)거래 일자 (YYYY-MM-DD) *승인일자 또는 취소일자 또는 부분취소일자를 의미하며, (PG)거래 상태를 토대로 구분 가능합니다. |
| pgcode | string | 10 | 결제수단 코드(5. 결제수단 & 오류코드 참조) |
| user_id | string | 50 | 고객사 사용자(회원) 아이디(이메일, 영문 및 숫자 가능) |
| tid | string | 50 | 거래 번호 |
| tx_amt | number | 거래 금액(취소, 부분 취소 상태는 취소 금액) | |
| taxfree_amt | number | 비과세 금액 | |
| tax_amt | number | 부가세 금액 | |
| order_no | string | 50 | (고객사)주문번호 |
| prod_nm | string | 50 | (거래)상품 명 |
| tx_state | number | 거래 상태(1: 결제, 2: 취소, 3: 부분 취소) | |
HTTP 1.1 200 OK
tot_cnt
3
tx_date,pgcode,user_id,tid,tx_amt,taxfree_amt,tax_amt,order_no,prod_nm,tx_state
2021-10-29,creditcard,test01,tpay_test202110291723360001,1100,0,90,1234567890,테스트상품,1
2021-10-29,zeropay,test02,tpay_test202110290953250002,1000,0,90,1234567891,테스트상품,2
2021-10-29,creditcard,test03,tpay_test202110291723360003,5000,0,455,1234567892,테스트상품,3
정산 내역 조회
고객사 정산 대사용 정산 내역 조회 API 입니다. 요청 일자의 건 별 정산 확정 내역을 응답합니다.
API 요청
| URL | HTTP 메서드 | HTTP 헤더 | 키 유형 |
|---|---|---|---|
| /1.0/sttllist | GET | Authorization: SPGKEY {API Key} | comparison |
요청 데이터
| 파라미터 | 필수 여부 | 자료형 | 크기 | 설명 |
|---|---|---|---|---|
| client_id | 필수 | string | 10 | 고객사 아이디 (고객사아이디 또는 고객사그룹아이디) |
| client_type | 필수 | string | 10 |
고객사 유형 (1:고객사아이디, 2:고객사그룹아이디) *O2O 서비스는 "1:고객사아이디" 고정 |
| req_ymd | 필수 | string | 10 | (조회)요청 일자 (예: 2021-09-29) |
| pgcode | string | 10 |
결제수단 코드 (5. 결제수단 & 오류코드 참조) *결제수단 코드가 없는 경우, 전체 결제수단의 정산 내역을 응답합니다. |
응답 데이터
처리 성공
Content-Type 은 text/csv, charset 은 UTF-8 입니다.
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| 헤더 | |||
| tot_cnt | number | (조회)총 수 | |
| 데이터 | |||
| sttl_date | string | 10 | (PG)정산 일자 (YYYY-MM-DD) |
| tx_date | string | 10 |
(PG)거래 일자 (YYYY-MM-DD) *승인일자 또는 취소일자 또는 부분취소일자를 의미하며, (PG)거래 상태를 토대로 구분 가능합니다. |
| tx_state | number | 거래 상태(1: 결제, 2: 취소, 3: 부분 취소) | |
| pgcode | string | 10 | 결제수단 코드(5. 결제수단 & 오류코드 참조) |
| user_id | string | 50 | 고객사 사용자(회원) 아이디 |
| tid | string | 50 | 거래 번호 |
| order_no | string | 50 | (고객사)주문번호 |
| tx_amt | number |
거래 금액 *거래 상태가 취소, 부분 취소 상태의 경우에는 마이너스 금액으로 응답 |
|
| sttl_amt | number |
정산 금액 *거래 상태가 취소, 부분 취소 상태의 경우에는 마이너스 금액으로 응답 |
|
| clnt_fee | number |
고객사 수수료 *고객사 거래에 부과되는 PG 수수료 |
|
| diff_adj_yn | string | 1 | 차액 정산 여부 (Y: 차액 정산, N: 일반 정산) |
HTTP 1.1 200 OK
tot_cnt
3
sttl_date,tx_date,tx_state,pgcode,user_id,tid,order_no,tx_amt,sttl_amt,clnt_fee,diff_adj_yn
2021-10-29,2021-10-28,1,creditcard,test01,tpay_test202110291723360001,1234567890,1000,900,10,N
2021-10-29,2021-10-28,2,creditcard,test02,tpay_test202110291723360003,1234567891,-1000,-950,-10,N
2021-10-29,2021-10-28,1,creditcard,test03,tpay_test202110291723360004,1234567892,1000,900,10,N
지급 대행 고객사 서브몰 등록 요청
고객사에서 PG로 서브몰 등록 요청을 하면 PG에서 연계시스템(펌뱅킹)에 예금주 계좌조회 API 호출하여 계좌번호를 검증 후 고객사 하위 서브몰을 등록합니다.
API 요청
| URL | HTTP 메서드 | HTTP 헤더 | 키 유형 |
|---|---|---|---|
| /v1.0/sttl-prcy/submall2 | POST | Authorization: SPGKEY {API Key} | payment |
요청 데이터
| 파라미터 | 필수 여부 | 자료형 | 크기 | 설명 |
|---|---|---|---|---|
| client_id | 필수 | string | 10 | 고객사 아이디 |
| param_ispt_hash | 필수 | string | 1000 |
파라미터 검증 해시 *고객사 요청 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256(client_id + 정산 API Key)" 조합으로 생성된다. |
| list | JSON Array |
최대 개수는 지급대행관리정보의 연동최대건수 컬럼 값이 max *고객사 별로 지급대행 관리정보 table의 연동최대건수 컬럼 값이 최대 요청 건수 |
||
| req_type | 필수 | number | 1:등록 2:갱신 3:만료 | |
| submall_id | 필수 | string | 40 | 서브몰 아이디 |
| bizr_type_cd | 선택 | number | 1:법인사업자 2:개인사업자 3:개인 (req_type이 등록일때만 필수) | |
| bizr_no | 선택적 필수 | string | 13 | 사업자 번호 (req_type이 등록일때만 필수) |
| submall_frnm | 선택적 필수 | string | 50 | 서브몰 상호명(req_type이 등록일때만 필수) |
| prsdtnm | 선택적 필수 | string | 20 | 대표자명(req_type이 등록일때만 필수) |
| dpstr | 선택적 필수 | string | 200 | 예금주명(req_type이 등록일때만 필수) |
| bank_cd | 선택적 필수 | string | 3 | 은행 코드(req_type이 등록일때만 필수) |
| acct_no | 선택적 필수 | string | 16 | 계좌번호(req_type이 등록일때만 필수) |
| chrgr_cntc | 선택적 필수 | string | 13 | 담당자연락처(req_type이 등록일때만 필수) |
응답 데이터
처리 성공
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| ret_code | number | 응답 코드 | |
| ret_msg | string | 100 | 응답 메시지 |
| list | JSON Array | ||
| req_type | number | 요청 유형 | |
| submall_id | string | 40 | 서브몰 아이디 |
| bizr_type_cd | number | 1:법인사업자 2:개인사업자 3:개인 | |
| bizr_no | string | 13 | 사업자 번호 |
| submall_frnm | string | 50 | 서브몰 상호명 |
| prsdtnm | string | 20 | 대표자명 |
| dpstr | string | 200 | 예금주명 |
| bank_cd | string | 3 | 은행코드 |
| acct_no | string | 16 | 계좌번호 |
| chrgr_cntc | string | 13 | 담당자연락처 |
| sbm_reg_ret_code | number | 서브몰 등록 결과 코드 | |
| sbm_reg_ret_msg | string | 100 | 서브몰 등록 결과 메시지 |
처리 실패
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| ret_code | number | 응답 코드 | |
| ret_msg | string | 100 | 응답 메시지 |
HTTP 1.1 200 OK
{
"ret_code": 0,
"ret_msg": "OK",
"client_id": "ddangyo001",
"list": [
{
"req_type": 1,
"submall_id": "sbmA0001",
"bizr_no": "990012232",
"submall_frnm": "테스트",
"prsdtnm": "홍길동",
"dpstr": "홍길동",
"bank_cd": "088",
"acct_no": "1233333342",
"chrgr_cntc": "01047483948",
"sbm_reg_ret_code": 0,
"sbm_reg_ret_msg": "서브몰 처리가 완료되었습니다."
},
{
"req_type": 2,
"submall_id": "sbmA0002",
"bizr_no": "2323211122",
"submall_frnm": "테스트",
"prsdtnm": "대표자명",
"dpstr": "예금주",
"bank_cd": "088",
"acct_no": "1233333342",
"chrgr_cntc": "01047483948",
"sbm_reg_ret_code": 0,
"sbm_reg_ret_msg": "서브몰 처리가 완료되었습니다."
},
{
"req_type": 1,
"submall_id": "sbmA0001",
"bizr_no": "990012232",
"submall_frnm": "테스트",
"prsdtnm": "대표자명",
"dpstr": "예금주",
"bank_cd": "088",
"acct_no": "1233333342",
"chrgr_cntc": "01047483948",
"sbm_reg_ret_code": 6020,
"sbm_reg_ret_msg": "지급대행 서브몰 등록 요청 에러"
},
{
"req_type": 3,
"submall_id": "sbmA0003",
"bizr_no": "990012232",
"submall_frnm": "테스트",
"prsdtnm": "대표자명",
"dpstr": "예금주",
"bank_cd": "088",
"acct_no": "1233333342",
"chrgr_cntc": "01047483948",
"sbm_reg_ret_code": 0,
"sbm_reg_ret_msg": "서브몰 처리가 완료되었습니다."
}
]
}
HTTP 1.1 401 Unauthorized
{
"ret_code": 6020
"ret_msg": "지급대행 서브몰 등록 요청 에러"
}
지급 대행 고객사 지급 데이터 등록
고객사에서 지급 데이터 등록을 요청하면 고객사 별로 등록된 서브몰을 검증하고, 고객사 별로 잔액을 체크하여 지급 데이터를 등록합니다.
API 요청
| URL | HTTP 메서드 | HTTP 헤더 | 키 유형 |
|---|---|---|---|
| /v1.0/sttl-prcy/sttldata | POST | Authorization: SPGKEY {API Key} | payment |
요청 데이터
| 파라미터 | 필수 여부 | 자료형 | 크기 | 설명 |
|---|---|---|---|---|
| client_id | 필수 | string | 10 | 고객사 아이디 |
| param_ispt_hash | 필수 | string | 1000 |
파라미터 검증 해시 *고객사 요청 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256(client_id + 정산 API Key)" 조합으로 생성된다. |
| list | JSON Array |
최대 개수는 지급대행관리정보의 연동최대건수 컬럼 값이 max *고객사 별로 지급대행 관리정보 table의 연동최대건수 컬럼 값이 최대 요청 건수 |
||
| submall_id | 필수 | string | 40 | 서브몰 아이디 |
| sttl_prcy_clf | 필수 | number | 지급대행구분(1:고객사지급대행 , 2:중계사지급대행, 3:대리점, 4:GID, 5:서브몰) | |
| sttl_ymd | 필수 | string | 8 | 지급 일자 |
| sttl_tm | 필수 | string | 6 | 지급 시간 |
| stttl_req_amt | 필수 | number | 지급 요청 금액 |
응답 데이터
처리 성공
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| ret_code | number | 응답 코드 | |
| ret_msg | string | 100 | 응답 메시지 |
처리 실패
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| ret_code | number | 응답 코드 | |
| ret_msg | string | 100 | 응답 메시지 |
HTTP 1.1 200 OK
{
"ret_code": 0,
"ret_msg": "OK",
}
HTTP 1.1 401 Unauthorized
{
"ret_code": 998,
"ret_msg": "client id is missing or incorrect."
}
지급 대행 고객사 지급 데이터 정보 조회
고객사의 지급 데이터 등록 정보를 조회하는 조회 용 API 입니다.
API 요청
| URL | HTTP 메서드 | HTTP 헤더 | 키 유형 |
|---|---|---|---|
| /v1.0/sttl-prcy/sttldata-inqry | POST | Authorization: SPGKEY {API Key} | payment |
요청 데이터
| 파라미터 | 필수 여부 | 자료형 | 크기 | 설명 |
|---|---|---|---|---|
| client_id | 필수 | string | 10 | 고객사 아이디 |
| submall_id | 필수 | string | 40 | 서브몰 아이디 |
| sttl_req_ymd | 선택 | string | 8 | 지급요청일 |
| param_ispt_hash | 필수 | string | 1000 |
파라미터 검증 해시 *고객사 요청 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256(client_id + 정산 API Key)" 조합으로 생성된다. |
응답 데이터
처리 성공
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| ret_code | number | 응답 코드 | |
| ret_msg | string | 100 | 응답 메시지 |
| total_count | number | (응답 결과)총 수 | |
| client_id | string | 10 | 고객사 아이디 |
| submall_id | string | 40 | 서브몰 아이디 |
| list | JSON Array |
||
| sttl_req_seq | number | 요청순번 | |
| sttl_prcy_clf | number | 지급대행구분(1:고객사지급대행 , 2:중계사지급대행, 3:대리점, 4:GID, 5:서브몰) | |
| sttl_req_ymd | string | 8 | 지급 요청일자 |
| sttl_ymd | string | 8 | 지급일자 |
| sttl_tm | string | 6 | 지급시간 |
| stttl_req_amt | number | 지급 요청 금액 | |
| sttl_proc_stat | number | 지급 처리 상태(1:지급전 , 2:고객사확정, 3:지급확정 , 4:지급완료 , 5.지급실패) |
처리 실패
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| ret_code | number | 응답 코드 | |
| ret_msg | string | 100 | 응답 메시지 |
HTTP 1.1 200 OK
{
"ret_code": 0,
"ret_msg": "OK",
"total_count": 2,
"client_id": "ci1232562345",
"submall_id": "submall123",
“list”:[
{
“sttl_req_seq” : 1
"sttl_prcy_clf ": 1,
"sttl_req_ymd ": “20240107”,
"sttl_tm": "20240201”,
"sttl_req_tm": "193000”,
"stttl_req_amt": 1000000,
"sttl_proc_stat": “1”
},
{
“sttl_req_seq” : 1
"sttl_prcy_clf ": 1,
"sttl_req_ymd ": “20240109”,
"sttl_tm": "20240201”,
"sttl_req_tm": "203000”,
"stttl_req_amt": 190000,
"sttl_proc_stat": “2”
}
]
}
HTTP 1.1 401 Unauthorized
{
"ret_code": 998,
"ret_msg": "client id is missing or incorrect."
}
지급 대행 고객사 서브몰 금액 지급 요청
고객사에서 서브몰 금액 지급 요청을 하면 지급처리상태를 ‘고객사담당자 지급확정’ 으로 변경한다.
API 요청
| URL | HTTP 메서드 | HTTP 헤더 | 키 유형 |
|---|---|---|---|
| /v1.0/sttl-prcy/amtsttl | POST | Authorization: SPGKEY {API Key} | payment |
요청 데이터
| 파라미터 | 필수 여부 | 자료형 | 크기 | 설명 |
|---|---|---|---|---|
| client_id | 필수 | string | 10 | 고객사 아이디 |
| submall_id | 필수 | string | 40 | 서브몰 아이디 |
| sttl_req_ymd | 필수 | string | 8 | 지급 요청일 |
| param_ispt_hash | 필수 | string | 1000 |
파라미터 검증 해시 *고객사 요청 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256(client_id + sttl_req_ymd + 정산 API Key)" 조합으로 생성된다. |
응답 데이터
처리 성공
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| ret_code | number | 응답 코드 | |
| ret_msg | string | 100 | 응답 메시지 |
| total_count | number | 처리건수 |
처리 실패
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| ret_code | number | 응답 코드 | |
| ret_msg | string | 100 | 응답 메시지 |
HTTP 1.1 200 OK
{
"ret_code": 0,
"ret_msg": "OK",
“total_count”: 2
}
HTTP 1.1 401 Unauthorized
{
"ret_code": 998,
"ret_msg": "client id is missing or incorrect."
}
지급 대행 환불 요청
고객사에서 환불 요청을 하면 잔액을 체크하여 환불요청 데이터를 등록하는 API 기능
API 요청
| URL | HTTP 메서드 | HTTP 헤더 | 키 유형 |
|---|---|---|---|
| v1.0/sttl-prcy/pybkreq | POST | Authorization: SPGKEY {API Key} | payment |
요청 데이터
| 파라미터 | 필수 여부 | 자료형 | 크기 | 설명 |
|---|---|---|---|---|
| client_id | 필수 | string | 10 | 고객사 아이디 |
| param_ispt_hash | 필수 | string | 1000 |
파라미터 검증 해시 *고객사 요청 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256(client_id + 정산 API Key)" 조합으로 생성된다. |
| list | JSON Array |
최대 개수는 지급대행관리정보의 연동최대건수 컬럼 값이 max *고객사 별로 지급대행 관리정보 table의 연동최대건수 컬럼 값이 최대 요청 건수 |
||
| submall_id | 필수 | string | 40 | 서브몰 아이디 |
| sttl_pybk_req_ymd | 필수 | string | 8 | 환불요청일자 |
| sttl_pybk_amt | 필수 | number | 환불요청금액 | |
| pybk_rsn | 필수 | string | 200 | 환불 요청 사유 |
응답 데이터
처리 성공
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| ret_code | number | 응답 코드 | |
| ret_msg | string | 100 | 응답 메시지 |
처리 실패
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| ret_code | number | 응답 코드 | |
| ret_msg | string | 100 | 응답 메시지 |
HTTP 1.1 200 OK
{
"ret_code": 0,
"ret_msg": "OK",
}
HTTP 1.1 401 Unauthorized
{
"ret_code": 998,
"ret_msg": "client id is missing or incorrect."
}
지급 대행 환불 데이터 확정
고객사에서 환불을 요청한 데이터에 대해서 지급상태코드를 고객사 확정으로 상태 변경 하는 API
API 요청
| URL | HTTP 메서드 | HTTP 헤더 | 키 유형 |
|---|---|---|---|
| /v1.0/sttl-prcy/pybkdcsn | POST | Authorization: SPGKEY {API Key} | payment |
요청 데이터
| 파라미터 | 필수 여부 | 자료형 | 크기 | 설명 |
|---|---|---|---|---|
| client_id | 필수 | string | 10 | 고객사 아이디 |
| submall_id | 필수 | string | 40 | 서브몰 아이디 |
| sttl_pybk_req_ymd | 필수 | string | 8 | 환불요청일자 |
| param_ispt_hash | 필수 | string | 1000 |
파라미터 검증 해시 *고객사 요청 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256(client_id + sttl_pybk_req_ymd + 정산 API Key)" 조합으로 생성된다. |
응답 데이터
처리 성공
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| ret_code | number | 응답 코드 | |
| ret_msg | string | 100 | 응답 메시지 |
처리 실패
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| ret_code | number | 응답 코드 | |
| ret_msg | string | 100 | 응답 메시지 |
HTTP 1.1 200 OK
{
"ret_code": 0,
"ret_msg": "OK",
}
HTTP 1.1 401 Unauthorized
{
"ret_code": 998,
"ret_msg": "client id is missing or incorrect."
}
지급 대행 환불 취소 요청
지급 대행에 등록된 환불 데이터 중 지급 이전 데이터에 대하여 환불 취소 요청하는 API
API 요청
| URL | HTTP 메서드 | HTTP 헤더 | 키 유형 |
|---|---|---|---|
| /v1.0/sttl-prcy/pybkcncl | POST | Authorization: SPGKEY {API Key} | payment |
요청 데이터
| 파라미터 | 필수 여부 | 자료형 | 크기 | 설명 |
|---|---|---|---|---|
| client_id | 필수 | string | 10 | 고객사 아이디 |
| submall_id | 필수 | string | 40 | 서브몰 아이디 |
| sttl_pybk_req_ymd | 필수 | string | 8 | 환불요청일자 |
| param_ispt_hash | 필수 | string | 1000 |
파라미터 검증 해시 *고객사 요청 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256(client_id + submall_id + sttl_pybk_req_ymd 정산 API Key)" 조합으로 생성된다. |
응답 데이터
처리 성공
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| ret_code | number | 응답 코드 | |
| ret_msg | string | 100 | 응답 메시지 |
| total_count | number | 처리건수 |
처리 실패
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| ret_code | number | 응답 코드 | |
| ret_msg | string | 100 | 응답 메시지 |
HTTP 1.1 200 OK
{
"ret_code": 0,
"ret_msg": "OK",
}
HTTP 1.1 401 Unauthorized
{
"ret_code": 998,
"ret_msg": "client id is missing or incorrect."
}
지급 대행 송금 결과 조회
지급 대행 송금 및 환불 결과에 대한 조회 API 입니다.
API 요청
| URL | HTTP 메서드 | HTTP 헤더 | 키 유형 |
|---|---|---|---|
| /v1.0/sttl-prcy/rmtrslt | POST | Authorization: SPGKEY {API Key} | payment |
요청 데이터
| 파라미터 | 필수 여부 | 자료형 | 크기 | 설명 |
|---|---|---|---|---|
| rslt_typ | 필수 | string | 1 | 결과 유형 (“1” : 지급결과 , “2” : 환불결과) |
| client_id | 필수 | string | 10 | 고객사 아이디 |
| submall_id | 필수 | string | 40 | 서브몰 아이디 |
| sttl_st_dt | 필수 | string | 8 | 지급 시작일[YYYYMMDD] |
| sttl_ed_dt | 필수 | string | 8 | 지급 종료일[YYYYMMDD] |
| param_ispt_hash | 필수 | string | 1000 |
파라미터 검증 해시 *고객사 요청 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256(client_id + submall_id + 정산 API Key)" 조합으로 생성된다. |
응답 데이터
처리 성공
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| ret_code | number | 응답 코드 | |
| ret_msg | string | 100 | 응답 메시지 |
| typ_clf | string | 1 | 유형 구분 (“1” : 지급결과 , “2” : 환불결과) |
| client_id | string | 10 | 고객사아이디 |
| submall_id | string | 40 | 서브몰 아이디 |
| bizr_no | string | 13 | 사업자 번호 |
| submall_frnm | string | 50 | 서브몰 상호명 |
| prsdtnm | string | 20 | 대표자명 |
| dpstr | string | 200 | 예금주명 |
| bank_cd | string | 3 | 은행 코드 |
| acct_no | string | 16 | 계좌번호 |
| list | JSON Array |
||
| sttl_ymd | string | 8 | 지급 일자 |
| sttl_amt | number | 지급액 | |
| sttl_proc_stat | string | 2 | 지급 처리 상태(4:지급완료 , 5.지급실패) |
| sttl_res_cd | string | 20 | 지급결과코드 |
| sttl_res_msg | string | 200 | 지급결과메시지 |
처리 실패
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| ret_code | number | 응답 코드 | |
| ret_msg | string | 100 | 응답 메시지 |
HTTP 1.1 200 OK
{
"ret_code": 0,
"ret_msg": "OK",
"total_count": 4,
"typ_clf": "1",
"client_id": "ddangyo001",
"submall_id": "sbm18",
"bizr_no": "1299918189",
"submall_frnm": "테스트",
"prsdtnm": "홍길동",
"dpstr": "홍길동",
"bank_cd": "088",
"acct_no": "100033295469",
"list": [
{
"sttl_ymd": "2024-03-13",
"sttl_amt": 120000,
"sttl_proc_stat": 4,
"sttl_res_cd": "0000",
"sttl_res_msg": "지급대행 해당 지급 송금이 완료되었습니다."
},
{
"sttl_ymd": "2024-03-13",
"sttl_amt": 91200,
"sttl_proc_stat": 4,
"sttl_res_cd": "0000",
"sttl_res_msg": "지급대행 해당 지급 송금이 완료되었습니다."
},
{
"sttl_ymd": "2024-03-20",
"sttl_amt": 200000,
"sttl_proc_stat": 4,
"sttl_res_cd": "0000",
"sttl_res_msg": "지급대행 해당 지급 송금이 완료되었습니다."
},
{
"sttl_ymd": "2024-03-20",
"sttl_amt": 120000,
"sttl_proc_stat": 4,
"sttl_res_cd": "0000",
"sttl_res_msg": "지급대행 해당 지급 송금이 완료되었습니다."
}
]
}
HTTP 1.1 401 Unauthorized
{
"ret_code": 998,
"ret_msg": "client id is missing or incorrect."
}
지급 대행 잔액 조회
지급 대행 고객사 별 잔액을 조회하는 API입니다.
API 요청
| URL | HTTP 메서드 | HTTP 헤더 | 키 유형 |
|---|---|---|---|
| /v1.0/sttl-prcy/blnc | POST | Authorization: SPGKEY {API Key} | payment |
요청 데이터
| 파라미터 | 필수 여부 | 자료형 | 크기 | 설명 |
|---|---|---|---|---|
| client_id | 필수 | string | 10 | 고객사 아이디 |
| stdr_ymd | 필수 | string | 8 | 기준일자[YYYYMMDD] |
| tx_st_ymd | 필수 | string | 8 | 거래 시작일[YYYYMMDD] |
| tx_ed_ymd | 필수 | string | 8 | 거래 종료일[YYYYMMDD] |
| param_ispt_hash | 필수 | string | 1000 |
파라미터 검증 해시 *고객사 요청 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256(client_id + stdr_ymd + 정산 API Key)" 조합으로 생성된다. |
응답 데이터
처리 성공
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| ret_code | number | 응답 코드 | |
| ret_msg | string | 100 | 응답 메시지 |
| client_id | string | 10 | 고객사 아이디 |
| stdr_ymd | string | 8 | 기준일자[YYYYMMDD] |
| tx_trm | string | 50 | 거래 기간[YYYYMMDDYYYYMMDD] |
| bizr_no | string | 13 | 사업자 번호 |
| blnc_amt | number | 잔액 |
처리 실패
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| ret_code | number | 응답 코드 | |
| ret_msg | string | 100 | 응답 메시지 |
HTTP 1.1 200 OK
{
"ret_code": 0,
"ret_msg": "OK",
"client_id": "ddangyo001",
"stdr_ymd ": "20240501",
"bizr_no": "1022321322",
"blnc_amt": "0"
}
HTTP 1.1 401 Unauthorized
{
"ret_code": 998,
"ret_msg": "client id is missing or incorrect."
}
결제수단
결제수단
| 결제수단 코드 | 결제수단 코드 설명 |
|---|---|
| card | 일반 신용/체크카드 |
| shpaycard | 전용페이 신용/체크카드 |
| shpaybank | 전용페이 계좌이체 |
| zeropay | 제로페이 |
| seoulpay | 서울페이 |