이 글의 목차
1. 정기결제란?
•
최초 1회 카드/계좌 정보 등록만 받고, 파트너사의 다양한 결제주기에 맞춰 자동으로 결제를 받을 수 있습니다.
페이플에서 제공하는 정기결제는 등록시 결제 스케줄링(예약)을 걸어 자동으로 결제가 발생하는 방식이 아닌 결제가 필요할 때마다 파트너가 발급된 빌링키(PCD_PAYER_ID)로 실시간으로 REST 결제요청을 진행하여 결제가 나는 방식입니다.
고객 입장에서는 한번의 결제수단 등록 후에 별도의 인증작업없이 결제가 일어나는 것으로 인식하게 됩니다.
)로 실시간으로 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
/*
* TEST : https://democpay.payple.kr/php/auth.php
* REAL : https://cpay.payple.kr/php/auth.php
*/
POST /php/auth.php HTTP/1.1
Host: democpay.payple.kr
Content-Type: application/json
Cache-Control: no-cache
referer: https://파트너사 도메인
/* ※ referer 설정 방법
* TEST : referer에는 테스트 결제창을 띄우는 도메인을 넣어주셔야합니다.
* 결제창을 띄울 도메인과 referer값이 다르면 [AUTH0007] 응답이 발생합니다.
* REAL : referer에는 파트너사 도메인으로 등록된 도메인을 넣어주셔야합니다.
* 다른 도메인을 넣으시면 [AUTH0004] 응답이 발생합니다.
* 또한, TEST에서와 마찬가지로 결제창을 띄우는 도메인과 같아야 합니다.
*/
{
"cst_id": "test",
"custKey": "abcd1234567890"
}
JSON
Referer에 '결제창을 띄우는 도메인'과 다른 도메인을 넣어서 보내실 경우, 결제창 호출이 차단 (AUTH0007 응답발생) 될 수 있으니 유의해주시기 바랍니다.
[AUTH0007]에 대한 설명을 이곳에서 확인해보세요.
에서 확인해보세요.PHP 샘플코드
JAVA 샘플코드
NODE 샘플코드
Referer에 대한 자세한 설명은 이곳에서 확인해보세요!
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)
•
파트너 인증 완료 후 결제창을 호출할 수 있는 스크립트를 작성하여 페이플에 요청합니다.
파트너 인증시 받은 AuthKey와 return_url Parameter 값을
각각 PCD_AUTH_KEY와PCD_PAY_URL에 추가하여 요청해주세요.
파트너 인증 후 Response 받은 AuthKey 값은
고정값이 아니므로 저장해놓고 계속해서 사용하면 안됩니다.
+ 한 번의 파트너 인증과 하나의 요청이 매칭되어야 합니다.
즉 한번의 파트너 인증으로 받은 AuthKey 값을 여러 요청에 사용하면 안됩니다.
결제없이 등록만을 수행할 때는 PCD_PAY_WORK 를 AUTH로 설정합니다.
결제와 동시에 등록을 수행할 때는 PCD_PAY_WORK 를 PAY로 설정합니다.
Request Message
Search
Search
PHP 샘플코드
JAVA 샘플코드
NODE 샘플코드
3-4. 등록 진행
고객 결제창
•
페이플에서 결제창을 고객의 브라우저에 호출시킵니다.
•
고객은 결제창에서 결제정보를 입력하여 등록을 완료합니다.
3-5. 결과 Response
페이플 서버
•
페이플에서 고객의 결제창을 종료시킵니다.
•
PCD_RST_URL로 고객의 브라우저를 리다이렉트(Redirect) 처리합니다.
•
파트너로 결과 리턴(Response)는 다음과 같이 진행됩니다.
◦
PCD_RST_URL 로 결과를 Response 합니다.
Search
◦
callbackFunction 을 사용한다면 PCD_RST_URL 을 대체하여 결과를 Response 합니다.
◦
Webhook URL 을 등록하였다면 페이플에서 해당 URL로 결과를 추가로 Response 합니다.
을 등록하였다면 페이플에서 해당 URL로 결과를 추가로 Response 합니다. - 페이플에서는 결과 수신실패 누락을 방지하기 위해 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
Search
Request sample
/*
* TEST : https://democpay.payple.kr
* REAL : https://cpay.payple.kr
*/
/* 결제요청 후 리턴받은 PCD_PAY_COFURL로 결제요청 재컨펌 (CERT) */
POST /php/PayCardConfirmAct.php?ACT_=PAYM HTTP/1.1
Host: democpay.payple.kr
Content-Type: application/json
Cache-Control: no-cache
{
"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
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
/*
* TEST : https://democpay.payple.kr/php/auth.php
* REAL : https://cpay.payple.kr/php/auth.php
*/
POST /php/auth.php HTTP/1.1
Host: democpay.payple.kr
Content-Type: application/json
Cache-Control: no-cache
referer: https://파트너사 도메인
/* ※ referer 설정 방법
* REAL : referer에는 파트너사 도메인으로 등록된 도메인을 넣어주셔야합니다.
* 다른 도메인을 넣으시면 [AUTH0004] 응답이 발생합니다.
*/
{
"cst_id": "test",
"custKey": "abcd1234567890",
"PCD_PAY_TYPE": "card",
"PCD_SIMPLE_FLAG": "Y
}
JSON
PHP 샘플코드
JAVA 샘플코드
NODE 샘플코드
Referer에 대한 자세한 설명은 이곳에서 확인해보세요!
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
Search
Search
Request sample
/*
* 재결제 요청
* TEST : https://democpay.payple.kr
* REAL : https://cpay.payple.kr
*/
POST 파트너 인증 후 리턴받은 PCD_PAY_URL HTTP/1.1
Host: 파트너 인증 후 리턴받은 PCD_PAY_HOST
Content-Type: application/json
Cache-Control: no-cache
{
"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
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" : "NS9qNTgzU2xRNHR2RmFBWWFBTWk5UT09"
"PCD_PAYER_NAME" : "홍길동"
"PCD_PAYER_HP" : "01012345678"
"PCD_PAYER_EMAIL" : "test@payple.kr"
"PCD_PAY_GOODS" : "상품1"
"PCD_PAY_TOTAL" : "100"
"PCD_PAY_TAXTOTAL" : ""
"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. 마무리
•
정기결제의 연동작업을 완료하였습니다! 축하드립니다!
