1. 정기결제란?
•
최초 1회 카드/계좌 정보 등록만 받고, 파트너사의 다양한 결제주기에 맞춰 자동으로 결제를 받을 수 있습니다.
페이플에서 제공하는 정기결제는 등록시 결제 스케줄링(예약)을 걸어 자동으로 결제가 발생하는 방식이 아닌 결제가 필요할 때마다 파트너가 발급된 빌링키(PCD_PAYER_ID
)로 실시간으로 REST 결제요청을 진행하여 결제가 나는 방식입니다.
고객 입장에서는 한번의 결제수단 등록 후에 별도의 인증작업없이 결제가 일어나는 것으로 인식하게 됩니다.
•
아래 링크를 클릭해서 정기결제 방식을 직접 체험해보세요.
◦
카드를 이용한 체험링크입니다. 등록 테스트 후 자동 해지됩니다.
◦
계좌를 이용한 체험링크입니다. 등록 테스트 후 자동 해지됩니다.
◦
REST 재결제 체험
발급된 빌링키로 REST 재결제하는 방식은 현재 체험하실 수 없습니다.
직접 연동테스트로 진행하셔야 합니다.
다른 결제방식의 연동방식을 안내받고 싶다면 이곳
을 클릭해서 확인해보세요.
2. 프로세스 개요
정기결제는 페이플 결제창에서 결제정보를 입력하여 등록하는 1단계와 등록된 빌링키(PCD_PAYER_ID)로 REST 재결제를 하는 2단계로 구분됩니다.
2-1. 등록 단계 프로세스
2-2. REST 재결제 프로세스
3. 첫등록& 첫결제
3-1. 서비스 신청버튼 클릭
고객 결제페이지(Web)
•
고객이 파트너의 쇼핑몰에서 정기결제(혹은 구독서비스)를 위해 결제수단 등록을 신청하였습니다.
3-2. 파트너 인증
파트너 서버
•
파트너는 요청을 할 수 있는 사전 준비 단계인 파트너 인증 프로세스를 진행합니다.
Request Message
기본 보기
Search
Request sample
•
Header 정보
/*
* Request HTTP URL
* TEST : https://democpay.payple.kr/php/auth.php
* REAL : https://cpay.payple.kr/php/auth.php
*/
Request URL: "https://democpay.payple.kr/php/auth.php"
HTTP Method: POST
Content-Type: application/json
Cache-Control: no-cache
Referer: "https://파트너사 도메인"
/* ※ Referer 설정 방법
* TEST : referer에는 테스트 결제창을 띄우는 도메인을 넣어주셔야합니다.
* 결제창을 띄울 도메인과 referer값이 다르면 [AUTH0007] 응답이 발생합니다.
* REAL : referer에는 파트너사 도메인으로 등록된 도메인을 넣어주셔야합니다.
* 다른 도메인을 넣으시면 [AUTH0004] 응답이 발생합니다.
* 또한, TEST에서와 마찬가지로 결제창을 띄우는 도메인과 같아야 합니다.
*/
JSON
Referer에 '결제창을 띄우는 도메인'과 다른 도메인을 넣어서 보내실 경우, 결제창 호출이 차단 (AUTH0007 응답발생) 될 수 있으니 유의해주시기 바랍니다.
[AUTH0007]에 대한 설명을 이곳
에서 확인해보세요.
Referer에 대한 자세한 설명은 이곳에서 확인해보세요!
•
Body(Payload) 값
{
"cst_id": "test",
"custKey": "abcd1234567890"
}
JSON
PHP 샘플코드
JAVA 샘플코드
NODE 샘플코드
Response Message
•
파트너 인증이 성공하면 페이플에서 파트너에 다음과 같은 성공 리턴을 드립니다.
기본 보기
Search
Response sample
{
"server_name": "요청 URL"
"result": "결과확인"
"result_msg": "결과 메시지"
"cst_id": "파트너사 아이디"
"custKey": "파트너사 키"
"AuthKey": "파트너사 인증토큰",
"PCD_PAY_HOST": "요청 도메인, (예: https://democpay.payple.kr)"
"PCD_PAY_URL": "요청 URL, (예: /auth.php)"
"return_url": "요청 URL (PCD_PAY_HOST + PCD_PAY_URL)"
}
JSON
실패 리턴 (result = error)을 받으신 경우,
result_msg 의 응답코드를 확인하고 잘못된 부분을 수정합니다.
응답코드 리스트는 이 곳
에서 확인하실 수 있습니다.
3-3. 등록 요청
파트너 결제페이지(Web)
•
파트너 인증 완료 후 결제창을 호출할 수 있는 스크립트를 추가하여 페이플에 요청합니다.
<!-- Payple JavaScript 호출. (테스트/운영 선택) -->
<script src="https://democpay.payple.kr/js/cpay.payple.1.0.1.js">< /script> <!-- 테스트 -->
<script src="https://cpay.payple.kr/js/cpay.payple.1.0.1.js">< /script> <!-- 운영 -->
PHP
페이플 결제창 스크립트 추가
샘플코드는 파라미터 정보 하단과 연동가이드 > 샘플코드에서 확인해보세요!
파트너 인증시 받은 AuthKey와 return_url Parameter 값을
각각 PCD_AUTH_KEY와PCD_PAY_URL에 추가하여 요청해주세요.
파트너 인증 후 Response 받은 AuthKey 값은
고정값이 아니므로 저장해놓고 계속해서 사용하면 안됩니다.
+ 한 번의 파트너 인증과 하나의 요청이 매칭되어야 합니다.
즉 한번의 파트너 인증으로 받은 AuthKey 값을 여러 요청에 사용하면 안됩니다.
결제없이 등록만을 수행할 때는 PCD_PAY_WORK 를 AUTH로 설정합니다.
결제와 동시에 등록을 수행할 때는 PCD_PAY_WORK 를 PAY로 설정합니다.
Request Message
Show All
Search
Show All
Search
PHP 샘플코드
JAVA 샘플코드
NODE 샘플코드
3-4. 등록 진행
고객 결제창
•
페이플에서 결제창을 고객의 브라우저에 호출시킵니다.
•
고객은 결제창에서 결제정보를 입력하여 등록을 완료합니다.
3-5. 결과 Response
페이플 서버
•
페이플에서 고객의 결제창을 종료시킵니다.
•
PCD_RST_URL로 고객의 브라우저를 리다이렉트(Redirect) 처리합니다.
◦
callbackFunction으로 결제결과를 수신할 경우, 콜백함수로 결제결과가 반환되며
PCD_RST_URL로 고객의 브라우저를 리다이렉트(Redirect) 처리합니다.
•
파트너로 결과 리턴(Response)은 다음과 같이 진행됩니다.
Show All
Search
•
callbackFunction 을 사용한다면 PCD_RST_URL 을 대체하여 결과를 반환합니다.
•
- 페이플에서는 결과 수신실패 누락을 방지하기 위해 Webhook URL 등록을 권장합니다.
- 테스트 서버에서는 별도의 계정을 발급받지 않는 한 Webhook URL 등록 및 테스트가 불가합니다.
- 테스트 서버에서 Webhook URL을 테스트하기 위해서 help@payple.kr 로 연락주시면 파트너 전용 테스트 계정을 발급하여 드립니다.
- Webhook URL 등록 없이 테스트하시려면 PCD_RST_URL 로 수신받은 Response 데이터로 결과를 처리합니다.
3-6. 결과 처리
파트너 서버
파트너에서 페이플에서 받은 Response 데이터로 결과를 처리합니다.
•
PCD_PAY_RST = success, PCD_PAY_CODE = "0000"이 포함될 경우 요청성공으로 판단합니다.
•
PCD_PAY_RST = error 일 경우 요청실패로 판단합니다.
•
PCD_PAY_RST = close 일 경우 요청실패로 판단합니다.
고객이 결제창을 결제 중 종료할 경우 리턴됩니다.
3-6-1. 요청이 성공했을 경우(success)
•
데이터 위변조 여부를 판별하기 위해 리턴받은 PCD_PAY_TOTAL 값과 요청했던 값을 대조하여 이상이 없음을 확인합니다.
결제 없이 등록만 처리하는 (PCD_PAY_WORK = AUTH) 경우에는
PCD_PAY_TOTAL 값이 없으므로 대조하지 않습니다.
•
거래를 요청했던 고객에게 약정된 서비스를 제공합니다.
•
Response 데이터 중 PCD_PAYER_ID 값을 고객DB에 매칭하여 저장합니다.
◦
재결제 이벤트시 해당 고객의 PCD_PAYER_ID를 사용해야 합니다.
3-6-2. 요청이 실패했을 경우(error / close)
•
PCD_PAY_CODE 와 PCD_PAY_MSG 로 원인을 파악하여 대응합니다.
•
응답코드 리스트
를 확인해보세요.
3-7 결제요청 재컨펌 (PCD_PAY_WORK: CERT)
파트너 서버
최종 결제요청을 위해 REST API를 통해 결제를 요청할 수 있습니다.
PAY(즉시결제) 방식과 달리 CERT(결제요청 재컨펌) 방식에서는 최종 승인 요청을 별도로 보내야합니다.
결제창을 호출하여 결제를 하는 경우, 결제요청 방식 파라미터인 PCD_PAY_WORK를
CERT(파트너 확인 후 결제)와 PAY(브라우저에서 즉시결제) 중 하나로 지정하여야 합니다.
결제요청 방식에 대한 자세한 설명은 파라미터 정의: PCD_PAY_WORK
에서 확인해보세요!
결제요청 재컨펌(CERT) 방식은 아래와 같은 프로세스로 결제가 진행됩니다.
•
1 ~ 4 : PAY와 마찬가지로 결제창을 브라우저에 호출하여 결제요청을 보내고 결과를 받습니다.
이때, 응답결과를 받아도 아직 결제는 완료되지 않습니다.
다음 단계까지 모두 완료해야, 즉 결제 최종승인요청을 보내야 결제가 완료됩니다.
•
5 ~ 8 : 인증결과 및 결제준비완료 리턴을 받은 후, 페이플 서버로 결제 최종승인 요청을 보내고
결과를 받습니다. 이때, 결제결과가 'success'면 결제 완료로 판단합니다.
결제요청 재컨펌(CERT)에 해당하는 부분은 5 ~ 8 입니다.
결제요청 재컨펌(CERT) 결제 프로세스
Request Message
Show All
Search
Request sample
•
Header 정보
/*
* Request HTTP URL
* ※결제요청 후 리턴받은 PCD_PAY_COFURL로 설정해주세요.
* TEST : https://democpay.payple.kr/php/PayCardConfirmAct.php?ACT_=PAYM
* REAL : https://cpay.payple.kr/php/PayCardConfirmAct.php?ACT_=PAYM
*/
Request URL: "https://democpay.payple.kr/php/PayCardConfirmAct.php?ACT_=PAYM"
HTTP Method: POST
Content-Type: application/json
Cache-Control: no-cache
Referer: http://localhost:8080
JSON
•
Body(Payload) 값
{
"PCD_CST_ID":"test",
"PCD_CUST_KEY": "abcd1234567890",
"PCD_AUTH_KEY": "결제요청 후 리턴받은 PCD_AUTH_KEY",
"PCD_PAY_REQKEY": "결제요청 후 리턴받은 PCD_PAY_REQKEY",
"PCD_PAYER_ID": "결제요청 후 리턴받은 PCD_PAYER_ID"
}
JSON
Response Message
Show All
Search
•
카드결제(CERT) Response Sample
Response sample
{
"PCD_PAY_RST": "success"
"PCD_PAY_CODE": "PCCF0000"
"PCD_PAY_MSG": "카드결제완료"
"PCD_PAY_REQKEY": "d2NtOFExTVF..."
"PCD_PAY_OID": "test123456789"
"PCD_PAY_TYPE": "card"
"PCD_PAYER_ID": "YWpJQXZ..."
"PCD_PAYER_NO": "1234"
"PCD_PAYER_NAME": "홍길동"
"PCD_PAYER_HP": "01012345678"
"PCD_PAYER_EMAIL": "test@payple.kr"
"PCD_PAY_GOODS": "상품명1"
"PCD_PAY_AMOUNT": "100"
"PCD_PAY_AMOUNT_REAL": "100"
"PCD_PAY_TOTAL": "100"
"PCD_PAY_TAXTOTAL": "0"
"PCD_PAY_ISTAX": "Y"
"PCD_PAY_CARDNAME": "NH"
"PCD_PAY_CARDNUM": "1234********5678"
"PCD_PAY_CARDTRADENUM": "202110201407049643824400"
"PCD_PAY_CARDAUTHNO": "12345678"
"PCD_PAY_CARDRECEIPT": "https://www.danalpay.com/receipt/creditcard/view..."
"PCD_PAY_TIME": "20211020140706"
"PCD_SIMPLE_FLAG": "N"
}
JSON
4. 재결제
등록 후 약정된 결제일이 다가왔습니다.
파트너는 고객에게 결제를 받아야 할 시점에 맞춰 페이플로 결제 요청을 준비합니다.
페이플에서는 별도의 스케줄링을 하지 않기 때문에, 파트너사에서 스케줄링 부분을 작업해주셔야 합니다.
4-1. 재결제 프로세스
4-2 파트너 인증
파트너 서버
REST로 재결제시 파트너 인증에서는 결제창을 호출했을 때와는 다르게
PCD_PAY_TYPE 와 PCD_SIMPLE_FLAG Parameter가 추가로 사용됩니다.
Request Message
기본 보기
Search
Request sample
•
Header 정보
/*
* Request HTTP URL
* TEST : https://democpay.payple.kr/php/auth.php
* REAL : https://cpay.payple.kr/php/auth.php
*/
Request URL: "https://democpay.payple.kr/php/auth.php"
HTTP Method: POST
Content-Type: application/json
Cache-Control: no-cache
referer: https://파트너사 도메인
/* ※ referer 설정 방법
* REAL : referer에는 파트너사 도메인으로 등록된 도메인을 넣어주셔야합니다.
* 다른 도메인을 넣으시면 [AUTH0004] 응답이 발생합니다.
*/
JSON
Referer에 대한 자세한 설명은 이곳에서 확인해보세요!
•
Body(Payload) 값
{
"cst_id": "test",
"custKey": "abcd1234567890",
"PCD_PAY_TYPE": "card",
"PCD_SIMPLE_FLAG": "Y"
}
JSON
PHP 샘플코드
JAVA 샘플코드
NODE 샘플코드
Response Message
•
파트너 인증이 성공하면 페이플에서 파트너에 다음과 같은 성공 리턴을 드립니다.
기본 보기
Search
Response sample
{
"server_name": "요청 URL"
"result": "결과확인"
"result_msg": "결과 메시지"
"cst_id": "파트너사 아이디"
"custKey": "파트너사 키"
"AuthKey": "파트너사 인증토큰",
"PCD_PAY_HOST": "요청 도메인, (예: https://democpay.payple.kr)"
"PCD_PAY_URL": "요청 URL, (예: /auth.php)"
"return_url": "요청 URL (PCD_PAY_HOST + PCD_PAY_URL)"
}
JSON
실패 리턴 (result = error)을 받으신 경우,
result_msg 의 응답코드를 확인하고 잘못된 부분을 수정합니다.
응답코드 리스트는 이 곳
에서 확인하실 수 있습니다.
4-3. 결제 요청
파트너 서버
•
파트너 인증 완료 후 페이플 서버로 결제 요청을 진행합니다.
•
이때 파트너 인증 후 Response 받은 cst_id, custKey, AuthKey 값을
각각 PCD_CST_ID, PCD_CUST_KEY, PCD_AUTH_KEY 에 넣어보내야 합니다.
파트너 인증 후 Response 받은 cst_id, custKey,AuthKey 값은
고정값이 아니므로 저장해놓고 계속해서 사용하면 안됩니다.
+ 한 번의 파트너 인증과 하나의 요청이 매칭되어야 합니다.
즉 한번의 파트너 인증으로 받은 cst_id, custKey,AuthKey 값을
여러 요청에 사용하면 안됩니다.
PCD_PAY_OID Parameter는 거래의 고유식별번호입니다.
요청시마다 유니크하게 새로 지정해 주세요.
PCD_PAY_OID 가 중복되면 처음 처리완료된 거래보다
나중에 들어온 거래요청건은 중복시도로 판단되어 거절됩니다.
→ 이러한 이유로, 파트너사에서 유니크하게 주문번호를 지정할 수 없을 경우에는
주문번호는 미지정하는 것을 권장하고 있습니다.
※ 파트너가 주문번호를 미지정 시, 페이플에서는 임의의 주문번호를 생성하여 리턴하여 드립니다.
Request Message
Show All
Search
Show All
Search
Request sample
•
Header 정보
/*
* 재결제(빌링키 결제) 요청
* Request HTTP URL
* ※파트너 인증 후 리턴받은 return_url로 설정해주세요.
* (return_url = PCD_PAY_HOST + PCD_PAY_URL)
* TEST : https://democpay.payple.kr/(파트너 인증 후 리턴 받은 요청 URL(PCD_PAY_URL))
* REAL : https://cpay.payple.kr/(파트너 인증 후 리턴 받은 요청 URL(PCD_PAY_URL))
*/
Request URL: "https://democpay.payple.kr/(파트너 인증후 리턴받은 PCD_PAY_URL)"
HTTP Method: POST
Content-Type: application/json
Cache-Control: no-cache
Referer: http://localhost:8080
JSON
•
Body(Payload) 값
{
"PCD_CST_ID": "파트너 인증 후 리턴받은 cst_id",
"PCD_CUST_KEY": "파트너 인증 후 리턴받은 custKey",
"PCD_AUTH_KEY": "파트너 인증 후 리턴받은 AuthKey",
"PCD_PAY_TYPE": "card",
"PCD_PAYER_ID": "d0to...",
"PCD_PAY_GOODS": "상품1",
"PCD_PAY_TOTAL": "100",
"PCD_SIMPLE_FLAG": "Y"
}
JSON
Response Message
Show All
Search
Response sample
{
"PCD_PAY_RST": "success|error"
"PCD_PAY_CODE": "SPCD0000"
"PCD_PAY_MSG": "카드결제완료|카드결제실패"
"PCD_PAY_OID": "test201804000001"
"PCD_PAY_TYPE": "card"
"PCD_PAYER_NO": "1234"
"PCD_PAYER_ID": "NS9qNTgzU2xRNHR2RmFB..."
"PCD_PAYER_NAME": "홍길동"
"PCD_PAYER_HP": "01012345678"
"PCD_PAYER_EMAIL": "test@payple.kr"
"PCD_PAY_GOODS": "상품1"
"PCD_PAY_TOTAL": "100"
"PCD_PAY_TAXTOTAL": "0"
"PCD_PAY_ISTAX": "Y"
"PCD_PAY_TIME": "20200323130201"
"PCD_PAY_CARDNANE": "BC 카드"
"PCD_PAY_CARDNUM": "12345678****1234"
"PCD_PAY_CARDTRADENUM": "201904141320332692022400"
"PCD_PAY_CARDAUTHNO": "98123445"
"PCD_PAY_CARDRECEIPT": "https://www.danalpay.."
"PCD_SIMPLE_FLAG": "Y"
}
JSON
4-4. 결과 처리
파트너 서버
파트너에서 페이플에서 받은 Response 데이터로 결과를 처리합니다.
•
PCD_PAY_RST = success, PCD_PAY_CODE = "0000"이 포함될 경우 요청성공으로 판단합니다.
•
PCD_PAY_RST = error 일 경우 요청실패로 판단합니다.
4-4-1. 요청이 성공했을 경우(success)
•
데이터 위변조 여부를 판별하기 위해 리턴받은 PCD_PAY_TOTAL 값과 요청했던 값을 대조하여 이상이 없음을 확인합니다.
•
리턴받은 거래 고유식별번호인 PCD_PAY_OID를 확인하여 요청했던 거래 정보와 매칭시킵니다.
•
거래를 요청했던 고객에게 약정된 서비스를 제공합니다.
4-4-2. 요청이 실패했을 경우(error / close)
•
PCD_PAY_CODE 와 PCD_PAY_MSG 로 원인을 파악하여 대응합니다.
•
응답코드 리스트
를 확인해보세요.
5. 마무리
•
정기결제의 연동작업을 완료하였습니다! 축하드립니다!