부가 API

부가 API는 결제 서비스 외에 별도 계약을 통해 사용할 수 있는 서비스입니다. 서비스 계약 문의는 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 해주세요.

지급대행

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

토스페이먼츠와 직접 계약하지 않은 셀러에게 토스페이먼츠가 정산금을 보내야 되기 때문에 KYC 등 리스크 검토 절차가 있습니다. 그리고 연동 측면에서도 더 강화된 보안을 요구합니다. Request Body가 있는 지급대행 POST 요청은 모두 ENCRYPTION 보안을 사용합니다. ENCRYPTION 보안은 토스페이먼츠에서 발급하는 보안 키를 사용해서 API의 Request Body를 JWE로 암호화하는 방식입니다. 자세한 암호화 방법은 지급대행 가이드에서 확인해주세요.

Balance 객체

오픈마켓 쇼핑몰에서 셀러에게 지급할 수 있는 정산 잔액 정보입니다.

객체 상세

pendingAmount object
셀러에게 지급할 수 없는 잔액 정보입니다. 발생한 매출이 정산 주기 2일 전에 pendingAmount 금액으로 업데이트됩니다. 토스페이먼츠 정산 주기가 지난 금액은 availableAmount로 전환됩니다.
- currency string
  통화입니다. 현재는 KRW만 지원합니다.
- value number
  잔액입니다.
availableAmount object
셀러에게 지급할 수 있는 잔액 정보입니다.
- currency string
  통화입니다. 현재는 KRW만 지원합니다.
- value number
  잔액입니다.

잔액 조회

GET /v2/balances

셀러에게 지급할 수 있는 정산 금액을 조회합니다.

Response

성공

잔액 조회에 성공하면 Balance 객체가 돌아옵니다.

실패

잔액 조회에 실패하면 에러 객체가 돌아옵니다.

Seller 객체

오픈마켓에 입점되어 있는 셀러의 사업자, 계좌 정보입니다.

객체 상세

id string
토스페이먼츠에서 발급하는 셀러의 고유 식별자입니다. 셀러 조회, 삭제, 지급대행 요청에 사용됩니다. 셀러의 상태 및 지급대행 상태가 바뀌어도 id는 바뀌지 않고, 삭제된 id는 다시 발급되지 않습니다. 최대 길이는 35자입니다.
refSellerId nullable · string
오픈마켓 상점에서 직접 등록하는 셀러의 고유 식별자입니다. 연동 중에 참고할 수 있는 값입니다. 등록 이후에는 수정할 수 없습니다. 허용된 길이는 7-20자 입니다.
businessType string
사업자 유형입니다. INDIVIDUAL(개인), INDIVIDUAL_BUSINESS (개인사업자), CORPORATE(법인사업자) 중 하나입니다.
company nullable · object
법인사업자 또는 개인사업자 셀러의 정보입니다.
- name string
  사업자명입니다
- representativeName string
  대표자명입니다.
- businessRegistrationNumber string
  사업자번호입니다
- email string
  사업자 이메일입니다. 최대 길이는 100자입니다. 해당 이메일로 KYC 심사 안내가 전송됩니다.
- phone string
  사업자 전화번호입니다.
individual nullable · object
개인 셀러의 정보입니다.
- name string
  개인의 이름입니다.
- email string
  개인 이메일입니다. 최대 길이는 100자입니다. 해당 이메일로 KYC 심사 안내가 전송됩니다.
- phone string
  개인 전화번호입니다.
status string
셀러 상태입니다. 셀러 상태가 바뀌면 seller.changed웹훅이 발송됩니다.
- APPROVAL_REQUIRED: 지급대행이 불가능한 상태입니다. 개인 및 개인사업자 셀러 등록 직후의 상태이며, 본인인증이 필요합니다.
- PARTIALLY_APPROVED: 일주일 동안 1천만원까지 지급대행이 가능한 상태입니다. 등록 직후의 법인사업자 셀러 또는 본인인증을 완료한 개인 및 개인사업자 셀러의 상태입니다.
- KYC_REQUIRED: 지급대행이 불가능한 상태입니다. 일주일 동안 1천만원을 초과하는 금액을 지급 요청하면 셀러는 해당 상태로 변경됩니다. 셀러가 KYC 심사를 완료해야 합니다.
- APPROVED: 금액 제한 없이 지급대행이 가능한 상태입니다. KYC 심사가 정상적으로 완료된 셀러의 상태입니다.
account object
셀러가 정산금을 지급받을 계좌 정보입니다.
- bankCode string
  은행 세 자리 코드입니다. 은행 코드와 증권사 코드를 참고하세요.
- accountNumber string
  계좌번호입니다. 최대 길이는 20자입니다.
- holderName string
  계좌 예금주입니다. 최대 길이는 공백을 포함해 한영 구분 없이 50자입니다.
metadata nullable · object
셀러와 관련된 추가 정보를 key-value 쌍으로 담고 있는 객체입니다. 최대 5개의 키-값(key-value) 쌍입니다. 키는 [ , ] 를 사용하지 않는 최대 40자의 문자열, 값은 최대 2000자의 문자열입니다.

셀러 등록

POST /v2/sellers

오픈마켓에 입점해있는 셀러의 정보를 토스페이먼츠에 등록합니다. 셀러의 사업자번호, 계좌 유효성을 검증합니다.

셀러 등록은 지급대행 서비스의 POST 요청입니다. ENCRYPTION 보안으로 요청을 보내주세요.

Request Body 파라미터

refSellerId 필수 · string
오픈마켓 상점에서 발급하는 셀러의 고유 식별자입니다. 연동 중에 참고할 수 있는 값입니다. 등록 이후에는 수정할 수 없습니다. 허용된 길이는 7-20자 입니다.
businessType 필수 · string
사업자 유형입니다. INDIVIDUAL(개인), INDIVIDUAL_BUSINESS(개인사업자), CORPORATE(법인사업자) 중 하나입니다.
company object
법인사업자 또는 개인사업자 셀러 정보입니다. businessType이 INDIVIDUAL_BUSINESS 또는 CORPORATE이면 필수입니다.
- name string
  사업자명입니다.
- representativeName 필수 · string
  대표자명입니다.
- businessRegistrationNumber 필수 · string
  사업자번호입니다. - 없이 10자리 사업자번호 숫자만 입력해주세요.
- email 필수 · string
  이메일입니다
- phone 필수 · string
  사업자 전화번호입니다. - 없이 숫자로만 구성된 최소 8자의 문자열입니다.
individual object
개인 셀러 정보입니다. businessType이 INDIVIDUAL이면 필수입니다.
- name 필수 · string
  개인의 이름입니다.
- email 필수 · string
  이메일입니다
- phone 필수 · string
  전화번호입니다. - 없이 숫자로만 구성된 최소 8자의 문자열입니다.
account 필수 · object
셀러가 정산 금액을 지급받을 계좌 정보입니다.
- bankCode 필수 · string
  계좌의 은행 코드입니다. 은행 코드와 증권사 코드를 참고해서 두 자리 코드 또는 세 자리 코드를 사용해주세요.
- accountNumber 필수 · string
  계좌번호입니다. - 없이 숫자만 입력해주세요. 최대 길이는 14자입니다.
- holderName 필수 · string
  계좌 예금주입니다. 최대 길이는 공백을 포함해 한영 구분 없이 50자입니다.
metadata object
셀러와 관련된 추가 정보를 key-value 쌍으로 담고 있는 JSON 객체입니다. 최대 5개의 키-값(key-value) 쌍입니다. 키는 [ , ] 를 사용하지 않는 최대 40자의 문자열, 값은 최대 2000자의 문자열입니다.

Response

성공

셀러 등록에 성공하면 JWE로 암호화된 Seller 객체가 돌아옵니다. 보안 키로 복호화해서 응답 값을 확인해주세요.

실패

셀러 등록에 실패하면 JWE로 암호화된 에러 객체가 돌아옵니다. 보안 키로 복호화해서 응답 값을 확인해주세요.

셀러 등록에서 발생할 수 있는 에러를 살펴보세요.

셀러 수정

POST /v2/sellers/{id}

등록된 셀러 정보를 수정합니다. 수정하고 싶은 필드만 Request Body 파라미터로 보내주세요. 파라미터를 보내지 않으면 정보가 바뀌지 않습니다. 데이터를 삭제하고 싶다면 파라미터의 값을 null로 보내주세요. 등록할 때 필수 값이었던 필드는 삭제할 수 없습니다.

셀러 수정은 지급대행 서비스의 POST 요청입니다. ENCRYPTION 보안으로 요청을 보내주세요.

Path 파라미터

id 필수 · string
수정하고 싶은 Seller 객체의 id입니다. 토스페이먼츠에서 발급한 값이며, 오픈마켓 상점에서 발급한 refSellerId와 다른 값입니다.

Request Body 파라미터

company object
법인사업자 또는 개인사업자 셀러 정보입니다.
- name string
  사업자명입니다.
- representativeName string
  대표자명입니다.
- email string
  사업자 이메일입니다.
- phone string
  사업자 전화번호입니다. - 없이 숫자로만 구성된 최소 8자의 문자열입니다.
individual object
개인 셀러 정보입니다.
- email string
  이메일입니다.
- phone string
  전화번호입니다. - 없이 숫자로만 구성된 최소 8자의 문자열입니다.
account object
셀러에서 정산 금액을 지급받을 계좌 정보입니다.
- bankCode string
  계좌의 은행 코드입니다. 은행 코드와 증권사 코드를 참고하세요.
- accountNumber string
  계좌번호입니다. - 없이 숫자만 입력해주세요. 최대 길이는 14자입니다.
- holderName string
  계좌 예금주입니다. 최대 길이는 공백을 포함해 한영 구분 없이 50자입니다.
metadata object
셀러와 관련된 추가 정보를 key-value 쌍으로 담고 있는 JSON 객체입니다. 최대 5개의 키-값(key-value) 쌍입니다. 키는 [ , ] 를 사용하지 않는 최대 40자의 문자열, 값은 최대 2000자의 문자열입니다.

Response

성공

셀러 수정에 성공하면 JWE로 암호화된 Seller 객체가 돌아옵니다. 보안 키로 복호화해서 응답 값을 확인해주세요.

실패

셀러 수정에 실패하면 JWE로 암호화된 에러 객체가 돌아옵니다. 보안 키로 복호화해서 응답 값을 확인해주세요.

셀러 수정에서 발생할 수 있는 에러를 살펴보세요.

셀러 삭제

DELETE /v2/sellers/{id}

등록된 셀러를 삭제합니다. 삭제한 셀러의 id 식별자는 다시 발급되지 않고 조회가 불가능합니다.

Path 파라미터

id 필수 · string
삭제하고 싶은 Seller 객체의 id입니다. 토스페이먼츠에서 발급한 값이며, 오픈마켓 상점에서 발급한 refSellerId와 다른 값입니다.

Response

성공

셀러 삭제에 성공하면 deleted-entity 객체가 돌아옵니다.

실패

셀러 삭제에 실패하면 에러 객체가 돌아옵니다.

셀러 삭제에서 발생할 수 있는 에러를 살펴보세요.

셀러 단건 조회

GET /v2/sellers/{id}

토스페이먼츠에 등록한 하나의 셀러를 조회합니다. 삭제되지 않은 셀러만 조회할 수 있어요.

Path 파라미터

id 필수 · string
조회하고 싶은 Seller 객체의 id입니다. 토스페이먼츠에서 발급한 값이며, 오픈마켓 상점에서 발급한 refSellerId와 다른 값입니다.

Response

성공

셀러 단건 조회에 성공하면 Seller 객체가 돌아옵니다.

실패

셀러 단건 조회에 실패하면 에러 객체가 돌아옵니다.

셀러 단건 조회에서 발생할 수 있는 에러를 살펴보세요.

셀러 목록 조회

GET /v2/sellers

토스페이먼츠에 등록한 셀러 목록을 조회합니다. 삭제되지 않은 셀러만 조회할 수 있어요.

* 라이브 환경에서 비정상적으로 많은 요청을 보내면 429 Too Many Requests 상태 코드가 내려올 수 있습니다.

Query 파라미터

limit integer
조회하고 싶은 셀러 개수입니다. 기본 값은 10입니다. 설정할 수 있는 최대값은 10000입니다.
startingAfter string
특정 셀러의 id입니다. 해당 id의 셀러 다음으로 등록된 셀러부터 조회됩니다. 기본 값은 최초에 등록된 셀러입니다.

Response

성공

셀러 목록 조회에 성공하면 seller-list 객체가 돌아옵니다. entityBody에 다음과 같은 필드가 있습니다.

hasMore boolean
더 조회할 수 있는 데이터가 있는지 알려줍니다. 마지막 데이터라면 false, 다음 데이터가 있다면 true입니다.
size integer
조회된 객체의 개수입니다. items의 크기입니다.
nextCursor nullable · stirng
다음 조회 시 startingAfter로 설정하면 되는 커서입니다. 만약에 더 조회할 데이터 없다면 null입니다.
items array
Seller 객체 목록입니다.

실패

셀러 목록 조회에 실패하면 에러 객체가 돌아옵니다.

셀러 목록 조회에서 발생할 수 있는 에러를 살펴보세요.

Payout 객체

지급대행 요청 정보입니다.

객체 상세

id string
토스페이먼츠에서 발급하는 지급대행 요청의 고유 식별자입니다. 지급대행 취소, 조회 등에 사용됩니다. 최대 길이는 35자입니다.
refPayoutId nullable · string
지급대행 상점에서 직접 발급하는 지급대행 요청의 고유 식별자입니다. 연동 중에 참고할 수 있는 값입니다. 등록 이후에 수정할 수 없고, 같은 값을 다시 사용할 수 없습니다. 최대 길이는 50자입니다.
destination string
정산금을 지급받는 셀러입니다. Seller 객체의 id 값입니다.
scheduleType string
지급대행의 유형입니다. 아래 둘 중 하나입니다.
- EXPRESS: 바로지급입니다. 요청한 당일 이내 정산이 지급됩니다.
- SCHEDULED: 예약지급입니다. 요청일을 설정해서 정산 지급을 예약합니다.
payoutDate string
yyyy-MM-dd 형식의 지급일입니다.
amount object
셀러에게 지급하는 정산 금액입니다.
- currency string
  통화입니다. 현재는 KRW만 지원합니다.
- value number
  잔액입니다.
transactionDescription string
이체 내역에 표시되는 적요입니다. 최대 길이는 7자입니다.
requestedAt string
지급대행이 요청된 시점입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm 형식입니다.
status string
지급대행 상태입니다. 지급대행 상태가 바뀌면 payout.changed 웹훅이 발송됩니다.
- REQUESTED: 지급이 요청되었지만 아직 처리되지 않은 상태입니다. REQUESTED 상태일 때만 지급대행 요청을 취소할 수 있습니다.
- IN_PROGRESS: 지급을 처리하고 있는 상태입니다.
- COMPLETED: 셀러에 지급이 완료된 상태입니다.
- FAILED: 지급 요청이 실패한 상태입니다.
- CANCELED: 지급 요청이 취소된 상태입니다.
- DELETED: 지급요청서가 삭제된 상태입니다. 웹훅이 발송되지 않습니다.
- REJECTED: 지급 요청이 반려된 상태입니다. 웹훅은 FAILED 상태로 발송됩니다.
error nullable
지급대행 요청에서 일어난 에러 객체입니다.
metadata nullable · object
지급과 관련된 추가 정보를 key-value 쌍으로 담고 있는 객체입니다. 최대 5개의 키-값(key-value) 쌍입니다. 키는 [ , ] 를 사용하지 않는 최대 40자의 문자열, 값은 최대 2000자의 문자열입니다.

지급대행 요청

POST /v2/payouts

지급 대상 셀러에게 정산 금액을 이체합니다. 요청 시점에 잔액이 부족하면 지급이 실패합니다.

지급대행 요청은 지급대행 서비스의 POST 요청입니다. ENCRYPTION 보안으로 요청을 보내주세요.

최대 100건의 지급대행을 한 번에 요청할 수 있습니다. 하지만 하나의 요청이 실패하면 요청 모두 실패하고 첫 번째 실패 건에 대한 에러 객체가 응답으로 돌아옵니다. 1건의 지급대행 요청에는 10억 미만의 정산 금액을 이체할 수 있습니다.

지급대행으로 셀러에게 지급한 정산 금액은 회수하기 어렵습니다. 토스페이먼츠는 지급 관련 책임이 없기 때문에 지급대행 서비스를 신중하게 사용해주세요.

API 키 접근 정책을 등록하면 허용한 IP에서만 API를 호출할 수 있어 키가 유출되어도 안전합니다.

* 지급대행 요청 API를 라이브 환경에서 테스트하면 수수료가 부과됩니다.

Request Body 파라미터

refPayoutId 필수 · string
상점에서 직접 발급하는 지급대행 식별자입니다. 각 지급대행 요청 건에 고유 값을 발급해야 되고 지급대행 상점에서 참고용으로 사용할 수 있습니다.
destination 필수 · string
정산금을 지급받는 셀러입니다. Seller 객체의 id 값입니다.
scheduleType 필수 · string
지급대행의 유형입니다. 아래 둘 중 하나입니다.
- EXPRESS: 바로지급입니다. 요청한 당일 이내 정산금이 지급됩니다. 바로지급을 요청할 수 있는 시간은 영업일 08:00~15:00입니다.
- SCHEDULED: 예약지급입니다. 요청일을 설정해서 정산금 지급을 예약합니다.
payoutDate string
yyyy-MM-dd 형식의 지급일입니다. 지급대행 유형이 SCHEDULED일 때는 필수입니다. 지급일은 미래에 1년 이내에 있는 영업일로만 설정할 수 있어요. 휴일, 공휴일, 과거일자로 설정하면 오류가 발생해요.
amount 필수 · object
지급 금액 정보입니다.
transactionDescription 필수 · string
이체 내역에 표시되는 적요입니다. 최대 길이는 7자입니다.
metadata object
요청과 관련된 추가 정보를 key-value 쌍으로 담고 있는 객체입니다. 최대 5개의 키-값(key-value) 쌍입니다. 키는 [ , ] 를 사용하지 않는 최대 40자의 문자열, 값은 최대 2000자의 문자열입니다.

Response

성공

지급대행 요청에 성공하면 JWE로 암호화된 payout-list 객체가 돌아옵니다. 보안 키로 복호화해서 응답 값을 확인해주세요.

객체의 entityBody 필드의 items에서 Payout 객체 목록을 확인할 수 있습니다.

실패

지급대행 요청에 실패하면 JWE로 암호화된 에러 객체가 돌아옵니다. 보안 키로 복호화해서 응답 값을 확인해주세요.

지급대행 요청에 실패하면 요청 건 모두 실패하고 요청 건 중에 첫 번째 에러에 대한 에러 객체가 돌아옵니다.

지급대행 요청에서 발생할 수 있는 에러를 살펴보세요.

지급대행 요청 취소

POST /v2/payouts/{id}/cancel

REQUESTED 상태의 지급대행 요청 건을 취소합니다. 이미 처리 중이거나 완료된 지급대행 요청 건은 취소할 수 없습니다.

Path 파라미터

id 필수 · string
취소하고 싶은 Payout 객체의 id입니다.

Response

성공

지급대행 요청 취소에 성공하면 status가 CANCELED로 바뀐 Payout 객체가 돌아옵니다.

실패

지급대행 요청 취소에 실패하면 에러 객체가 돌아옵니다.

지급대행 요청 취소에서 발생할 수 있는 에러를 살펴보세요.

지급 요청 단건 조회

GET /v2/payouts/{id}

지급 요청 한 건을 조회합니다.

Path 파라미터

id 필수 · string
조회하고 싶은 Payout 객체의 id입니다.

Response

성공

지급 요청 단건 조회에 성공하면 Payout 객체가 돌아옵니다.

실패

지급 요청 단건 조회에 실패하면 에러 객체가 돌아옵니다.

지급 요청 단건 조회에서 발생할 수 있는 에러를 살펴보세요.

지급 요청 목록 조회

GET /v2/payouts

지급 요청 목록을 조회합니다.

* 라이브 환경에서 비정상적으로 많은 요청을 보내면 429 Too Many Requests 상태 코드가 내려올 수 있습니다.

Query 파라미터

limit 필수 · integer
조회하고 싶은 지급대행 요청건의 개수입니다. 기본 값은 10이고, 설정할 수 있는 최대값은 10000입니다.
startingAfter 필수 · string
커서로 사용할 지급대행 요청건의 id입니다. 설정한 id의 지급대행 요청건 다음으로 등록된 요청건부터 조회됩니다. 설정하지 않으면 최초의 지급대행 요청건부터 조회됩니다.
payoutDateGte string
커서로 사용할 지급일입니다. 해당 지급일과 같거나 더 이후(이상)에 발생하는 지급대행 요청 건을 조회합니다.
payoutDateLte string
지급일입니다. 해당 지급일과 같거나 더 이전(이하)에 발생하는 지급대행 요청 건을 조회합니다.

Response

성공

지급대행 요청에 payout-list 객체가 돌아옵니다. entityBody에 다음과 같은 필드가 있습니다.

hasMore boolean
더 조회할 수 있는 데이터가 있는지 알려줍니다. 마지막 데이터라면 false, 다음 데이터가 있다면 true입니다.
size integer
조회된 객체의 개수입니다. items의 크기입니다.
nextCursor nullable · stirng
다음 조회 시 startingAfter로 설정하면 되는 커서입니다. 만약에 더 조회할 데이터 없다면 null입니다.
items array
Payout 객체 목록입니다.

실패

지급 요청 목록 조회에 실패하면 에러 객체가 돌아옵니다.

계좌인증

계좌인증은 계좌번호와 소유자 정보를 기반으로 계좌의 유효성과 일치 여부를 확인하는 서비스입니다. 가상계좌 환불이나 지급대행 셀러 등록 과정에서 계좌번호를 수취할 때, 해당 계좌번호가 유효한지 사전에 확인하는 데 사용할 수 있습니다.

* 테스트 환경에서는 실제 인증 절차를 거치지 않고, Mock 데이터가 응답으로 제공됩니다.

매일 23:30~00:30 사이에는 은행 점검으로 계좌인증 서비스가 일시적으로 실패할 수 있습니다. 실패하는 경우 {"code":"NOT_AVAILABLE_BANK_ACCOUNT_VERIFICATION","message":"은행계좌 검증 서비스를 이용할 수 없습니다."} 에러가 응답됩니다. 점검 시간대에도 항상 실패하는 것은 아니며, 정상 응답과 에러 응답이 번갈아 발생할 수 있으므로 재시도 로직을 함께 고려해주세요.

계좌번호로 예금주명 조회

POST /v2/bank-accounts/lookup-holder-name

계좌번호로 계좌의 예금주명을 조회합니다.

Request Body 파라미터

bankCode 필수 · string
계좌의 은행 코드입니다. 은행 코드와 증권사 코드를 참고해서 두 자리 코드 또는 세 자리 코드를 사용해주세요.
accountNumber 필수 · string
계좌번호입니다. - 없이 숫자만 입력해주세요. 최대 길이는 14자입니다.

Response

성공

계좌번호로 예금주명 조회에 성공했다면 예금주명(holderName)이 돌아옵니다. 발생할 수 있는 에러를 살펴보세요.

실패

계좌번호로 예금주명 조회에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

계좌번호 유효성 확인

POST /v2/bank-accounts/validate

계좌 정보로 계좌의 존재 여부를 확인합니다.

Request Body 파라미터

bankCode 필수 · string
계좌의 은행 코드입니다. 은행 코드와 증권사 코드를 참고해서 두 자리 코드 또는 세 자리 코드를 사용해주세요.
accountNumber 필수 · string
계좌번호입니다. - 없이 숫자만 입력해주세요. 최대 길이는 14자입니다.

Response

성공

확인에 성공했다면 확인 결과(isValid)가 돌아옵니다.

실패

확인에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다. 발생할 수 있는 에러를 살펴보세요.

계좌번호·식별자 일치 확인

POST /v2/bank-accounts/verify-identifier

계좌번호와 식별자(생년월일/사업자번호)가 일치하는지 확인합니다.

식별자(identityNumber) 일치 확인은 직접조회 은행에서만 지원됩니다. 간접조회 은행(카카오뱅크, 삼성증권을 제외한 증권사 등)에서는 식별자 검증이 수행되지 않아 실제 식별자와 다른 값을 입력해도 성공 응답이 돌아올 수 있습니다.

직접조회 은행: 농협, 우리은행, 국민은행, 신한은행, 하나은행, 기업은행, 부산은행, 우체국, 대구은행, 새마을금고, 광주은행, SC제일은행, 경남은행, 씨티은행, 신협, 전북은행, 수협은행, 제주은행, 산업은행, 케이뱅크, 토스뱅크, 삼성증권, 산림조합중앙회

Request Body 파라미터

bankCode 필수 · string
계좌의 은행 코드입니다. 은행 코드와 증권사 코드를 참고해서 두 자리 코드 또는 세 자리 코드를 사용해주세요.
accountNumber 필수 · string
계좌번호입니다. - 없이 숫자만 입력해주세요. 최대 길이는 14자입니다.
identityNumber 필수 · string
계좌 소유자의 식별자입니다. 개인 계좌의 경우 생년월일(YYMMDD)이며, 법인 계좌의 경우 사업자등록번호입니다. - 없이 숫자만 입력해주세요.

Response

성공

일치 확인에 성공했다면 확인 결과(isValid)가 돌아옵니다.

실패

일치 확인에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다. 발생할 수 있는 에러를 살펴보세요.

계좌번호·예금주명 일치 확인

POST /v2/bank-accounts/verify-holder-name

계좌번호와 예금주 이름이 일치하는지 확인합니다. 아래와 같은 상황에서 사용하세요.

가상계좌 환불 계좌 유효성 검증
지급대행 셀러 등록 시 계좌 예금주 확인
결제 서비스 외 계좌 예금주 일치 여부 확인이 필요한 경우

계좌 존재 여부만 확인하려면 계좌번호 유효성 확인 API를 사용하세요. 예금주명 없이 식별자(생년월일·사업자번호)만 확인하려면 계좌번호·식별자 일치 확인 API를, 예금주명과 식별자를 함께 확인하려면 계좌번호·예금주명·식별자 일치 확인 API를 사용하세요.

Request Body 파라미터

bankCode 필수 · string
계좌의 은행 코드입니다. 은행 코드와 증권사 코드를 참고해서 두 자리 코드 또는 세 자리 코드를 사용해주세요.
accountNumber 필수 · string
계좌번호입니다. - 없이 숫자만 입력해주세요. 최대 길이는 14자입니다.
holderName 필수 · string
계좌 예금주입니다. 최대 길이는 공백을 포함해 한영 구분 없이 50자입니다.

Response

성공

일치 확인에 성공했다면 확인 결과(isValid)가 돌아옵니다.

실패

일치 확인에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다. 발생할 수 있는 에러를 살펴보세요.

계좌번호·예금주명·식별자 일치 확인

POST /v2/bank-accounts/verify-holder-real-name

계좌번호와 예금주명, 그리고 식별자(생년월일/사업자번호)가 일치하는지 확인합니다.

Request Body 파라미터

bankCode 필수 · string
계좌의 은행 코드입니다. 은행 코드와 증권사 코드를 참고해서 두 자리 코드 또는 세 자리 코드를 사용해주세요.
accountNumber 필수 · string
계좌번호입니다. - 없이 숫자만 입력해주세요. 최대 길이는 14자입니다.
holderName 필수 · string
계좌 예금주입니다. 최대 길이는 공백을 포함해 한영 구분 없이 50자입니다.
identityNumber 필수 · string
계좌 소유자의 식별자입니다. 개인 계좌의 경우 생년월일(YYMMDD)이며, 법인 계좌의 경우 사업자등록번호입니다. - 없이 숫자만 입력해주세요.

Response

성공

일치 확인에 성공했다면 확인 결과(isValid)가 돌아옵니다.

실패

일치 확인에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다. 발생할 수 있는 에러를 살펴보세요.

에스크로

에스크로는 구매자가 결제한 대금을 토스페이먼츠가 보관하고 있다가 배송과 구매확정이 끝나면 상점에 지급하는 구매자 보호 서비스입니다. 결제가 완료(가상계좌는 입금)되면 에스크로 거래가 개설되고, 상점은 배송 등록·취소 요청 수락·구매확정 요청 메일 재발송을 API로 처리합니다. 대상 결제수단은 카드·가상계좌·계좌이체입니다. 전체 흐름과 상태 모델은 에스크로 가이드에서 확인하세요.

Escrow 객체

에스크로 거래 리소스입니다. 거래 상태·확정·취소·상품·배송 정보를 담습니다.

객체 상세

id string
에스크로 거래 ID입니다. 결제 응답의 escrowKey와 같은 값입니다. 후속 요청은 이 값으로 보냅니다.
targetId string
에스크로가 성립한 대상 리소스의 ID입니다. Payment 객체의 paymentKey와 이 값으로 연결하세요.
targetType string
에스크로가 성립한 대상 리소스의 종류입니다. 지금은 결제(PAYMENT)만 지원됩니다.
mid string
상점 ID입니다.
status string
에스크로 상태입니다. 상태가 바뀌면 escrow.changed 웹훅이 발송됩니다.
- IN_PROGRESS: 결제 완료·구매확정 전 상태입니다.
- CANCEL_REQUESTED: 구매자가 취소를 신청해 상점의 수락 판단을 기다리는 상태입니다.
- CONFIRMED: 구매확정이 완료된 상태입니다.
- CANCELED: 취소가 확정된 상태(종결)입니다.
openedAt string
거래가 개설된 시각입니다. 결제가 완료(가상계좌는 입금)되어 대금이 에스크로에 맡겨진 순간이며, 항상 값이 있습니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.
confirmType nullable · string
확정 종류입니다. status=CONFIRMED일 때만 채워집니다. CUSTOMER(구매자가 확정) 또는 AUTO(기한 도래 자동확정) 중 하나입니다.
confirmedAt nullable · string
구매확정 시각입니다. status=CONFIRMED일 때만 값이 있습니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.
cancelType nullable · string
취소 종류입니다. status=CANCELED일 때만 채워집니다. CUSTOMER(구매자가 취소를 신청하고 상점이 수락한 거래) 또는 TARGET_CANCELED(대상 결제가 취소되어 에스크로도 함께 종결된 거래) 중 하나입니다. 둘 다 결과는 CANCELED로 같지만 상점이 판단한 취소인지가 다르므로, 집계할 때 둘을 한데 묶지 마세요.
canceledAt nullable · string
취소 확정 시각입니다. status=CANCELED일 때만 값이 있습니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.
cancelRequestedAt nullable · string
구매자가 취소를 신청한 시각입니다. 신청이 없었으면 null입니다. cancelType=TARGET_CANCELED인 경우 canceledAt과 같은 값으로 내려옵니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.
products array
거래 상품 구성입니다. 결제 요청의 escrowProducts로 전달한 값이 그대로 실립니다. escrowProducts를 전달하지 않으면 Payment 객체의 orderId, orderName을 기반으로 1개가 디폴트로 생성됩니다.
- id string
  상품 ID입니다. 배송 등록 요청의 targetId에 이 값을 넣습니다(targetType: ESCROW_PRODUCT).
- refProductId string
  상점이 결제 요청 escrowProducts[].id로 보낸 값입니다. 상점 카탈로그 조인용입니다. 값이 없으면 null이 아니라 빈 문자열("")입니다.
- name string
  상품 이름입니다. 값이 없으면 null이 아니라 빈 문자열("")입니다.
- quantity integer
  수량입니다.
deliveryIds array
이 거래에 등록된 배송 리소스의 ID 목록입니다(delivery_ 접두). products보다 개수가 적으면 아직 등록할 배송이 남은 것입니다. 상태·송장·대상 키는 배송 조회 API로 조회하세요.

Delivery 객체

상품 하나의 배송 리소스입니다. 상품:배송 = 1:1 관계이며, 거래 status와는 별개의 자체 status를 가집니다.

객체 상세

id string
배송 리소스 ID입니다.
targetType string
배송 대상 리소스의 종류입니다. 지금은 에스크로 상품(ESCROW_PRODUCT)만 지원됩니다.
targetId string
배송 대상 리소스의 키입니다. targetType: ESCROW_PRODUCT에서는 거래 조회 응답의 products[].id와 같은 값입니다.
status string
배송 상태입니다. 상태가 바뀌면 delivery.changed 웹훅이 발송됩니다.
- IN_TRANSIT: 배송중 상태입니다. 택배 등록 시 이 상태로 진입합니다.
- COMPLETED: 배송완료 상태입니다. 택배는 배송추적이 완료 판정하면, 직접 전달은 등록 즉시 이 상태가 됩니다.
deliveryMethod string
배송 방법입니다. SHIPMENT(택배) 또는 DIRECT(직접 전달)입니다.
completedAt nullable · string
배송완료 시각입니다. DIRECT는 등록 요청의 receivedAt이 그대로 들어가고, SHIPMENT는 배송추적이 완료를 판정한 시각입니다. status=COMPLETED일 때만 값이 있습니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.
submittedAt nullable · string
지금 실려 있는 배송 정보를 제출한 시각입니다. 수정하면 갱신됩니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.
shipment nullable · object
택배 배송 정보입니다. deliveryMethod=SHIPMENT일 때만 채워집니다.
- carrierCode string
  택배사 코드입니다. 지원 목록은 택배사 코드를 참고하세요.
- carrierName string
  택배사 이름입니다. 코드에 매칭되는 이름을 토스페이먼츠가 채웁니다.
- trackingNumber string
  송장번호입니다.
- shippedAt string
  발송일시입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.
direct nullable · object
직접 전달 정보입니다. deliveryMethod=DIRECT일 때만 채워집니다.
- receiverName string
  수령인 이름입니다.
- receiverRelation string
  수령인과 구매자의 관계입니다. BUYER·FAMILY·OFFICE·OTHER 중 하나입니다.

에스크로 거래 조회

GET /v2/escrows/{id}

에스크로 거래를 조회합니다.

Path 파라미터

id 필수 · string
에스크로 거래 ID입니다. 결제 승인 응답 escrowKey에서 받아 보관하세요. 최대 50자입니다.

Response

성공

조회에 성공하면 Escrow 객체가 entityBody로 돌아옵니다.

실패

조회에 실패하면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

배송 등록

POST /v2/deliveries

배송 정보를 등록합니다.

한 번의 호출 = 상품 하나의 배송입니다. 상품이 여러 개인 거래는 상품 수만큼 호출하세요.
자동확정 기한은 상품 전체가 배송완료됐을 때 기산됩니다.
성공 시 delivery.changed 웹훅이 발송됩니다.

Request Body 파라미터

targetType 필수 · string
배송을 붙일 대상 리소스의 종류입니다. 지금은 에스크로 상품(ESCROW_PRODUCT)만 지원됩니다.
targetId 필수 · string
배송할 대상의 리소스 키입니다. targetType: ESCROW_PRODUCT에서는 거래 조회 응답의 products[].id입니다. 상품이 하나뿐이어도 명시하세요. 최대 50자입니다.
deliveryMethod 필수 · string
SHIPMENT(택배) 또는 DIRECT(직접 전달)입니다.
shipment object
SHIPMENT일 때 전달합니다.
- carrierCode 필수 · string
  최대 15자. 택배사 코드입니다. 지원 목록은 아래 택배사 코드를 확인하세요.
- trackingNumber 필수 · string
  최대 80자. 송장번호입니다. 택배사별 송장번호 형식 검증을 거치며, 형식이 틀리면 400 INVALID_REQUEST입니다.
- shippedAt 필수 · string
  발송일시는 yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.
direct object
DIRECT일 때 전달합니다.
- receivedAt 필수 · string
  실수령일시는 yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.
- receiverName 필수 · string
  최대 50자. 수령인 이름입니다.
- receiverRelation string
  수령인과 구매자의 관계입니다(BUYER·FAMILY·OFFICE·OTHER).

택배(SHIPMENT)는 등록 즉시 status: IN_TRANSIT이 되고, 배송추적이 완료를 판정하면 status: COMPLETED로 전이됩니다. 직접 전달(DIRECT)은 등록 즉시 status: COMPLETED입니다.

Response

성공

등록에 성공하면 등록한 상품의 Delivery 객체 하나가 돌아옵니다. 거래의 다른 배송은 포함되지 않습니다.

실패

등록에 실패하면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

배송 수정

POST /v2/deliveries/{id}

등록한 배송 정보를 수정합니다. deliveryMethod는 항상 명시하며, shipment 안은 바꿀 필드만 보내면 됩니다.

수정할 수 있는 건 배송중(IN_TRANSIT)인 SHIPMENT뿐이며, 가능한 작업은 두 가지입니다.
1. 송장 정보 정정 — 택배사·송장번호를 고칩니다.
2. 직접 전달로 전환 — 택배로 잘못 등록했거나 실제로는 직접 전달한 경우. 즉시 배송완료 처리됩니다(completedAt=제출한 receivedAt).
배송완료된 배송은 수정할 수 없습니다(403 FORBIDDEN_COMPLETED_DELIVERY).
수정 자체로는 웹훅이 발송되지 않습니다 — 송장 정정은 상태가 그대로라 미발송, 직접 전달 전환은 COMPLETED로 바뀌므로 delivery.changed가 발송됩니다.

Path 파라미터

id 필수 · string
배송 ID입니다.

Request Body 파라미터

deliveryMethod 필수 · string
SHIPMENT 또는 DIRECT입니다. 유형과 무관한 객체를 보내면(SHIPMENT인데 direct 등) 400 INVALID_REQUEST입니다.
shipment object
바꿀 필드만 보내면 됩니다(필드 정의는 배송 등록과 동일, targetType/targetId 제외).
direct object
직접 전달 전환일 때 사용합니다. 필드 정의는 배송 등록과 동일합니다.

Response

성공

수정에 성공하면 수정이 반영된 Delivery 객체가 돌아옵니다.

실패

수정에 실패하면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

배송 조회

GET /v2/deliveries/{id}

배송 하나를 조회합니다. 배송은 최상위 리소스이므로 자기 ID로 읽습니다. ID는 배송 등록 응답·에스크로 거래 조회의 deliveryIds·delivery.changed 웹훅에서 얻습니다.

Path 파라미터

id 필수 · string
배송 ID입니다. 최대 50자입니다.

Response

성공

조회에 성공하면 Delivery 객체가 돌아옵니다.

실패

없는 키·다른 상점의 배송·입금 전 거래의 배송이면 404 NOT_FOUND입니다. 그 밖의 실패는 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

구매확정 요청 메일 재발송

POST /v2/escrows/{id}/confirm-request

구매자에게 구매확정을 요청하는 메일을 다시 보냅니다. 배송이 끝났는데 구매자가 확정하지 않거나, 취소 요청을 수락할 수 없는 상황에서 사용합니다.

상태는 바뀌지 않습니다. CANCEL_REQUESTED에서 호출해도 취소 요청이 철회되지 않으며, 성공 응답의 status도 호출 전과 같습니다.
자동확정 기한은 리셋되지 않습니다.
웹훅은 발송되지 않습니다 — 상태 변화가 없기 때문입니다. 구매자가 실제로 확정하면 그때 escrow.changed(status=CONFIRMED)가 발송됩니다.

호출 조건 (상태별로 다릅니다):

거래 `status`	배송 조건	결과
`CANCEL_REQUESTED`	무관	호출 가능 (배송 전이어도 가능 — 취소 철회 수단이 사실상 확정뿐이므로)
`IN_PROGRESS`	전 상품 배송완료	호출 가능
`IN_PROGRESS`	하나라도 미등록·배송중	`403 FORBIDDEN_INCOMPLETE_DELIVERY`
`CONFIRMED`·`CANCELED`	—	종결된 거래라 호출 불가

연속 호출 제한 — 확정 요청 메일이 발송 대기 중이거나, 마지막 발송(배송완료 시 자동으로 나가는 최초 안내 메일 포함) 후 24시간이 지나지 않았으면 403 FORBIDDEN_RECENT_CONFIRM_REQUEST입니다. 남은 쿨다운 시간은 노출되지 않으므로 24시간 뒤에 재시도하세요.

본문에 email을 넣으면 이번 한 통만 그 주소로 보냅니다. 구매자 이메일(원장)은 바뀌지 않아서, 이후 자동으로 나가는 메일은 여전히 원래 주소로 발송됩니다. 본문 없이 호출하면 구매자 이메일로 보냅니다.

Path 파라미터

id 필수 · string
에스크로 거래 ID입니다.

Request Body 파라미터

email string
받는 사람 지정으로, 이번 발송에만 적용되고 구매자 이메일은 바뀌지 않습니다. 형식이 올바르지 않으면 400 INVALID_REQUEST입니다.

Response

성공

재발송에 성공하면 거래의 Escrow 객체가 그대로 돌아옵니다. 상태를 바꾸는 API가 아니라 status도 호출 전과 같습니다.

실패

재발송에 실패하면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

취소 요청 수락

POST /v2/escrows/{id}/cancel

구매자의 취소 요청(status=CANCEL_REQUESTED)을 수락해 거래를 취소합니다. 환불을 일으키는 API이므로 멱등키가 필수입니다. 성공하면 status가 CANCELED, cancelType이 CUSTOMER가 되고 escrow.changed 웹훅이 발송됩니다.

에스크로 거래는 진행 중 부분취소가 불가하므로 전액 취소입니다. 금액을 지정하지 않습니다. 환불 계좌는 구매자가 취소 요청 과정에서 등록한 계좌가 사용되며, 상점이 전달하거나 응답에 노출되지 않습니다. 취소 요청을 반려하는 경로는 없습니다 — 선택지는 수락 또는 미조치, 또는 구매확정 요청 메일 재발송입니다.

Path 파라미터

id 필수 · string
에스크로 거래 ID입니다.

Request Body 파라미터

reason string
취소 사유로, 결제 취소 내역에 함께 기록됩니다. 최대 150자입니다.

Response

성공

취소 수락에 성공하면 취소가 반영된 Escrow 객체가 돌아옵니다(status=CANCELED·cancelType=CUSTOMER·canceledAt 채워짐).

실패

취소 수락에 실패하면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

.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;}지급대행

Balance 객체

객체 상세

잔액 조회

Response

Seller 객체

객체 상세

셀러 등록

Request Body 파라미터

Response

셀러 수정

Path 파라미터

Request Body 파라미터

Response

셀러 삭제

Path 파라미터

Response

셀러 단건 조회

Path 파라미터

Response

셀러 목록 조회

Query 파라미터

Response

Payout 객체

객체 상세

지급대행 요청

Request Body 파라미터

Response

지급대행 요청 취소

Path 파라미터

Response

지급 요청 단건 조회

Path 파라미터

Response

지급 요청 목록 조회

Query 파라미터

Response

계좌인증

계좌번호로 예금주명 조회

Request Body 파라미터

Response

계좌번호 유효성 확인

Request Body 파라미터

Response

계좌번호·식별자 일치 확인

Request Body 파라미터

Response

계좌번호·예금주명 일치 확인

Request Body 파라미터

Response

계좌번호·예금주명·식별자 일치 확인

Request Body 파라미터

Response

에스크로

Escrow 객체

객체 상세

Delivery 객체

객체 상세

에스크로 거래 조회

Path 파라미터

Response

배송 등록

Request Body 파라미터

Response

배송 수정

Path 파라미터

Request Body 파라미터

Response

배송 조회

Path 파라미터

Response

구매확정 요청 메일 재발송

Path 파라미터

Request Body 파라미터

Response

취소 요청 수락

Path 파라미터

Request Body 파라미터

Response

지급대행