Search
▶️

지급이체 실행(execute) API

1. 정의

지급이체 실행(execute)이란 지급이체 요청(request)을 보낸 요청건에 대해 지급이체 수행을 요청하는 기능입니다.
지급이체 실행(execute)은 지급이체 요청(request)시 요청한 건들에 대해서만 수행할 수 있습니다. ⦁ 지급이체 요청(request) 후 받은 그룹키(group_key)를 기준으로 지급이체를 수행합니다.
그룹키(group_key)에 대한 자세한 설명은 여기에서 확인해보세요!

2. 프로세스 개요

3. 토큰발급

파트너 서버
파트너 인증을 위한 토큰발급을 진행해야합니다.
발급받은 access_token은 이후 다른 요청에서 필요하며, 토큰의 만료기간(60초)이 지나면 다시 토큰을 발급받으셔야 합니다. ⦁ 파트너에서는 access_token 유효기간에 맞춰서 유효한 토큰값 유지를 위한 로직을 구현하셔야 합니다.
페이플 허브에서는 사용자 인증을 OAuth 2.0으로 진행합니다.

Request Message

code는 반드시 영문자+숫자만 포함하여 10자만 입력해야합니다.
기본 보기
Search
파라미터 정보
Parameter
더 알아보기
Request Value
필수
Type (Length)
Reference
custKey
Open
"abcd1234567890"
Y
aN(255)
파트너 인증키
code
Open
"as12345678"
Y
aN(10)
파트너용 토큰 확인 코드
요청 파라미터의 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
Parameter
더 알아보기
Response Value
Reference
Type
result
Open
"T0000"
응답 코드
String
message
Open
"처리 성공"
응답 메시지
String
code
Open
"as12345678"
파트너용 토큰 확인 코드
String
access_token
Open
"eyJhlNDlj..."
발행된 Access Token
String
token_type
Open
"Bearer" (고정값)
Access Token 유형
String
expires_in
Open
"60"
Access Token 만료 기간(초)
String
COUNT6
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
Parameter
더 알아보기
Request Value
필수
Type (Length)
Reference
cst_id
Open
"test"
Y
aN(8)
파트너 ID
custKey
Open
"abcd1234567890"
Y
aN(255)
파트너 인증키
group_key
Open
"Q0RSSkYzWUI3..."
Y
aN(64)
실행 그룹 키
billing_tran_id
Open
[ "6fen3g2m-j9hb-..." | "ALL" ]
Y
aNS(40)
(실명 인증된) 계좌 빌링키
execute_type
Open
"NOW"
Y
A
실행 구분 - 즉시이체
webhook_url
Open
"http://test.payple.kr/webhook"
Y
테스트시 지급이체결과를 받을 웹훅 URL
지급이체 실행 요청 파라미터 중 특히 유의해야하는 부분에 대해 확인해보세요.
지급이체 실행 요청시, 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
Parameter
더 알아보기
Response Value
Reference
Type
result
Open
"A0000"
응답 코드
String
message
Open
"처리 성공"
응답 메시지
String
cst_id
Open
"test"
파트너 ID
String
group_key
Open
"Q0RSSkYzWUI3..."
실행 그룹 키
String
billing_tran_id
Open
[ "6fen3g2m-j9hb-..." | "ALL" ]
(실명 인증된) 계좌 빌링키
String
tot_tran_amt
Open
"5000"
총 지급이체금액
String
remain_amt
Open
"9995000"
지급이체 한도 잔여금액
String
execute_type
Open
"NOW"
실행 구분 - 즉시이체
String
api_tran_dtm
Open
"20211022152040289"
지급이체일시(밀리세컨드)
String
COUNT9
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
Parameter
더 알아보기
Response Value
Reference
Type
result
Open
"A0000"
응답 코드
String
message
Open
"처리 성공"
응답 메시지
String
cst_id
Open
"test"
파트너 ID
String
sub_id
Open
"test12385610"
파트너사 하위고객 ID
String
distinct_key
Open
“c9z116521650283...”
파트너사 중복방지키
String
group_key
Open
"UGtpaHJJTDkxd..."
실행 그룹 키
String
billing_tran_id
Open
"6fen3g2m-j9hb-..."
(실명 인증된) 계좌 빌링키
String
api_tran_id
Open
"411ga67b-azzg-..."
지급이체 고유키
String
api_tran_dtm
Open
"20211022152040289"
지급이체일시(밀리세컨드)
String
bank_tran_id
Open
"M202112389U152040289"
은행 거래고유번호
String
bank_tran_date
Open
"20211022"
지급이체일자
String
bank_rsp_code
Open
"000"
지급이체기관 응답코드
String
bank_code_std
Open
"020"
지급이체기관 표준코드
String
bank_code_sub
Open
"1234567"
지급이체기관 점별코드
String
bank_name
Open
"우리은행"
지급이체기관명
String
account_num
Open
"1234567890123456"
계좌번호
String
account_num_masked
Open
"1234567890123***"
계좌번호(마스킹처리)
String
account_holder_name
Open
"홍길동"
계좌예금주명
String
print_content
Open
"정산테스트"
입금계좌인자내역
String
tran_amt
Open
"1000"
지급이체금액
String
COUNT20
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)에 대한 자세한 설명은 여기에서 확인해보세요!
특정 사유에 의해 지급이체가 실패할 경우 빌링키를 다시 사용할 수 없습니다. 자세한 내용은 를 확인해주세요.