국내 정산금 이체
페이플 정산지급대행은 페이플이 파트너(플랫폼)에게 정산할 금액을 플랫폼이 지정한 셀러의 계좌로 자동으로 지급하는 서비스입니다.
주말 및 공휴일과 같은 비영업일에도 실시간 이체가 가능합니다.
00연동 준비
페이플이 제공하는 테스트 정보를 통해 계약 전 단계에서도 누구나 연동 체험이 가능합니다.
테스트 환경 접속 정보
접속 도메인
https://demohub.payple.krcst_id
testcustKey
abcd1234567890참고
연동 전 확인사항화이트(White) IP 등록, 테스트 환경(demo)문서 바로가기웹훅이체실행 완료 결과를 받아 누락을 막습니다문서 바로가기환경별 키 분리테스트와 라이브는 cst_idcustKey 가 다릅니다. 환경변수로 분리해두세요.
통신 보안파트너사는 TLS v1.2 이상 / SSL 보안 통신(HTTPS)을 필수적으로 적용해야 합니다.
01파트너 인증 요청
server참고
요청마다 새 토큰파트너 인증은 매 요청마다 필요합니다. 발급된 토큰(
access_token)은 60초간 유효합니다.POST테스트
https://demohub.payple.kr/oauth/tokenPOST라이브
https://hub.payple.kr/oauth/token파트너 인증에 필요한 Request 파라미터는 아래와 같습니다.
| 파라미터 | 타입 | 설명 | 값 예시 |
|---|---|---|---|
| cst_id필수 | String 12 | 파트너 인증을 위한 ID 입니다. 라이브 ID 는 계약이 완료되어야 발급 가능합니다. | test |
| custKey필수 | String 255 | 파트너 인증을 위한 키입니다. 라이브 키는 계약이 완료되어야 발급 가능합니다.외부에 노출되면 안되는 정보입니다. 보안에 유의해주세요. | abcd1234567890 |
| code필수 | String 10 | 파트너 인증에 필요한 토큰을 확인하는 용도로 사용되며, 파트너(상점)가 직접 생성하여 전송해야 하는 중요한 요소입니다.영문+숫자 조합 10자리로 구성되어야 합니다. | as12345678 |
02계좌조회 요청
server파트너 인증 후 REST API를 사용해 계좌 조회를 요청하면, 예금주 이름이 반환됩니다.
저장해두기
sub_id03 빌링키로 이체 대기 요청billing_tran_id03 빌링키로 이체 대기 요청POST테스트
https://demohub.payple.kr/inquiry/real_namePOST라이브
https://hub.payple.kr/inquiry/real_name파트너 인증 후 계좌조회 요청 시 필요한 Request 파라미터는 아래와 같습니다.
| 파라미터 | 타입 | 설명 | 값 예시 |
|---|---|---|---|
| cst_id필수 | String 255 | 파트너 인증을 위한 ID 입니다. 라이브 ID 는 계약이 완료되어야 발급 가능합니다. | test |
| custKey필수 | String 255 | 파트너 인증을 위한 키입니다. 라이브 키는 계약이 완료되어야 발급 가능합니다.외부에 노출되면 안되는 정보입니다. 보안에 유의해주세요. | abcd1234567890 |
| bank_code_std필수 | String 3 | 금융기관 코드입니다. | 020 |
| account_num필수 | String 16 | 계좌번호입니다. | 1234567890123456 |
| account_holder_info_type필수 | String 1 | 예금주 구분 코드입니다.0 : 개인, 개인사업자6 : 법인사업자 | 0 |
| account_holder_info필수 | String 10 | 예금주 생년월일(사업자번호)입니다.개인, 개인사업자 : 생년월일 6자리(YYMMDD)법인사업자 : 사업자번호 10자리 | 880212 |
| sub_id | String 64 | 파트너 하위 셀러의 ID 입니다. | sub01 |
03빌링키로 이체 대기 요청
server계좌조회가 성공적으로 완료된 후에는 대기 단계가 시작되며, 이 단계에서는 실제 이체가 이루어지지 않습니다.
받아서 넣기
billing_tran_id02 계좌조회 요청sub_id02 계좌조회 요청저장해두기
group_key04 이체 실행 요청billing_tran_id04 이체 실행 요청POST테스트
https://demohub.payple.kr/transfer/requestPOST라이브
https://hub.payple.kr/transfer/request파트너 인증 후 이체대기 요청 시 필요한 Request 파라미터는 아래와 같습니다.
| 파라미터 | 타입 | 설명 | 값 예시 |
|---|---|---|---|
| cst_id필수 | String 255 | 파트너 인증을 위한 ID 입니다. 라이브 ID 는 계약이 완료되어야 발급 가능합니다. | test |
| custKey필수 | String 255 | 파트너 인증을 위한 키입니다. 라이브 키는 계약이 완료되어야 발급 가능합니다.외부에 노출되면 안되는 정보입니다. 보안에 유의해주세요. | abcd1234567890 |
| billing_tran_id필수 | String 40 | 계좌조회 완료된 계좌의 빌링키입니다. | cb9d695e-c034-4eeb-9550-c53a9ab7c2e4 |
| tran_amt필수 | String 12 | 이체할 금액입니다.테스트 시에는 금액을 1000으로 고정해야 합니다. 이 금액 이외의 다른 값으로 요청하실 경우 오류가 발생하여 요청이 거부될 수 있으니 이 점을 유의하시기 바랍니다. | 1000 |
| sub_id | String 64 | 파트너 하위 셀러의 ID 입니다. | sub01 |
| distinct_key | String 64 | 중복 이체를 방지하기 위한 키입니다. 미입력 시 페이플에서 자동 발급됩니다. | c9z116521650283… |
| print_content | String Byte 가 아닌 자릿수(6자) | 상대방 계좌 거래 내역에 표시될 수 있는 최대 6자까지의 문구입니다. 미입력 시 파트너(상점) 상호명으로 표시됩니다. | 테스트입니다 |
04이체 실행 요청
server이체 대기가 성공적으로 완료된 후에 실제 이체가 진행되는 단계입니다. 아래의 내용을 주의 깊게 확인해주세요.
참고
빌링키
billing_tran_id값에 따라 그룹키 group_key에 속한 대기 건의 이체 실행이 결정됩니다.- ALL :
group_key에 속한 모든 대기 건의 이체가 진행됩니다. - 특정 빌링키 :
group_key에 속한 특정 빌링키 대기 건의 이체가 진행됩니다.
group_key 는 이체 대기를 수행한 여러 건을 하나의 그룹으로 묶는 역할을 하며, 이체 실행 요청 시 이 그룹키를 기준으로 실제 이체가 진행됩니다.- 특정 빌링키
group_key내의 여러 건 중 일부만 이체 실행이 완료되었을 경우, 나머지 미실행 건들은 기존group_key에 계속 묶여 있습니다.
받아서 넣기
group_key03 빌링키로 이체 대기 요청billing_tran_id03 빌링키로 이체 대기 요청저장해두기
group_key06 운영billing_tran_id06 운영execute_type06 운영POST테스트
https://demohub.payple.kr/transfer/executePOST라이브
https://hub.payple.kr/transfer/execute파트너 인증 후 이체 실행 요청 시 필요한 Request 파라미터는 아래와 같습니다.
| 파라미터 | 타입 | 설명 | 값 예시 |
|---|---|---|---|
| cst_id필수 | String 255 | 파트너 인증을 위한 ID 입니다. 라이브 ID 는 계약이 완료되어야 발급 가능합니다. | test |
| custKey필수 | String 255 | 파트너 인증을 위한 키입니다. 라이브 키는 계약이 완료되어야 발급 가능합니다.외부에 노출되면 안되는 정보입니다. 보안에 유의해주세요. | abcd1234567890 |
| group_key필수 | String 40 | 이체 대기 요청 후 수신한 그룹키로 이체 실행을 진행합니다.그룹키 내의 여러 건 중 일부만 이체 실행이 완료되었을 경우, 나머지 미실행 건들은 기존 그룹키에 계속 묶여 있습니다. | QlJKZDZrNVBzbW9Yc1UzTWNIdW05dz09 |
| billing_tran_id필수 | String 40 | 계좌의 빌링키입니다.ALL : 그룹키에 속한 모든 대기 건의 이체가 진행특정 빌링키 : 그룹키에 속한 특정 빌링키 대기 건의 이체가 진행 | cb9d695e-c034-4eeb-9550-c53a9ab7c2e4 |
| execute_type필수 | String 8 | 이체 실행을 위한 구분값입니다.NOW : 즉시 이체 실행CANCEL : 대기 중인 이체 취소 | NOW |
| webhook_url필수 - 테스트 시 | String 255 | 이체 실행 결과를 수신하는 주소입니다. 테스트 서버로 요청시에만 필요합니다. | http://your-test-domain.com |
05결과 수신
server이체가 성공적으로 완료되면, 결과는 웹훅을 통해 건별로 수신됩니다.
예를 들어, 그룹키 A에 묶인 5건의 이체 대기 건이 있을 경우, 모든 대기 건에 대해 ALL로 이체를 실행하면, 결과적으로 총 5건의 이체 결과를 수신하게 됩니다.
저장해두기
group_key06 운영billing_tran_id06 운영api_tran_id06 운영참고이체실행을 ALL 로 한 번 요청해도 웹훅은 이체 건마다 따로 옵니다. 5건을 실행하면 5번 수신합니다.
06운영
ops대기 중인 이체의 조회, 취소, 실행 결과 조회, 이체 가능 잔액 조회에 쓰는 API 입니다.
필요한 기능만 골라 연동하세요.
POST테스트
https://demohub.payple.kr/transfer/executePOST라이브
https://hub.payple.kr/transfer/execute