지급대행하기

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

지급대행 API는 추가 계약이 필요한 유료 서비스입니다. 계약을 하고 싶다면 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.

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입니다. 서브몰 별로 지급대행 상태를 가지고 있습니다.

응답

[
  {
    "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
  }
]

JSON

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

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

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

지급성공

{
  "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
  }
}

JSON

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

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

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

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

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

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

{
  "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
}

JSON

특정 기간에 요청된 여러 개의 지급대행 상태를 한 번에 확인하려면 지급대행 조회 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=='

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

[
  {
    "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
  }
]

JSON

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

.css-p1o082{width:calc(0.8em + 8px);height:0.8em;position:absolute;top:calc(50% - 0.4em);left:calc(-0.8em - 8px);padding-right:8px;opacity:0;-webkit-transition:opacity 0.2s ease-in-out;-webkit-transition:opacity 0.2s ease-in-out;transition:opacity 0.2s ease-in-out;}지급대행하기

2. 정산 금액 보내기

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

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

지급대행하기