국내 계좌 비밀번호 결제
반복 구매가 잦은 서비스에 이상적인 결제 방식입니다.
구매자가 페이플 결제창에서 계좌를 한 번 등록하면 이후부터는 비밀번호만으로 결제 요청이 가능합니다.
00연동 준비
페이플이 제공하는 테스트 정보를 통해 계약 전 단계에서도 누구나 연동 체험이 가능합니다.
테스트 환경 접속 정보
접속 도메인
https://democpay.payple.krcst_id
testcustKey
abcd1234567890clientKey
test_DF55F29DA654A8CBC0F0A9DD4B556486PCD_REFUND_KEY (결제취소 시 이용)
a41ce010ede9fcbfb3be86b24858806596a9db68b79d138b147c3e563e1829a0clientKey (체험하기 전용)
test_FD3876EF0522D8D6B7D9B783F858DC5A주의
요청 header 설정파트너 인증시 referer 헤더의 값을 결제창이 호출될 도메인으로 입력해주세요. 별도의 테스트 계정을 발급 받으신 경우, 도메인을 검증하므로 등록한 도메인이 포함된 referer로 설정해야합니다. 일치하지 않으면 가 반환됩니다.
참고
테스트 환경카드는 실제 결제 후 24시간 내 자동 취소, 계좌는 실제 출금 없음문서 바로가기웹훅결제 완료, 취소 완료, 결제수단 등록, 결제수단 해지 결과를 받아 누락을 막습니다문서 바로가기체험하기 키는 별도연동 코드에는 위 연동용 clientKey 를, 데모 콘솔 탭의 체험하기에는 전용 키를 씁니다.
환경별 키 분리테스트와 라이브는 clientKeycst_idcustKey 가 모두 다릅니다. 환경변수로 분리해두면 같은 인증 오류를 피할 수 있습니다.
통신 보안파트너사는 TLS v1.2 이상 / SSL 보안 통신(HTTPS)을 필수적으로 적용해야 합니다.
파라미터 값 유의사항
Emoji 등 한글, 영어, 숫자를 제외한 문자를 파라미터에 포함할 경우, 결제 또는 결제내역 조회가 정상적으로 처리되지 않을 수 있습니다.
모든 파라미터 값에는 이모지 사용을 지양해 주시기 바라며 파라미터에 사용 가능한 특수문자는 아래와 같습니다.
`!@#$%^*()_=-[]{};:./?01결제창 호출
client아래는 결제창 호출 시 사용 가능한 Request 파라미터 목록입니다.
| 파라미터 | 타입 | 설명 | 값 예시 |
|---|---|---|---|
| clientKey필수 | String 128 | 파트너 인증을 위한 클라이언트키입니다. 라이브 클라이언트키는 계약 완료 후 발급가능합니다. | test_DF55F29DA654A8CBC0F0A9DD4B556486 |
| PCD_PAY_TYPE필수 | String 20 | 결제수단(카드/계좌)을 선택합니다.카드 : card / 계좌: transfer | transfer |
| PCD_PAY_WORK필수 | String 20 | 승인 요청 방식이며 비밀번호 간편결제는 계좌 등록과 동시에 결제가 진행되므로 CERT로 설정합니다. | CERT |
| PCD_SIMPLE_FLAG필수 | String 1 | 비밀번호 간편결제 이용을 위한 설정값입니다. | Y |
| PCD_PAYER_AUTHTYPE필수 | String 3 | 비밀번호 이용을 위한 설정값입니다. | pwd |
| PCD_PAY_GOODS필수 | String 255 | 상품명입니다. Emoji 또는 허용되지 않은 특수문자(& ' " \ < > | \n \r\n , +)만으로 구성된 값은 입력할 수 없습니다. | 테스트 상품 |
| PCD_PAY_TOTAL필수 | Number 10 | 총 결제금액입니다. | 1000 |
| PCD_RST_URL필수 | String | 결제 정보가 성공적으로 입력된 경우, 인증 결과가 POST 방식으로 전송됩니다. 경로지정 방식에 따라 결제창이 다르게 띄워집니다. | https://result-domain.com |
| PCD_PAYER_ID필수 - 재결제 시 | String 255 | 재결제 시 필요한 빌링키입니다.첫결제 시에는 사용하지 않습니다. | OVA3… |
| PCD_PAY_OID | String 64 | 승인 요청 건의 주문번호로 파트너(상점)에서 생성한 거래의 고유 식별번호입니다. 중복되지 않는 고유한 값을 발급해야 하며, 미전송 시 페이플에서 발급한 주문번호를 응답합니다. 한글은 사용할 수 없으며 영문, 숫자, 특수문자(-, _, .)만 사용 가능합니다. | order12345 |
| PCD_PAYER_NO | Number 18 | 파트너(상점)에서 이용하는 회원번호입니다. | 1234 |
| PCD_PAYER_NAME | String 80 | 구매자 이름입니다. Emoji 또는 허용되지 않은 특수문자(& ' " \ < > | \n \r\n , +)만으로 구성된 값은 입력할 수 없습니다. | 김이플 |
| PCD_PAYER_HP | String 20 | 구매자 휴대폰번호입니다. 구매자에게 결제된 상점정보를 알림톡으로 발송합니다. | 01012345678 |
| PCD_PAYER_EMAIL | String 100 | 구매자 이메일입니다. 결제완료, 취소 메일이 발송됩니다. | complete@payer-email.com |
| PCD_PAY_ISTAX | String 1 | 과세 여부입니다. 기본값은 Y 이며, 유형별로 아래와 같이 설정해주세요.과세, 복합과세 : Y비과세 : N | Y |
| PCD_PAY_TAXTOTAL | Number 9 | 복합과세 주문 시에만 이용하며, 복합과세 주문의 부가세를 설정합니다.예 : 총 결제금액(PCD_PAY_TOTAL) 10,000원 중 복합과세 주문의 부가세가 500원이면 500으로 설정 | 500 |
| PCD_TAXSAVE_FLAG | String 1 | 현금영수증 발행창 호출 여부입니다. | Y |
| callbackFunction | - | 클라이언트단에서 결과수신이 필요할 경우 사용합니다. callbackFunction을 사용해도 PCD_RST_URL은 필수로 입력되어야 합니다. | getResult |
| PCD_USER_DEFINE1 | String 2048 | 파트너(상점)에서 입력한 값을 그대로 응답합니다. | define1 |
| PCD_USER_DEFINE2 | String 2048 | 파트너(상점)에서 입력한 값을 그대로 응답합니다. | define2 |
주의결제 요청 화면과 결제창이 서로 다른 브라우저나 웹뷰면 이 발생합니다. SameSite 설정도 함께 확인하세요.
02인증결과 수신
server결제 정보가 성공적으로 입력된 경우, 인증 결과는 POST 방식으로 PCD_RST_URL로 전송됩니다. 경로지정 방식에 따라 결제창이 다르게 띄워집니다.
주의
callbackFunction 안에 넣으면 안 되는 것callbackFunction 내부에 아래 요소가 있으면 XSS 공격으로 인식되어 요청이 차단될 수 있습니다.
HTML 주석(
HTML 주석(
<!-- -->), <div> <span> 같은 HTML 태그, <iframe> 태그. 필요하면 순수 텍스트로 바꿔 주세요.참고
PCD_RST_URL 경로에 따라 달라지는 결제창상대경로(예:
절대경로(예:
모바일에서 팝업 차단이 켜져 있으면 상대경로 방식은 창이 열리지 않습니다. 카카오톡, 페이스북 같은 인앱 브라우저에서 결제가 일어나면 절대경로(다이렉트)를 권장합니다.
/result)는 PC 에서 레이어팝업, 모바일에서 새 탭(새 창)으로 열립니다. PC 에서 범용적으로 쓰는 방식입니다.절대경로(예:
https://your-domain.com/result)는 결제창으로 화면이 바로 전환(다이렉트)됩니다. 모바일에 권장합니다.모바일에서 팝업 차단이 켜져 있으면 상대경로 방식은 창이 열리지 않습니다. 카카오톡, 페이스북 같은 인앱 브라우저에서 결제가 일어나면 절대경로(다이렉트)를 권장합니다.
SPA 에서 결과 받기SPA 처럼 화면 이동 없이 결과를 받으려면 결제창 요청에
callbackFunction 을 추가합니다. PCD_RST_URL 을 상대경로로 지정한 경우에만 쓸 수 있습니다.저장해두기
PCD_AUTH_KEY03 API로 승인 요청PCD_PAY_REQKEY03 API로 승인 요청PCD_PAYER_ID03 API로 승인 요청03API로 승인 요청
server주의
승인 전 원 주문 확인승인 요청이 이루어지면 실제 결제가 완료됩니다. 요청 전에 서버에 저장한 주문(
PCD_PAY_OID)의 금액과 인증결과의 PCD_PAY_TOTAL 이 같은지 확인하고, 다르면 승인하지 마세요.참고
Referer 헤더
Referer 에는 페이플에 등록된 파트너(상점)의 도메인을 정확히 넣어 주세요. 일치하지 않으면 AUTH0004 가 반환됩니다.받아서 넣기
PCD_AUTH_KEY02 인증결과 수신PCD_PAY_REQKEY02 인증결과 수신PCD_PAYER_ID02 인증결과 수신저장해두기
PCD_PAYER_ID05 운영POST테스트
https://democpay.payple.kr/php/PayConfirmAct.php?ACT_=PAYMPOST라이브
https://cpay.payple.kr/php/PayConfirmAct.php?ACT_=PAYM실결제 승인 과정에서 필요한 Request 파라미터는 다음과 같습니다.
| 파라미터 | 타입 | 설명 | 값 예시 |
|---|---|---|---|
| PCD_CST_ID필수 | String 12 | 파트너 인증을 위한 ID 입니다. 라이브 ID 는 계약이 완료되어야 발급 가능합니다. | test |
| PCD_CUST_KEY필수 | String 255 | 파트너 인증을 위한 키입니다. 라이브 키는 계약이 완료되어야 발급 가능합니다.외부에 노출되면 안되는 정보입니다. 보안에 유의해주세요. | abcd1234567890 |
| PCD_AUTH_KEY필수 | String | 인증결과로 수신하는 파트너 인증 키입니다. 파트너 인증 응답으로 받은 값을 그대로 사용해주세요. | K0VnW… |
| PCD_PAY_REQKEY필수 | String 255 | 인증결과로 수신하는 결제 키입니다. | Vnx... |
| PCD_PAYER_ID필수 | String 255 | 정기(빌링), 비밀번호 간편결제 시 필요한 설정값입니다. | OVA3… |
04재결제
client저장한 빌링키(PCD_PAYER_ID)를 결제창 요청에 추가하면 등록한 계좌의 비밀번호 입력창이 열립니다. 나머지 요청 값은 첫 결제와 같습니다. 구매자가 비밀번호를 입력하면 02 인증결과를 다시 받고, 03 과 같은 방식으로 승인을 요청합니다.
주의결제 요청 화면과 결제창이 서로 다른 브라우저나 웹뷰면 이 발생합니다. SameSite 설정도 함께 확인하세요.
05운영
ops결제가 끝나면 취소, 조회, 해지가 따라옵니다.
실제 연동 흐름상 결제 기능과 연계되는 부분이므로 이어 설명합니다.
POST테스트
https://democpay.payple.kr/php/account/api/cPayCAct.phpPOST라이브
https://cpay.payple.kr/php/account/api/cPayCAct.php