국내 정산금 이체
페이플 정산지급대행은 페이플이 파트너(플랫폼)에게 정산할 금액을 플랫폼이 지정한 셀러의 계좌로 자동으로 지급하는 서비스입니다.
주말 및 공휴일과 같은 비영업일에도 실시간 이체가 가능합니다.
00연동 준비
페이플 가입 계약 심사가 완료되면 테스트 계정이 발급되며, 발급받은 테스트 계정으로 연동을 체험할 수 있습니다.
https://demohub.payple.kr발급받은 cst_id발급받은 custKey01파트너 인증 요청
serveraccess_token)은 60초간 유효합니다.https://demohub.payple.kr/oauth/tokenhttps://hub.payple.kr/oauth/token파트너 인증에 필요한 Request 파라미터는 아래와 같습니다.
| 파라미터 | 타입 | 설명 | 값 예시 |
|---|---|---|---|
| cst_id필수 | String 12 | 파트너 인증을 위한 ID 입니다. 라이브 ID 는 계약이 완료되어야 발급 가능합니다. | 발급받은 cst_id |
| custKey필수 | String 255 | 파트너 인증을 위한 키입니다. 라이브 키는 계약이 완료되어야 발급 가능합니다.외부에 노출되면 안되는 정보입니다. 보안에 유의해주세요. | 발급받은 custKey |
| code필수 | String 10 | 파트너 인증에 필요한 토큰을 확인하는 용도로 사용되며, 파트너(상점)가 직접 생성하여 전송해야 하는 중요한 요소입니다.영문+숫자 조합 10자리로 구성되어야 합니다. | 영문+숫자 10자리 (직접 생성) |
02계좌조회 요청
server파트너 인증 후 REST API를 사용해 계좌 조회를 요청하면, 예금주 이름이 반환됩니다.
sub_id03 빌링키로 이체 대기 요청billing_tran_id03 빌링키로 이체 대기 요청https://demohub.payple.kr/inquiry/real_namehttps://hub.payple.kr/inquiry/real_name파트너 인증 후 계좌조회 요청 시 필요한 Request 파라미터는 아래와 같습니다.
| 파라미터 | 타입 | 설명 | 값 예시 |
|---|---|---|---|
| cst_id필수 | String 255 | 파트너 인증을 위한 ID 입니다. 라이브 ID 는 계약이 완료되어야 발급 가능합니다. | 발급받은 cst_id |
| custKey필수 | String 255 | 파트너 인증을 위한 키입니다. 라이브 키는 계약이 완료되어야 발급 가능합니다.외부에 노출되면 안되는 정보입니다. 보안에 유의해주세요. | 발급받은 custKey |
| 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 계좌조회 요청distinct_key06 운영group_key04 이체 실행 요청billing_tran_id04 이체 실행 요청https://demohub.payple.kr/transfer/requesthttps://hub.payple.kr/transfer/request파트너 인증 후 이체대기 요청 시 필요한 Request 파라미터는 아래와 같습니다.
| 파라미터 | 타입 | 설명 | 값 예시 |
|---|---|---|---|
| cst_id필수 | String 255 | 파트너 인증을 위한 ID 입니다. 라이브 ID 는 계약이 완료되어야 발급 가능합니다. | 발급받은 cst_id |
| custKey필수 | String 255 | 파트너 인증을 위한 키입니다. 라이브 키는 계약이 완료되어야 발급 가능합니다.외부에 노출되면 안되는 정보입니다. 보안에 유의해주세요. | 발급받은 custKey |
| 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이체 대기가 성공적으로 완료된 후에 이체 실행을 요청하는 단계입니다. 이체 실행 요청은 접수만 처리되고, 실제 이체는 접수 이후 페이플이 순차적으로 진행합니다. 아래의 내용을 주의 깊게 확인해주세요.
응답의
result 가 A0000(처리 성공)이면 이체 요청이 정상 접수되었다는 뜻이며, 이체가 완료되었다는 뜻이 아닙니다.billing_tran_id에 ALL 을 지정한 경우와 특정 빌링키를 지정한 경우 모두 같은 방식으로 접수 응답이 반환됩니다.
이 시간에 요청하면 거부되니 01:00 이후에 다시 요청해 주세요.
- 건별 실행결과 조회도 이 시간에는 처리되지 않습니다.
일별·그룹별 실행결과 조회는 시간 제한이 없습니다.
- 일별·그룹별 실행결과 조회는 이체에 성공한 건만 반환합니다.
실패한 건은 웹훅 또는 건별 실행결과 조회로 확인해 주세요. - 이체 실행 요청 응답 직후에 실행결과 조회 API를 호출하면 아직 처리 전이라 이체 내역이 조회되지 않을 수 있습니다.
웹훅을 수신한 뒤 조회하거나, 일정 시간 간격을 두고 조회해 주세요.
billing_tran_id값에 따라 그룹키 group_key에 속한 대기 건의 이체 실행이 결정됩니다.- ALL :
group_key에 속한 모든 대기 건의 이체가 진행됩니다. - 특정 빌링키 :
group_key에 속한 해당 빌링키의 대기 건이 모두 실행됩니다. - 실행되지 않은 대기 건은
group_key에 그대로 남습니다.
같은group_key에 같은 빌링키로 등록한 대기 건이 여러 개 있으면 함께 실행되니, 실행 전에 이체대기 조회로 확인하고 필요 없는 건은 이체대기 취소로 정리해 주세요.
group_key 는 이체 대기를 수행한 여러 건을 하나의 그룹으로 묶는 역할을 하며, 이체 실행 요청 시 이 그룹키 단위로 이체가 접수됩니다.group_key는 파트너가 만드는 값이 아니라 이체 대기 요청 응답으로 페이플이 발급합니다.
같은 날 등록한 대기 건은 이체 실행을 하기 전까지 같은group_key로 묶이고, 이체 실행 후에 등록하는 대기 건부터 새group_key가 발급됩니다.- 실행하지 않은 대기 건은 날짜가 바뀌어도 자동으로 취소되지 않고 남아 있습니다.
필요 없는 대기 건은 이체대기 취소로 정리해 주세요. - 권장 사용 방법 : 지급할 건을 모두 이체 대기 요청으로 등록한 뒤,
billing_tran_id를 ALL 로 지정해 한 번에 이체 실행하세요.
1건 등록 → 1건 실행을 반복하면 건마다 새 그룹키가 발급되어 접수·처리 횟수가 늘어나고 전체 완료가 늦어집니다. - 특정 빌링키
group_key내의 여러 건 중 일부만 이체 실행이 완료되었을 경우, 나머지 미실행 건들은 기존group_key에 계속 묶여 있습니다.
ALL 로 다시 실행하면 남아 있는 미실행 건만 실행됩니다.
group_key03 빌링키로 이체 대기 요청billing_tran_id03 빌링키로 이체 대기 요청group_key06 운영billing_tran_id06 운영execute_type06 운영https://demohub.payple.kr/transfer/executehttps://hub.payple.kr/transfer/execute파트너 인증 후 이체 실행 요청 시 필요한 Request 파라미터는 아래와 같습니다.
| 파라미터 | 타입 | 설명 | 값 예시 |
|---|---|---|---|
| cst_id필수 | String 255 | 파트너 인증을 위한 ID 입니다. 라이브 ID 는 계약이 완료되어야 발급 가능합니다. | 발급받은 cst_id |
| custKey필수 | String 255 | 파트너 인증을 위한 키입니다. 라이브 키는 계약이 완료되어야 발급 가능합니다.외부에 노출되면 안되는 정보입니다. 보안에 유의해주세요. | 발급받은 custKey |
| group_key필수 | String 40 | 이체 대기 요청 후 수신한 그룹키로 이체 실행을 진행합니다.그룹키 내의 여러 건 중 일부만 이체 실행이 완료되었을 경우, 나머지 미실행 건들은 기존 그룹키에 계속 묶여 있습니다. ALL 로 다시 실행하면 남아 있는 미실행 건만 실행됩니다. | QlJKZDZrNVBzbW9Yc1UzTWNIdW05dz09 |
| billing_tran_id필수 | String 40 | 계좌의 빌링키입니다.ALL : 그룹키에 속한 모든 대기 건의 이체가 진행특정 빌링키 : 그룹키에 속한 해당 빌링키의 대기 건이 모두 이체 진행 (같은 빌링키 대기 건이 여러 개면 함께 실행) | ALL 혹은 특정 빌링키(cb9d695e-c034-4eeb-9550-c53a9ab7c2e4) |
| execute_type필수 | String 8 | 이체 실행을 위한 구분값입니다.NOW : 이체 실행 접수 (접수 후 페이플이 순차 처리하며, 응답은 접수 결과)CANCEL : 대기 중인 이체 취소 | NOW |
| webhook_url필수 - 테스트 시 | String 255 | 이체 실행 결과를 수신하는 주소입니다. 테스트 서버로 요청시에만 필요합니다. | http://your-test-domain.com |
05결과 수신
server이체가 처리되면 결과(성공/실패)는 웹훅을 통해 건별로 수신됩니다.
웹훅을 받지 못했거나 따로 확인해야 할 때는 실행결과 조회 API (건별 실행결과 조회 / 일별 실행결과 조회 / 그룹별 실행결과 조회)로 조회할 수 있습니다.
예를 들어 그룹키 A에 묶인 이체 대기 건이 5건일 때 ALL 로 이체를 실행하면, 총 5건의 이체 결과를 건별로 수신하게 됩니다.
- 웹훅의
result가A0000이면 이체 성공, 그 외 코드는 실패 또는 처리 중입니다.
코드별 의미는 응답 코드에서 확인하세요. - 금융기관 처리가 지연되면 웹훅이 처리 중(A0001 등) 결과로 먼저 발송될 수 있습니다.
이때는 아직 결과가 확정된 것이 아니며, 처리가 완료되면 최종 결과 웹훅이 다시 발송됩니다. - 처리 중 결과와 재발송 때문에 같은 이체 건의 웹훅을 여러 번 받을 수 있습니다.
distinct_key로 같은 건인지 확인해 중복 처리되지 않도록 해 주세요. - 일별·그룹별 실행결과 조회는 이체에 성공한 건만 반환합니다.
실패한 건은 웹훅 또는 건별 실행결과 조회로 확인해 주세요. - 실행결과 조회 API는 이체 실행 요청 직후에는 처리 전이라 내역이 조회되지 않을 수 있습니다.
웹훅 수신 후 또는 일정 시간 뒤에 조회해 주세요.
distinct_key06 운영group_key06 운영billing_tran_id06 운영api_tran_id06 운영06운영
ops대기 중인 이체의 조회, 취소, 실행 결과 조회, 이체 가능 잔액 조회에 쓰는 API 입니다.
필요한 기능만 골라 연동하세요.
https://demohub.payple.kr/transfer/executehttps://hub.payple.kr/transfer/execute