가상계좌

개발 전 확인이 필요한 공통적인 가이드

소개

고객사 API 목록

고객사 API 목록
API 구분 API 리소스 경로
결제 요청 POSTv1.0/payments/request
결제 승인 POSTv1.0/payments/confirm
결제 취소 POSTv1.0/payments/cancel
거래 확인서 GETv1.0/receipt/info/{tid}
결제 거래정보 조회 GETv1.0/payments/confirm-info
PG약관 조회 GETv1.0/payments/info/terms-info-list
가상계좌 결제 요청 POSTv1.0/virtualAccount/requestVaPayment
가상계좌 환불 요청 POSTv1.0/virtualAccount/requestVaPaymentBack
가상계좌 대출 연계 결제 요청 POSTv1.0/virtualAccount/requestLoanPayment
가상계좌 입금 조회 POSTv1.0/virtualAccount/requestVaDpstInqry
BIZBANK 결제 대상 조회 POSTv1.0/virtualAccount/bizbankPayTargetInqry

*고객사 API의 미디어 타입은 "content-type application/json" 입니다.

PG API 목록

API 구분 API 리소스 경로
가상계좌 결제 요청 POSTv1.0/virtualAccount/requestVaPayment
가상계좌 환불 요청 POSTv1.0/virtualAccount/requestVaPaymentBack
가상계좌 대출 연계 결제 요청 POSTv1.0/virtualAccount/requestLoanPayment
가상계좌 입금 조회 POSTv1.0/virtualAccount/requestVaDpstInqry
여신약정한도보유여부조회 POSTv1.0/virtualAccount/requestLoanLimitYnInquiry
건별여신잔액정보조회 POSTv1.0/virtualAccount/requestLoanBalanceInquiry
정산 내역 조회 GET1.0/sttllist

API의 미디어 타입은 "content-type application/json" 입니다.

통신 규칙

표준 RESTful-API 통신 방식을 따르며, HTTP 1.1 Specification을 준수합니다.

HTTP Method, Resource URL을 요청하면, JSON 데이터를 응답합니다.

가상계좌 결제 흐름

  1. 고객사에서 PG로 결제 요청 API를 호출합니다.
  2. PG에서 고객사로 결제 요청 결과(인증토큰)가 전달됩니다.
  3. 이용자 입금 후 고객사에서 개발하여 고객사관리자에 등록한 입금통보API를 PG에서 호출하여 가상계좌입금통보정보를 전달합니다.
  4. 고객사에서 입금된 결제내역에 대한 환불 사유가 발생한 경우 가상계좌환불요청API를 호출하여 환불요청을 PG로 접수합니다.
    (담당자 확인 후 D+1영업일 환불, 계약사항에 따라 주기는 다를 수 있습니다.)
    * 호출방식이 아닌 실시간 통지 방식을 원하는 경우 웹훅(고객사에서 수신 API 구현 후 고객사관리자에서 URI 등록)방식으로 통지 가능 가능하며 담당자분을 통해 웹훅 연동정의서 별도 수신 바랍니다.
  5. 건별여신잔액정보조회 API 연동을 통해 상환잔액정보를 확인한다.

가상계좌 대출연계 결제 흐름

  1. 고객사에서 여신약정한도보유여부조회 API를 호출하여 약정한도보유 여부를 조회한다.
  2. 약정한도가 미 보유 시 거래 종료, 한도 보유 시 고객사에서 PG로 가상계좌 대출연계 결제(취소) 요청 API를 호출하여 거래정보를 전송 합니다.
  3. PG에서 고객사로 가상계좌 대출연계 결제(취소) 요청 결과가 전달됩니다.
  4. 고객사에서 가상계좌 입금조회 API를 호출하여 입금결과가 PG로 전달됩니다.
    * 호출방식이 아닌 실시간 통지 방식을 원하는 경우 웹훅(고객사에서 수신 API 구현 후 고객사관리자에서 URI 등록)방식으로 통지 가능 가능하며 담당자분을 통해 웹훅 연동정의서 별도 수신 바랍니다.
  5. 건별여신잔액정보조회 API 연동을 통해 상환잔액정보를 확인한다.

고객사 API 정의

결제 요청

고객사 결제 요청 용 API 입니다. 최소 승인 금액은 일반카드, 전용페이카드 100원, 계좌이체 1원, 제로페이 1원이며, 해당 금액 미만의 결제 요청은 처리되지 않습니다. API 요청

API 요청

API 요청
URL HTTP 메서드 HTTP 헤더 키 유형
v1.0/payments/request POST Authorization: SPGKEY {API Key} payment

요청 데이터

요청 데이터
파라미터 필수 여부 자료형 크기 설명
공통필수영역
pgcode 필수 string 10 결제수단 코드(5. 결제수단 & 오류코드 참조)
client_id 필수 string 10 고객사 아이디
user_id 필수 string 50 고객사 사용자(회원) 아이디(이메일, 영문 및 숫자 가능)
user_name 필수 string 20 고객사 사용자(회원) 명
order_no 필수 string 50 고객사 주문번호
pay_type 필수 number   결제 유형 (1: 단일 결제, 2: 복합 일반, 3: 복합 전용)
device_type 필수 number   (결제 요청)기기 유형 (1: 모바일, 2: PC)
amount 필수 number   (결제 상품)금액
*(결제 요청) 컵반환 보증금이 있는 경우 상품금액에 더하여 호출합니다.
예) 총금액 10,000원, 컵반환 보증금 300원
-> amount : 10,300원으로 설정
*(결제 요청) 선불전자결제수단 금액이 있는 경우 상품금액에서 제외하여 호출합니다.
예) 총금액 10,000원, 선불전자결제 : 2,000원
-> amount : 8,000원으로 설정
product_name 필수 string 50 (결제)상품 명
return_url 필수 string 255 결제 인증 결과 수신 및 결제 승인 API를 호출하는 고객사 URL
cancel_url 필수 string 255 결제 취소 시 이동하는 고객사 URL
fail_url 필수 string 255 결제 실패 시 이동하는 고객사 URL
param_ispt_hash 필수 string 1000 파라메터 검증 해시
*고객사 요청 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256(client_id + user_id + order_no + pay_type + amount + payment API Key)" 조합으로 생성된다.
공통부가영역
user_ci 선택적 필수 string 88 고객사 사용자 CI(Connecting information)
*제로페이 최초 사용자를 위한 본인인증 시, 고객사에서 전달한 user_ci, mobile_no와 휴대폰 본인인증 결과가 다를 경우, 제로페이 회원 등록이 불가합니다.
*지역화폐 단일 결제 요청 시 필수 값 입니다.
*결제수단이 shpay일 때 필수 값 입니다.
*핏콜라보 결제 요청 시 필수 값 입니다.
taxfree_amount   number   비과세 금액
*(결제 요청)금액이 모두 비과세액인 경우, amount, taxfree_amount 모두 동일한 값을 설정하여야 합니다.
예) (결제 요청)금액 1,000원 모두 비과세 금액인 경우
→ amount, taxfree_amount 모두 1,000원 설정
*(결제 요청)금액 중 일부가 비과세 금액인 경우, 해당 금액만 taxfree_amount에 설정하여야 합니다.
예) (결제 요청)금액 1,000원중 비과세 금액이 100원인 경우
→ amount 1,000원, taxfree_amount 100원 설정
tax_amount   number   부가세 금액
*요청 파라미터 값이 없으면,
((amount - taxfree_amount - cup_return_deposit) / 11)
계산식을 적용, 소수점 이하 반올림으로 자동 계산합니다
cup_return_deposit   number   컵반환보증금
card_cpny_cd 선택적 필수 string   카드사 코드
* 6.1 카드사 코드 참조
* 일반 신용카드 결제 시 고객사 화면에서 카드사를 선택하여
결제 요청시 필수 값 입니다.
install_month   string 2 할부 개월수(00~12)
* 다이렉트 결제 요청시 필수 값 입니다.
*핏콜라보 결제 요청 시 필수 값 입니다.
inst_type 선택적 필수 number   할부 타입
1: 일반,
2: 무이자,
3: 청구할인5%일반
4: 청구할인5%무이자
5: 청구할인7%일반
6: 청구할인7%무이자
7: 청구할인10%일반
8: 청구할인 10%무이자
*핏콜라보 결제 요청 시 필수 값 입니다.
email_flag   string 1 (결제)메일 수신 여부 (Y: 사용, N: 미사용)
*기본 값은 "N: 미사용" 입니다.
email_addr   string 50 (결제)메일 수신 주소
        (결제)메일 수신 주소*email_flag 'Y'인 경우에만 사용합니다.
main_color   string 6 PG 결제 화면 메인 색상 코드
*기본값은 FFFFFF
point_color   string 6 PG 결제 화면 포인트 색상 코드
*기본값은 5379FF
custom_parameter   string 1000 고객사 전용 값을 의미하며, 암호화를 권장합니다.
*결제 요청 시 고객사에서 필요한 고객, 주문, 기타 등 정보를 전달하면, 그 값 그대로 고객사 return_url로 반환합니다.
mobile_no 선택적 필수 string 11 사용자 휴대폰 번호
*지역화폐 단일 결제 요청 시 필수 값 입니다.
*가상계좌일 때 선택 값 입니다.
card_purpost_type 선택적 필수 number   카드 용도 유형 (1: 일반 신용카드, 2: 프로모션 일반 신용카드, 3: 비인증 신용카드, 4: 환금성 신용카드)
*기본값은 1
app_return_url 선택적 필수 string   일반 신용카드(ISP) 결제 이후 이동할 고객사 앱 스키마 정보
*모바일 앱의 일반 신용카드 결제 요청 시 필수 값 입니다.
app_cancel_url 선택적 필수 string   일반 신용카드(ISP) 결제 진행 중단 시 이동할 고객사 앱 스키마 정보
*모바일 앱의 일반 신용카드 결제 요청 시 필수 값 입니다.
가상계좌전용
acct_key   string 18 계좌키 (결제수단이 가상계좌일 때 고객사에서 부여)
* 고정가상계좌를 사용하는 고객과 매칭시킨 계좌의 고유한 키값입니다. 특정고객에게 같은 가상계좌를 다시 발급하려면 처음 고정 가상계좌를 발급할 때 사용했던 계좌키를 설정해주세요. 최대갈이는 18자입니다

응답 데이터

처리 성공

처리 성공
파라미터 자료형 크기 설명
ret_code number   응답 코드
ret_msg string 100 응답 메시지
redirect_url string 1000 (결제용)웹 화면
*PG 웹 화면 접근 후 redirect_url token은 다시 사용할 수 없습니다.

처리 실패

처리 실패
파라미터 자료형 크기 설명
ret_code number   응답 코드
ret_msg string 100 응답 메시지 
HTTP 1.1 200 OK
{
"ret_code": 0,
"ret_msg": "OK",
"redirect_url": "https://devpayapispg.shinhan.com/pgsvc/pay?token=2021083110239001duf.." // (결제 인증용)웹 화면
}

                                
HTTP 1.1 401 Unauthorized
{
    "ret_code": 998,
    "ret_msg": "token is missing or incorrect."
}

가상계좌 결제 요청

고객사에서 가상계좌 결제를 요청합니다.

가상계좌 입금요청내역과 가상계좌를 발번하여 응답 내용으로 전송합니다.

API 요청

URL HTTP 메서드 HTTP 헤더 키 유형
v1.0/virtualAccount/requestVaPayment POST Authorization: “SPGKEY” + {API Key}  

요청 데이터

요청 데이터
파라미터 필수 여부 자료형 크기 설명
client_id 필수 String 20 고객사 아이디(신한PG로부터 부여받은 고객사 식별아이디)
ordr_no 필수 String 50 주문번호
ordr_no 필수 String 50 주문번호
acct_key   String 18 계좌키
* 고정가상계좌를 사용하는 고객과 매칭시킨 계좌의 고유한 키값입니다. 특정고객에게 같은 가상계좌를 다시 발급하려면 처음 고정 가상계좌를 발급할 때 사용했던 계좌키를 설정해주세요. 최대길이는 18자입니다
* 대리점방식을 사용하는 고객사의 경우 대리점번호를 설정해주세요
gods_nm 필수 String 100 상품명
gods_qty 필수 Number   수량
pay_amt 필수 Number   결제금액
email_addr   String 50 고객이메일
고객의 이메일 주소입니다. 결제 결과를 알려줄 때 사용합니다
user_name 필수 String 20 사용자명
mobile_no   String 13 고객휴대폰번호
고객의 휴대폰 번호입니다. 가상계좌 입금 안내가 전송되는 번호 입니다.
cash_rcpt_pub_type   number   현금 영수증 발행 유형 (1: 소득공제용, 2: 지출증빙용)
*해당 요청 파라미터와 현금 영수증 발행 번호 유형, 현금 영수증 발행 번호 파라미터들의 값이 있으면 전용페이 계좌 결제 승인 이후 해당 정보들로 현금영수증을 발행 처리합니다. 만약 해당 요청 값들이 없으면 자진 발급번호로 발행 처리합니다.
cash_rcpt_pub_no_type   number   현금 영수증 발행 번호 유형 (1: 휴대폰번호, 2: 사업자번호, 3: 자진발급 등 기타)
*해당 요청 파라미터와 현금 영수증 발행 유형, 현금 영수증 발행 번호 파라미터들의 값이 있으면 전용페이 계좌 결제 승인 이후 해당 정보들로 현금영수증을 발행 처리합니다. 만약 해당 요청 값들이 없으면 자진 발급번호로 발행 처리합니다.
taxfree_amount   number   비과세 금액
*(결제 요청)금액이 모두 비과세액인 경우, amount, taxfree_amount 모두 동일한 값을 설정하여야 합니다.
예) (결제 요청)금액 1,000원 모두 비과세 금액인 경우
→ amount, taxfree_amount 모두 1,000원 설정
*(결제 요청)금액 중 일부가 비과세 금액인 경우, 해당 금액만 taxfree_amount에 설정하여야 합니다.
예) (결제 요청)금액 1,000원중 비과세 금액이 100원인 경우
→ amount 1,000원, taxfree_amount 100원 설정
tax_amount   number   부가세 금액
*요청 파라미터 값이 없으면,
((amount - taxfree_amount - cup_return_deposit) / 11)
계산식을 적용, 소수점 이하 반올림으로 자동 계산합니다.
valid_hours 옵션 number   유효시간
* 가상계좌 발급 시점으로부터 유효한 시간 범위입니다.
설정한 유효시간 안에 구매자가 입금을 하지 않으면 주문은 취소됩니다. 가상계좌 발급 후 일정시간 뒤에 반납됩니다. 예를 들어 가상계좌 발급 후 24시간내에 입금해야 한다면 24로 설정합니다. 값을 넣지 않으면 기본값 168 시간(7일)으로 설정됩니다. 설정할 수 있는 최대값은 720 시간(30일) 입니다. 유효시간과 유효일자 중 하나만 사용할 수 있습니다.
lmt_day 옵션 String   유효일자
* 입금 기한을 날자로 특정합니다. 지정한 시점에 가상계좌가 반납됩니다. 예를 들어 입금시간을 주문 후 3일 뒤 자정 과 같이 특정 시점으로 설정하고 싶을 때 20241010000000 와 같이 설정한다.
escr_yn 필수 Char 1 에스크로여부(N:아니오, Y:예)
adj_req_ymd 옵션 String   정산요청일자
pay_hash 필수 String 1000 파라메터 검증 해시
*고객사 요청 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256( client_id + ordr_no + payment API Key)" 조합으로 생성된다. 
{
    “client_id”: “c000000001”,
    “ordr_no”: “order123123”,
    "acct_key": "a45625x00000",
    "gods_nm": "테스트상품",
    "gods_qty": 100,
    "pay_amt": 1000000,
    “email_addr”: “test@test.co.kr”,
    “mobile_no”: “01012341234”,
    “cash_rcpt_pub_type”:1
    “cash_rcpt_pub_no_type”:01012341234
    “valid_hours”:24
    “escr_yn”: “N”,
    “adj_req_ymd”: “20240310”,
    “pay_hash”: "dfhuoi892ashiozxui123…”
}

응답 데이터

처리 성공

처리 성공
파라미터 자료형 크기 설명
ret_code Number   응답 코드
ret_msg String 100 응답 메시지
authti_tkn String 50 인증 토큰
가상계좌 웹훅이 정상적인 요청인지 검증하는 값입니다. 이값이 가상계좌 웹훅 이벤트 본문으로 전송된 인증토큰과 같으면 정상적인 요청 입니다.
ordr_no String 50 고객사 거래번호
client_id String 20 고객사아이디
va_typ String 20 가상계좌타입
1(일반),2(고정)
bank_cd String 3 은행코드
va_no String 30 가상계좌번호
expr_tlml String 14 만료기한
20241010000000		 
HTTP 1.1 200 OK
{
    "ret_code": 0,
    "ret_msg": "결제 요청이 성공하였습니다.",
    “authti_tkn”: “A1946B873612”,
    “ordr_no”: “order123123”,
    “client_id”: “c000000001”,
    "va_typ": "a00000000",
    “bank_cd”:”086”
    "va_no": "0000000000000”
    "expr_tlmt": “20241010000000”
}

처리 실패

처리 실패
파라미터 자료형 크기 설명
ret_code Number   응답 코드
ret_msg String 100 응답 메시지 
HTTP 1.1 401 Unauthorized
{
    "ret_code": 999,
    "ret_msg": "결제 요청이 실패하였습니다."
}

통합결제창용 결제 요청

개인/법인용 통합결제창 결제 호출 용 API 입니다. 최소 승인 금액은 일반카드, 전용페이카드 100원, 계좌이체 1원이며, 해당 금액 미만의 결제 요청은 처리되지 않습니다.

API 요청

URL HTTP 메서드 HTTP 헤더 키 유형
v1.0/payments/request POST Authorization: SPGKEY {API Key} payment

요청 데이터

요청 데이터
파라미터 필수 여부 자료형 크기 설명
공통(개인/법인)필수영역
pgcode 필수 string 10 결제수단 코드(개인: selpay / 법인: bizselpay)
client_id 필수 string 10 고객사 아이디
user_id 필수 string 50 고객사 사용자(회원) 아이디(이메일, 영문 및 숫자 가능)
user_name 필수 string 20 고객사 사용자(회원) 명
order_no 필수 string 50 고객사 주문번호
pay_type 필수 number   결제 유형 (1: 단일 결제)
device_type 필수 number   기기 유형.
1: 모바일(개인),
2: PC(개인/법인)
amount 필수 number   금액
*컵반환 보증금이 있는 경우 상품금액에 더하여 호출합니다.
예) 총금액 10,000원, 컵반환 보증금 300원
-> amount : 10,300원으로 설정
법인대출연계에 사용될 때는
일시지급일때는 총구매금액(100%), 잔금지급일때는 지원신청금액(70%)
product_name 필수 string 50 (결제)상품 명
param_ispt_hash 필수 string 1000 파라메터 검증 해시
*고객사 요청 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256(client_id + user_id + order_no + pay_type + amount + payment API Key)" 조합으로 생성된다.
법인대출연계요청영역 (법인대출연계시 필수)
buyr_bizr_no 선택적 필수 string 10 구매자 사업자 번호
dpst_req_no 선택적 필수 string 8 입금요청번호
clnt_pay_clf_cd 선택적 필수 string 6 결제 구분
SGLPAY: 일시지급(선수금없음)
RMDPAY: 잔금지급(선수금대상)
req_amt 선택적 필수 number 13 지원신청금액(원)
대출금액으로 기본 70%
신한 은행 여신 기준에 맞춰 천원 단위로 절사 처리 필요
(로직 제공, 금액이 안 맞는 경우 처리결과 ‘F’ 리턴,
고객부담금에 나머지 금액 추가)
chrg_amt 선택적 필수 number 13 고객부담금액(원)
tot_tx_amt 선택적 필수 number 13 총구매금액(원)
pay_amt 선택적 필수 number 13 결제요청금액(원)
일시지급일때는 총구매금액(100%), 잔금지급일때는 지원신청금액(70%)
clnt_tx_clf_cd 선택적 필수 string 6 거래 구분 (고객사거래구분코드)
고객사결제구분코드 (GNR: 일반거래 / IMPL: 전용거래)
cncl_yn 선택적 필수 string 1 취소 여부
주문취소 건인 경우 취소 여부(‘Y’)와 PK정보(사업자 번호, 입금요청번호)만 전송
clnt_tx_ymd 선택적 필수 string 8 낙찰일 (고객사 거래일자)
seller_name 선택적 필수 string 20 판매사명
플랫폼이 판매사인 경우 플랫폼명
오픈마켓 : 판매자
email_addr   string 50 고객이메일
고객의 이메일 주소입니다. 결제 결과를 알려줄 때 사용합니다
mobile_no   string 13 고객휴대폰번호
고객의 휴대폰 번호입니다. 가상계좌 입금 안내가 전송되는 번호 입니다.
개인부가영역
taxfree_amount   number   비과세 금액
*금액이 모두 비과세액인 경우, amount, taxfree_amount 모두 동일한 값을 설정하여야 합니다.
예) 금액 1,000원 모두 비과세 금액인 경우
→ amount, taxfree_amount 모두 1,000원 설정
*금액 중 일부가 비과세 금액인 경우, 해당 금액만 taxfree_amount에 설정하여야 합니다.
예) (결제 요청)금액 1,000원중 비과세 금액이 100원인 경우
→ amount 1,000원, taxfree_amount 100원 설정
tax_amount   number   부가세 금액
*요청 파라미터 값이 없으면,
((amount - taxfree_amount - cup_return_deposit) / 11)
계산식을 적용, 소수점 이하 반올림으로 자동 계산합니다.
cup_return_deposit   number   컵반환보증금
email_flag   string 1 (결제)메일 수신 여부 (Y: 사용, N: 미사용)
*기본 값은 "N: 미사용" 입니다.
email_addr   string 50 (결제)메일 수신 주소
*email_flag 'Y'인 경우에만 사용합니다.
custom_parameter   string 1000 고객사 전용 값을 의미하며, 암호화를 권장합니다.
*결제 요청 시 고객사에서 필요한 고객, 주문, 기타 등 정보를 전달하면, 그 값 그대로 고객사 return_url로 반환합니다.
mobile_no   string 11 사용자 휴대폰 번호
card_purpost_type 선택적 필수 number   카드 용도 유형 (1: 일반 신용카드, 2: 프로모션 일반 신용카드, 3: 비인증 신용카드, 4: 환금성 신용카드)
*기본값은 1
통합결제창(개인)전용
user_ci 필수 string 88 고객사 사용자 CI(Connecting information)
main_color   string 6 PG 결제 화면 메인 색상 코드
*기본값은 FFFFFF
point_color   string 6 PG 결제 화면 포인트 색상 코드
*기본값은 5379FF
app_return_url 선택적 필수 string 100 일반 신용카드(ISP) 결제 이후 이동할 고객사 앱 스키마 정보
*모바일 앱의 일반 신용카드 결제 요청 시 필수 값 입니다.
return_url 필수 string 255 결제 인증 결과 수신 및 결제 승인 API를 호출하는 고객사 URL
cancel_url 필수 string 255 결제 취소 시 이동하는 고객사 URL
fail_url 필수 string 255 결제 실패 시 이동하는 고객사 URL
가상계좌(개인)전용
acct_key   string 18 계좌키 (결제수단이 가상계좌일 때 고객사에서 부여)
* 고정가상계좌를 사용하는 고객과 매칭시킨 계좌의 고유한 키값입니다. 특정고객에게 같은 가상계좌를 다시 발급하려면 처음 고정 가상계좌를 발급할 때 사용했던 계좌키를 설정해주세요. 최대갈이는 18자입니다 
◎ 개인용 통합결제창 결제를 요청하는 경우
{
    "pgcode": "selpay",
    "client_id": "o2o",
    "user_id": "test_01",
    "user_name": "테스터01",
    "order_no": "202108311259590001",
    "pay_type”: 1,    // 단일 결제
    "device_type": 1,
    "amount": 11000,
    "product_name": "테스트 상품",
    "return_url": "https://o2odev.shinhan.com/partner/pay/approval",
    "cancel_url": "https://o2odev.shinhan.com/partner/pay/cancel",
    "fail_url": "https://o2odev.shinhan.com/partner/pay/fail",
    “param_ispt_hash”:”821b7bf742abfb49c8e535ee9a0801c4e6cefe4d49c9c8209b8c54d5077082f8"
    "taxfree_amount": 0,
    "tax_amount": 90,
    "email_flag": "Y",
    "email_addr": "bae1222@payletter.com",
    "pay_hash": "dfhuoi892ashiozxui123…”,
    "custom_parameter": "asdfoxuoy12uyisadouydfouayiouf…",
    "card_purpost_type": 1,                  // 일반 신용카드는 필수 설정
    "app_return_url": "scheme://path",    // 모바일 앱 환경의 일반 신용카드는 필수 설정
    "app_cancel_url": "scheme://path",    // 모바일 앱 환경의 일반 신용카드는 필수 설정
    “cup_return_deposit”: “100”,         // 컵반환 보증금
    “card_cpny_cd”: “S005”,               // 고객사 화면에서 카드사를 선택하여 결제요청하는 경우 필수 설정
}
                                
◎ 법인용 통합결제창 결제를 요청하는 경우
{
    "pgcode": "bizselpay",
    "client_id": "o2o",
    "user_id": "test_01",
    "user_name": "테스터01",
    "order_no": "202108311259590001",
    "pay_type”: 1,             // 단일 결제
    "device_type": 2,         // 법인은 PC전용
    "amount": 11000,
    "taxfree_amount": 0,
    "tax_amount": 1000,
    "product_name": "테스트 상품",
    “param_ispt_hash”:”821b7bf742abfb49c8e535ee9a0801c4e6cefe4d49c9c8209b8c54d5077082f8"
    "email_flag": "Y",
    "email_addr": "bae1222@payletter.com",
    "pay_hash": "dfhuoi892ashiozxui123…”,
    "custom_parameter": "asdfoxuoy12uyisadouydfouayiouf…",
    “cup_return_deposit”: “100” ,            // 컵반환 보증금,
    “buyr_bizr_no”:”1234567890”,
    “clnt_pay_clf_cd”:”20240208”,
    “req_amt”: 700000000,
    “chrg_amt”: 300000000,
    “tot_tx_amt”: 1000000000,
    “pay_amt”: 1000000000,
    “clnt_tx_clf_cd”:”IMPL”,
    “cncl_yn”:”N”,
    “clnt_tx_ymd”:”20240601”,
    “seller_name”:”테스트판매사”
}

응답 데이터

처리 성공

처리 성공
파라미터 자료형 크기 설명
ret_code number   응답 코드
ret_msg string 100 응답 메시지
redirect_url string 1000 (결제용)웹 화면
*PG 웹 화면 접근 후 redirect_url token은 다시 사용할 수 없습니다.

처리 실패

처리 실패
파라미터 자료형 크기 설명
ret_code number   응답 코드
ret_msg string 100 응답 메시지 
HTTP 1.1 200 OK
{
    "ret_code": 0,
    "ret_msg": "OK",
    "redirect_url": "https://devpayapispg.shinhan.com/pgsvc/pay?token=2021083110239001duf.." // (결제 인증용)웹 화면
}
                                
HTTP 1.1 401 Unauthorized
{
    "ret_code": 998,
    "ret_msg": "token is missing or incorrect."
}

기업통합결제 결제창 호출

Html 내 script tag 추가
<script src="https://payspg.shinhan.com/businessPayment/unifiedPay/script" ></script>

통합결제창 결제요청 응답값 (redirect_url) 으로 팝업 호출
ShinhanBizPay.openPopup(result.redirect_url, function(retCode, retMessage) {
if(retCode == ShinhanBizPay.RES_SUCCESS) {
    console.log(“성공”);
} else {
    console.log("실패”, retMessage);
}
});

결제 화면 출력 (고객사 호출)

결제 요청 API의 redirect_url 을 이용하여, 고객사 사용자에게 PG 웹 화면을 출력합니다.

일반결제/비인증결제/전용페이 일 경우와 가상계좌일 경우 응답 파라미터가 달라집니다.

화면 요청

Redirect URL HTTP 메서드
redirect_url GET

결제 인증 결과 (PG 호출)

고객사 사용자의 PG 통합결제 결제하기(인증) 완료 이후, 고객사의 return_url POST 데이터로 주문 및 승인 토큰 정보가 전달됩니다. return_url은 결제 요청 API에 전달한 파라미터 값을 의미합니다.

화면 이동

Redirect URL HTTP 메서드
return_url POST

POST 데이터

파라미터 자료형 크기 설명
order_no string 50 (일반결제) 고객사 주문번호
custom_parameter string 1000 (일반결제) 고객사 전용 값
confirm_token string 50 (일반결제) 승인 토큰
escr_yn Char 1 (일반결제/가상계좌) 에스크로여부
* 고객사가 에스크로 사용 가능하고
PG에서 에스크로여부를 선택 한 경우
tid string 50 (가상계좌) 거래번호
bank_nm string 100 (가상계좌) 입금은행
user_nm string 20 (가상계좌) 예금주명
vald_dt string 8 (가상계좌) 입금기한(YYYYMMDD)
gods_nm string 100 (가상계좌) 상품명
email string 20 (가상계좌) 이메일
user_tel_no string 20 (가상계좌) 사용자 전화번호
pay_amt number   (가상계좌) 결제금액
ret_code number   (가상계좌) 응답 코드
ret_msg string 100 (가상계좌) 응답 메시지 
HTTP 1.1 200 OK
{
    "order_no": "202108310937510001",
    "custom_parameter": "auoh1238u123uy...",
    "confinm_token": "aaaaaa.bbbbbb.ccccc"
    “escr_yn”:”N”
    “tid”:”거래번호”
    "bank_nm": "입금은행",
    "user_nm": "예금주명",
    "vald_dt": "20240909"
    "gods_nm": "상품명"
    "email": "aaaaaa@ccc.com"
    "user_tel_no": "01012345678"
    "pay_amt": "46000"
    "ret_code": 0,
    "ret_msg": "OK"
}

결제 승인

고객사 결제 승인 용 API 입니다. "결제 인증 결과 (UI)"로 이동 후 30분(토큰 만료) 안에 요청하여야 합니다.

전용페이 계좌이체는 전용페이 사용자 휴대폰 번호(본인인증 결과정보)로 현금영수증을 자동 발행합니다.

API 요청

URL HTTP 메서드 HTTP 헤더 토큰 유형
v1.0/payments/confirm POST Authorization: SPGKEY {API Key} payment

요청 데이터

요청 데이터
파라미터 필수 여부 자료형 크기 설명
client_id 필수 string 10 고객사 아이디
order_no 필수 string 50 고객사 주문번호
confirm_token 필수 string 50 (결제)승인 토큰
ip_addr 필수 string 50 아이피 주소
(*사용자 아이피 주소 수집 시 결제 요청 이력 확인이 용이함)

응답 데이터

처리 성공

처리 성공
파라미터 자료형 크기 설명
ret_code number   응답 코드
ret_msg string 100 응답 메시지
pay_type number   결제 유형 (1: 단일 결제, 2: 복합 일반, 3: 복합 전용)
order_no string 50 고객사 주문번호
product_name string 50 (결제)상품 명
user_id string 50 고객사 사용자(회원) 아이디
user_name string 20 고객사 사용자(회원) 명
amount number   (결제 요청)금액
discount_amount number   할인 금액(신용카드사 프로모션 할인 금액)
*신용카드, 계좌이체, 간편결제 해당
taxfree_amount number   비과세 금액
*신용카드, 계좌이체, 간편결제 해당
tax_amount number   부가세 금액
*신용카드, 계좌이체, 간편결제 해당
tid string 50 (결제)거래 번호
pay_ispt_hash string 1000 결제 인증 해시
*PG의 결제 승인 응답 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256(user_id + amount + tid + payment API Key)" 조합으로 생성된다.
tx_date string 19 거래 일시(YYYY-MM-DD HH:MM:SS)
reserved1 string 200 가맹점 예약 필드
1.계좌 상품코드
신용카드(pay_info)
card_cpny_cd string 4 카드사 코드
card_name string 20 카드 종류
card_no string 18 카드 번호 (*전용페이 카드결제 시 전달되는 중간 6자리 마스킹 카드번호)
card_aprv_no string 50 카드 승인 번호
install_month string 2 할부 개월 수
card_pay_amt number   카드 결제 금액
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
zeropay_pay_amt number   제로페이 결제 금액
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
zeropay_tid string 50 제로페이 거래번호
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
seoulpay_pay_amt number   서울페이 결제 금액
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
seoulpay_tid string 50 서울페이 거래번호
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
locpay_pay_amt number   지역화폐 결제 금액
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
locpay_tid string 50 지역화폐 거래번호
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
list JSON
Array		   -
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
gfct_cd string 20 상품권 코드
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
gfct_name string 50 상품권 명
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
gfct_amt number   상품권 금액
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
계좌이체(pay_info)
bank_cd string 3 은행 코드
bank_name string 20 은행 명
bank_acct_no string 14 은행 계좌 번호 (*전용페이 계좌이체 시 전달되는 앞 3자리, 맨 뒤 3자리 외 마스킹 계좌번호)
bank_acct_pay_amt number   은행 계좌 결제 금액
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
zeropay_pay_amt number   제로페이 결제 금액
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
zeropay_tid string 50 제로페이 거래번호
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
seoulpay_pay_amt number   서울페이 결제 금액
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
seoulpay_tid string 50 서울페이 거래번호
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
locpay_pay_amt number   지역화폐 결제 금액
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
locpay_tid string 50 지역화폐 거래번호
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
list JSON
Array		   -
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
gfct_cd string 20 상품권 코드
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
gfct_name string 50 상품권 명
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
gfct_amt number   상품권 금액
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
cash_rcpt_ret_code number   현금 영수증 응답 코드
cash_rcpt_ret_msg string 100 현금 영수증 응답 메시지
cash_rcpt_pub_tid string 50 (PG 발행취소 · 재발행 요청용)현금 영수증 발행 거래번호
cash_rcpt_aprv_no string 50 현금 영수증 승인 번호
cash_rcpt_pub_type number   현금 영수증 발행 유형 (1: 소득공제용, 2: 지출증빙용)
cash_rcpt_pub_clf_type number   현금 영수증 발행 구분 유형(1: 구매자발급, 2: 자진발급)
cash_rcpt_pub_no_type number   현금 영수증 발행 번호 유형 (1: 휴대폰번호, 2: 사업자번호, 3: 자진발급)
cash_rcpt_pub_no string 20 현금 영수증 발행 번호 (소득공제용 휴대폰번호 또는 지출증빙용 사업자 번호 또는 자진 발급용 국세청 지정 코드 010-000-1234 등)
cash_rcpt_amt number   현금 영수증 발행 금액
간편결제 (pay_info)
primary_pymt_cd string 10 CARD : 카드, BANK : 계좌, MONEY : 머니
crcd_cpny_cd string 4 카드사 코드
*카드 결제인 경우
card_name string 20 카드 종류
*카드 결제인 경우
card_no string 18 카드 번호 (*마스킹 처리)
*카드 결제인 경우
card_aprv_no string 50 카드 승인 번호
*카드 결제인 경우
install_month string 2 할부 개월 수
*카드 결제인 경우
bank_cd string 3 은행 코드
*계좌 결제인 경우
bank_name string 20 은행 명
*계좌 결제인 경우
bank_acct_no string 14 은행 계좌 번호 (*마스킹 처리)
*계좌 결제인 경우
total_pay_amount number   간편결제 총 결제금액
구매자 결제금액+할인금액(discount_amount)
apply_pay_amount number   구매자 결제 금액
주 결제 수단 결제금액+포인트/머니 결제금액+기프트 카드 결제금액
primary_pay_amount number   주 결제 수단 결제금액
point_pay_amount number   포인트/머니 결제금액
gift_card_amount number   기프트 카드 결제금액
smp_discount_amount number   간편결제 할인금액
zeropay_pay_amt number   제로페이 결제 금액
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
zeropay_tid string 50 제로페이 거래번호
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
seoulpay_pay_amt number   서울페이 결제 금액
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
seoulpay_tid string 50 서울페이 거래번호
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
locpay_pay_amt number   지역화폐 결제 금액
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
locpay_tid string 50 지역화폐 거래번호
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
list JSON
Array		   -
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
gfct_cd string 20 상품권 코드
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
gfct_name string 50 상품권 명
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
gfct_amt number   상품권 금액
*복합 결제용 응답 입니다. 단일 결제 응답 데이터에는 포함되지 않습니다.
cash_rcpt_ret_code number   현금 영수증 응답 코드
cash_rcpt_ret_msg string 100 현금 영수증 응답 메시지
cash_rcpt_pub_tid string 50 (PG 발행취소 · 재발행 요청용)현금 영수증 발행 거래번호
cash_rcpt_aprv_no string 50 현금 영수증 승인 번호
cash_rcpt_pub_type number   현금 영수증 발행 유형 (1: 소득공제용, 2: 지출증빙용)
cash_rcpt_pub_clf_type number   현금 영수증 발행 구분 유형(1: 구매자발급, 2: 자진발급)
cash_rcpt_pub_no_type number   현금 영수증 발행 번호 유형 (1: 휴대폰번호, 2: 사업자번호, 3: 자진발급)
cash_rcpt_pub_no string 20 현금 영수증 발행 번호 (소득공제용 휴대폰번호 또는 지출증빙용 사업자 번호 또는 자진 발급용 국세청 지정 코드 010-000-1234 등)
cash_rcpt_amt number   현금 영수증 발행 금액
npoint_cash_amount number   포인트/머니 결제 금액중 현금 영수증 발행 금액
*네이버 페이인 경우.
gift_card_cash_amount number   기프트카드 결제 금액중 현금 영수증 발행 금액
*네이버 페이인 경우.
primary_cash_amount number   현금성 주 결제 수단 결제 금액중 현금 영수증 발행 금액
*네이버 페이인 경우.

처리 실패

처리 실패
파라미터 자료형 크기 설명
ret_code number   응답 코드
ret_msg string 100 응답 메시지 
HTTP 1.1 200 OK
{
"ret_code": 0,
"ret_msg": "OK",
“pay_type": 2,     // 결제 유형 (2: 복합 일반)
"order_no": "202108311259590001",
"product_name": "테스트 상품",
"user_id": "test01",
"user_name": "test01",
"amount": "1000",
"discount_amount": "100",
"taxfree_amount": "0",
"tax_amount": "90",
"tid": "202108311259590006",
"install_month": "00",
"pay_ispt_hash": "941365C04218FF129B790AB1244F8A012BA64E872C3CB8E0C9978A2F76C202F0",
"tx_date": "2021-08-31 12:59:59",
"pay_info": [
       {
… …
}]
}
                                
HTTP 1.1 401 Unauthorized
{
"ret_code": 998,
    "ret_msg": "token is missing or incorrect."
}

결제 취소

고객사 결제 취소 용 API 입니다.

API 요청

URL HTTP 메서드 HTTP 헤더 키 유형
v1.0/payments/cancel POST Authorization: SPGKEY {API Key} payment

요청 데이터

요청 데이터
파라미터 필수 여부 자료형 크기 설명
client_id 필수 string 10 고객사 아이디
user_id 필수 string 50 고객사 사용자(회원) 아이디(이메일, 영문 및 숫자 가능)
tid 필수 string 50 (결제)거래 번호
amount 필수 number   (취소)금액
cncl_rsn 필수 string 100 취소 사유
ip_addr 필수 string 50 (고객사 사용자)아이피 주소
bank_cd 선택 string 3 (가상계좌용)은행코드(가상계좌)
bank_acct_no 선택 string 14 (가상계좌용)은행 계좌 번호 (환불받을 계좌번호)
bank_name 선택 string 20 (가상계좌용)계좌주명

응답 데이터

처리 성공

처리 성공
파라미터 자료형 크기 설명
ret_code number   응답 코드
ret_msg string 100 응답 메시지
tid string 50 (결제)거래 번호
cid string 50 (취소)승인 번호
amount number   (취소)금액
tx_date string 19 (취소)거래 일시(YYYY-MM-DD HH:MM:SS)

처리 실패

처리 실패
파라미터 자료형 크기 설명
ret_code number   응답 코드
ret_msg string 100 응답 메시지 
HTTP 1.1 200 OK
{
    "ret_code": 0,
    "ret_msg": "OK",
    "tid" :"tpay_test202108311259590002",
    "cid":"123456",
    "amount":1000,
    "tx_date":"2021-08-31 15:01:07"
}
                                
HTTP 1.1 401 Unauthorized
{
    "ret_code": 998,
    "ret_msg": "token is missing or incorrect."
}

거래 확인서 요청

고객사 사용자의 PG (결제)거래 확인서 화면 요청 용 API 입니다.

API 요청

URL HTTP 메서드 HTTP 헤더 키 유형
v1.0/receipt/info/{tid} GET Authorization: SPGKEY {API Key} search

요청 데이터

요청 데이터
파라미터 필수 여부 자료형 크기 설명
client_id 필수 string 10 고객사 아이디
amunt 필수 number   (결제)금액
tx_ymd 필수 string 10 거래 일자(YYYY-MM-DD)

응답 데이터

처리 성공

처리 성공
파라미터 자료형 크기 설명
ret_code number   응답 코드
ret_msg string 100 응답 메시지
redirect_url string 1000 (거래 내역 확인용)웹 화면

처리 실패

처리 실패
파라미터 자료형 크기 설명
ret_code number   응답 코드
ret_msg string 100 응답 메시지 
HTTP 1.1 200 OK
{
"ret_code": 0,
"ret_msg": "OK",
"redirect_url": "https://devpayapispg.shinhan.com/pgsvc/receipt/receipt_all.asp?id=..." //(거래내역확인용) PG 웹 화면
}
                                
HTTP 1.1 401 Unauthorized
{
"ret_code": 998,
    "ret_msg": "token is missing or incorrect."
}

결제 거래정보 조회

고객사 결제 거래 정보 조회용 API 입니다.

API 요청

URL HTTP 메서드 HTTP 헤더 토큰 유형
v1.0/payments/confirm-info GET Authorization: SPGKEY {API Key} search

요청 데이터

요청 데이터
파라미터 필수 여부 자료형 크기 설명
client_id 필수 String 10 고객사 아이디
ordr_no 필수 String 50 고객사 주문번호

응답 데이터

처리 성공

처리 성공
파라미터 자료형 크기 설명
ret_code number   응답 코드
ret_msg string 100 응답 메시지
user_id string 50 고객사 사용자(회원) 아이디(이메일, 영문 및 숫자 가능)
tid string 50 (결제)거래 번호
tx_amount number   (결제)거래 금액
tx_stat number   (결제)거래 상태 (1: 승인, 2: 취소, 3: 부분취소)
tx_date string 19 거래 일시(YYYY-MM-DD HH:MM:SS)
cncl_date string 19 취소 일시(YYYY-MM-DD HH:MM:SS)
*거래 상태 "2:취소"의 경우에만 응답하는 정보입니다.
cncl_rsn string 100 취소 사유
*거래 상태 "2:취소"의 경우에만 응답하는 정보입니다.

처리 실패

처리 실패
파라미터 자료형 크기 설명
ret_code number   응답 코드
ret_msg string 100 응답 메시지 
HTTP 1.1 200 OK
{
"ret_code": 0,
"ret_msg": "OK",
"user_id": "test_01",
"tid": "202108311259590006",
"tax_amount": "10,00",
"tx_stat": 2,
"tx_date": "2021-12-22 12:59:59",
"cncl_date": "2021-12-22 13:05:59",
      "cncl_rsn”: “고객 요청”
}
                                
HTTP 1.1 401 Unauthorized
{
"ret_code": 998,
    "ret_msg": "there is no data."
}

가상계좌 환불 요청

API 요청

고객사에서 입금 취소를 요청합니다.(당일만 가능)

URL HTTP 메서드 HTTP 헤더 키 유형
v1.0/virtualAccount/requestVaPaymentBack POST Authorization: “SPGKEY” + {API Key}  

요청 데이터

요청 데이터
파라미터 필수 여부 자료형 크기 설명
req_type 필수 number 1 요청유형(환불요청유형, 1:전체취소, 2:부분취소)
client_id 필수 String 20 고객사 아이디(신한PG로부터 부여받은 고객사 식별아이디)
tid 필수 String 50 (결제)거래 번호
bank_cd 필수 String 3 은행코드
bank_acct_no 필수 String 14 은행 계좌 번호 (환불받을 계좌번호)
bank_name 필수 String 20 계좌주명
amount 필수 number 15 (부분 취소)금액
taxfree_amount 옵션 number 13 비과세 금액
*요청 파라미터 값이 없으면 0 원 적용
tax_amount 옵션 number 13 부가세 금액
*요청 파라미터 값이 없으면, ((amount - taxfree_amount) / 11) 계산식을 적용, 소수점 이하 반올림으로 자동 계산한다.
cncl_rsn 옵션 String 100 취소 사유
pay_hash 필수 String 1000 파라메터 검증 해시
*고객사 요청 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256( client_id + tid + payment API Key)" 조합으로 생성된다. 
{
    “req_type”:1,
    “client_id”: “c000000001”,
    "tid": " c0000000001202301090000000001",
    “bank_cd”: “086”,
    “bank_acct_no”: “1234123412”,
    “bank_name”: “테스트계좌명”,
    "amount":1000,
    "taxfree_amount ":0,
    "tax_amount":0,
    "cncl_rsn":”고객요청취소”,
    “pay_hash”: "dfhuoi892ashiozxui123…”
}

응답 데이터

처리 성공

처리 성공
파라미터 자료형 크기 설명
ret_code Number   응답 코드
ret_msg String 100 응답 메시지
tid String 50 거래번호
amount Number   금액 
HTTP 1.1 200 OK
{
    "ret_code": 0,
        "ret_msg": "고객사 환불 요청이 완료되었습니다.”,
    “tid”: “c0000000001202301090000000001”,
    “amt”: 7000000,
}

처리 실패

처리 실패
파라미터 자료형 크기 설명
ret_code Number   응답 코드
ret_msg String 100 응답 메시지 

HTTP 1.1 401 Unauthorized
{
    "ret_code": 999,
    "ret_msg": "고객사 환불 요청이 실패하였습니다. "
}

가상계좌 대출 연계 결제(취소) 요청

API 요청

고객사에서 대출 연계 결제(취소) 요청을 합니다.

URL HTTP 메서드 HTTP 헤더 키 유형
v1.0/virtualAccount/requestLoanPayment POST Authorization: “SPGKEY” + {API Key} payment

요청 데이터

요청 데이터
파라미터 필수 여부 자료형 크기 설명
client_id 필수 String 20 고객사 아이디(신한PG로부터 부여받은 고객사 식별아이디)
buyr_bizr_no 필수 String 10 구매자 사업자 번호
ordr_no 필수 String 50 입금요청번호 (주문번호)
gods_nm   String 110 거래 품목 (상품명) 결제요청 시 필수
clnt_pay_clf_cd   String 6 결제 구분 결제요청 시 필수
SGLPAY: 일시지급(선수금없음)
RMDPAY: 잔금지급(선수금대상)
req_amt   Number 13 지원신청금액(원) 결제요청 시 필수
대출금액으로 기본 70%
신한 은행 여신 기준에 맞춰 천원 단위로 절사 처리 필요
(로직 제공, 금액이 안 맞는 경우 처리결과 ‘F’ 리턴,
고객부담금에 나머지 금액 추가)
chrg_amt   Number 13 고객부담금액(원) 결제요청 시 필수
tot_tx_amt   Number 13 총구매금액(원) 결제요청 시 필수
pay_amt   Number 13 결제요청금액(원) 결제요청 시 필수
일시지급일때는 총구매금액(100%), 잔금지급일때는 지원신청금액(70%)
clnt_tx_clf_cd 필수 String 6 거래 구분 (고객사거래구분코드)
고객사결제구분코드 (GNR: 일반거래 / IMPL: 전용거래)
cncl_yn 필수 String 1 취소 여부
주문취소 건인 경우 취소 여부(‘Y’)와 PK정보(사업자 번호, 입금요청번호)만 전송
clnt_tx_ymd   String 8 낙찰일 (고객사 거래일자) 결제요청 시 필수
seller_name   String 20 판매사명 결제요청 시 필수
플랫폼이 판매사인 경우 플랫폼명
오픈마켓 : 판매자
user_name   String 20 사용자명
email_addr   String 50 고객이메일
고객의 이메일 주소입니다. 결제 결과를 알려줄 때 사용합니다
mobile_no   String 13 고객휴대폰번호
고객의 휴대폰 번호입니다. 가상계좌 입금 안내가 전송되는 번호 입니다.
pay_hash 필수 String 1000 파라메터 검증 해시
*고객사 요청 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256( client_id + ordr_no + payment API Key)" 조합으로 생성된다. 
{
    “client_id”: “c000000001”,
    "buyr_bizr_no": " 1234567890",
    “ordr_no”: “1a234”,
    “gods_nm”: “철강 외”,
    “clnt_payr_clf_cd”: “SGLPAY”,
    “req_amt”: 700000000,
    “chrg_amt”: 300000000,
    “tot_tx_amt”: 1000000000,
    “pay_amt”: 1000000000,
    “clnt_tx_clf_cd”: “IMPL”,
    “cncl _yn“: “N”,
    “clnt_tx_ymd“: “20240208”
    “seller_name”: “테스트판매사”
    “user_name“: “홍길동”,
    “email_addr“: “aaa@shinhan.com”,
    “mobile_no“: “01012345678”,
    “pay_hash“: “dfhuoi892ashiozxui123…”
}

응답 데이터

처리 성공

처리 성공
파라미터 자료형 크기 설명
ret_code Number   응답 코드 (성공 : 0, 실패 : 999)
ret_msg String 1000 응답 메시지
ret_datetime Date   처리 일시(yyyyMMddHH24miss)
authti_tkn String 50 인증 토큰
가상계좌 웹훅이 정상적인 요청인지 검증하는 값입니다. 이값이 가상계좌 웹훅 이벤트 본문으로 전송된 인증토큰과 같으면 정상적인 요청입니다.
ordr_no String 50 고객사 거래번호
client_id String 20 고객사 아이디
expr_tlml String 14 만료기한 (yyyyMMddHH24miss)
tid String 50 결제(PG)거래번호 (선 발번, 후 사용) 
HTTP 1.1 200 OK
{
    "ret_code": 0,
    "ret_msg": "입금 요청이 완료 되었습니다.”,
    "ret_datetime": 202402071641,
    "authti_tkn": "A1946B873612”,
    "ordr_no": "ordr123123”,
    "client_id": "C000000001”,
    "expr_tlml": "20240329180000”,
    "tid": "c0000000001202301090000000001"
}

처리 실패

처리 실패
파라미터 자료형 크기 설명
ret_code Number   응답 코드 (성공 : 0, 실패 : 999)
ret_msg String 100 응답 메시지 
                                    
HTTP 1.1 401 Unauthorized
{
    "ret_code": 999,
    "ret_msg": "입금요청번호가 중복입니다./지원신청급액이 맞지 않습니다. "
}

가상계좌 입금 조회

API 요청

고객사에서 가상계좌 입금 여부를 조회 합니다.

URL HTTP 메서드 HTTP 헤더 키 유형
v1.0/virtualAccount/requestVaDpstInqry POST Authorization: “SPGKEY” + {API Key} payment

요청 데이터

요청 데이터
파라미터 필수 여부 자료형 크기 설명
client_id 필수 String 10 고객사 아이디(신한PG로부터 부여받은 고객사 식별아이디)
ordr_no 필수 String 50 입금요청번호 (주문번호)
buyr_bizr_no 필수 String 10 구매자 사업자 번호
tid 필수 String 50 결제(구매정보)요청 응답으로 수신한 결제(PG)거래번호
pay_hash 필수 String 1000 파라메터 검증 해시
*고객사 요청 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256( client_id + ordr_no + payment API Key)" 조합으로 생성된다. 
{
    “client_id”: “c000000001”,
    “ordr_no”: “1a234”,
    "buyr_bizr_no": " 1234567890",
    "tid": " c0000000001202301090000000001",
    “pay_hash“: “dfhuoi892ashiozxui123…”
}

응답 데이터

처리 성공

처리 성공
파라미터 자료형 크기 설명
ret_code Number   응답 코드 (성공 : 0, 실패 : 999)
ret_msg String 1000 응답 메시지
dpst_datetime Date   입금일시(yyyyMMddHH24miss)
dpst_stat String 1 입금상태
1:입금대기
2:입금완료
3:입금만료
4:입금요청취소 
HTTP 1.1 200 OK
{
    "ret_code": 0,
    "ret_msg": "입금 완료 되었습니다/입금 대기중입니다.”,
    "dpst_datetime": 202402071641,
    "dpst_stat": "1"
    }

처리 실패

처리 실패
파라미터 자료형 크기 설명
ret_code Number   응답 코드 (성공 : 0, 실패 : 999)
ret_msg String 100 응답 메시지 
                                    
HTTP 1.1 401 Unauthorized
{
    "ret_code": 999,
    "ret_msg": "요청 정보가 확인되지 않습니다."
}

여신약정한도보유여부조회

API 요청

고객사에서 약정한보보유여부 확인을 위해 조회 합니다.

URL HTTP 메서드 HTTP 헤더 키 유형
v1.0/virtualAccount/requestLoanLimitYnInquiry POST Authorization: “SPGKEY” + {API Key} payment

요청 데이터

요청 데이터
파라미터 필수 여부 자료형 크기 설명
client_id 필수 String 10 고객사 아이디(신한PG로부터 부여받은 고객사 식별아이디)
buyr_bizr_no 필수 String 10 구매자 사업자번호
pay_hash 필수 String 1000 파라메터 검증 해시
*고객사 요청 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256( client_id + buyr_bizr_no + payment API Key)" 조합으로 생성된다. 
{
    “client_id”: “c000000001”,
    “buyr_bizr_no”: “1253258756”,
    “pay_hash“: “dfhuoi892ashiozxui123…”
}

응답 데이터

처리 성공

처리 성공
파라미터 자료형 크기 설명
ret_code Number   응답 코드 (성공 : 0, 실패 : 999)
ret_msg String 1000 응답 메시지
contract_limit_yn String 3 0:미보유,1:보유 
HTTP 1.1 200 OK
{
    "ret_code": 0,
    "ret_msg": "약정한도여부 조회성공.”,
    “contract_limit_yn”: “1”
}

처리 실패

처리 실패
파라미터 자료형 크기 설명
ret_code Number   응답 코드 (성공 : 0, 실패 : 999)
ret_msg String 100 응답 메시지 
                                    
HTTP 1.1 401 Unauthorized
{
    "ret_code": 999,
    "ret_msg": "약정한도 조회에 실패하였습니다. "
}

건별여신잔액정보조회

API 요청

고객사에서 대출잔액을 조회 합니다.

URL HTTP 메서드 HTTP 헤더 키 유형
v1.0/virtualAccount/requestLoanBalanceInquiry POST Authorization: “SPGKEY” + {API Key} payment

요청 데이터

요청 데이터
파라미터 필수 여부 자료형 크기 설명
client_id 필수 String 20 고객사 아이디(신한PG로부터 부여받은 고객사 식별아이디)
buyr_bizr_no 필수 String 10 구매자 사업자 번호
ordr_no 필수 String 50 입금요청번호 (주문번호)
pay_hash 필수 String 1000 파라메터 검증 해시
*고객사 요청 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256( client_id + buyr_bizr_no + ordr_no + payment API Key)" 조합으로 생성된다. 
{
    “client_id”: “c000000001”,
    "buyr_bizr_no": " 1234567890",
    “ordr_no”: “1a234”,
    “pay_hash“: “dfhuoi892ashiozxui123…”
}

응답 데이터

처리 성공

처리 성공
파라미터 자료형 크기 설명
ret_code Number   응답 코드 (성공 : 0, 실패 : 999)
ret_msg String 100 응답 메시지
loan_balance Number   여신잔액 
HTTP 1.1 200 OK
{
    "ret_code": 0,
    "ret_msg": "잔액 조회성공.”,
    “loan_balance”: 55000
}

처리 실패

처리 실패
파라미터 자료형 크기 설명
ret_code Number   응답 코드 (성공 : 0, 실패 : 999)
ret_msg String 100 응답 메시지 
                                    
HTTP 1.1 401 Unauthorized
{
    "ret_code": 999,
    "ret_msg": "잔액 조회에 실패하였습니다. "
}

정산내역 조회

고객사 정산 내역 조회 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

가상계좌 결제 요청

고객사에서 가상계좌 결제를 요청합니다.

가상계좌 입금요청내역과 가상계좌를 발번하여 응답 내용으로 전송합니다.

API 요청

URL HTTP 메서드 HTTP 헤더 키 유형
v1.0/virtualAccount/requestVaPayment POST Authorization: “SPGKEY” + {API Key}  

요청 데이터

요청 데이터
파라미터 필수 여부 자료형 크기 설명
client_id 필수 String 20 고객사 아이디(신한PG로부터 부여받은 고객사 식별아이디)
ordr_no 필수 String 50 주문번호
acct_key   String 18 계좌키
* 고정가상계좌를 사용하는 고객과 매칭시킨 계좌의 고유한 키값입니다. 특정고객에게 같은 가상계좌를 다시 발급하려면 처음 고정 가상계좌를 발급할 때 사용했던 계좌키를 설정해주세요. 최대갈이는 18자입니다
gods_nm 필수 String 100 상품명
gods_qty 필수 Number   수량
pay_amt 필수 Number   결제금액
email_addr   String 50 고객이메일
고객의 이메일 주소입니다. 결제 결과를 알려줄 때 사용합니다
user_name 필수 string 20 사용자명
mobile_no   String 13 고객휴대폰번호
고객의 휴대폰 번호입니다. 가상계좌 입금 안내가 전송되는 번호 입니다.
cash_rcpt_pub_type   number   현금 영수증 발행 유형 (1: 소득공제용, 2: 지출증빙용)
*해당 요청 파라미터와 현금 영수증 발행 번호 유형, 현금 영수증 발행 번호 파라미터들의 값이 있으면 전용페이 계좌 결제 승인 이후 해당 정보들로 현금영수증을 발행 처리합니다. 만약 해당 요청 값들이 없으면 자진 발급번호로 발행 처리합니다.
cash_rcpt_pub_no_type   number   현금 영수증 발행 번호 유형 (1: 휴대폰번호, 2: 사업자번호, 3: 자진발급 등 기타)
*해당 요청 파라미터와 현금 영수증 발행 유형, 현금 영수증 발행 번호 파라미터들의 값이 있으면 전용페이 계좌 결제 승인 이후 해당 정보들로 현금영수증을 발행 처리합니다. 만약 해당 요청 값들이 없으면 자진 발급번호로 발행 처리합니다.
taxfree_amount   number   비과세 금액
*(결제 요청)금액이 모두 비과세액인 경우, amount, taxfree_amount 모두 동일한 값을 설정하여야 합니다.
예) (결제 요청)금액 1,000원 모두 비과세 금액인 경우
→ amount, taxfree_amount 모두 1,000원 설정
*(결제 요청)금액 중 일부가 비과세 금액인 경우, 해당 금액만 taxfree_amount에 설정하여야 합니다.
예) (결제 요청)금액 1,000원중 비과세 금액이 100원인 경우
→ amount 1,000원, taxfree_amount 100원 설정
tax_amount   number   부가세 금액
*요청 파라미터 값이 없으면,
((amount - taxfree_amount - cup_return_deposit) / 11)
계산식을 적용, 소수점 이하 반올림으로 자동 계산합니다.
valid_hours 옵션 Number   유효시간
* 가상계좌 발급 시점으로부터 유효한 시간 범위입니다.
설정한 유효시간 안에 구매자가 입금을 하지 않으면 주문은 취소됩니다. 가상계좌 발급 후 일정시간 뒤에 반납됩니다. 예를 들어 가상계좌 발급 후 24시간내에 입금해야 한다면 24로 설정합니다. 값을 넣지 않으면 기본값 168 시간(7일)으로 설정됩니다. 설정할 수 있는 최대값은 720 시간(30일) 입니다. 유효시간과 유효일자 중 하나만 사용할 수 있습니다.
lmt_day 옵션 String   유효일자
* 입금 기한을 날자로 특정합니다. 지정한 시점에 가상계좌가 반납됩니다. 예를 들어 입금시간을 주문 후 3일 뒤 자정 과 같이 특정 시점으로 설정하고 싶을 때 20241010000000 와 같이 설정한다.
escr_yn 필수 Char 1 에스크로여부(N:아니오, Y:예)
adj_req_ymd 옵션 String   정산요청일자
pay_hash 필수 String 1000 파라메터 검증 해시
*고객사 요청 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256( client_id + ordr_no + payment API Key)" 조합으로 생성된다. 
{
    “client_id”: “c000000001”,
    “ordr_no”: “order123123”,
    "acct_key": "a45625x00000",
    "gods_nm": "테스트상품",
    "gods_qty": 100,
    "pay_amt": 1000000,
    “email_addr”: “test@test.co.kr”,
    “mobile_no”: “01012341234”,
    “cash_rcpt_pub_type”:1
    “cash_rcpt_pub_no_type”:01012341234
    “valid_hours”:24
    “escr_yn”: “N”,
    “adj_req_ymd”: “20240310”,
    “pay_hash”: "dfhuoi892ashiozxui123…”
}

응답 데이터

처리 성공

처리 성공
파라미터 자료형 크기 설명
ret_code Number   응답 코드
ret_msg String 100 응답 메시지
authti_tkn String 50 인증 토큰
가상계좌 웹훅이 정상적인 요청인지 검증하는 값입니다. 이값이 가상계좌 웹훅 이벤트 본문으로 전송된 인증토큰과 같으면 정상적인 요청 입니다.
ordr_no String 50 고객사 거래번호
client_id String 20 고객사아이디
va_typ String 20 가상계좌타입
1(일반),2(고정)
bank_cd String 3 은행코드
va_no String 30 가상계좌번호
expr_tlml String 14 만료기한
20241010000000 
HTTP 1.1 200 OK
{
    "ret_code": 0,
    "ret_msg": "결제 요청이 성공하였습니다.",
    “authti_tkn”: “A1946B873612”,
    “ordr_no”: “order123123”,
    “client_id”: “c000000001”,
    "va_typ": "a00000000",
    “bank_cd”:”086”
    "va_no": "0000000000000”
    "expr_tlmt": “20241010000000”
}

처리 실패

처리 실패
파라미터 자료형 크기 설명
ret_code Number   응답 코드
ret_msg String 100 응답 메시지 
HTTP 1.1 401 Unauthorized
{
    "ret_code": 999,
    "ret_msg": "결제 요청이 실패하였습니다."
}

가상계좌 환불 요청

API 요청

고객사에서 입금 취소를 요청합니다.(당일만 가능)

URL HTTP 메서드 HTTP 헤더 키 유형
v1.0/virtualAccount/requestVaPaymentBack POST Authorization: “SPGKEY” + {API Key}  

요청 데이터

요청 데이터
파라미터 필수 여부 자료형 크기 설명
req_type 필수 String 1 요청유형(환불요청유형, 2:전체취소, 3:부분취소
client_id 필수 String 20 고객사 아이디(신한PG로부터 부여받은 고객사 식별아이디)
tid 필수 String 50 (결제)거래 번호
bank_cd 필수 String 3 은행코드
bank_acct_no 필수 String 14 은행 계좌 번호 (환불받을 계좌번호)
bank_name 필수 String 20 계좌주명
amount 필수 number   (부분 취소)금액
taxfree_amount 옵션 number   비과세 금액
*요청 파라미터 값이 없으면 0 원 적용
tax_amount 옵션 number   부가세 금액
*요청 파라미터 값이 없으면, ((amount - taxfree_amount) / 11) 계산식을 적용, 소수점 이하 반올림으로 자동 계산한다.
cncl_rsn 옵션 String 100 취소 사유
pay_hash 필수 String 1000 파라메터 검증 해시
*고객사 요청 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256( client_id + tid + payment API Key)" 조합으로 생성된다. 
{
    “client_id”: “c000000001”,
    "tid": " c0000000001202301090000000001",
    “bank_cd”: “086”,
    “bank_acct_no”: “1234123412”,
    “bank_name”: “테스트계좌명”,
    "amount":1000,
    "taxfree_amount ":,
    "tax_amount":,
    "cncl_rsn":”고객요청취소”,
    “pay_hash”: "dfhuoi892ashiozxui123…”
}

응답 데이터

처리 성공

처리 성공
파라미터 자료형 크기 설명
ret_code Number   응답 코드
ret_msg String 100 응답 메시지
tid String 50 거래번호
amount Number   금액 
HTTP 1.1 200 OK
{
    "ret_code": 0,
    "ret_msg": "고객사 환불 요청이 완료되었습니다.”,
    “tid”: “c0000000001202301090000000001”,
    “amt”: 7000000,
}

처리 실패

처리 실패
파라미터 자료형 크기 설명
ret_code Number   응답코드
ret_msg String 100 응답 메시지 
                                    
HTTP 1.1 401 Unauthorized
{
    "ret_code": 999,
    "ret_msg": "고객사 환불 요청이 실패하였습니다. "
}

가상계좌 대출 연계 결제(취소) 요청

API 요청

고객사에서 대출 연계 결제(취소) 요청을 합니다.

URL HTTP 메서드 HTTP 헤더 키 유형
v1.0/virtualAccount/requestLoanPayment POST Authorization: “SPGKEY” + {API Key}  

요청 데이터

요청 데이터
파라미터 필수 여부 자료형 크기 설명
client_id 필수 String 20 고객사 아이디(신한PG로부터 부여받은 고객사 식별아이디)
buyr_bizr_no 필수 String 10 구매자 사업자 번호
ordr_no 필수 String 50 입금요청번호 (주문번호)/td>
gods_nm   String 110 거래 품목 (상품명) 결제요청 시 필수
clnt_pay_clf_cd   String 6 결제 구분 결제요청 시 필수
SGLPAY: 일시지급(선수금없음)
RMDPAY: 잔금지급(선수금대상)
req_amt   Number 13 지원신청금액(원) 결제요청 시 필수
대출금액으로 기본 70%
신한 은행 여신 기준에 맞춰 천원 단위로 절사 처리 필요
(로직 제공, 금액이 안 맞는 경우 처리결과 ‘F’ 리턴,
고객부담금에 나머지 금액 추가)
chrg_amt   Number 13 고객부담금액(원) 결제요청 시 필수
tot_tx_amt   Number 13 총구매금액(원) 결제요청 시 필수
pay_amt   Number 13 결제요청금액(원) 결제요청 시 필수
일시지급일때는 총구매금액(100%), 잔금지급일때는 지원신청금액(70%)
clnt_tx_clf_cd 필수 String 6 거래 구분 (고객사거래구분코드)
고객사결제구분코드 (GNR: 일반거래 / IMPL: 전용거래)
cncl_yn 필수 String 1 취소 여부
주문취소 건인 경우 취소 여부(‘Y’)와 PK정보(사업자 번호, 입금요청번호)만 전송
clnt_tx_ymd   String 8 낙찰일 (고객사 거래일자) 결제요청 시 필수
user_name   String 20 사용자명
email_addr   String 50 고객이메일
고객의 이메일 주소입니다. 결제 결과를 알려줄 때 사용합니다
mobile_no   String 13 고객휴대폰번호
고객의 휴대폰 번호입니다. 가상계좌 입금 안내가 전송되는 번호 입니다.
pay_hash 필수 String 1000 파라메터 검증 해시
*고객사 요청 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256( client_id + ordr_no + payment API Key)" 조합으로 생성된다. 
{
    “client_id”: “c000000001”,
    "buyr_bizr_no": " 1234567890",
    “ordr_no”: “1a234”,
    “gods_nm”: “철강 외”,
    “clnt_payr_clf_cd”: “SGLPAY”,
    “req_amt”: 700000000,
    “chrg_amt”: 300000000,
    “tot_tx_amt”: 1000000000,
    “pay_amt”: 1000000000,
    “clnt_tx_clf_cd”: “IMPL”,
    “cncl _yn“: “N”,
    “clnt_tx_ymd“: “20240208”
    “user_name“: “홍길동”,
    “email_addr“: “aaa@shinhan.com”,
    “mobile_no“: “01012345678”,
    “pay_hash“: “dfhuoi892ashiozxui123…”
}

응답 데이터

처리 성공

처리 성공
파라미터 자료형 크기 설명
ret_code Number   응답 코드 (성공 : 0, 실패 : 999)
ret_msg String 100 응답 메시지
ret_datetime Date   처리 일시(yyyyMMddHH24miss)
authti_tkn String 50 인증 토큰
가상계좌 웹훅이 정상적인 요청인지 검증하는 값입니다. 이값이 가상계좌 웹훅 이벤트 본문으로 전송된 인증토큰과 같으면 정상적인 요청입니다.
ordr_no String 50 고객사 거래번호
client_id String 20 고객사 아이디
expr_tlml String 14 만료기한 (yyyyMMddHH24miss)
tid String 50 결제(PG)거래번호 (선 발번, 후 사용) 
HTTP 1.1 200 OK
{
    "ret_code": 0,
    "ret_msg": "입금 요청이 완료 되었습니다.”,
    "ret_datetime": 202402071641,
    "authti_tkn": "A1946B873612”,
    "ordr_no": "ordr123123”,
    "client_id": "C000000001”,
    "expr_tlml": "20240329180000”,
    "tid": "c0000000001202301090000000001"
}

처리 실패

처리 실패
파라미터 자료형 크기 설명
ret_code Number   응답 코드 (성공 : 0, 실패 : 999)
ret_msg String 100 응답 메시지
ret_datetime Date   처리 일시 
                                    
HTTP 1.1 401 Unauthorized
{
    "ret_code": 999,
    "ret_msg": "입금요청번호가 중복입니다./지원신청급액이 맞지 않습니다. "
}

가상계좌 입금 조회

API 요청

고객사에서 가상계좌 입금 여부를 조회 합니다.

URL HTTP 메서드 HTTP 헤더 키 유형
v1.0/virtualAccount/requestLVaDpstInqry POST Authorization: “SPGKEY” + {API Key}  

요청 데이터

요청 데이터
파라미터 필수 여부 자료형 크기 설명
client_id 필수 String 10 고객사 아이디(신한PG로부터 부여받은 고객사 식별아이디)
ordr_no 필수 String 50 입금요청번호 (주문번호)
buyr_bizr_no 필수 String 10 구매자 사업자 번호
tid 필수 String 50 결제(구매정보)요청 응답으로 수신한 결제(PG)거래번호
pay_hash 필수 String 1000 파라메터 검증 해시
*고객사 요청 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256( client_id + ordr_no + payment API Key)" 조합으로 생성된다. 
{
    “client_id”: “c000000001”,
    “ordr_no”: “1a234”,
    "buyr_bizr_no": " 1234567890",
    "tid": " c0000000001202301090000000001",
    “pay_hash“: “dfhuoi892ashiozxui123…”
}

응답 데이터

처리 성공

처리 성공
파라미터 자료형 크기 설명
ret_code Number   응답 코드 (성공 : 0, 실패 : 999)
ret_msg String 100 응답 메시지
dpst_datetime Date   입금일시(yyyyMMddHH24miss)
dpst_stat String 1 입금상태
1:입금대기
2:입금완료
3:입금만료
4:입금요청취소 
HTTP 1.1 200 OK
{
    "ret_code": 0,
    "ret_msg": "입금 완료 되었습니다/입금 대기중입니다.”,
    "dpst_datetime": 202402071641,
    "dpst_stat": "1"
}

처리 실패

처리 실패
파라미터 자료형 크기 설명
ret_code Number   응답 코드 (성공 : 0, 실패 : 999)
ret_msg String 100 응답 메시지 
                                    
HTTP 1.1 401 Unauthorized
{
    "ret_code": 999,
    "ret_msg": "요청 정보가 확인되지 않습니다."
}

BIZ Bank 결제대상조회

API 요청

BIZ Bznk에서 가상계좌 결제 대상을 조회 합니다.

URL HTTP 메서드 HTTP 헤더 키 유형
v1.0/virtualAccount/bizbankPayTargetInqry POST Authorization: “SPGKEY” + {API Key}  

요청 데이터

요청 데이터
파라미터 필수 여부 자료형 크기 설명
buyr_bizr_no 필수 String 10 구매자 사업자번호
inqry_clf 필수 String 1 조회구분 (전체(0), 결제요청(1), 결제완료(2), 취소(3))
plfm_cd   String 3 플랫폼 (코드(001)-플랫폼명(이스틸포유) 매핑하여 코드값으로 조회)
inqry_st_ymd   String 8 조회시작일 YYYYMMDD
inqry_ed_ymd   String 8 조회종료일 YYYYMMDD 
{
    “buyr_bizr_no”: “1253258756”,
    “inqry_clf”: “1”,
    "plfm_cd": "001",
    "inqry_st_ymd": "20240301",
    “inqry_ed_ymd“: “20240318”
}

응답 데이터

처리 성공

파라미터 필수여부 자료형 크기 설명
buyr_bizr_no 필수 String 10 구매자 사업자번호
inqry_clf 필수 String 1 조회구분 (전체(0), 결제요청(1), 결제완료(2), 취소(3))
plfm_cd   String 3 플랫폼 (코드(001)-플랫폼명(이스틸포유) 매핑하여 코드값으로 조회)
inqry_st_ymd   String 8 조회시작일 YYYYMMDD
inqry_ed_ymd   String 8 조회종료일 YYYYMMDD
rst_cnt   Number 3 조회 건수
rst_list   JSONArray    
plfm_nm 필수 String 100 플랫폼(이름)
plfm_cd 필수 String 3 플랫폼(코드)
ordr_no 필수 String 50 입금요청번호 (주문번호)
gods_nm   String 110 거래 품목 (상품명)
clnt_pay_clf_cd   String 6 결제구분
SGLPAY: 일시지급(선수금없음)
RMDPAY: 잔금지급(선수금대상)
req_amt   Number 13 지원신청금액(원)
대출금액으로 기본 70%
신한 은행 여신 기준에 맞춰 천원 단위로 절사 처리 필요
(로직 제공, 금액이 안 맞는 경우 처리결과 ‘F’ 리턴,
고객부담금에 나머지 금액 추가)
ppay_amt   Number 13 선수금(원) (선수금 = 고객부담금액),고객부담금에 추가금
(선수금+추가금)이 있을 경우 추가금 별도 분리 불가
chrg_amt   Number 13 고객부담금액(원)
tot_tx_amt   Number 13 총구매금액(원)
pay_amt   Number 13 결제요청금액(원)
일시지급일때는 총구매금액(100%), 잔금지급일때는 지원신청금액(70%)
clnt_tx_clf_cd 필수 String 6 거래 구분 (고객사거래구분코드)
고객사결제구분코드 (GNR: 일반거래 / IMPL: 전용거래)
dpst_stat_cd   Number 1 상태 (1.결제요청, 2.결제완료, 3.취소)
clnt_tx_ymd   String 8 낙찰일 (고객사 거래일자)
proc_dt 필수 TIMESTAMP   처리일시 (등록일시: 최초 처리일시)
va_no   String 20 가상계좌번호
tid   String 50 PG인증번호 (거래번호) 
HTTP 1.1 200 OK
{
    “buyr_bizr_no”: “1253258756”,
    “inqry_clf”: “1”,
    "plfm": "001",
    "inqry_st_ymd": "20240301",
    “inqry_ed_ymd“: “20240318”,
    “rst_cnt“: 2,
        "rst_data": [{
                    "plfm_nm" : "이스틸포유",
                    "plfm_cd" : "001",
                                    "ordr_no" : "SH231103001",
                    "gods_nm" : "철강 외",
                    "clnt_pay_clf_cd" : "SGLPAY",
                    "req_amt" : 77000000,
                    "ppay_amt" 33000000: ,
                    "chrg_amt" : 33000000,
                    "tot_tx_amt" : 110000000,
                    "pay_amt" : 110000000,
                    "clnt_tx_clf_cd" : "IMPL",
                    "dpst_stat_cd" : 1,
                    "clnt_tx_ymd" : "20240228",
                    "proc_dt" : "20240228140101",
                    "va_no" : "1234123412341234",
                    "tid" : " paytest0012023021820544062803448073 "
    },{
                    "plfm_nm" : "이스틸포유",
                    "plfm_cd" : "001",
                    "ordr_no" : "SH231103002",
                        .
                        .
                        .
    }]
}

결제수단 & 오류코드

결제수단

결제수단 코드 결제수단 코드 설명
selpay 통합결제창(간편결제, 신용카드, 신용카드(카드번호입력), 가상계좌 선택 UI 호출)
bizselpay 법인통합결제창(신용카드(카드번호입력), 가상계좌, 연계대출 선택 UI 호출)
va 가상계좌