1. 정의
•
지급이체 실행(execute)이란 지급이체 요청(request)을 보낸 요청건에 대해 지급이체 수행을 요청하는 기능입니다.
지급이체 실행(execute)은 지급이체 요청(request)시 요청한 건들에 대해서만 수행할 수 있습니다.
⦁ 지급이체 요청(request) 후 받은 그룹키(group_key)를 기준으로 지급이체를 수행합니다.
지급이체 실행(execute) 전 필수로 해야하는 지급이체 요청(request)에 대한 자세한 설명은 여기에서 확인해보세요!
에서 확인해보세요!2. 프로세스 개요
3. 토큰발급
파트너 서버
•
파트너 인증을 위한 토큰발급을 진행해야합니다.
발급받은 access_token은 이후 다른 요청에서 필요하며, 토큰의 만료기간(60초)이 지나면 다시 토큰을 발급받으셔야 합니다.
⦁ 파트너에서는 access_token 유효기간에 맞춰서 유효한 토큰값 유지를 위한 로직을 구현하셔야 합니다.
페이플 허브에서는 사용자 인증을 OAuth 2.0으로 진행합니다.
Request Message
code는 반드시 영문자+숫자만 포함하여 10자만 입력해야합니다.
기본 보기
Search
요청 파라미터의 Type 보는 방법에 대해 더 자세히 알아보세요!
에 대해 더 자세히 알아보세요!Request sample
•
Header 정보
/*
* Request HTTP URL
* TEST : https://demohub.payple.kr/oauth/token
* REAL : https://hub.payple.kr/oauth/token
*/
Request HTTP URL: "https://demohub.payple.kr/oauth/token"
HTTP Method: POST
Content-Type: application/json
Cache-Control: no-cache
JSON
•
Body(Payload) 값
{
"cst_id":"test",
"custKey":"abcd1234567890",
"code":"as12345678"
}
JSON
Response Message
•
토큰발급 요청이 성공하면 페이플에서 파트너에 다음과 같은 성공 리턴을 드립니다.
기본 보기
Search
Response sample
{
"result":"T0000",
"message":"처리 성공",
"code":"as12345678",
"access_token":"eyJhlNDlj...",
"token_type":"Bearer",
"expires_in":"60"
}
JSON
result= "T0000", message= "처리 성공"인 경우 요청 성공으로 판단합니다.
발급받은 access_token은 모든 요청에 Authorization 값으로 필요합니다.
4. 지급이체 실행(execute)
파트너 서버
•
파트너는 토큰발급 및 지급이체 요청(request) 후 지급이체 요청건의 지급이체 실행(execute)을 수행합니다.
Request Message
기본 보기
Search
•
지급이체 실행 요청 파라미터 중 특히 유의해야하는 부분에 대해 확인해보세요.
지급이체 실행 요청시, billing_tran_id의 값에 따라 지급이체 되는 범위가 달라집니다.
⦁ ALL
- group_key에 속한 모든 지급이체 요청건들의 지급이체가 실행됩니다.
※ 모든 요청건의 지급이체 실행은 스케줄링을 거는 방식이기 때문에
지급이체 실행이 최대 1분 후에 시작될 수 있습니다.
⦁ (특정 빌링키)
- group_key에 속한 특정 빌링키의 요청건만 지급이체가 실행됩니다.
group_key는 지급이체 요청(request)시 Response 받은 값을 넣어주셔야 합니다.
⦁ 지급이체 실행(execute)을 모두 완료하여 지급이체 요청건이 남아있지 않은
group_key로 지급이체 실행(execute)을 수행하면 요청이 거부됩니다.
⦁ 지급이체 실행(execute)을 수행하면 group_key에 아직 지급이체 하지 않은 요청건들이
남아있더라도, 지급이체 요청(request)시 gruop_key는 새로 생성됩니다.
group_key는 어떤 방식으로 묶이나요?
group_key는 지급이체 요청(request)시 최초로 생성되며 지급이체 실행(execute)전까지는 해당 그룹키로 요청건이 묶입니다. 다시 말해서, 지급이체 실행(execute)이후 새로운 지급이체 요청(request)시, 새로운 그룹키가 발급되는 것입니다.
group_key에 대한 자세한 설명은 이곳에서 확인해보세요!
에서 확인해보세요!webhook_url은 테스트(TEST) 요청시에만 (cst_id = “test”) 필수값이며, 운영(REAL) 요청시 보내면 해당 값은 무시됩니다.
•
별도의 테스트 계정을 발급받아 테스트 하는 경우, 파트너사의 테스트 계정에 등록된 Webhook URL로 지급이체 결과가 발송됩니다.
요청 파라미터의 Type 보는 방법에 대해 더 자세히 알아보세요!
에 대해 더 자세히 알아보세요!Request example
•
Header 정보
/*
* Request HTTP URL
* TEST : https://demohub.payple.kr/transfer/execute
* REAL : https://hub.payple.kr/transfer/execute
*/
Request HTTP URL: "https://demohub.payple.kr/transfer/execute"
HTTP Method: POST
Content-Type: application/json
Cache-Control: no-cache
Authorization: Bearer, Access Token
JSON
$arrObHeader = array (
"Authorization: Bearer $paypleToken[access_token]",
"Accept: application/json"
);
PHP
PHP - Header 값 설정 예시
•
Body(Payload) 값
{
"cst_id":"test",
"custKey":"abcd1234567890",
"group_key":"Q0RSSkYzWUI3...",
"billing_tran_id":"ALL",
"execute_type":"NOW",
"webhook_url":"http://test.payple.kr/webhook" // 테스트 계정으로 요청시에만 필요
}
JSON
Response Message
•
지급이체 실행(execute) 요청이 성공하면 페이플에서 파트너에 다음과 같은 성공 리턴을 드립니다.
해당 응답은 지급이체 실행(execute) 요청에 대한 응답이고,
실제 지급이체가 실행된 결과는 웹훅(Webhook)으로 전송하고 있습니다.
기본 보기
Search
Response example
{
"result":"A0000",
"message":"처리 성공",
"cst_id":"test",
"group_key":"Q0RSSkYzWUI3...",
"billing_tran_id":"ALL",
"tot_tran_amt":"5000",
"remain_amt":"9995000",
"execute_type":"NOW",
"api_tran_dtm":"20211022152040289"
}
JSON
result= "A0000", message= "처리 성공"인 경우 요청성공으로 판단합니다.
지급이체 실행 결과 Return
•
지급이체 실행(execute)의 결과, 즉 실제 지급이체가 완료된 결과는 웹훅(Webhook)으로 전송하고 있습니다.
지급이체 실행 완료 결과는 지급이체 요청(request)건별로 결과를 전송하고 있습니다.
즉, 하나의 그룹키(group_key)의 지급이체 결과가 아닌, 하나의 요청건별로 결과를 받아보실 수 있습니다.
예시) 그룹키 A에 지급이체 요청이 총 5건이 있고,
모든 요청건에 대한 지급이체 실행시(ALL),
웹훅으로 보내지는 결과는 (요청건별로 보내지기 때문에) 총 5건입니다.
응답 결과
◦
지급이체 성공 : result="A0000" , message="처리 성공"
◦
지급이체 지연 : result="A0003" , result="A0007"
지급이체 지연응답을 받은경우, 페이플 고객센터(help@payple.kr)로 문의바랍니다.
◦
지급이체 실패 : 이외 응답 결과
기본 보기
Search
Response example
{
"result": "A0000",
"message": "처리 성공",
"cst_id": "test",
"sub_id": "test12385610",
"group_key": "Q0RSSkYzWUI3...",
"distinct_key": "6u7a166805...",
"billing_tran_id": "6fen3g2m-j9hb-...",
"api_tran_id": "ohr8ps3m-j5x...",
"api_tran_dtm": "20211025142315647",
"bank_tran_id": "M202112389U142315646",
"bank_tran_date": "20211025",
"bank_rsp_code": "000",
"bank_code_std": "020",
"bank_code_sub": "0000000",
"bank_name": "우리은행",
"account_num": "1234567890123456",
"account_num_masked": "1234567890123***",
"account_holder_name": "홍길동",
"print_content": "정산테스트",
"tran_amt": "1000"
}
JSON
지급이체 실행결과 웹훅 예시
웹훅(Webhook)에 대한 자세한 설명은 여기에서 확인해보세요!
에서 확인해보세요!특정 사유에 의해 지급이체가 실패할 경우 빌링키를 다시 사용할 수 없습니다.
자세한 내용은 를 확인해주세요.