개발 전 확인이 필요한 공통적인 가이드
| API 구분 | API 리소스 경로 |
|---|---|
| 정기결제 신청(비인증 카드) | POST v1.0/rpay/req |
| 정기결제 신청(전용페이) | POST v1.0/rpay/xclv-pay-req |
| 정기결제 승인 | POST v1.0/rpay/confirm |
| 정기결제 해지 | POST v1.0/rpay/rels |
*고객사 API의 미디어 타입은 “content-type application/json” 입니다.
정기결제 신청 API입니다. 정기결제빌키(rpay_billkey)와 카드빌키(card_billkey)가 발급되며 정기결제 승인요청 전에 신청이 필요 합니다.
| URL | HTTP 메서드 | HTTP 헤더 | 토큰 유형 |
|---|---|---|---|
| v1.0/rpay/req | POST | Authorization: SPGKEY {API Key} | payment |
| 파라미터 | 필수 여부 | 자료형 | 크기 | 설명 |
|---|---|---|---|---|
| pgcode | 필수 | string | 10 | 결제수단 코드(5. 결제수단 & 오류코드 참조) * 결제수단 : nauthcard 비인증 고정 |
| client_id | 필수 | string | 10 | 고객사 아이디 |
| user_id | 필수 | string | 50 | 고객사 사용자(회원) 아이디(이메일, 영문 및 숫자 가능) |
| user_name | 필수 | string | 20 | 고객사 사용자(회원) 명 |
| product_id | 필수 | string | 10 | (결제)상품 아이디 |
| product_name | 필수 | string | 50 | (결제)상품 명 |
| amount | 필수 | number | (결제 상품)금액 | |
| 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) / 11) 계산식을 적용, 소수점 이하 반올림으로 자동 계산합니다. |
||
| mphn_no | string | 15 | 휴대폰번호 | |
| email_addr | string | 50 | 메일 주소 | |
| return_url | 필수 | string | 100 | 정기결제 등록 이후 이동하는 고객사 URL |
| cancel_url | 필수 | string | 200 | 정기결제 등록 취소 시 이동하는 고객사 URL |
| fail_url | 필수 | string | 200 | 정기결제 등록 실패 시 이동하는 고객사 URL |
| param_ispt_hash | 필수 | string | 1000 | 파라메터 검증 해시 *고객사 요청 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256(client_id + user_id + product_id + payment API Key)" 조합으로 생성된다. |
| pay_amt_cnfm_yn | 필수 | char | 1 | 결제금액확인유무 (Y: 사용[기본값], N: 사용 안 함) |
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| 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",
"user_id": "test_01",
"rpay_billkey": "auoh1238u123uy...",
"card_billkey": "hkjf1238u123uy...",
}
HTTP 1.1 401 Unauthorized
{
"ret_code": 998,
"ret_msg": "token is missing or incorrect."
}
결제 요청 API의 redirect_url 을 이용하여, 고객사 사용자에게 PG 웹 화면을 출력합니다.
| Redirect URL | HTTP 메서드 |
|---|---|
| redirect_url | GET |
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| ret_code | number | 응답 코드 | |
| ret_msg | string | 100 | 응답 메시지 |
| user_id | string | 50 | 고객사 사용자(회원) 아이디(이메일, 영문 및 숫자 가능) |
| rpay_billkey | string | 50 | 정기결제빌키 |
| card_billkey | string | 50 | 카드빌키 |
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| ret_code | number | 응답 코드 | |
| ret_msg | string | 100 | 응답 메시지 |
HTTP 1.1 200 OK
{
"ret_code": 0,
"ret_msg": "OK",
"user_id": "test_01",
"rpay_billkey": "auoh1238u123uy...",
"card_billkey": "hkjf1238u123uy...",
}
HTTP 1.1 401 Unauthorized
{
"ret_code": 998,
"ret_msg": "token is missing or incorrect."
}
전용페이 정기결제 신청 API입니다. 정기결제 승인요청 전에 신청이 필요 합니다.
| URL | HTTP 메서드 | HTTP 헤더 | 토큰 유형 |
|---|---|---|---|
| v1.0/rpay/xclv-pay-req | POST | Authorization: SPGKEY {API Key} | payment |
| 파라미터 | 필수 여부 | 자료형 | 크기 | 설명 |
|---|---|---|---|---|
| pgcode | 필수 | string | 10 | 결제수단 코드(5. 결제수단 & 오류코드 참조) shpaycard 고정. * bill_key 있으면 바로 신청처리. * bill_key 없으면 결제수단 선택 화면 호출 |
| client_id | 필수 | string | 10 | 고객사 아이디 |
| user_id | 필수 | string | 50 | 고객사 사용자(회원) 아이디(이메일, 영문 및 숫자 가능) |
| user_name | 필수 | string | 20 | 고객사 사용자(회원) 명 |
| product_id | 필수 | string | 10 | (결제)상품 아이디 |
| product_name | 필수 | string | 50 | (결제)상품 명 |
| amount | 필수 | number | (결제 상품)금액 | |
| 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) 계산식을 적용, 소수점 이하 반올림으로 자동 계산합니다. |
||
| mphn_no | string | 15 | 휴대폰번호 | |
| email_addr | string | 50 | 메일 주소 | |
| return_url | 필수 | string | 100 | 정기결제 등록 이후 이동하는 고객사 URL |
| cancel_url | 필수 | string | 200 | 정기결제 등록 취소 시 이동하는 고객사 URL |
| fail_url | 필수 | string | 200 | 정기결제 등록 실패 시 이동하는 고객사 URL |
| param_ispt_hash | 필수 | string | 1000 | 파라메터 검증 해시 *고객사 요청 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256(client_id + user_id + product_id + payment API Key)" 조합으로 생성된다. |
| bill_key | string | 50 | 빌 키 (전용페이 결제수단 등록 시 발급되는 고유 식별 정보) * bill_key 있으면 바로 신청처리. * bill_key 없으면 결제수단 선택 화면 호출. |
|
| user_ci | 선택적 필수 | string | 88 | 고객사 사용자 CI(Connecting information) * bill_key가 없을때 필수. |
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| 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."
}
결제수단을 shpay 로 요청했을 경우 결제 요청 API의 redirect_url 을 이용하여, 고객사 사용자에게 PG 웹 화면을 출력합니다.
| Redirect URL | HTTP 메서드 |
|---|---|
| redirect_url | GET |
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| ret_code | number | 응답 코드 | |
| ret_msg | string | 100 | 응답 메시지 |
| user_id | string | 50 | 고객사 사용자(회원) 아이디(이메일, 영문 및 숫자 가능) |
| rpay_billkey | string | 50 | 정기결제빌키 |
| card_billkey | string | 50 | 카드빌키 |
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| ret_code | number | 응답 코드 | |
| ret_msg | string | 100 | 응답 메시지 [땡겨요전용] “정기결제 카드등록에 실패하였습니다. 카드 등록 전환이 필요합니다.” 8002 에러 메시지 응답시.. 4.34 전용페이 카드등록 전환을 위한 등록카드 삭제 요청 API 처리 필요. |
HTTP 1.1 200 OK
{
"ret_code": 0,
"ret_msg": "OK",
"user_id": "test_01",
"rpay_billkey": "auoh1238u123uy...",
"card_billkey": "hkjf1238u123uy...",
}
HTTP 1.1 401 Unauthorized
{
"ret_code": 998,
"ret_msg": "token is missing or incorrect."
}
정기결제 승인 요청을 한다.
| URL | HTTP 메서드 | HTTP 헤더 | 토큰 유형 |
|---|---|---|---|
| v1.0/rpay/confirm | POST | Authorization: SPGKEY {API Key} | payment |
| 파라미터 | 필수 여부 | 자료형 | 크기 | 설명 |
|---|---|---|---|---|
| client_id | 필수 | string | 10 | 고객사 아이디 |
| total_count | number | (요청) 리스트 건수 | ||
| list | JSON Array | - | list는 최대 50건까지 가능. *승인건을 120건 요청하고 싶을 때 50,50,20 나눠서 요청해야함. |
|
| user_id | 필수 | string | 50 | 고객사 사용자(회원) 아이디(이메일, 영문 및 숫자 가능) |
| user_name | 필수 | string | 20 | 고객사 사용자(회원) 명 |
| order_no | 필수 | string | 50 | 고객사 주문번호 |
| rpay_billkey | 필수 | string | 50 | 정기결제빌키 |
| card_billkey | 필수 | string | 50 | 카드빌키 구인증카드결제 : 정기결제빌키 전용페이카드결제 : 전용페이빌키 |
| amount | 필수 | number | (결제 상품)금액 | |
| 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) 계산식을 적용, 소수점 이하 반올림으로 자동 계산합니다. |
||
| product_id | string | 10 | (결제)상품 아이디 | |
| product_name | 필수 | string | 50 | (결제)상품 명 |
| mphn_no | string | 15 | 휴대폰번호 | |
| param_ispt_hash | 필수 | string | 1000 | 파라메터 검증 해시 *고객사 요청 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256(client_id + user_id + product_id + payment API Key)" 조합으로 생성된다. |
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| total_count | number | (응답) 총 건수 | |
| list | JSON Array | list는 최대 50건. | |
| ret_code | number | 응답 코드 | |
| ret_msg | string | 100 | 응답 메시지 |
| user_id | string | 50 | 고객사 사용자(회원) 아이디(이메일, 영문 및 숫자 가능) |
| user_name | string | 20 | 고객사 사용자(회원) 명 |
| tid | string | 50 | (결제)거래 번호 |
| tx_amount | number | (결제)거래 금액 | |
| tx_stat | number | (결제)거래 상태 (1: 승인, 2: 취소, 3: 부분취소) | |
| tx_date | string | 19 | 거래 일시(YYYY-MM-DD HH:MM:SS) |
| crcd_cpny_cd | string | 4 | 카드사 코드 |
| card_aprv_no | string | 50 | 카드 승인 번호 |
| product_name | string | 50 | (결제)상품 명 |
| rpay_billkey | string | 50 | 정기결제빌키 |
| card_billkey | string | 50 | 카드빌키 |
HTTP 1.1 200 OK
{
“total_count”: 2,
"list": [
{
"ret_code": 0,
"ret_msg": "OK",
"user_id": "test_01",
“user_name”:”홍길동”,
"tid": "202108311259590006",
"tax_amount": "10,00",
"tx_stat": 2,
"tx_date": "2021-12-22 12:59:59",
"crcd_cpny_cd": "S005",
"card_name”: “고객 요청”,
“card_no”:” 1234*****01”,
“card_aprv_no”:”55445”,
“product_name”:”테스트 상품1”,
"rpay_billkey": "auoh1238u123uy...",
"card_billkey": "hkjf1238u123uy..."
},
{
"ret_code": 0,
"ret_msg": "OK",
"user_id": "test_02",
“user_name”:”홍길동”,
"tid": "202108311259590007",
"tax_amount": "10,00",
"tx_stat": 2,
"tx_date": "2021-12-22 12:59:59",
"crcd_cpny_cd": "S005",
"card_name”: “고객 요청”,
“card_no”:” 1234*****01”,
“card_aprv_no”:”55445”,
“product_name”:”테스트 상품2”,
"rpay_billkey": "auoh6655u123uy...",
"card_billkey": "hkjf6446u123uy..."
}
]
}
정기결제 해지 요청을 한다.
| URL | HTTP 메서드 | HTTP 헤더 | 토큰 유형 |
|---|---|---|---|
| v1.0/rpay/rels | POST | Authorization: SPGKEY {API Key} | payment |
| 파라미터 | 필수 여부 | 자료형 | 크기 | 설명 |
|---|---|---|---|---|
| client_id | 필수 | string | 10 | 고객사 아이디 |
| user_id | 필수 | string | 50 | 고객사 사용자(회원) 아이디(이메일, 영문 및 숫자 가능) |
| rpay_billkey | 필수 | string | 50 | 정기결제빌키 |
| param_ispt_hash | 필수 | string | 1000 | 파라메터 검증 해시 *고객사 요청 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256(client_id + user_id + product_id + payment 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": "token is missing or incorrect."
}
| 결제수단 코드 | 결제수단 코드 설명 |
|---|---|
| nauthcard | 비인증 신용/체크카드 (개인/법인) |