국내 정산금 이체
V1구버전 개발자센터
V2신버전 개발자센터

국내 정산금 이체

페이플 정산지급대행은 페이플이 파트너(플랫폼)에게 정산할 금액을 플랫폼이 지정한 셀러의 계좌로 자동으로 지급하는 서비스입니다.
주말 및 공휴일과 같은 비영업일에도 실시간 이체가 가능합니다.

00연동 준비

페이플 가입 계약 심사가 완료되면 테스트 계정이 발급되며, 발급받은 테스트 계정으로 연동을 체험할 수 있습니다.

테스트 환경 접속 정보
접속 도메인https://demohub.payple.kr
cst_id발급받은 cst_id
custKey발급받은 custKey
참고
환경별 키 분리테스트와 라이브는 cst_idcustKey 가 다릅니다. 환경변수로 분리해두세요.
통신 보안파트너사는 TLS v1.2 이상 / SSL 보안 통신(HTTPS)을 필수적으로 적용해야 합니다.
연동 전 확인사항화이트(White) IP 등록, 테스트 환경(demo)문서 바로가기웹훅이체실행 완료 결과를 받아 누락을 막습니다문서 바로가기

01파트너 인증 요청

server
참고
요청마다 새 토큰파트너 인증은 매 요청마다 필요합니다. 발급된 토큰(access_token)은 60초간 유효합니다.
POST테스트https://demohub.payple.kr/oauth/token
POST라이브https://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 빌링키로 이체 대기 요청
POST테스트https://demohub.payple.kr/inquiry/real_name
POST라이브https://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_idString
64
파트너 하위 셀러의 ID 입니다.sub01

03빌링키로 이체 대기 요청

server

계좌조회가 성공적으로 완료된 후에는 대기 단계가 시작되며, 이 단계에서는 실제 이체가 이루어지지 않습니다.

받아서 넣기billing_tran_id02 계좌조회 요청sub_id02 계좌조회 요청
저장해두기distinct_key06 운영group_key04 이체 실행 요청billing_tran_id04 이체 실행 요청
POST테스트https://demohub.payple.kr/transfer/request
POST라이브https://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_idString
64
파트너 하위 셀러의 ID 입니다.sub01
distinct_keyString
64
중복 이체를 방지하기 위한 키입니다. 미입력 시 페이플에서 자동 발급됩니다.c9z116521650283…
print_contentString
Byte 가 아닌 자릿수(6자)
상대방 계좌 거래 내역에 표시될 수 있는 최대 6자까지의 문구입니다. 미입력 시 파트너(상점) 상호명으로 표시됩니다.테스트입니다

04이체 실행 요청

server

이체 대기가 성공적으로 완료된 후에 이체 실행을 요청하는 단계입니다. 이체 실행 요청은 접수만 처리되고, 실제 이체는 접수 이후 페이플이 순차적으로 진행합니다. 아래의 내용을 주의 깊게 확인해주세요.

참고
접수 응답의 의미이체 실행 요청의 응답은 이체 결과가 아니라 접수 결과입니다.
응답의 result 가 A0000(처리 성공)이면 이체 요청이 정상 접수되었다는 뜻이며, 이체가 완료되었다는 뜻이 아닙니다.
  • billing_tran_id 에 ALL 을 지정한 경우와 특정 빌링키를 지정한 경우 모두 같은 방식으로 접수 응답이 반환됩니다.
참고
이체 실행 불가 시간매일 23:00부터 다음 날 01:00 전까지는 이체 실행 요청(이체대기 취소 포함)이 처리되지 않습니다.
이 시간에 요청하면 거부되니 01:00 이후에 다시 요청해 주세요.
  • 건별 실행결과 조회도 이 시간에는 처리되지 않습니다.
    일별·그룹별 실행결과 조회는 시간 제한이 없습니다.
참고
이체 결과 확인 방법실제 이체 결과(성공/실패)는 다음 단계의 웹훅 또는 실행결과 조회 API (건별 실행결과 조회 / 일별 실행결과 조회 / 그룹별 실행결과 조회)로 건별로 확인해야 합니다.
  • 일별·그룹별 실행결과 조회는 이체에 성공한 건만 반환합니다.
    실패한 건은 웹훅 또는 건별 실행결과 조회로 확인해 주세요.
  • 이체 실행 요청 응답 직후에 실행결과 조회 API를 호출하면 아직 처리 전이라 이체 내역이 조회되지 않을 수 있습니다.
    웹훅을 수신한 뒤 조회하거나, 일정 시간 간격을 두고 조회해 주세요.
참고
billing_tran_id 값에 따른 실행 범위빌링키 billing_tran_id값에 따라 그룹키 group_key에 속한 대기 건의 이체 실행이 결정됩니다.
  • ALL : group_key 에 속한 모든 대기 건의 이체가 진행됩니다.
  • 특정 빌링키 : 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 운영
POST테스트https://demohub.payple.kr/transfer/execute
POST라이브https://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건의 이체 결과를 건별로 수신하게 됩니다.

참고
이체 완료 판단 기준이체 완료 여부는 이체 실행 요청 응답(A0000)이 아니라 이 단계에서 수신하는 웹훅 또는 실행결과 조회 API 응답으로 판단해야 합니다.
  • 웹훅의 result 가 A0000 이면 이체 성공, 그 외 코드는 실패 또는 처리 중입니다.
    코드별 의미는 응답 코드에서 확인하세요.
  • 금융기관 처리가 지연되면 웹훅이 처리 중(A0001 등) 결과로 먼저 발송될 수 있습니다.
    이때는 아직 결과가 확정된 것이 아니며, 처리가 완료되면 최종 결과 웹훅이 다시 발송됩니다.
  • 처리 중 결과와 재발송 때문에 같은 이체 건의 웹훅을 여러 번 받을 수 있습니다.
    distinct_key 로 같은 건인지 확인해 중복 처리되지 않도록 해 주세요.
  • 일별·그룹별 실행결과 조회는 이체에 성공한 건만 반환합니다.
    실패한 건은 웹훅 또는 건별 실행결과 조회로 확인해 주세요.
  • 실행결과 조회 API는 이체 실행 요청 직후에는 처리 전이라 내역이 조회되지 않을 수 있습니다.
    웹훅 수신 후 또는 일정 시간 뒤에 조회해 주세요.
저장해두기distinct_key06 운영group_key06 운영billing_tran_id06 운영api_tran_id06 운영
참고이체 실행 요청의 응답은 접수 결과입니다. 이체 완료 여부는 이 웹훅 또는 실행결과 조회 API 로 확인하세요. 이체실행을 ALL 로 한 번 요청해도 웹훅은 이체 건마다 따로 옵니다. 5건을 실행하면 5번 수신합니다.

06운영

ops

대기 중인 이체의 조회, 취소, 실행 결과 조회, 이체 가능 잔액 조회에 쓰는 API 입니다.
필요한 기능만 골라 연동하세요.

POST테스트https://demohub.payple.kr/transfer/execute
POST라이브https://hub.payple.kr/transfer/execute
결제 연동과 관련된 무엇이든 물어보세요