결제 운영/지급대행(하위 상점 정산)
목차

지급대행은 하위 상점(서브몰)의 정산 금액을 토스페이먼츠가 대신 지급하는 서비스입니다. 지급대행 API를 사용하면 상점에서 따로 서브몰 정보를 관리하거나 서브몰에 각각 송금할 필요 없이 편리하게 지급 업무를 할 수 있습니다.

지급대행 API는 더 이상 신규 계약을 받지 않는 서비스입니다. 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.

지급대행 API지급대행 API를 자세히 알아보세요.

1. 서브몰 정보 등록하기

서브몰 등록 API를 사용해서 먼저 정산 금액을 지급할 서브몰 정보를 등록합니다. 요청 본문에는 아래와 같이 서브몰에서 정산받을 은행 계좌 정보가 포함되어야 합니다.

요청
curl --request POST \
--url https://api.tosspayments.com/v1/payouts/sub-malls \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '{"subMallId":"testmall100","type":"CORPORATE","companyName":"테스트몰100","representativeName":"김토페","businessNumber":"1200220000","account":{"bank":"03","accountNumber":"34000000000011"}}'

등록한 서브몰의 정보를 수정하거나 삭제하려면 Path 파라미터에 subMallId를 포함해 서브몰 정보를 수정하거나 삭제하는 API를 요청하세요.

요청
curl --request POST \
--url https://api.tosspayments.com/v1/payouts/sub-malls/testmall100/delete \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='

서브몰 정보를 수정하면 변경된 서브몰 정보가 응답으로 돌아오고, 서브몰 정보를 삭제하면 삭제된 서브몰 ID가 응답으로 돌아옵니다. 삭제된 서브몰 ID는 다시 사용할 수 없습니다.

2. 정산 금액 보내기

서브몰에 정산할 금액을 직접 계산하세요. 정산 금액을 보내기 전에 잔액 조회 API를 사용해서 내 상점 계좌의 잔액이 충분한지 확인할 수 있습니다.

잔액이 충분하다면 지급대행을 요청하세요. 지급대행을 요청할 때는 아래와 같이 서브몰 별로 서브몰 ID와 지급할 액수, 지급할 날짜를 요청 본문에 포함해주세요. 여러 서브몰의 지급 정보를 배열로 보내서 한꺼번에 처리할 수 있습니다.

내부 지급대행 처리로 인해 11:00시-12:00시 사이에는 지급대행 요청을 할 수 없습니다. 지급대행 서비스를 정상적으로 이용하려면 해당 시간대를 피해서 API를 호출하세요.

요청
curl --request POST \
--url https://api.tosspayments.com/v1/payouts/sub-malls/settlements \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '[{"subMallId":"testmall100","payoutAmount":100,"payoutDate":"2022-01-03"},{"subMallId":"testmall200","payoutAmount":200,"payoutDate":"2022-01-03"}]'

API 요청이 반복적으로 일어나는 문제를 막을 수 있는 멱등키를 요청 헤더에 추가하면 중복 지급 없이 안전하게 처리됩니다.

요청에 성공하면 아래와 같이 Payout 객체가 담긴 배열이 돌아옵니다. 요청 후 최초 상태는 REQUESTED입니다. 서브몰 별로 지급대행 상태를 가지고 있습니다.

응답
JSON
[
{
"payoutKey": "FPA1000000001",
"requestId": "102200046000003",
"subMallId": null,
"payoutDate": "20221107",
"payoutAmount": 50,
"requestedAt": "20221106210031",
"account": {
"bankCode": "03",
"accountNumber": "00123412341234",
"holderName": null
},
"status": "COMPLETED",
"metadata": null,
"failure": null,
"transferSummary": null
},
{
"payoutKey": "FPA1000000002",
"requestId": "102200046000004",
"subMallId": null,
"payoutDate": "20221107",
"payoutAmount": 50,
"requestedAt": "20221106210031",
"account": {
"bankCode": "20",
"accountNumber": "X6505636518308",
"holderName": null
},
"status": "COMPLETED",
"metadata": null,
"failure": null,
"transferSummary": null
}
]

3. 지급대행 결과 웹훅으로 확인하기

요청한 지급대행이 완료됐는지 궁금하다면 웹훅으로 받아볼 수 있습니다. 개발자센터 웹훅 페이지에서 PAYOUT_STATUS_CHANGED 이벤트를 등록해주세요. 웹훅 등록 및 테스트 방법은 웹훅 페이지에서 더 알아보세요.

지급대행이 완료됐거나 실패해서 요청했을 때 REQUESTED였던 status 값이 COMPLETEDFAILED로 바뀌면 아래와 같은 웹훅 이벤트 본문이 전송됩니다.

지급성공
JSON
{
"eventType": "PAYOUT_STATUS_CHANGED",
"createdAt": "2022-01-01T00:00:00.000000",
"data": {
"payoutKey": "",
"subMallId": "testmall100",
"payoutDate": "20220103",
"payoutAmount": 10000,
"requestedAt": "20220101100130",
"account": {
"bankCode": "03",
"accountNumber": "00123412341234",
"holderName": null
},
"status": "COMPLETED",
"metadata": null,
"failure": null,
"transferSummary": null
}
}

만약 지급대행에 실패해서 status 값이 FAILED로 바뀌면, Payout 객체에 failure 값이 추가되어 돌아옵니다. 이 정보로 지급대행 요청이 왜 실패했는지 알 수 있습니다.

지급대행 상태를 조회하는 두 가지 방법

지급대행을 마친 후 상태를 조회하고 싶다면 단 건을 조회하는 API와 여러 건을 조회하는 API 두 가지 중 하나를 사용해서 확인할 수 있습니다.

특정 지급대행 하나의 상태가 궁금하다면 payoutKey를 사용해서 지급대행 단건 조회 API를 요청하세요.

curl --request GET \
--url https://api.tosspayments.com/v1/payouts/sub-malls/settlements/FPA1000000001 \
--header 'Authorization: Basic dGVzdF9za19PeUwwcVo0RzFWT0xvYkI2S3d2cm9XYjJNUVlnOg=='

요청 결과로 하나의 지급대행 정보가 돌아옵니다.

JSON
{
"payoutKey": "FPA1000000001",
"requestId": "102200046000003",
"subMallId": null,
"payoutDate": "20221107",
"payoutAmount": 50,
"requestedAt": "20221106210031",
"account": {
"bankCode": "03",
"accountNumber": "00123412341234",
"holderName": null
},
"status": "COMPLETED",
"metadata": null,
"failure": null,
"transferSummary": null
}

특정 기간에 요청된 여러 개의 지급대행 상태를 한 번에 확인하려면 지급대행 조회 API를 사용하세요. 날짜는 지급대행 요청에서 사용한 payoutDate 값을 기준으로 조회를 시작하고 싶은 날짜를 startDate에, 마치고 싶은 날짜를 endDate에 Query 파라미터로 추가해서 아래와 같이 요청합니다.

curl --request GET \
--url 'https://api.tosspayments.com/v1/payouts/sub-malls/settlements?startDate=2022-01-01&endDate=2022-01-03' \
--header 'Authorization: Basic dGVzdF9za19PeUwwcVo0RzFWT0xvYkI2S3d2cm9XYjJNUVlnOg=='

요청 결과로 여러 개의 지급대행 정보가 배열에 담겨 돌아옵니다.

JSON
[
{
"payoutKey": "FPA1000000001",
"requestId": "102200046000003",
"subMallId": null,
"payoutDate": "20221107",
"payoutAmount": 50,
"requestedAt": "20221106210031",
"account": {
"bankCode": "03",
"accountNumber": "00123412341234",
"holderName": null
},
"status": "COMPLETED",
"metadata": null,
"failure": null,
"transferSummary": null
},
{
"payoutKey": "FPA1000000002",
"requestId": "102200046000004",
"subMallId": null,
"payoutDate": "20221107",
"payoutAmount": 50,
"requestedAt": "20221106210031",
"account": {
"bankCode": "20",
"accountNumber": "X6505636518308",
"holderName": null
},
"status": "COMPLETED",
"metadata": null,
"failure": null,
"transferSummary": null
}
]
  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    실시간 문의|이메일 보내기