개발 전 확인이 필요한 공통적인 가이드
| API 구분 | API 리소스 경로 |
|---|---|
| 결제 요청 | POST v1.0/payments/request |
| 결제 승인 | POST v1.0/payments/confirm |
| 결제 취소 | POST v1.0/payments/cancel |
| 거래 확인서 | GET v1.0/receipt/info/{tid} |
| 결제 거래정보 조회 | GET v1.0/payments/confirm-info |
| 에스크로 배송등록 요청 | POST v1.0/regshpp |
*고객사 API의 미디어 타입은 “content-type application/json” 입니다.
고객사 결제 요청 용 API 입니다. 최소 승인 금액은 일반카드, 전용페이카드 100원, 계좌이체 1원, 제로페이 1원이며, 해당 금액 미만의 결제 요청은 처리되지 않습니다. 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 | 100 | 일반 신용카드(ISP) 결제 이후 이동할 고객사 앱 스키마 정보 *모바일 앱의 일반 신용카드 결제 요청 시 필수 값 입니다. |
| app_cancel_url | 선택적 필수 | string | 100 | 일반 신용카드(ISP) 결제 진행 중단 시 이동할 고객사 앱 스키마 정보 *모바일 앱의 일반 신용카드 결제 요청 시 필수 값 입니다. |
| 에스크로전용 | ||||
| escr_yn | Char | 1 | 에스크로여부(N:아니오, Y:예) 기본값은 “N:아니오” 입니다. * 에스크로를 사용하기로 동의 한 고객사에게만 적용 |
|
◎ 일반 신용카드 단일 결제를 요청하는 경우
{
"pgcode": "card",
"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”, // 고객사 화면에서 카드사를 선택하여 결제요청하는 경우 필수 설정
“prepay_amount”: 2000 // 선불전자지급수단을 사용할 경우 필수 설정
}
◎ 전용페이 카드 단일 결제를 요청하는 경우
{
"pgcode": "shpaycard",
"client_id": "o2o",
"user_id": "test_01",
"user_name": "테스터01",
"order_no": "202108311259590001",
"pay_type”: 1, // 단일 결제
"device_type": 1,
"amount": 11000,
"taxfree_amount": 0,
"tax_amount": 90,
"product_name": "테스트 상품",
“param_ispt_hash”:”821b7bf742abfb49c8e535ee9a0801c4e6cefe4d49c9c8209b8c54d5077082f8"
"email_flag": "Y",
"email_addr": "bae1222@payletter.com",
"pay_hash": "dfhuoi892ashiozxui123…”,
"custom_parameter": "asdfoxuoy12uyisadouydfouayiouf…",
"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",
"card_purpost_type": 1, // 신용카드는 필수 설정
"bill_key": "hoiu123yox134yauyxf", // 전용페이 결제수단 등록 시 발급되는 고유 식별 정보
“cup_return_deposit”: “100” , // 컵반환 보증금
“prepay_amount”: 2000 // 선불전자지급수단을 사용할 경우 필수 설정
}
◎ 일반 신용카드 & 제로페이 상품권 잔액 사용의 복합 결제를 요청하는 경우
{
"pgcode": "card",
"client_id": "o2o",
"user_id": "test_01",
"user_name": "테스터01",
"order_no": "202108311259590001",
"pay_type”: 2, // 2: 복합 일반(일반 신용카드 + 제로페이 상품권 잔액)
"device_type": 1,
"amount": 11000, // (제로페이 상품권 사용 잔액을 포함하는)총 결제 금액
"taxfree_amount": 0,
"tax_amount": 0,
"lwr_cp_bizr_reg_no": "1234567890", // 제로페이 결제 요청은 필수 설정
"product_category": “F", // 제로페이 결제 요청은 필수 설정
"product_name": "테스트 상품",
“param_ispt_hash”:”821b7bf742abfb49c8e535ee9a0801c4e6cefe4d49c9c8209b8c54d5077082f8"
"email_flag": "Y",
"email_addr": "bae1222@payletter.com",
"pay_hash": "dfhuoi892ashiozxui123…",
"custom_parameter": "asdfoxuoy12uyisadouydfouayiouf…",
"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",
"card_purpost_type": 1, // 일반 신용카드는 필수 설정
"app_return_url": "scheme://path", // 모바일 앱 환경의 일반 신용카드는 필수 설정
"app_cancel_url": "scheme://path", // 모바일 앱 환경의 일반 신용카드는 필수 설정
"zeropay_blnc_inqry_tid”: 1, // 제로페이 잔액 조회 거래번호
“cup_return_deposit”: “100”, // 컵반환 보증금
“prepay_amount”: 2000 // 선불전자지급수단을 사용할 경우 필수 설정
}
◎ 전용페이 계좌이체 & 제로페이 상품권 잔액 사용의 복합 결제를 요청하는 경우
{
"pgcode": "shpaybank",
"client_id": "o2o",
"user_id": "test_01",
"user_name": "테스터01",
"order_no": "202108311259590001",
"pay_type”: 3, // 3: 복합 전용(전용페이 + 제로페이 상품권 잔액)
"device_type": 1,
"amount": 11000, // (제로페이 상품권 사용 잔액을 포함하는)총 결제 금액
"taxfree_amount": 0,
"tax_amount": 0,
"lwr_cp_bizr_reg_no": "1234567890", // 제로페이 결제 요청은 필수 설정
"product_category": “F",
"product_name": "테스트 상품",
“param_ispt_hash”:”821b7bf742abfb49c8e535ee9a0801c4e6cefe4d49c9c8209b8c54d5077082f8"
"email_flag": "Y",
"email_addr": "bae1222@payletter.com",
"pay_hash": "dfhuoi892ashiozxui123…",
"custom_parameter": "asdfoxuoy12uyisadouydfouayiouf…",
"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",
"bill_key": "hoiu123yox134yauyxf…", // 전용페이 결제수단 등록 시 발급되는 고유 식별 정보
"zeropay_blnc_inqry_tid”: 1, // 제로페이 잔액 조회 거래번호
“cup_return_deposit”: “100” , // 컵반환 보증금
“prepay_amount”: 2000 // 선불전자지급수단을 사용할 경우 필수 설정
}
◎ 제로페이 상품권 사용 잔액 설정 후 별도 결제수단 없이 단일 결제를 요청하는 경우
{
"pgcode": "zeropay", // zeropay 필수 설정
"client_id": "o2o",
"user_id": "test_01",
"user_name": "테스터01",
"order_no": "202108311259590001",
"pay_type”: 1, // 단일 결제
"device_type": 1,
"amount": 1000, // (제로페이 상품권 사용 잔액을 포함하는)총 결제 금액
"taxfree_amount": 0,
"tax_amount": 0,
"lwr_cp_bizr_reg_no": "1234567890", // 제로페이 결제 요청은 필수 설정
"product_category": “F", // 제로페이 결제 요청은 필수 설정
"product_name": "테스트 상품",
“param_ispt_hash”:”821b7bf742abfb49c8e535ee9a0801c4e6cefe4d49c9c8209b8c54d5077082f8"
"email_flag": "Y",
"email_addr": "bae1222@payletter.com",
"pay_hash": "dfhuoi892ashiozxui123…",
"custom_parameter": "asdfoxuoy12uyisadouydfouayiouf…",
"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",
"zeropay_blnc_inqry_tid”: 1, // 제로페이 잔액 조회 거래번호
“cup_return_deposit”: “100”, // 컵반환 보증금
“prepay_amount”: 2000 // 선불전자지급수단을 사용할 경우 필수 설정
}
◎ 일반 신용카드 & 서울페이 상품권 잔액 사용의 복합 결제를 요청하는 경우
{
"pgcode": "card",
"client_id": "o2o",
"user_id": "test_01",
"user_name": "테스터01",
"order_no": "202108311259590001",
"pay_type”: 2, // 2: 복합 일반(일반 신용카드 + 제로페이 상품권 잔액)
"device_type": 1,
"amount": 11000, // (서울페이 상품권 사용 잔액을 포함하는)총 결제 금액
"taxfree_amount": 0,
"tax_amount": 0,
"product_name": "테스트 상품",
“param_ispt_hash”:”821b7bf742abfb49c8e535ee9a0801c4e6cefe4d49c9c8209b8c54d5077082f8",
"email_flag": "Y",
"email_addr": "bae1222@payletter.com",
"pay_hash": "dfhuoi892ashiozxui123…",
"custom_parameter": "asdfoxuoy12uyisadouydfouayiouf…",
"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",
"card_purpost_type": 1, // 일반 신용카드는 필수 설정
"app_return_url": "scheme://path", // 모바일 앱 환경의 일반 신용카드는 필수 설정
"app_cancel_url": "scheme://path", // 모바일 앱 환경의 일반 신용카드는 필수 설정
"seoulpay_blnc_inqry_tid”: 1, // 서울페이 잔액 조회 거래번호
“cup_return_deposit”: “100”, // 컵반환 보증금
“prepay_amount”: 2000 // 선불전자지급수단을 사용할 경우 필수 설정
}
◎ 전용페이 계좌이체 & 서울페이 상품권 잔액 사용의 복합 결제를 요청하는 경우
{
"pgcode": "shpaybank",
"client_id": "o2o",
"user_id": "test_01",
"user_name": "테스터01",
"order_no": "202108311259590001",
"pay_type”: 3, // 3: 복합 전용(전용페이 + 제로페이 상품권 잔액)
"device_type": 1,
"amount": 11000, // (서울페이 상품권 사용 잔액을 포함하는)총 결제 금액
"taxfree_amount": 0,
"tax_amount": 0,
"lwr_cp_bizr_reg_no": "1234567890", // 서울페이 결제 요청은 필수 설정
"product_name": "테스트 상품",
“param_ispt_hash”:”821b7bf742abfb49c8e535ee9a0801c4e6cefe4d49c9c8209b8c54d5077082f8",
"email_flag": "Y",
"email_addr": "bae1222@payletter.com",
"pay_hash": "dfhuoi892ashiozxui123…",
"custom_parameter": "asdfoxuoy12uyisadouydfouayiouf…",
"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",
"bill_key": "hoiu123yox134yauyxf…", // 전용페이 결제수단 등록 시 발급되는 고유 식별 정보
"seoulpay_blnc_inqry_tid”: 1, // 서울페이 잔액 조회 거래번호
“cup_return_deposit”: “100”, // 컵반환 보증금
“prepay_amount”: 2000 // 선불전자지급수단을 사용할 경우 필수 설정
}
◎ 서울페이 상품권 사용 잔액 설정 후 별도 결제수단 없이 단일 결제를 요청하는 경우
{
"pgcode": "seoulpay", // seoulpay 필수 설정
"client_id": "o2o",
"user_id": "test_01",
"user_name": "테스터01",
"order_no": "202108311259590001",
"pay_type”: 1, // 단일 결제
"device_type": 1,
"amount": 1000, // (서울페이 상품권 사용 잔액을 포함하는)총 결제 금액
"taxfree_amount": 0,
"tax_amount": 0,
"lwr_cp_bizr_reg_no": "1234567890", // 서울페이 결제 요청은 필수 설정
"product_name": "테스트 상품",
“param_ispt_hash”:”821b7bf742abfb49c8e535ee9a0801c4e6cefe4d49c9c8209b8c54d5077082f8",
"email_flag": "Y",
"email_addr": "bae1222@payletter.com",
"pay_hash": "dfhuoi892ashiozxui123…",
"custom_parameter": "asdfoxuoy12uyisadouydfouayiouf…",
"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",
"seoulpay_blnc_inqry_tid”: 1, // 서울페이 잔액 조회 거래번호
“cup_return_deposit”: “100”, // 컵반환 보증금
“prepay_amount”: 2000 // 선불전자지급수단을 사용할 경우 필수 설정
}
◎ 전용페이 계좌이체 & 서울페이 상품권 잔액 사용의 복합 결제를 요청하는 경우
{
"pgcode": "shpaybank",
"client_id": "o2o",
"user_id": "test_01",
"user_name": "테스터01",
"order_no": "202108311259590001",
"pay_type”: 3, // 3: 복합 전용(전용페이 + 제로페이 상품권 잔액)
"device_type": 1,
"amount": 11000, // (서울페이 상품권 사용 잔액을 포함하는)총 결제 금액
"taxfree_amount": 0,
"tax_amount": 0,
"lwr_cp_bizr_reg_no": "1234567890", // 서울페이 결제 요청은 필수 설정
"product_name": "테스트 상품",
“param_ispt_hash”:”821b7bf742abfb49c8e535ee9a0801c4e6cefe4d49c9c8209b8c54d5077082f8",
"email_flag": "Y",
"email_addr": "bae1222@payletter.com",
"pay_hash": "dfhuoi892ashiozxui123…",
"custom_parameter": "asdfoxuoy12uyisadouydfouayiouf…",
"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",
"bill_key": "hoiu123yox134yauyxf…", // 전용페이 결제수단 등록 시 발급되는 고유 식별 정보
"seoulpay_blnc_inqry_tid”: 1, // 서울페이 잔액 조회 거래번호
“cup_return_deposit”: “100”, // 컵반환 보증금
“prepay_amount”: 2000 // 선불전자지급수단을 사용할 경우 필수 설정
}
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| 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 입니다. 최소 승인 금액은 일반카드, 전용페이카드 100원, 계좌이체 1원이며, 해당 금액 미만의 결제 요청은 처리되지 않습니다.
| 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) 결제 이후 이동할 고객사 앱 스키마 정보 *모바일 앱의 일반 신용카드 결제 요청 시 필수 값 입니다. |
| app_cancel_url | 선택적 필수 | string | 100 | 일반 신용카드(ISP) 결제 진행 중단 시 이동할 고객사 앱 스키마 정보 *모바일 앱의 일반 신용카드 결제 요청 시 필수 값 입니다. |
| return_url | 필수 | string | 255 | 결제 인증 결과 수신 및 결제 승인 API를 호출하는 고객사 URL |
| cancel_url | 필수 | string | 255 | 결제 취소 시 이동하는 고객사 URL |
| fail_url | 필수 | string | 255 | 결제 실패 시 이동하는 고객사 URL |
| 현금영수증(개인)전용 | ||||
| cash_rcpt_pub_type | number | 현금 영수증 발행 유형 (1: 소득공제용, 2: 지출증빙용) *해당 요청 파라미터와 현금 영수증 발행 번호 유형, 현금 영수증 발행 번호 파라미터들의 값이 있으면 전용페이 계좌/가상계좌 결제 승인 이후 해당 정보들로 현금영수증을 발행 처리합니다. 만약 해당 요청 값들이 없으면 자진 발급번호로 발행 처리합니다. |
||
| cash_rcpt_pub_no_type | number | 현금 영수증 발행 번호 유형 (1: 휴대폰번호, 2: 사업자번호, 3: 자진발급 등 기타) *해당 요청 파라미터와 현금 영수증 발행 유형, 현금 영수증 발행 번호 파라미터들의 값이 있으면 전용페이 계좌/가상계좌 결제 승인 이후 해당 정보들로 현금영수증을 발행 처리합니다. 만약 해당 요청 값들이 없으면 자진 발급번호로 발행 처리합니다. |
||
| cash_rcpt_pub_no | string | 20 | 현금 영수증 발행 번호 (*발행 유형 "소득공제"는 휴대폰번호, “지출증빙"은 사업자 번호, 발행 유형 “자진 발급”은 국세청 지정 코드 "010-000-1234”을 발행 번호로 자체 발급 처리) *해당 요청 파라미터와 현금 영수증 발행 유형, 현금 영수증 발행 번호 유형 파라미터들의 값이 있으면 전용페이 계좌/가상계좌 결제 승인 이후 해당 정보들로 현금영수증을 발행 처리합니다. 만약 해당 요청 값들이 없으면 자진 발급번호로 발행 처리합니다. |
|
| 가상계좌(개인)전용 | ||||
| acct_key | String | 18 | 계좌키 (결제수단이 가상계좌일 때 고객사에서 부여) * 고정가상계좌를 사용하는 고객과 매칭시킨 계좌의 고유한 키값입니다. 특정고객에게 같은 가상계좌를 다시 발급하려면 처음 고정 가상계좌를 발급할 때 사용했던 계좌키를 설정해주세요. 최대갈이는 18자입니다 |
|
| 에스크로(개인)전용 | ||||
| escr_yn | Char | 1 | 에스크로여부(N:아니오, 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",
"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."
}
1.Html 내 script tag 추가
<script src="https://payspg.shinhan.com/businessPayment/unifiedPay/script" ></script>
2.통합결제창 결제요청 응답값 (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 통합결제 결제하기(인증) 완료 이후, 고객사의 return_url POST 데이터로 주문 및 승인 토큰 정보가 전달됩니다. return_url은 결제 요청 API에 전달한 파라미터 값을 의미합니다.
| Redirect URL | HTTP 메서드 |
|---|---|
| return_url | 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 | (가상계좌) 상품명 |
| 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분(토큰 만료) 안에 요청하여야 합니다.
전용페이 계좌이체는 전용페이 사용자 휴대폰 번호(본인인증 결과정보)로 현금영수증을 자동 발행합니다.
| 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) | ||||
| 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) | ||||
| list | JSON Array | - | ||
| gfct_cd | string | 20 | 상품권 코드 | |
| gfct_name | string | 50 | 상품권 명 | |
| gfct_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 입니다.
| 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 입니다.
| 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 입니다.
| URL | HTTP 메서드 | HTTP 헤더 | 토큰 유형 |
|---|---|---|---|
| v1.0/payments/confirm-info | GET | Authorization: SPGKEY {API Key} | search |
| 파라미터 | 필수 여부 | 자료형 | 크기 | 설명 |
|---|---|---|---|---|
| client_id | 필수 | string | 10 | 고객사 아이디 |
| order_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/escrow/shippmentreg | POST | Authorization: SPGKEY {API Key} | payment |
| 파라미터 | 필수 여부 | 자료형 | 크기 | 설명 |
|---|---|---|---|---|
| client_id | 필수 | string | 10 | 고객사아이디 |
| req_ymd | 필수 | string | 10 | 요청일자 (YYYY-MM-DD) |
| tid | 필수 | string | 40 | 거래번호(에스크로 결제 승인 TID) |
| ship_code | 필수 | string | 20 | 배송사코드 |
| invoice | 필수 | string | 20 | 운송장번호 |
| pay_date | string | 14 | 결제일시(YYYYMMDDhhmmss) | |
| proc_date | 필수 | string | 14 | 배송 처리 일시(YYYMMDDhhmmss) |
| changer_id | 옵션 | number | 10 | 변경자아이디 |
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| 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."
}
구매결정 처리 요청 API 입니다. 구매 확정하거나 구매 거절할 때 호출되어 선택 요건에 맞춰 처리합니다.
| URL | HTTP 메서드 | HTTP 헤더 | 키 유형 |
|---|---|---|---|
| v1.0/escrow/buydecision | POST | Authorization: SPGKEY {API Key} | payment |
| 파라미터 | 필수 여부 | 자료형 | 크기 | 설명 |
|---|---|---|---|---|
| client_id | 필수 | string | 10 | 고객사아이디 |
| req_ymd | 필수 | string | 10 | 요청일자 (YYYY-MM-DD) |
| tid | 필수 | string | 40 | 거래번호(에스크로 결제 승인 TID) |
| proc_date | 필수 | string | 14 | 구매결정 처리 일시(YYYMMDDhhmmss) |
| escrow_stat_code | 필수 | string | 1 | 에스크로 상태코드 형태 (구매확정,구매취소요청) |
| changer_id | 옵션 | number | 10 | 변경자아이디 |
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| 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."
}
구매거절(취소) 확정을 위한 API 입니다. 구매거절 요청이 있을 때, 판매자가 구매거절 확정할 수 있습니다.
| URL | HTTP 메서드 | HTTP 헤더 | 키 유형 |
|---|---|---|---|
| /v1.0/escrow/buycancelaprv | 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 | (고객사 사용자)아이피 주소 |
| escr_cncl_clf | 선택 | number | 1 | 에스크로취소구분. 1: 에스크로취소, 2:에스크로강제취소 * 1 : 에스크로거래.에스크로상태코드 = 6:구매취소요청 거래인 경우만 취소 실행 * 2 : 에스크로거래.에스크로상태 코드 값과 관계없이 취소 실행 |
| bank_cd | 선택 | String | 3 | 은행코드 |
| bank_acct_no | 선택 | String | 14 | 은행 계좌 번호 (환불받을 계좌번호) |
| bank_name | 선택 | String | 20 | 계좌주명 |
| param_ispt_hash | 필수 | string | 1000 | 파라미터 검증 해시 *고객사 요청 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256(client_id + tid + 결제 API Key)" 조합으로 생성된다. |
| changer_id | 옵션 | number | 10 | 변경자아이디 |
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| 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."
}
구매 부분취소 확정을 위한 API 입니다. 구매확정 후 부분취소 요청이 있을 때, 결제 부분취소 처리 진행한다.
| URL | HTTP 메서드 | HTTP 헤더 | 키 유형 |
|---|---|---|---|
| /v1.0/escrow/partialcancel | POST | Authorization: SPGKEY {API Key} | payment |
| 파라미터 | 필수 여부 | 자료형 | 크기 | 설명 |
|---|---|---|---|---|
| client_id | 필수 | string | 10 | 고객사 아이디 |
| user_id | 필수 | string | 50 | 고객사 사용자(회원) 아이디(이메일, 영문 및 숫자 가능) |
| tid | 필수 | string | 50 | (결제)거래 번호 |
| amount | 필수 | number | (부분 취소)금액 | |
| taxfree_amount | number | 비과세 금액 | ||
| tax_amount | number | 부가세 금액 *요청 파라미터 값이 없으면, ((amount - taxfree_amount) / 11) 계산식을 적용, 소수점 이하 반올림으로 자동 계산한다. |
||
| cncl_rsn | 필수 | string | 100 | 취소 사유 |
| ip_addr | 필수 | string | 50 | (고객사 사용자)아이피 주소 |
| bank_cd | 선택 | String | 3 | 은행코드 |
| bank_acct_no | 선택 | String | 14 | 은행 계좌 번호 (환불받을 계좌번호) |
| bank_name | 선택 | String | 20 | 계좌주명 |
| param_ispt_hash | 필수 | string | 1000 | 파라미터 검증 해시 *고객사 요청 파라미터 검증을 위한 sha256 hash 값을 의미하며, "sha256(client_id + tid + 결제 API Key)" 조합으로 생성된다. |
| changer_id | 옵션 | number | 10 | 변경자아이디 |
| 파라미터 | 자료형 | 크기 | 설명 |
|---|---|---|---|
| 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."
}
| 결제수단 코드 | 결제수단 코드 설명 |
|---|---|
| selpay | 통합결제창(간편결제, 신용카드, 신용카드(카드번호입력), 가상계좌 선택 UI 호출) |
| bizselpay | 법인통합결제창(신용카드(카드번호입력), 가상계좌, 연계대출 선택 UI 호출) |
| card | 일반 신용/체크카드 |
| nauthcard | 비인증 신용/체크카드 (개인/법인) |