*** title: 부가 API description: 부가 API는 결제 서비스 외에 별도 계약 또는 신청을 통해 사용할 수 있는 서비스입니다. 각 서비스 신청 경로는 아래 섹션에서 확인하세요. ------------------------------------------------------------------------------------------- title: 인증 및 기타 헤더 설정 description: href: /reference/using-api/authorization title: 요청·응답 본문 description: href: /reference/using-api/req-res > **참고**: 토스페이먼츠가 발급하는 식별자는 파싱하지 말고 불투명한 문자열로 다루세요. 형식과 길이는 최대 길이 안에서 바뀔 수 있으니 저장 컬럼은 64자 이상으로 잡으세요. 필드 설명에 더 긴 최대 길이가 적혀 있으면 그 길이로 잡으세요. 자세한 내용은 [식별자](/reference/using-api/req-res#식별자)를 참고하세요. ## 지급대행 지급대행은 오픈마켓에서 발생한 매출을 토스페이먼츠가 오픈마켓을 대신하여 셀러(입점 판매자)에게 지급하는 서비스입니다. 직접 수많은 셀러에게 정산할 필요 없이, 정산 업무를 토스페이먼츠한테 맡기고 자금 흐름을 더 효율적으로 관리할 수 있어요. 토스페이먼츠와 직접 계약하지 않은 셀러에게 토스페이먼츠가 정산금을 보내야 되기 때문에 [KYC](/resources/glossary/kyc) 등 리스크 검토 절차가 있습니다. 그리고 연동 측면에서도 더 강화된 보안을 요구합니다. Request Body가 있는 **지급대행 POST 요청은 모두 [`ENCRYPTION` 보안](/guides/v2/payouts#encryption-보안)을 사용합니다.** `ENCRYPTION` 보안은 토스페이먼츠에서 발급하는 보안 키를 사용해서 API의 Request Body를 JWE로 암호화하는 방식입니다. 자세한 암호화 방법은 [지급대행 가이드](/guides/v2/payouts)에서 확인해주세요. > **참고**: 지급대행 서비스는 상점관리자에서 직접 이용 신청할 수 있어요. **상점관리자 > 이용 정보 > 서비스 추가 신청** 메뉴로 이동하세요. ### Balance 객체 오픈마켓 쇼핑몰에서 셀러에게 지급할 수 있는 정산 잔액 정보입니다. #### 객체 상세 * **pendingAmount** 셀러에게 지급할 수 없는 잔액 정보입니다. 발생한 매출이 정산 주기 2일 전에 `pendingAmount` 금액으로 업데이트됩니다. 토스페이먼츠 정산 주기가 지난 금액은 `availableAmount`로 전환됩니다. * **currency** 통화입니다. 현재는 `KRW`만 지원합니다. * **value** 잔액입니다. * **availableAmount** 셀러에게 지급할 수 있는 잔액 정보입니다. * **currency** 통화입니다. 현재는 `KRW`만 지원합니다. * **value** 잔액입니다. method: GET path: /v2/balances ### 잔액 조회 셀러에게 지급할 수 있는 정산 금액을 조회합니다. #### Response 잔액 조회에 성공하면 [Balance 객체](#balance-객체)가 돌아옵니다. 잔액 조회에 실패하면 [에러 객체](/reference/using-api/req-res#api-v2-에러-객체)가 돌아옵니다. ### Seller 객체 오픈마켓에 입점되어 있는 셀러의 사업자, 계좌 정보입니다. #### 객체 상세 * **id** 토스페이먼츠에서 발급하는 셀러의 고유 식별자입니다. 셀러 조회, 삭제, 지급대행 요청에 사용됩니다. 셀러의 상태 및 지급대행 상태가 바뀌어도 `id`는 바뀌지 않고, 삭제된 `id`는 다시 발급되지 않습니다. 최대 길이는 35자입니다. * **refSellerId** `nullable` 오픈마켓 상점에서 직접 등록하는 셀러의 고유 식별자입니다. 연동 중에 참고할 수 있는 값입니다. 등록 이후에는 수정할 수 없습니다. 길이는 7자 이상 20자 이하입니다. * **businessType** 사업자 유형입니다. `INDIVIDUAL`(개인), `INDIVIDUAL_BUSINESS` (개인사업자), `CORPORATE`(법인사업자) 중 하나입니다. * **company** `nullable` 법인사업자 또는 개인사업자 셀러의 정보입니다. * **name** 사업자명입니다 * **representativeName** 대표자명입니다. * **businessRegistrationNumber** 사업자번호입니다 * **email** 사업자 이메일입니다. 해당 이메일로 KYC 심사 안내가 전송됩니다. 최대 길이는 100자입니다. * **phone** 사업자 전화번호입니다. * **individual** `nullable` 개인 셀러의 정보입니다. * **name** 개인의 이름입니다. * **email** 개인 이메일입니다. 해당 이메일로 KYC 심사 안내가 전송됩니다. 최대 길이는 100자입니다. * **phone** 개인 전화번호입니다. * **status** 셀러 상태입니다. 셀러 상태가 바뀌면 [`seller.changed`](/reference/using-api/webhook-events#sellerchanged)웹훅이 발송됩니다. \- `APPROVAL_REQUIRED`: 지급대행이 불가능한 상태입니다. 개인 및 개인사업자 셀러 등록 직후의 상태이며, 본인인증이 필요합니다. \- `PARTIALLY_APPROVED`: 일주일 동안 1천만원까지 지급대행이 가능한 상태입니다. 등록 직후의 법인사업자 셀러 또는 본인인증을 완료한 개인 및 개인사업자 셀러의 상태입니다. \- `KYC_REQUIRED`: 지급대행이 불가능한 상태입니다. 일주일 동안 1천만원을 초과하는 금액을 지급 요청하면 셀러는 해당 상태로 변경됩니다. 셀러가 KYC 심사를 완료해야 합니다. \- `APPROVED`: 금액 제한 없이 지급대행이 가능한 상태입니다. KYC 심사가 정상적으로 완료된 셀러의 상태입니다. * **account** 셀러가 정산금을 지급받을 계좌 정보입니다. * **bankCode** 은행 세 자리 코드입니다. [은행 코드](/codes/org-codes#은행-코드)와 [증권사 코드](/codes/org-codes#증권사-코드)를 참고하세요. * **accountNumber** 계좌번호입니다. 최대 길이는 20자입니다. * **holderName** 계좌 예금주입니다. 글자 수는 공백을 포함해 한영 구분 없이 셉니다. 최대 길이는 50자입니다. * **metadata** `nullable` 셀러와 관련된 추가 정보를 key-value 쌍으로 담고 있는 객체입니다. 최대 5개의 키-값(key-value) 쌍입니다. 키는 `[` , `]` 를 사용하지 않는 최대 40자의 문자열, 값은 최대 2000자의 문자열입니다. method: POST path: /v2/sellers ### 셀러 등록 오픈마켓에 입점해있는 셀러의 정보를 토스페이먼츠에 등록합니다. 셀러의 사업자번호, 계좌 유효성을 검증합니다. 셀러 등록은 지급대행 서비스의 POST 요청입니다. [`ENCRYPTION` 보안](/guides/v2/payouts#encryption-보안)으로 요청을 보내주세요. #### Request Body 파라미터 * **refSellerId** 오픈마켓 상점에서 발급하는 셀러의 고유 식별자입니다. 연동 중에 참고할 수 있는 값입니다. 등록 이후에는 수정할 수 없습니다. 길이는 7자 이상 20자 이하입니다. * **businessType** 사업자 유형입니다. `INDIVIDUAL`(개인), `INDIVIDUAL_BUSINESS`(개인사업자), `CORPORATE`(법인사업자) 중 하나입니다. * **company** 법인사업자 또는 개인사업자 셀러 정보입니다. `businessType`이 `INDIVIDUAL_BUSINESS` 또는 `CORPORATE`이면 필수입니다. * **name** 사업자명입니다. * **representativeName** 대표자명입니다. * **businessRegistrationNumber** 사업자번호입니다. `-` 없이 10자리 사업자번호 숫자만 입력해주세요. * **email** 이메일입니다 * **phone** 사업자 전화번호입니다. `-` 없이 숫자로만 구성된 문자열입니다. 최소 길이는 8자입니다. * **individual** 개인 셀러 정보입니다. `businessType`이 `INDIVIDUAL`이면 필수입니다. * **name** 개인의 이름입니다. * **email** 이메일입니다 * **phone** 전화번호입니다. `-` 없이 숫자로만 구성된 문자열입니다. 최소 길이는 8자입니다. * **account** 셀러가 정산 금액을 지급받을 계좌 정보입니다. * **bankCode** 계좌의 은행 코드입니다. [은행 코드](/codes/org-codes#은행-코드)와 [증권사 코드](/codes/org-codes#증권사-코드)를 참고해서 두 자리 코드 또는 세 자리 코드를 사용해주세요. * **accountNumber** 계좌번호입니다. `-` 없이 숫자만 입력해주세요. 최대 길이는 14자입니다. * **holderName** 계좌 예금주입니다. 글자 수는 공백을 포함해 한영 구분 없이 셉니다. 최대 길이는 50자입니다. * **metadata** 셀러와 관련된 추가 정보를 key-value 쌍으로 담고 있는 JSON 객체입니다. 최대 5개의 키-값(key-value) 쌍입니다. 키는 `[` , `]` 를 사용하지 않는 최대 40자의 문자열, 값은 최대 2000자의 문자열입니다. #### Response 셀러 등록에 성공하면 JWE로 암호화된 [Seller 객체](#seller-객체)가 돌아옵니다. 보안 키로 복호화해서 응답 값을 확인해주세요. 셀러 등록에 실패하면 JWE로 암호화된 [에러 객체](/reference/using-api/req-res#api-v2-에러-객체)가 돌아옵니다. 보안 키로 복호화해서 응답 값을 확인해주세요. 셀러 등록에서 [발생할 수 있는 에러](/reference/error-codes#셀러-등록)를 살펴보세요. method: POST path: /v2/sellers/\{id} ### 셀러 수정 등록된 셀러 정보를 수정합니다. 수정하고 싶은 필드만 Request Body 파라미터로 보내주세요. 파라미터를 보내지 않으면 정보가 바뀌지 않습니다. 데이터를 삭제하고 싶다면 파라미터의 값을 `null`로 보내주세요. 등록할 때 필수 값이었던 필드는 삭제할 수 없습니다. 셀러 수정은 지급대행 서비스의 POST 요청입니다. [`ENCRYPTION` 보안](/guides/v2/payouts#encryption-보안)으로 요청을 보내주세요. #### Path 파라미터 * **id** 수정하고 싶은 Seller 객체의 `id`입니다. 토스페이먼츠에서 발급한 값이며, 오픈마켓 상점에서 발급한 `refSellerId`와 다른 값입니다. #### Request Body 파라미터 * **company** 법인사업자 또는 개인사업자 셀러 정보입니다. * **name** 사업자명입니다. * **representativeName** 대표자명입니다. * **email** 사업자 이메일입니다. * **phone** 사업자 전화번호입니다. `-` 없이 숫자로만 구성된 문자열입니다. 최소 길이는 8자입니다. * **individual** 개인 셀러 정보입니다. * **email** 이메일입니다. * **phone** 전화번호입니다. `-` 없이 숫자로만 구성된 문자열입니다. 최소 길이는 8자입니다. * **account** 셀러에서 정산 금액을 지급받을 계좌 정보입니다. * **bankCode** 계좌의 은행 코드입니다. 은행 코드와 증권사 코드를 참고하세요. * **accountNumber** 계좌번호입니다. `-` 없이 숫자만 입력해주세요. 최대 길이는 14자입니다. * **holderName** 계좌 예금주입니다. 글자 수는 공백을 포함해 한영 구분 없이 셉니다. 최대 길이는 50자입니다. * **metadata** 셀러와 관련된 추가 정보를 key-value 쌍으로 담고 있는 JSON 객체입니다. 최대 5개의 키-값(key-value) 쌍입니다. 키는 `[` , `]` 를 사용하지 않는 최대 40자의 문자열, 값은 최대 2000자의 문자열입니다. #### Response 셀러 수정에 성공하면 JWE로 암호화된 [Seller 객체](#seller-객체)가 돌아옵니다. 보안 키로 복호화해서 응답 값을 확인해주세요. 셀러 수정에 실패하면 JWE로 암호화된 [에러 객체](/reference/using-api/req-res#api-v2-에러-객체)가 돌아옵니다. 보안 키로 복호화해서 응답 값을 확인해주세요. 셀러 수정에서 [발생할 수 있는 에러](/reference/error-codes#셀러-수정)를 살펴보세요. method: DELETE path: /v2/sellers/\{id} ### 셀러 삭제 등록된 셀러를 삭제합니다. 삭제한 셀러의 `id` 식별자는 다시 발급되지 않고 조회가 불가능합니다. #### Path 파라미터 * **id** 삭제하고 싶은 Seller 객체의 `id`입니다. 토스페이먼츠에서 발급한 값이며, 오픈마켓 상점에서 발급한 `refSellerId`와 다른 값입니다. #### Response 셀러 삭제에 성공하면 [`deleted-entity` 객체](/reference/using-api/req-res#삭제된-객체)가 돌아옵니다. 셀러 삭제에 실패하면 [에러 객체](/reference/using-api/req-res#api-v2-에러-객체)가 돌아옵니다. 셀러 삭제에서 [발생할 수 있는 에러](/reference/error-codes#셀러-삭제)를 살펴보세요. method: GET path: /v2/sellers/\{id} ### 셀러 단건 조회 토스페이먼츠에 등록한 하나의 셀러를 조회합니다. 삭제되지 않은 셀러만 조회할 수 있어요. #### Path 파라미터 * **id** 조회하고 싶은 Seller 객체의 `id`입니다. 토스페이먼츠에서 발급한 값이며, 오픈마켓 상점에서 발급한 `refSellerId`와 다른 값입니다. #### Response 셀러 단건 조회에 성공하면 [Seller 객체](#seller-객체)가 돌아옵니다. 셀러 단건 조회에 실패하면 [에러 객체](/reference/using-api/req-res#api-v2-에러-객체)가 돌아옵니다. 셀러 단건 조회에서 [발생할 수 있는 에러](/reference/error-codes#셀러-단건-조회)를 살펴보세요. method: GET path: /v2/sellers ### 셀러 목록 조회 토스페이먼츠에 등록한 셀러 목록을 조회합니다. 삭제되지 않은 셀러만 조회할 수 있어요. \* 라이브 환경에서 비정상적으로 많은 요청을 보내면 `429 Too Many Requests` 상태 코드가 내려올 수 있습니다. #### Query 파라미터 * **limit** 조회하고 싶은 셀러 개수입니다. 기본 값은 `10`입니다. 설정할 수 있는 최대값은 `10000`입니다. * **startingAfter** 특정 셀러의 `id`입니다. 해당 `id`의 셀러 다음으로 등록된 셀러부터 조회됩니다. 기본 값은 최초에 등록된 셀러입니다. #### Response 셀러 목록 조회에 성공하면 [`seller-list`](/reference/using-api/req-res#리스트-객체) 객체가 돌아옵니다. `entityBody`에 다음과 같은 필드가 있습니다. name: hasMore type: boolean 더 조회할 수 있는 데이터가 있는지 알려줍니다. 마지막 데이터라면 `false`, 다음 데이터가 있다면 `true`입니다. name: size type: integer 조회된 객체의 개수입니다. `items`의 크기입니다. name: nextCursor type: stirng 다음 조회 시 `startingAfter`로 설정하면 되는 커서입니다. 만약에 더 조회할 데이터 없다면 `null`입니다. name: items type: array [Seller 객체](#seller-객체) 목록입니다. 셀러 목록 조회에 실패하면 [에러 객체](/reference/using-api/req-res#api-v2-에러-객체)가 돌아옵니다. 셀러 목록 조회에서 [발생할 수 있는 에러](/reference/error-codes#셀러-단건-조회)를 살펴보세요. ### Payout 객체 지급대행 요청 정보입니다. #### 객체 상세 * **id** 토스페이먼츠에서 발급하는 지급대행 요청의 고유 식별자입니다. 지급대행 취소, 조회 등에 사용됩니다. 최대 길이는 35자입니다. * **refPayoutId** `nullable` 지급대행 상점에서 직접 발급하는 지급대행 요청의 고유 식별자입니다. 연동 중에 참고할 수 있는 값입니다. 등록 이후에 수정할 수 없고, 같은 값을 다시 사용할 수 없습니다. 최대 길이는 50자입니다. * **destination** 정산금을 지급받는 셀러입니다. [Seller 객체](#seller-객체)의 `id` 값입니다. * **scheduleType** 지급대행의 유형입니다. 아래 둘 중 하나입니다. \- `EXPRESS`: 바로지급입니다. 요청한 당일 이내 정산이 지급됩니다. \- `SCHEDULED`: 예약지급입니다. 요청일을 설정해서 정산 지급을 예약합니다. * **payoutDate** `yyyy-MM-dd` 형식의 지급일입니다. * **amount** 셀러에게 지급하는 정산 금액입니다. * **currency** 통화입니다. 현재는 `KRW`만 지원합니다. * **value** 잔액입니다. * **transactionDescription** 이체 내역에 표시되는 적요입니다. 최대 길이는 7자입니다. * **requestedAt** 지급대행이 요청된 시점입니다. `yyyy-MM-dd'T'HH:mm:ss±hh:mm` 형식입니다. * **status** 지급대행 상태입니다. 지급대행 상태가 바뀌면 [`payout.changed`](/reference/using-api/webhook-events#payoutchanged) 웹훅이 발송됩니다. \- `REQUESTED`: 지급이 요청되었지만 아직 처리되지 않은 상태입니다. `REQUESTED` 상태일 때만 지급대행 요청을 취소할 수 있습니다. \- `IN_PROGRESS`: 지급을 처리하고 있는 상태입니다. \- `COMPLETED`: 셀러에 지급이 완료된 상태입니다. \- `FAILED`: 지급 요청이 실패한 상태입니다. \- `CANCELED`: 지급 요청이 취소된 상태입니다. \- `DELETED`: 지급요청서가 삭제된 상태입니다. 웹훅이 발송되지 않습니다. \- `REJECTED`: 지급 요청이 반려된 상태입니다. 웹훅은 `FAILED` 상태로 발송됩니다. * **error** `nullable` 지급대행 요청에서 일어난 에러 객체입니다. * **metadata** `nullable` 지급과 관련된 추가 정보를 key-value 쌍으로 담고 있는 객체입니다. 최대 5개의 키-값(key-value) 쌍입니다. 키는 `[` , `]` 를 사용하지 않는 최대 40자의 문자열, 값은 최대 2000자의 문자열입니다. method: POST path: /v2/payouts ### 지급대행 요청 지급 대상 셀러에게 정산 금액을 이체합니다. 요청 시점에 잔액이 부족하면 지급이 실패합니다. 지급대행 요청은 지급대행 서비스의 POST 요청입니다. [`ENCRYPTION` 보안](/guides/v2/payouts#encryption-보안)으로 요청을 보내주세요. 최대 100건의 지급대행을 한 번에 요청할 수 있습니다. 하지만 하나의 요청이 실패하면 요청 모두 실패하고 첫 번째 실패 건에 대한 에러 객체가 응답으로 돌아옵니다. 1건의 지급대행 요청에는 10억 미만의 정산 금액을 이체할 수 있습니다. 지급대행으로 셀러에게 지급한 정산 금액은 회수하기 어렵습니다. 토스페이먼츠는 지급 관련 책임이 없기 때문에 지급대행 서비스를 신중하게 사용해주세요. > **경고**: [API 키 접근 정책](/reference/using-api/api-keys#api-키-접근-정책)을 등록하면 허용한 IP에서만 API를 호출할 수 있어 키가 유출되어도 안전합니다. \* 지급대행 요청 API를 라이브 환경에서 테스트하면 수수료가 부과됩니다. #### Request Body 파라미터 * **refPayoutId** 상점에서 직접 발급하는 지급대행 식별자입니다. 각 지급대행 요청 건에 고유 값을 발급해야 되고 지급대행 상점에서 참고용으로 사용할 수 있습니다. 최대 길이는 50자입니다. * **destination** 정산금을 지급받는 셀러입니다. [Seller 객체](#seller-객체)의 `id` 값입니다. * **scheduleType** 지급대행의 유형입니다. 아래 둘 중 하나입니다. \- `EXPRESS`: 바로지급입니다. 요청한 당일 이내 정산금이 지급됩니다. 바로지급을 요청할 수 있는 시간은 영업일 08:00~15:00입니다. \- `SCHEDULED`: 예약지급입니다. 요청일을 설정해서 정산금 지급을 예약합니다. * **payoutDate** `yyyy-MM-dd` 형식의 지급일입니다. 지급대행 유형이 `SCHEDULED`일 때는 필수입니다. 지급일은 미래에 1년 이내에 있는 영업일로만 설정할 수 있어요. 휴일, 공휴일, 과거일자로 설정하면 오류가 발생해요. * **amount** 지급 금액 정보입니다. * **transactionDescription** 이체 내역에 표시되는 적요입니다. 최대 길이는 7자입니다. * **metadata** 요청과 관련된 추가 정보를 key-value 쌍으로 담고 있는 객체입니다. 최대 5개의 키-값(key-value) 쌍입니다. 키는 `[` , `]` 를 사용하지 않는 최대 40자의 문자열, 값은 최대 2000자의 문자열입니다. #### Response 지급대행 요청에 성공하면 JWE로 암호화된 [`payout-list` 객체](/reference/using-api/req-res#리스트-객체)가 돌아옵니다. 보안 키로 복호화해서 응답 값을 확인해주세요. 객체의 `entityBody` 필드의 items에서 [Payout 객체](#payout-객체) 목록을 확인할 수 있습니다. 지급대행 요청에 실패하면 JWE로 암호화된 [에러 객체](/reference/using-api/req-res#api-v2-에러-객체)가 돌아옵니다. 보안 키로 복호화해서 응답 값을 확인해주세요. 지급대행 요청에 실패하면 요청 건 모두 실패하고 요청 건 중에 첫 번째 에러에 대한 에러 객체가 돌아옵니다. 지급대행 요청에서 [발생할 수 있는 에러](/reference/error-codes#지급대행-요청)를 살펴보세요. method: POST path: /v2/payouts/\{id}/cancel ### 지급대행 요청 취소 `REQUESTED` 상태의 지급대행 요청 건을 취소합니다. 이미 처리 중이거나 완료된 지급대행 요청 건은 취소할 수 없습니다. #### Path 파라미터 * **id** 취소하고 싶은 Payout 객체의 `id`입니다. #### Response 지급대행 요청 취소에 성공하면 `status`가 `CANCELED`로 바뀐 [Payout 객체](#payout-객체)가 돌아옵니다. 지급대행 요청 취소에 실패하면 [에러 객체](/reference/using-api/req-res#api-v2-에러-객체)가 돌아옵니다. 지급대행 요청 취소에서 [발생할 수 있는 에러](/reference/error-codes#지급대행-요청-취소)를 살펴보세요. method: GET path: /v2/payouts/\{id} ### 지급 요청 단건 조회 지급 요청 한 건을 조회합니다. #### Path 파라미터 * **id** 조회하고 싶은 Payout 객체의 `id`입니다. #### Response 지급 요청 단건 조회에 성공하면 [Payout 객체](#payout-객체)가 돌아옵니다. 지급 요청 단건 조회에 실패하면 [에러 객체](/reference/using-api/req-res#api-v2-에러-객체)가 돌아옵니다. 지급 요청 단건 조회에서 [발생할 수 있는 에러](/reference/error-codes#지급-요청-단건-조회)를 살펴보세요. method: GET path: /v2/payouts ### 지급 요청 목록 조회 지급 요청 목록을 조회합니다. \* 라이브 환경에서 비정상적으로 많은 요청을 보내면 `429 Too Many Requests` 상태 코드가 내려올 수 있습니다. #### Query 파라미터 * **limit** 조회하고 싶은 지급대행 요청건의 개수입니다. 기본 값은 `10`이고, 설정할 수 있는 최대값은 `10000`입니다. * **startingAfter** 커서로 사용할 지급대행 요청건의 `id`입니다. 설정한 `id`의 지급대행 요청건 다음으로 등록된 요청건부터 조회됩니다. 설정하지 않으면 최초의 지급대행 요청건부터 조회됩니다. * **payoutDateGte** 커서로 사용할 지급일입니다. 해당 지급일과 같거나 더 이후(이상)에 발생하는 지급대행 요청 건을 조회합니다. * **payoutDateLte** 지급일입니다. 해당 지급일과 같거나 더 이전(이하)에 발생하는 지급대행 요청 건을 조회합니다. #### Response 지급대행 요청에 [`payout-list` 객체](/reference/using-api/req-res#리스트-객체)가 돌아옵니다. `entityBody`에 다음과 같은 필드가 있습니다. name: hasMore type: boolean 더 조회할 수 있는 데이터가 있는지 알려줍니다. 마지막 데이터라면 `false`, 다음 데이터가 있다면 `true`입니다. name: size type: integer 조회된 객체의 개수입니다. `items`의 크기입니다. name: nextCursor type: stirng 다음 조회 시 `startingAfter`로 설정하면 되는 커서입니다. 만약에 더 조회할 데이터 없다면 `null`입니다. name: items type: array [Payout 객체](#payout-객체) 목록입니다. 지급 요청 목록 조회에 실패하면 [에러 객체](/reference/using-api/req-res#api-v2-에러-객체)가 돌아옵니다. ## 계좌인증 계좌인증은 계좌번호와 소유자 정보를 기반으로 계좌의 유효성과 일치 여부를 확인하는 서비스입니다. [가상계좌 환불](/reference#결제-취소)이나 [지급대행 셀러 등록](/reference/additional#셀러-등록) 과정에서 계좌번호를 수취할 때, 해당 계좌번호가 유효한지 사전에 확인하는 데 사용할 수 있습니다. > **참고**: 계좌유효성 인증 서비스는 [서비스 신청 폼](https://builder.tosspayments.com/to/b37f74d033d74f2290f26c6cfc33378a)으로 접수해주세요. \* 테스트 환경에서는 실제 인증 절차를 거치지 않고, Mock 데이터가 응답으로 제공됩니다. > **경고**: 매일 23:30~00:30 사이에는 은행 점검으로 계좌인증 서비스가 일시적으로 실패할 수 있습니다. 실패하는 경우 `{"code":"NOT_AVAILABLE_BANK_ACCOUNT_VERIFICATION","message":"은행계좌 검증 서비스를 이용할 수 없습니다."}` 에러가 응답됩니다. 점검 시간대에도 항상 실패하는 것은 아니며, 정상 응답과 에러 응답이 번갈아 발생할 수 있으므로 재시도 로직을 함께 고려해주세요. method: POST path: /v2/bank-accounts/lookup-holder-name ### 계좌번호로 예금주명 조회 계좌번호로 계좌의 예금주명을 조회합니다. #### Request Body 파라미터 * **bankCode** 계좌의 은행 코드입니다. 은행 코드와 증권사 코드를 참고해서 두 자리 코드 또는 세 자리 코드를 사용해주세요. * **accountNumber** 계좌번호입니다. - 없이 숫자만 입력해주세요. 최대 길이는 14자입니다. #### Response 계좌번호로 예금주명 조회에 성공했다면 예금주명(`holderName`)이 돌아옵니다. [발생할 수 있는 에러](/reference/error-codes#계좌인증-에러-목록)를 살펴보세요. 계좌번호로 예금주명 조회에 실패했다면 HTTP 상태 코드와 함께 [에러 객체](/reference/using-api/req-res#에러-객체)가 돌아옵니다. method: POST path: /v2/bank-accounts/validate ### 계좌번호 유효성 확인 계좌 정보로 계좌의 존재 여부를 확인합니다. #### Request Body 파라미터 * **bankCode** 계좌의 은행 코드입니다. 은행 코드와 증권사 코드를 참고해서 두 자리 코드 또는 세 자리 코드를 사용해주세요. * **accountNumber** 계좌번호입니다. - 없이 숫자만 입력해주세요. 최대 길이는 14자입니다. #### Response 확인에 성공했다면 확인 결과(`isValid`)가 돌아옵니다. 확인에 실패했다면 HTTP 상태 코드와 함께 [에러 객체](/reference/using-api/req-res#에러-객체)가 돌아옵니다. [발생할 수 있는 에러](/reference/error-codes#계좌인증-에러-목록)를 살펴보세요. method: POST path: /v2/bank-accounts/verify-identifier ### 계좌번호·식별자 일치 확인 계좌번호와 식별자(생년월일/사업자번호)가 일치하는지 확인합니다. > **경고**: 식별자(`identityNumber`) 일치 확인은 직접조회 은행에서만 지원됩니다. 간접조회 은행(카카오뱅크, 삼성증권을 제외한 증권사 등)에서는 식별자 검증이 수행되지 않아 실제 식별자와 다른 값을 입력해도 성공 응답이 돌아올 수 있습니다.**직접조회 은행**: 농협, 우리은행, 국민은행, 신한은행, 하나은행, 기업은행, 부산은행, 우체국, 대구은행, 새마을금고, 광주은행, SC제일은행, 경남은행, 씨티은행, 신협, 전북은행, 수협은행, 제주은행, 산업은행, 케이뱅크, 토스뱅크, 삼성증권, 산림조합중앙회 #### Request Body 파라미터 * **bankCode** 계좌의 은행 코드입니다. 은행 코드와 증권사 코드를 참고해서 두 자리 코드 또는 세 자리 코드를 사용해주세요. * **accountNumber** 계좌번호입니다. - 없이 숫자만 입력해주세요. 최대 길이는 14자입니다. * **identityNumber** 계좌 소유자의 식별자입니다. 개인 계좌의 경우 생년월일(YYMMDD)이며, 법인 계좌의 경우 사업자등록번호입니다. - 없이 숫자만 입력해주세요. #### Response 일치 확인에 성공했다면 확인 결과(`isValid`)가 돌아옵니다. 일치 확인에 실패했다면 HTTP 상태 코드와 함께 [에러 객체](/reference/using-api/req-res#에러-객체)가 돌아옵니다. [발생할 수 있는 에러](/reference/error-codes#계좌인증-에러-목록)를 살펴보세요. method: POST path: /v2/bank-accounts/verify-holder-name ### 계좌번호·예금주명 일치 확인 계좌번호와 예금주 이름이 일치하는지 확인합니다. 아래와 같은 상황에서 사용하세요. * 가상계좌 환불 계좌 유효성 검증 * 지급대행 셀러 등록 시 계좌 예금주 확인 * 결제 서비스 외 계좌 예금주 일치 여부 확인이 필요한 경우 > **참고**: 계좌 존재 여부만 확인하려면 [계좌번호 유효성 확인](#계좌번호-유효성-확인) API를 사용하세요. 예금주명 없이 식별자(생년월일·사업자번호)만 확인하려면 [계좌번호·식별자 일치 확인](#계좌번호식별자-일치-확인) API를, 예금주명과 식별자를 함께 확인하려면 [계좌번호·예금주명·식별자 일치 확인](#계좌번호예금주명식별자-일치-확인) API를 사용하세요. #### Request Body 파라미터 * **bankCode** 계좌의 은행 코드입니다. 은행 코드와 증권사 코드를 참고해서 두 자리 코드 또는 세 자리 코드를 사용해주세요. * **accountNumber** 계좌번호입니다. - 없이 숫자만 입력해주세요. 최대 길이는 14자입니다. * **holderName** 계좌 예금주입니다. 글자 수는 공백을 포함해 한영 구분 없이 셉니다. 최대 길이는 50자입니다. #### Response 일치 확인에 성공했다면 확인 결과(`isValid`)가 돌아옵니다. 일치 확인에 실패했다면 HTTP 상태 코드와 함께 [에러 객체](/reference/using-api/req-res#에러-객체)가 돌아옵니다. [발생할 수 있는 에러](/reference/error-codes#계좌인증-에러-목록)를 살펴보세요. method: POST path: /v2/bank-accounts/verify-holder-real-name ### 계좌번호·예금주명·식별자 일치 확인 계좌번호와 예금주명, 그리고 식별자(생년월일/사업자번호)가 일치하는지 확인합니다. > **경고**: 식별자(`identityNumber`) 일치 확인은 직접조회 은행에서만 지원됩니다. 간접조회 은행(카카오뱅크, 삼성증권을 제외한 증권사 등)에서는 식별자 검증이 수행되지 않아 실제 식별자와 다른 값을 입력해도 성공 응답이 돌아올 수 있습니다.**직접조회 은행**: 농협, 우리은행, 국민은행, 신한은행, 하나은행, 기업은행, 부산은행, 우체국, 대구은행, 새마을금고, 광주은행, SC제일은행, 경남은행, 씨티은행, 신협, 전북은행, 수협은행, 제주은행, 산업은행, 케이뱅크, 토스뱅크, 삼성증권, 산림조합중앙회 #### Request Body 파라미터 * **bankCode** 계좌의 은행 코드입니다. 은행 코드와 증권사 코드를 참고해서 두 자리 코드 또는 세 자리 코드를 사용해주세요. * **accountNumber** 계좌번호입니다. - 없이 숫자만 입력해주세요. 최대 길이는 14자입니다. * **holderName** 계좌 예금주입니다. 글자 수는 공백을 포함해 한영 구분 없이 셉니다. 최대 길이는 50자입니다. * **identityNumber** 계좌 소유자의 식별자입니다. 개인 계좌의 경우 생년월일(YYMMDD)이며, 법인 계좌의 경우 사업자등록번호입니다. `-` 없이 숫자만 입력해주세요. #### Response 일치 확인에 성공했다면 확인 결과(`isValid`)가 돌아옵니다. 일치 확인에 실패했다면 HTTP 상태 코드와 함께 [에러 객체](/reference/using-api/req-res#에러-객체)가 돌아옵니다. [발생할 수 있는 에러](/reference/error-codes#계좌인증-에러-목록)를 살펴보세요. ## 에스크로 에스크로는 구매자가 결제한 대금을 토스페이먼츠가 보관하고 있다가 배송과 구매확정이 끝나면 상점에 지급하는 구매자 보호 서비스입니다. 결제가 완료(가상계좌는 입금)되면 에스크로 거래가 개설되고, 상점은 배송 등록·취소 요청 수락·구매확정 요청 메일 재발송을 API로 처리합니다. 대상 결제수단은 카드·가상계좌·계좌이체입니다. 전체 흐름과 상태 모델은 [에스크로 가이드](/guides/v2/escrow)에서 확인하세요. > **참고**: 에스크로 서비스는 상점관리자에서 직접 이용 신청할 수 있어요. **상점관리자 > 이용 정보 > 결제·부가서비스**에서 결제수단별 '에스크로' 오른쪽 **\[변경]** 버튼을 눌러 설정하세요. ### Escrow 객체 에스크로 거래 리소스입니다. 거래 상태·확정·취소·상품·배송 정보를 담습니다. #### 객체 상세 * **id** 에스크로 거래 ID입니다. 결제 응답의 `escrowKey`와 같은 값입니다. 후속 요청은 이 값으로 보냅니다. 최대 길이는 64자입니다. * **targetId** 에스크로가 성립한 대상 리소스의 ID입니다. Payment 객체의 `paymentKey`와 이 값으로 연결하세요. 최대 길이는 200자입니다. * **targetType** 에스크로가 성립한 대상 리소스의 종류입니다. 지금은 결제(`PAYMENT`)만 지원됩니다. * **mid** 상점 ID입니다. * **status** 에스크로 상태입니다. 상태가 바뀌면 [`escrow.changed`](/reference/using-api/webhook-events#escrowchanged) 웹훅이 발송됩니다. \- `IN_PROGRESS`: 결제 완료·구매확정 전 상태입니다. \- `CANCEL_REQUESTED`: 구매자가 취소를 신청해 상점의 수락 판단을 기다리는 상태입니다. \- `CONFIRMED`: 구매확정이 완료된 상태입니다. \- `CANCELED`: 취소가 확정된 상태(종결)입니다. * **openedAt** 거래가 개설된 시각입니다. 결제가 완료(가상계좌는 입금)되어 대금이 에스크로에 맡겨진 순간이며, 항상 값이 있습니다. `yyyy-MM-dd'T'HH:mm:ss±hh:mm` ISO 8601 형식입니다. * **confirmType** `nullable` 확정 종류입니다. `status=CONFIRMED`일 때만 채워집니다. `CUSTOMER`(구매자가 확정) 또는 `AUTO`(기한 도래 자동확정) 중 하나입니다. * **confirmedAt** `nullable` 구매확정 시각입니다. `status=CONFIRMED`일 때만 값이 있습니다. `yyyy-MM-dd'T'HH:mm:ss±hh:mm` ISO 8601 형식입니다. * **cancelType** `nullable` 취소 종류입니다. `status=CANCELED`일 때만 채워집니다. `CUSTOMER`(구매자가 취소를 신청하고 상점이 수락한 거래) 또는 `TARGET_CANCELED`(대상 결제가 취소되어 에스크로도 함께 종결된 거래) 중 하나입니다. 둘 다 결과는 `CANCELED`로 같지만 **상점이 판단한 취소인지**가 다르므로, 집계할 때 둘을 한데 묶지 마세요. * **canceledAt** `nullable` 취소 확정 시각입니다. `status=CANCELED`일 때만 값이 있습니다. `yyyy-MM-dd'T'HH:mm:ss±hh:mm` ISO 8601 형식입니다. * **cancelRequestedAt** `nullable` 구매자가 취소를 신청한 시각입니다. 신청이 없었으면 `null`입니다. `cancelType=TARGET_CANCELED`인 경우 `canceledAt`과 같은 값으로 내려옵니다. `yyyy-MM-dd'T'HH:mm:ss±hh:mm` ISO 8601 형식입니다. * **products** 거래 상품 구성입니다. 결제 요청의 `escrowProducts`로 전달한 값이 그대로 실립니다. `escrowProducts`를 전달하지 않으면 Payment 객체의 `orderId`, `orderName`을 기반으로 1개가 디폴트로 생성됩니다. * **id** 상품 ID입니다. 배송 등록 요청의 `targetId`에 이 값을 넣습니다(`targetType: ESCROW_PRODUCT`). 최대 길이는 64자입니다. * **refProductId** 상점이 결제 요청 `escrowProducts[].id`로 보낸 값입니다. 상점 카탈로그 조인용입니다. 값이 없으면 `null`이 아니라 빈 문자열(`""`)입니다. 40바이트를 넘으면 앞에서부터 40바이트까지만 저장되어, 거래 조회 응답의 `refProductId`에 잘린 값이 돌아옵니다. 최대 길이는 40바이트입니다. * **name** 상품 이름입니다. 값이 없으면 `null`이 아니라 빈 문자열(`""`)입니다. * **quantity** 수량입니다. * **deliveryIds** 이 거래에 등록된 배송 리소스의 ID 목록입니다. `products`보다 개수가 적으면 아직 등록할 배송이 남은 것입니다. 상태·송장·대상 키는 [배송 조회 API](#배송-조회)로 조회하세요. ### Delivery 객체 상품 하나의 배송 리소스입니다. 상품:배송 = 1:1 관계이며, 거래 `status`와는 별개의 자체 `status`를 가집니다. #### 객체 상세 * **id** 배송 리소스 ID입니다. 최대 길이는 64자입니다. * **targetType** 배송 대상 리소스의 종류입니다. 지금은 에스크로 상품(`ESCROW_PRODUCT`)만 지원됩니다. * **targetId** 배송 대상 리소스의 키입니다. `targetType: ESCROW_PRODUCT`에서는 거래 조회 응답의 `products[].id`와 같은 값입니다. 최대 길이는 200자입니다. * **status** 배송 상태입니다. 상태가 바뀌면 [`delivery.changed`](/reference/using-api/webhook-events#deliverychanged) 웹훅이 발송됩니다. \- `IN_TRANSIT`: 배송중 상태입니다. 택배 등록 시 이 상태로 진입합니다. \- `COMPLETED`: 배송완료 상태입니다. 택배는 배송추적이 완료 판정하면, 직접 전달은 등록 즉시 이 상태가 됩니다. * **deliveryMethod** 배송 방법입니다. `SHIPMENT`(택배) 또는 `DIRECT`(직접 전달)입니다. * **completedAt** `nullable` 배송완료 시각입니다. `DIRECT`는 등록 요청의 `receivedAt`이 그대로 들어가고, `SHIPMENT`는 배송추적이 완료를 판정한 시각입니다. `status=COMPLETED`일 때만 값이 있습니다. `yyyy-MM-dd'T'HH:mm:ss±hh:mm` ISO 8601 형식입니다. * **submittedAt** `nullable` 지금 실려 있는 배송 정보를 제출한 시각입니다. 수정하면 갱신됩니다. `yyyy-MM-dd'T'HH:mm:ss±hh:mm` ISO 8601 형식입니다. * **shipment** `nullable` 택배 배송 정보입니다. `deliveryMethod=SHIPMENT`일 때만 채워집니다. * **carrierCode** 택배사 코드입니다. 지원 목록은 [택배사 코드](/codes/org-codes#택배사-코드)를 참고하세요. * **carrierName** 택배사 이름입니다. 코드에 매칭되는 이름을 토스페이먼츠가 채웁니다. * **trackingNumber** 송장번호입니다. * **shippedAt** 발송일시입니다. `yyyy-MM-dd'T'HH:mm:ss±hh:mm` ISO 8601 형식입니다. * **direct** `nullable` 직접 전달 정보입니다. `deliveryMethod=DIRECT`일 때만 채워집니다. * **receiverName** 수령인 이름입니다. * **receiverRelation** 수령인과 구매자의 관계입니다. `BUYER`·`FAMILY`·`OFFICE`·`OTHER` 중 하나입니다. method: GET path: /v2/escrows/\{id} ### 에스크로 거래 조회 에스크로 거래를 조회합니다. #### Path 파라미터 * **id** 에스크로 거래 ID입니다. 결제 승인 응답 `escrowKey`에서 받아 보관하세요. #### Response 조회에 성공하면 [Escrow 객체](#escrow-객체)가 `entityBody`로 돌아옵니다. 조회에 실패하면 HTTP 상태 코드와 함께 [에러 객체](/reference/using-api/req-res#api-v2-에러-객체)가 돌아옵니다. method: POST path: /v2/deliveries ### 배송 등록 배송 정보를 등록합니다. > **경고**: - **한 번의 호출 = 상품 하나의 배송**입니다. 상품이 여러 개인 거래는 상품 수만큼 호출하세요. > - **자동확정 기한은 상품 전체가 배송완료됐을 때 기산**됩니다. > - 성공 시 `delivery.changed` 웹훅이 발송됩니다. #### Request Body 파라미터 * **targetType** 배송을 붙일 대상 리소스의 종류입니다. 지금은 에스크로 상품(`ESCROW_PRODUCT`)만 지원됩니다. * **targetId** 배송할 대상의 리소스 키입니다. `targetType: ESCROW_PRODUCT`에서는 거래 조회 응답의 `products[].id`입니다. 상품이 하나뿐이어도 명시하세요. 최대 길이는 200자입니다. * **deliveryMethod** `SHIPMENT`(택배) 또는 `DIRECT`(직접 전달)입니다. * **shipment** `SHIPMENT`일 때 전달합니다. * **carrierCode** 택배사 코드입니다. 지원 목록은 아래 [택배사 코드](/codes/org-codes#택배사-코드)를 확인하세요. 최대 길이는 15자입니다. * **trackingNumber** 송장번호입니다. 택배사별 송장번호 형식 검증을 거치며, 형식이 틀리면 `400 INVALID_REQUEST`입니다. 최대 길이는 80자입니다. * **shippedAt** 발송일시는 `yyyy-MM-dd'T'HH:mm:ss±hh:mm` ISO 8601 형식입니다. * **direct** `DIRECT`일 때 전달합니다. * **receivedAt** 실수령일시는 `yyyy-MM-dd'T'HH:mm:ss±hh:mm` ISO 8601 형식입니다. * **receiverName** 수령인 이름입니다. 최대 길이는 50자입니다. * **receiverRelation** 수령인과 구매자의 관계입니다(`BUYER`·`FAMILY`·`OFFICE`·`OTHER`). 택배(`SHIPMENT`)는 등록 즉시 `status: IN_TRANSIT`이 되고, 배송추적이 완료를 판정하면 `status: COMPLETED`로 전이됩니다. 직접 전달(`DIRECT`)은 등록 즉시 `status: COMPLETED`입니다. #### Response 등록에 성공하면 등록한 상품의 [Delivery 객체](#delivery-객체) 하나가 돌아옵니다. 거래의 다른 배송은 포함되지 않습니다. 등록에 실패하면 HTTP 상태 코드와 함께 [에러 객체](/reference/using-api/req-res#api-v2-에러-객체)가 돌아옵니다. method: POST path: /v2/deliveries/\{id} ### 배송 수정 등록한 배송 정보를 수정합니다. `deliveryMethod`는 항상 명시하며, `shipment` 안은 바꿀 필드만 보내면 됩니다. > **경고**: - **수정할 수 있는 건 배송중(`IN_TRANSIT`)인 `SHIPMENT`뿐**이며, 가능한 작업은 두 가지입니다. > 1. **송장 정보 정정** — 택배사·송장번호를 고칩니다. > 2. **직접 전달로 전환** — 택배로 잘못 등록했거나 실제로는 직접 전달한 경우. 즉시 배송완료 처리됩니다(`completedAt`=제출한 `receivedAt`). > - **배송완료된 배송은 수정할 수 없습니다**(`403 FORBIDDEN_COMPLETED_DELIVERY`). > - **수정 자체로는 웹훅이 발송되지 않습니다** — 송장 정정은 상태가 그대로라 미발송, 직접 전달 전환은 `COMPLETED`로 바뀌므로 `delivery.changed`가 발송됩니다. #### Path 파라미터 * **id** 배송 ID입니다. #### Request Body 파라미터 * **deliveryMethod** `SHIPMENT` 또는 `DIRECT`입니다. 유형과 무관한 객체를 보내면(`SHIPMENT`인데 `direct` 등) `400 INVALID_REQUEST`입니다. * **shipment** 바꿀 필드만 보내면 됩니다(필드 정의는 [배송 등록](#배송-등록)과 동일, `targetType`/`targetId` 제외). * **direct** 직접 전달 전환일 때 사용합니다. 필드 정의는 [배송 등록](#배송-등록)과 동일합니다. #### Response 수정에 성공하면 수정이 반영된 [Delivery 객체](#delivery-객체)가 돌아옵니다. 수정에 실패하면 HTTP 상태 코드와 함께 [에러 객체](/reference/using-api/req-res#api-v2-에러-객체)가 돌아옵니다. method: GET path: /v2/deliveries/\{id} ### 배송 조회 배송 하나를 조회합니다. 배송은 최상위 리소스이므로 자기 ID로 읽습니다. ID는 **배송 등록 응답**·에스크로 거래 조회의 **`deliveryIds`**·**`delivery.changed` 웹훅**에서 얻습니다. #### Path 파라미터 * **id** 배송 ID입니다. #### Response 조회에 성공하면 [Delivery 객체](#delivery-객체)가 돌아옵니다. 없는 키·다른 상점의 배송·입금 전 거래의 배송이면 `404 NOT_FOUND`입니다. 그 밖의 실패는 HTTP 상태 코드와 함께 [에러 객체](/reference/using-api/req-res#api-v2-에러-객체)가 돌아옵니다. method: POST path: /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** 에스크로 거래 ID입니다. #### Request Body 파라미터 * **email** 받는 사람 지정으로, 이번 발송에만 적용되고 구매자 이메일은 바뀌지 않습니다. 형식이 올바르지 않으면 `400 INVALID_REQUEST`입니다. #### Response 재발송에 성공하면 거래의 [Escrow 객체](#escrow-객체)가 그대로 돌아옵니다. 상태를 바꾸는 API가 아니라 `status`도 호출 전과 같습니다. 재발송에 실패하면 HTTP 상태 코드와 함께 [에러 객체](/reference/using-api/req-res#api-v2-에러-객체)가 돌아옵니다. method: POST path: /v2/escrows/\{id}/cancel ### 취소 요청 수락 구매자의 취소 요청(`status=CANCEL_REQUESTED`)을 수락해 거래를 취소합니다. 환불을 일으키는 API이므로 [멱등키](/reference/using-api/authorization#멱등키-사용하기)가 필수입니다. 성공하면 `status`가 `CANCELED`, `cancelType`이 `CUSTOMER`가 되고 `escrow.changed` 웹훅이 발송됩니다. > **경고**: 에스크로 거래는 진행 중 **부분취소가 불가하므로 전액 취소**입니다. 금액을 지정하지 않습니다. 환불 계좌는 구매자가 취소 요청 과정에서 등록한 계좌가 사용되며, 상점이 전달하거나 응답에 노출되지 않습니다. 취소 요청을 **반려하는 경로는 없습니다** — 선택지는 수락 또는 미조치, 또는 [구매확정 요청 메일 재발송](#구매확정-요청-메일-재발송)입니다. #### Path 파라미터 * **id** 에스크로 거래 ID입니다. #### Request Body 파라미터 * **reason** 취소 사유로, 결제 취소 내역에 함께 기록됩니다. 최대 길이는 150자입니다. #### Response 취소 수락에 성공하면 취소가 반영된 [Escrow 객체](#escrow-객체)가 돌아옵니다(`status=CANCELED`·`cancelType=CUSTOMER`·`canceledAt` 채워짐). 취소 수락에 실패하면 HTTP 상태 코드와 함께 [에러 객체](/reference/using-api/req-res#api-v2-에러-객체)가 돌아옵니다.