지급대행하기

지급대행은 오픈마켓에서 발생한 매출을 토스페이먼츠가 오픈마켓을 대신하여 셀러(입점 판매자)에게 지급하는 서비스입니다. 직접 수많은 셀러에게 정산할 필요 없이, 정산 업무를 토스페이먼츠한테 맡기고 자금 흐름을 더 효율적으로 관리할 수 있어요.

지급대행은 토스페이먼츠와 직접 계약하지 않은 셀러에게 돈을 지급하는 서비스이기 때문에 KYC 등 강화된 리스크 검토 절차가 있고, 연동 측면에서도 더 강화된 보안을 요구합니다.

Request Body가 있는 지급대행 서비스의 POST 요청은 모두 ENCRYPTION 보안을 사용합니다. ENCRYPTION 보안은 토스페이먼츠에서 발급하는 보안 키를 사용해서 API의 Request Body를 JWE로 암호화하는 방식입니다. ENCRYPTION 보안이 설정된 요청은 응답도 암호화되어 돌아옵니다. 응답도 동일한 보안 키로 복호화해주세요.

ENCRYPTION 보안이 적용되는 API는 셀러 등록, 셀러 수정, 지급대행 요청입니다. 지급대행 요청 취소도 POST 요청이지만 Request Body 파라미터가 없기 때문에 ENCRYPTION 보안을 사용하지 않습니다.

토스페이먼츠 개발자센터의 API 키 메뉴에서 API 개별 키 > 보안 키를 확인하세요. 보안 키는 절대 외부에 노출되면 안 됩니다.

보안 키는 64자의 Hexadecimal 문자열입니다. JWE 암호화할 때는 보안 키를 아래와 같이 바이트로 전환해야 됩니다.

아래 코드와 같이 JWE 헤더를 생성한 다음에 Request Body를 암호화해주세요. 필수 헤더 외에 iat, nonce 커스텀 JWE 헤더를 요구합니다.

• alg: 보안 키의 암호화 알고리즘입니다. 토스페이먼츠 보안 키는 암호화되어 있지 않기 때문에 dir 값으로 설정해주세요.
• enc: JWE 암호화 알고리즘입니다. A256GCM로 설정해주세요.
• iat(issued at): Request Body를 생성한 시간입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.
• nonce: JWE의 고유 식별자입니다. UUID와 같이 충분히 무작위적인 고유 값입니다.

ENCRYPTION 보안이 적용된 요청은 응답도 암호화되어 돌아옵니다. API 응답도 암호화에 사용한 같은 보안 키로 복호화하고 응답 값을 확인하세요. 성공 응답, 실패 응답 모두 암호화되어 돌아옵니다.

먼저 셀러 등록 API로 내 오픈마켓에 입점해있는 셀러의 정보를 토스페이먼츠에 등록해주세요. API 파라미터를 확인해서 Request Body 데이터를 만든 다음에, 해당 데이터를 보안 키로 암호화해주세요.

JWE로 암호화한 Request Body를 API 요청의 데이터값으로 넣고 TossPayments-api-security-mode: ENCRYPTION 헤더를 추가하세요. API 개별 연동 키 > 시크릿 키를 이용하는 Basic 인증도 반드시 해주세요.

성공적으로 셀러가 등록되면 아래와 같이 JWE로 암호화된 Seller 객체가 돌아옵니다. JWE를 복호화해서 응답 값을 확인해주세요.

개인 및 개인사업자 셀러는 본인인증이 필요해요

셀러 등록 직후 셀러의 사업자 유형에 따라 상태(status)가 다른데요. 개인 및 개인사업자 셀러는 APPROVAL_REQUIRED 상태로 등록돼요. 개인 및 개인사업자에게는 phone으로 등록된 전화번호로 본인인증 문자가 발송됩니다. 본인인증을 성공적으로 마친 이후에만 상태가 PARTIALLY_APPROVED로 바뀌고, 해당 셀러에게 일주일에 1천만원 미만의 정산금을 지급대행할 수 있어요. 법인사업자는 등록 직후 일주일에 1천만원 미만의 정산금을 바로 지급대행할 수 있어요.

셀러에게 일주일에 1천만원 이상 지급하려면 KYC 심사가 필요해요

셀러에게 일주일에 1천만원 이상 지급대행을 시도하면 셀러의 상태가 KYC_REQUIRED로 바뀌고 셀러의 이메일 주소로 KYC 심사 안내가 발송돼요. 해당 상태에서는 셀러에게 지급대행이 불가능합니다. KYC 심사가 통과하면 셀러의 상태는 APPROVED로 바뀌고, 금액 제한 없이 지급대행이 가능합니다. KYC 심사를 마친 셀러는 1년 또는 3년에 다시 심사를 받아야 되기 때문에 상태가 다시 KYC_REQUIRED로 바뀝니다.

셀러 유형과 상관없이 셀러에게 일주일에 1천만원 이상 지급하려면 해당 절차는 필수입니다.

웹훅으로 셀러의 상태 변경을 받으세요

셀러의 상태 변경은 seller.changed 웹훅 이벤트로 받을 수 있어요.

등록한 셀러에게 지급대행을 요청하기 전에, 정산 잔액이 충분한지 확인해주세요. 잔액 조회 API를 호출하면 셀러에게 지급할 수 있는 정산금(availableAmount)과 아직 지급할 수 없는 정산금(pendingAmount)을 확인할 수 있어요. 아직 지급할 수 없는 정산금은 매출이 일어났지만, 토스페이먼츠로부터 아직 정산 받지 않은 금액입니다. 토스페이먼츠와 계약한 정산 주기에 따라 지급할 수 있는 정산금으로 전환됩니다.

잔액 조회에 성공하면 아래와 같은 Balance 객체가 응답됩니다. 현재 지급대행은 KRW 통화만 지원합니다.

설레에게 지급할 정산 금액을 확인했다면 지급대행 요청 API를 호출해주세요. 최대 100건의 지급대행 요청을 한 번에 보낼 수 있어요. 1건의 지급대행 요청에는 10억 미만의 정산 금액을 이체할 수 있습니다. 지급대행으로 셀러에게 지급한 정산 금액은 회수하기 어렵습니다. 토스페이먼츠는 지급 관련 책임이 없기 때문에 지급대행 서비스를 신중하게 사용해주세요.

요청 파라미터를 확인해주세요. 토스페이먼츠 지급대행에는 두 가지 scheduleType이 있어요. EXPRESS는 바로 지급이에요. 요청 당일에 셀러에게 정산금이 지급돼요. SCHEDULED는 예약 지급이며, payoutDate 파라미터로 설정한 날짜에 정산금이 지급돼요. Request Body 데이터를 보안 키로 암호화해주세요.

바로지급(EXPRESS)은 영업일 08:00~15:00 사이에만 요청할 수 있어요. 휴일, 공휴일에 바로지급 지급대행을 요청하면 오류가 발생해요. 예약지급(SCHEDULED)의 지급일은 미래에 1년 이내에 있는 영업일로만 설정할 수 있어요. 휴일, 공휴일, 과거 일자로 설정하면 오류가 발생해요.

JWE로 암호화한 Request Body를 API 요청의 데이터값으로 넣고 TossPayments-api-security-mode: ENCRYPTION 헤더를 추가하세요. API 개별 연동 키 > 시크릿 키를 이용하는 Basic 인증도 반드시 해주세요.

멱등키를 요청 헤더에 추가하면 중복 지급 없이 안전하게 처리됩니다. 하지만 멱등한 요청에서 에러가 반환되었을 때 멱등키를 변경해서 동일한 요청을 재시도하는 것은 위험이 있습니다. 정확한 오류 원인을 토스페이먼츠로부터 확인한 다음에 다시 요청을 보내주세요.

지급대행이 성공적으로 요청되면 아래와 같이 JWE로 암호화된 Payout 객체가 돌아옵니다. JWE를 복호화해서 응답 값을 확인해주세요.

지급대행 요청에 실패하면 JWE로 암호화된 에러 객체가 돌아옵니다. 지급대행 요청에 실패하면 요청 건 모두 실패하고 요청 건 중에 첫 번째 에러에 대한 에러 객체가 돌아옵니다. 예를 들어 지급대행 요청 3번, 51번에 오류가 났다면, 요청은 전체 실패하고 3번에 대한 에러 객체가 응답돼요.

은행 오류로 지급대행이 실패할 수 있어요

하지만 지급대행 요청이 끝났다고 지급대행이 항상 성공하지는 않아요. 한도 초과 또는 원천사 점검 중에는 지급대행이 실패해요. 그런 경우에는 Payout 객체의 상태는 FAILED로 바뀌고, error 필드에서 에러를 확인할 수 있어요. 지급대행의 최종 성공 및 실패 상태는 payout.changed 웹훅 이벤트를 등록해서 받을 수 있습니다.

만약에 지급대행 요청이 은행 오류로 실패하는 케이스를 테스트하고 싶다면 아래 계좌번호를 등록해보세요. 아래 계좌를 셀러에 등록하고, 해당 셀러에게 지급대행을 요청해주세요.

예약 지급대행 요청만 취소할 수 있어요

SCHEDULED 지급대행 요청은 지급일 전에 요청을 취소할 수 있어요. EXPRESS 지급대행 요청은 당일에 처리되기 때문에 요청을 취소할 수 없어요. 지급대행 요청의 상태 변화는 payout.changed 웹훅으로 확인해주세요.