정산 지급대행 v1

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

* 지급대행 API는 최대 60초가 소요됩니다. 타임아웃 값을 최소 60초로 설정하세요.

서브몰의 사업자번호, 계좌번호 등 정산 지급에 필요한 정보입니다.

• subMallId string
  

  서브몰의 ID입니다. 최대 길이는 20자입니다.

• type string
  

  서브몰의 타입입니다. CORPORATE(사업자), INDIVIDUAL(개인) 중 하나입니다.

• status string
  

  서브몰의 지급 가능 상태입니다. 상태 변경 알림을 받고 싶다면 SUBMALL_STATUS_CHANGED 웹훅을 연동하세요.

  • PARTIALLY_APPROVED: 1천만원 이하의 금액을 지급대행할 수 있는 상태입니다. 서브몰 등록 이후 최초 상태입니다.

  • KYC_REQUIRED: 지급대행이 보류된 상태입니다. 1천만원 이상의 금액을 지급대행 요청하면 지급대행이 실패하고 KYC 심사가 진행됩니다.

  • APPROVED: 지급대행 금액에 제한이 없는 상태입니다. 서브몰이 KYC 심사를 통과했기 때문입니다.

• companyName nullable · string
  

  서브몰의 상호명입니다. 최대 길이는 공백을 포함한 한글 30자, 영문 60자입니다. 서브몰의 type이 CORPORATE(사업자)일 때만 사용됩니다.

• representativeName nullable · string
  

  서브몰의 대표자명입니다. 최대 길이는 40자입니다. 서브몰의 type이 CORPORATE(사업자)일 때만 사용됩니다.

• businessNumber nullable · string
  

  서브몰의 사업자등록번호 입니다. 길이는 10자입니다. 서브몰의 type이 CORPORATE(사업자)일 때만 사용됩니다.

• account object
  

  서브몰이 정산 금액을 지급받을 계좌 정보입니다.

• bankCode string
  

  은행 두 자리 코드입니다. 은행 코드와 증권사 코드를 참고하세요.

• accountNumber string
  

  계좌번호입니다. 최대 길이는 20자입니다.

• holderName nullable · string
  

  지급받을 계좌의 예금주입니다. 최대 길이는 공백을 포함한 한글 30자, 영문 60자입니다.

• email nullable · string
  

  서브몰 이메일 주소입니다.

• phoneNumber nullable · string
  

  서브몰 연락처입니다. - 없이 숫자만 넣어야 합니다. 길이는 8자 이상 11자 이하여야 합니다.

• metadata nullable · object
  

  서브몰과 관련된 추가 정보를 key-value 쌍으로 담고 있는 객체입니다. 최대 50개의 key-value 쌍을 포함할 수 있으며 전체 크기는 4kB 이하입니다.

상점 하위에 새로운 서브몰을 등록합니다. 서브몰에서 정산 받을 은행 계좌 정보를 포함해야 합니다.

* 서브몰 등록은 최대 60초가 소요됩니다. 타임아웃 값을 최소 60초로 설정하세요.

Request Body 파라미터

• subMallId 필수 · string
  

  서브몰의 ID입니다. 최대 길이는 20자입니다.

• account 필수 · object
  

  서브몰이 정산 금액을 지급받을 계좌 정보입니다.

• bank 필수 · string
  

  지급받을 계좌의 은행 코드입니다. 은행 코드와 증권사 코드를 참고하세요.

• accountNumber 필수 · string
  

  계좌번호입니다. - 없이 숫자만 넣어야 합니다. 최대 길이는 20자입니다.

• holderName string
  

  지급받을 계좌의 예금주입니다. 최대 길이는 공백을 포함한 한글 30자, 영문 60자입니다.

• type 필수 · string
  

  서브몰의 타입입니다. CORPORATE(사업자), INDIVIDUAL(개인) 중 하나의 값을 넣어주세요.

• email 필수 · string
  

  서브몰 이메일 주소입니다.

• phoneNumber 필수 · string
  

  서브몰 연락처입니다. - 없이 숫자만 넣어야 합니다.

• companyName string
  

  서브몰의 상호명입니다. 서브몰의 type이 CORPORATE일 때 필수로 보내야 하는 파라미터입니다. 최대 길이는 공백을 포함한 한글 30자, 영문 60자입니다.

• representativeName string
  

  서브몰의 대표자명입니다. 서브몰의 type이 CORPORATE일 때 필수로 보내야 하는 파라미터입니다. 최대 길이는 공백을 포함한 한글 20자, 영문 40자입니다.

• businessNumber string
  

  서브몰의 사업자등록번호 입니다. 서브몰의 type이 CORPORATE일 때 필수로 보내야 하는 파라미터입니다. 길이는 10자입니다.

• metadata object
  

  서브몰과 관련된 추가 정보를 key-value 쌍으로 담고 있는 객체입니다. 최대 50개의 key-value 쌍을 포함할 수 있으며 전체 크기는 4kB 이하여야 합니다. key와 value 모두 문자열 형식이어야 합니다.

서브몰 등록에 성공하면 아래와 같이 Submall 객체가 돌아옵니다. 서브몰 등록에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다. 서브몰 등록 API에서 발생할 수 있는 에러를 살펴보세요.

상점 하위에 등록되어 있는 모든 서브몰을 조회합니다.

* 서브몰 조회는 최대 60초가 소요됩니다. 타임아웃 값을 최소 60초로 설정하세요.

서브몰 조회에 성공하면 아래와 같이 Submall 객체가 담긴 배열이 돌아옵니다. 서브몰 조회에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다. 서브몰 조회 API에서 발생할 수 있는 에러를 살펴보세요.

상점 하위에 등록되어 있는 서브몰을 조회합니다.

• subMallId 필수 · string
  

  조회하고 싶은 서브몰의 ID입니다. 서브몰을 등록할 때 설정한 값입니다.

서브몰 단건 조회에 성공하면 아래와 같이 Submall 객체가 돌아옵니다. 서브몰 단건 조회에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.서브몰 단건 조회 API에서 발생할 수 있는 에러를 살펴보세요.

submallId에 해당하는 서브몰의 정보를 새로운 정보로 수정합니다.

* 서브몰 수정은 최대 60초가 소요됩니다. 타임아웃 값을 최소 60초로 설정하세요.

• subMallId 필수 · string
  

  수정하고 싶은 서브몰의 ID입니다. 서브몰을 등록할 때 설정한 값입니다.

Request Body 파라미터

• account 필수 · object
  

  서브몰에서 정산 금액을 지급받을 계좌 정보를 담은 객체입니다.

• bank 필수 · string
  

  지급받을 계좌의 은행 코드입니다. 은행 코드와 증권사 코드를 참고하세요.

• accountNumber 필수 · string
  

  계좌번호입니다. - 없이 숫자만 넣어야 합니다. 최대 길이는 20자입니다.

• holderName string
  

  지급받을 계좌의 예금주입니다. 최대 길이는 공백을 포함한 한글 30자, 영문 60자입니다.

• companyName string
  

  서브몰의 상호명입니다. 서브몰의 type이 CORPORATE일 때 필수로 보내야 하는 파라미터입니다. 최대 길이는 공백을 포함한 한글 30자, 영문 60자입니다.

• representativeName string
  

  서브몰의 대표자명입니다. 서브몰의 type이 CORPORATE일 때 필수로 보내야 하는 파라미터입니다. 최대 길이는 공백을 포함한 한글 20자, 영문 40자입니다.

• businessNumber string
  

  서브몰의 사업자등록번호 입니다. 서브몰의 type이 CORPORATE일 때 필수로 보내야 하는 파라미터입니다. 길이는 10자입니다.

• email string
  

  서브몰 이메일 주소입니다.

• phoneNumber string
  

  서브몰 연락처입니다. - 없이 숫자만 넣어야 합니다. 길이는 8자 이상 11자 이하여야 합니다.

• metadata object
  

  서브몰과 관련된 추가 정보를 key-value 쌍으로 담고 있는 객체입니다. 최대 50개의 key-value 쌍을 포함할 수 있으며 전체 크기는 4kB 이하여야 합니다. key와 value 모두 문자열 형식이어야 합니다.

서브몰 수정에 성공하면 아래와 같이 수정된 Submall 객체가 돌아옵니다. 서브몰 수정에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다. 서브몰 수정 API에서 발생할 수 있는 에러를 살펴보세요.

submallId에 해당하는 서브몰 정보를 삭제합니다.

* 서브몰 삭제는 최대 60초가 소요됩니다. 타임아웃 값을 최소 60초로 설정하세요.

• subMallId 필수 · string
  

  서브몰의 ID입니다. 최대 길이는 20자입니다.

서브몰 삭제에 성공하면 삭제된 서브몰 아이디가 문자열로 돌아옵니다. 삭제된 서브몰 ID는 다시 사용할 수 없습니다. 서브몰 삭제에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.서브몰 삭제 API에서 발생할 수 있는 에러를 살펴보세요.

지급대행 정보입니다.

• payoutKey string
  

  하나의 지급대행 건의 키입니다. 최대 길이는 24자입니다.

• subMallId nullable · string
  

  서브몰의 ID입니다. 최대 길이는 20자입니다.

• payoutDate string
  

  금액이 지급될 날짜와 시간 정보입니다. yyyyMMdd 형식으로 돌아옵니다. (e.g. 20220101)

• payoutAmount number
  

  지급할 금액입니다.

• account nullable · object
  

  서브몰이 정산 금액을 지급받을 계좌 정보입니다.

• bankCode string
  

  은행 두 자리 코드입니다. 은행 코드와 증권사 코드를 참고하세요.

• accountNumber string
  

  계좌번호입니다. 최대 길이는 20자입니다.

• holderName nullable · string
  

  지급받을 계좌의 예금주입니다. 최대 길이는 공백을 포함한 한글 30자, 영문 60자입니다.

• requestedAt string
  

  지급대행을 요청한 날짜와 시간 정보입니다. yyyyMMddHHmmSS 형식입니다. (e.g. 20220101125959)

• status string
  

  지급대행 상태입니다. 아래와 같은 상태 값을 가질 수 있습니다.

  • REQUESTED: 지급이 요청된 상태입니다.

  • IN_PROGRESS: 지급을 처리하고 있는 상태입니다.

  • COMPLETED: 서브몰에 지급이 완료된 상태입니다.

  • FAILED: 지급 요청이 실패한 상태입니다.

  • CANCELED: 지급 요청을 취소한 상태입니다.

• failure nullable · object
  

  지급대행 요청이 실패하면 보내주는 정보입니다. status 필드가 FAILED 일 때만 정보를 보여줍니다.

• code string
  

  오류 타입을 보여주는 에러 코드입니다. INVALID_ACCOUNT, TRANSFER_FAILED 두 가지 코드만 돌아옵니다.

• message string
  

  에러 메시지입니다. 에러 발생 이유를 알려줍니다.

• transferSummary string
  

  지급대행으로 입금된 금액의 세부 내용(적요)입니다. 서브몰 통장에 표기되는 정보입니다. 최대 길이는 7자입니다.

• metadata nullable · object
  

  서브몰과 관련된 추가 정보를 key-value 쌍으로 담고 있는 객체입니다. 최대 50개의 key-value 쌍을 포함할 수 있으며 전체 크기는 4kB 이하입니다.

서브몰에 정산하기 전에 상점이 현재 지급할 수 있는 잔액을 먼저 조회합니다. 내 상점 계좌의 잔액이 충분한지 확인할 수 있습니다.

* 지급 가능한 잔액 조회는 최대 60초가 소요됩니다. 타임아웃 값을 최소 60초로 설정하세요.

지급 가능한 잔액 조회에 성공하면 balance 필드에 잔액 정보가 담긴 객체가 돌아옵니다. 지급 가능한 잔액 조회에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

지급 가능한 잔액 조회 API에서 발생할 수 있는 에러를 살펴보세요.

잔액이 충분하다면 서브몰 정보를 배열로 보내서 지급대행을 요청합니다. 한 번에 처리할 수 있는 배열의 최대 길이는 1000개입니다. 멱등키를 요청 헤더에 추가하면 중복 지급 없이 안전하게 처리됩니다. 하지만 멱등한 요청에서 에러가 반환되었을 때 멱등키를 변경해서 동일한 요청을 재시도하는 것은 위험이 있습니다. 정확한 오류 원인을 토스페이먼츠로부터 확인한 다음에 다시 요청을 보내주세요.

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

* 지급대행 요청은 최대 60초가 소요됩니다. 타임아웃 값을 최소 60초로 설정하세요.

Request Body 파라미터

• subMallId 필수 · string
  

  서브몰의 ID입니다. 최대 길이는 20자입니다.

• payoutDate 필수 · string
  

  정산한 금액을 지급할 날짜 정보입니다. yyyy-MM-dd ISO 8601 형식입니다. (e.g. 2022-01-01)

• payoutAmount 필수 · integer
  

  정산할 금액입니다.

• transferSummary string
  

  지급대행으로 입금된 금액의 세부 내용(적요)입니다. 서브몰 통장에 표기되는 정보입니다. 최대 길이는 7자입니다.

• metadata object
  

  서브몰과 관련된 추가 정보를 key-value 쌍으로 담고 있는 객체입니다. 최대 50개의 key-value 쌍을 포함할 수 있으며 전체 크기는 4kB 이하여야 합니다. key와 value 모두 문자열 형식이어야 합니다.

지급대행 요청에 성공하면 Payout 객체가 배열에 담겨 돌아옵니다. 요청 후 최초 상태(status)는 REQUESTED입니다. 지급 받는 서브몰마다 각각 지급대행 상태를 가지고 있습니다. 지급대행 상태 변경은 웹훅으로 받아볼 수 있습니다. 개발자센터 웹훅 페이지에서 PAYOUT_STATUS_CHANGED 이벤트를 등록해주세요. 웹훅 등록 및 테스트 방법은 웹훅 가이드에서 더 알아보세요.

지급대행 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다. 지급대행 요청 API에서 발생할 수 있는 에러를 살펴보세요.

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

payoutKey를 Path 파라미터에 추가해서 요청한 지급대행을 취소합니다. 아직 status 값이 REQUESTED인 요청 건만 취소할 수 있습니다.

* 지급대행 취소는 최대 60초가 소요됩니다. 타임아웃 값을 최소 60초로 설정하세요.

• payoutKey 필수 · string
  

  요청한 지급대행 건의 키입니다.

지급대행 취소에 성공하면 payoutKey에 해당하는 Payout 객체가 돌아옵니다. 지급대행 취소에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다. 지급대행 요청 취소 API에서 발생할 수 있는 에러를 살펴보세요.

payoutKey를 Path 파라미터에 추가해서 조회하고 싶은 한 건의 지급 정보를 조회합니다.

* 지급대행 단건 조회는 최대 60초가 소요됩니다. 타임아웃 값을 최소 60초로 설정하세요.

• payoutKey 필수 · string
  

  요청한 지급대행 건의 키입니다.

지급대행 단건 조회에 성공하면 payoutKey에 해당하는 Payout 객체가 돌아옵니다. 지급대행 단건 조회에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다. 지급대행 단 건 조회 API에서 발생할 수 있는 에러를 살펴보세요.

지급대행 요청에서 사용한 payoutDate를 기준으로, 지정한 날짜 사이에 지급되었거나 지급될 예정인 지급대행 건을 조회합니다. 조회를 시작하고 싶은 날짜를 startDate에, 마치고 싶은 날짜를 endDate에 Query 파라미터로 추가한 뒤 요청합니다.

* 지급대행 조회는 최대 60초가 소요됩니다. 타임아웃 값을 최소 60초로 설정하세요.

• startDate 필수 · string
  

  조회를 시작하고 싶은 날짜 정보입니다. ISO 8601 형식인 yyyy-MM-dd를 사용합니다. (e.g. 2022-01-01)

• endDate 필수 · string
  

  조회를 마치고 싶은 날짜 정보입니다. yyyy-MM-dd ISO 8601 형식입니다. (e.g. 2022-01-01)

지급대행 조회에 성공하면 각 지급대행 정보를 가지고 있는 Payout 객체의 배열이 돌아옵니다. 지급대행 조회에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

지급대행 요청 상태가 COMPLETED, FAILED로 변경되면 웹훅이 전송됩니다. 자세한 상태 설명은 status에서 확인하세요.

• eventType 필수 · string
  

  웹훅 이벤트 타입입니다.

• createdAt 필수 · string
  

  웹훅이 생성된 시간입니다. yyyy-MM-dd'T'HH:mm:ss.SSSSSS ISO 8601 형식입니다.

• data 필수 · object
  

  상태가 변경된 Payout 객체입니다.

서브몰의 지급 가능 상태가 변경되면 웹훅이 전송됩니다. 서브몰의 상태가 KYC_REQUIRED로 변경되면 서브몰 이메일 주소로 정보 입력 안내가 발송돼요. 서브몰에서 모든 정보를 입력하고 토스페이먼츠 KYC 심사가 끝나면 상태가 APPROVED로 변경돼요.

• eventType 필수 · string
  

  웹훅 이벤트 타입입니다.

• createdAt 필수 · string
  

  웹훅이 생성된 시간입니다. yyyy-MM-dd'T'HH:mm:ss.SSSSSS ISO 8601 형식입니다.

• data 필수 · object
  

  상태가 변경된 Submall 객체입니다.