*** title: 코어 API description: 토스페이먼츠 API 엔드포인트(Endpoint)와 객체 정보, 파라미터, 요청 및 응답 예제를 살펴보세요. hasVersion: true ---------------- title: API 키 description: href: /reference/using-api/api-keys title: 인증 및 기타 헤더 설정 description: href: /reference/using-api/authorization title: 요청·응답 본문 description: href: /reference/using-api/req-res title: 보안 description: href: /reference/using-api/security > **경고**: API를 사용하기 전에 [버전 정책](/reference/versioning)을 확인하세요. API 응답이나 웹훅 이벤트 본문에 새로운 필드가 추가와 같이 [하위 호환을 지원하는 변경 사항](/reference/versioning#하위-호환을-지원하는-변경-사항)은 버전 릴리즈 없이 기존 API에 반영되니 유의하세요. 자세한 내용은 [요청·응답 본문](/reference/using-api/req-res#유의사항)을 참고하세요. ## 결제 결제에 관한 모든 API와 결제 API의 응답으로 돌아오는 Payment 객체, Cancel 객체를 살펴봅니다. ### Payment 객체 결제 정보를 담고 있는 객체입니다. 결제 한 건의 결제 상태, 결제 취소 기록, 매출 전표, 현금영수증 정보 등을 자세히 알 수 있습니다. 결제가 승인됐을 때 응답은 Payment 객체로 항상 동일합니다. 객체의 구성은 결제수단(카드, 가상계좌, 간편결제 등)에 따라 조금씩 달라집니다. #### 객체 상세 * **version** Payment 객체의 응답 버전입니다. [버전 2022-06-08](/resources/release-note#2022-06-08)부터 날짜 기반 버저닝을 사용합니다. * **paymentKey** 결제의 키값입니다. 최대 길이는 200자입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 값이 유지됩니다. [결제 승인](#결제-승인), [결제 조회](#paymentkey로-결제-조회), [결제 취소](#결제-취소) API에 사용합니다. * **type** 결제 타입 정보입니다. `NORMAL`(일반결제), `BILLING`(자동결제), `BRANDPAY`(브랜드페이) 중 하나입니다. * **orderId** 주문번호입니다. 결제 요청에서 내 상점이 직접 생성한 영문 대소문자, 숫자, 특수문자 `-`, `_`로 이루어진 6자 이상 64자 이하의 문자열입니다. 각 주문을 식별하는 역할로, 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 `orderId`는 유지됩니다. * **orderName** 구매상품입니다. 예를 들면 `생수 외 1건` 같은 형식입니다. 최대 길이는 100자입니다. * **mId** 상점아이디(MID)입니다. 토스페이먼츠에서 발급합니다. 최대 길이는 14자입니다. * **currency** 결제할 때 사용한 통화입니다. * **method** `nullable` 결제수단입니다. `카드`, `가상계좌`, `간편결제`, `휴대폰`, `계좌이체`, `문화상품권`, `도서문화상품권`, `게임문화상품권` 중 하나입니다. * **totalAmount** 총 결제 금액입니다. 결제가 취소되는 등 결제 상태가 변해도 최초에 결제된 결제 금액으로 유지됩니다. * **balanceAmount** 취소할 수 있는 금액(잔고)입니다. 이 값은 결제 취소나 부분 취소가 되고 나서 남은 값입니다. 결제 상태 변화에 따라 `vat`, `suppliedAmount`, `taxFreeAmount`, `taxExemptionAmount`와 함께 값이 변합니다. * **status** 결제 처리 상태입니다. 아래와 같은 상태 값을 가질 수 있습니다. 상태 변화 흐름이 궁금하다면 [흐름도](/reference/using-api/webhook-events#payment_status_changed)를 살펴보세요. \- `READY`: 결제를 생성하면 가지게 되는 초기 상태입니다. 인증 전까지는 `READY` 상태를 유지합니다. \- `IN_PROGRESS`: 결제수단 정보와 해당 결제수단의 소유자가 맞는지 인증을 마친 상태입니다. [결제 승인 API](#결제-승인)를 호출하면 결제가 완료됩니다. \- `WAITING_FOR_DEPOSIT`: [가상계좌](/resources/glossary/virtual-account) 결제 흐름에만 있는 상태입니다. 발급된 가상계좌에 구매자가 아직 입금하지 않은 상태입니다. \- `DONE`: 인증된 결제수단으로 요청한 결제가 승인된 상태입니다. \- `CANCELED`: 승인된 결제가 취소된 상태입니다. 가상계좌 입금 전에 결제가 취소된 경우도 이 상태로 전환됩니다. \- `PARTIAL_CANCELED`: 승인된 결제가 부분 취소된 상태입니다. \- `ABORTED`: 결제 승인이 실패한 상태입니다. \- `EXPIRED`: 결제 유효 시간 30분이 지나 거래가 취소된 상태입니다. `IN_PROGRESS` 상태에서 [결제 승인 API](#결제-승인)를 호출하지 않으면 `EXPIRED`가 됩니다. * **requestedAt** 결제가 일어난 날짜와 시간 정보입니다. `yyyy-MM-dd'T'HH:mm:ss±hh:mm` ISO 8601 형식입니다. (e.g. `2022-01-01T00:00:00+09:00`) * **approvedAt** `nullable` 결제 승인이 일어난 날짜와 시간 정보입니다. `yyyy-MM-dd'T'HH:mm:ss±hh:mm` ISO 8601 형식입니다. (e.g. `2022-01-01T00:00:00+09:00`) * **useEscrow** [에스크로](/resources/glossary/escrow) 사용 여부입니다. * **lastTransactionKey** `nullable` 마지막 거래의 키값입니다. 한 결제 건의 승인 거래와 취소 거래를 구분하는 데 사용됩니다. 예를 들어 결제 승인 후 부분 취소를 두 번 했다면 마지막 부분 취소 거래의 키값이 할당됩니다. 최대 길이는 64자입니다. * **transactionKey** `nullable` 마지막 거래의 키값입니다. 한 결제 건의 승인 거래와 취소 거래를 구분하는 데 사용됩니다. 예를 들어 결제 승인 후 부분 취소를 두 번 했다면 마지막 부분 취소 거래의 키값이 할당됩니다. 최대 길이는 64자입니다. * **suppliedAmount** 공급가액입니다. 결제 취소 및 부분 취소가 되면 공급가액도 일부 취소되어 값이 바뀝니다. * **vat** 부가세입니다. 결제 취소 및 부분 취소가 되면 부가세도 일부 취소되어 값이 바뀝니다. (결제 금액 `amount` - 면세 금액 [`taxFreeAmount`](/reference#paymentdetaildto-taxfreeamount)) / 11 후 소수점 첫째 자리에서 반올림해서 계산합니다. (e.g. 결제 금액이 10,000원이고, 면세 금액이 3,000원이라면 부가세는 `(10000-3000)/11 = 636.3636..`을 반올림한 값 636원입니다.) 더 자세한 내용은 [세금 처리하기](/guides/v2/learn/tax)에서 살펴보세요. * **cultureExpense** 문화비(도서, 공연 티켓, 박물관·미술관 입장권 등) 지출 여부입니다. [계좌이체](/resources/glossary/transfer-payment), [가상계좌](/resources/glossary/virtual-account) 결제에만 적용됩니다. \* 카드 결제는 항상 `false`로 돌아옵니다. 카드 결제 문화비는 카드사에 [문화비 소득공제 전용 가맹점번호](https://www.culture.go.kr/deduction/companyGuide.do)로 등록하면 자동으로 처리됩니다. * **taxFreeAmount** 결제 금액 중 면세 금액입니다. 결제 취소 및 부분 취소가 되면 면세 금액도 일부 취소되어 값이 바뀝니다. \* 일반 상점일 때는 면세 금액으로 `0`이 돌아옵니다. 면세 상점, 복합 과세 상점일 때만 면세 금액이 돌아옵니다. 더 자세한 내용은 [세금 처리하기](/guides/v2/learn/tax)에서 살펴보세요. * **taxExemptionAmount** 과세를 제외한 결제 금액(컵 보증금 등)입니다. 이 값은 결제 취소 및 부분 취소가 되면 과세 제외 금액도 일부 취소되어 값이 바뀝니다. \* 과세 제외 금액이 있는 카드 결제는 부분 취소가 안 됩니다. * **cancels** `nullable` 결제 취소 이력입니다. * **cancelAmount** 결제를 취소한 금액입니다. * **cancelReason** 결제를 취소한 이유입니다. 최대 길이는 200자입니다. * **taxFreeAmount** 취소된 금액 중 면세 금액입니다. * **taxExemptionAmount** 취소된 금액 중 과세 제외 금액(컵 보증금 등)입니다. * **refundableAmount** 결제 취소 후 환불 가능한 잔액입니다. * **cardDiscountAmount** 카드 서비스의 즉시할인에서 취소된 금액입니다. * **transferDiscountAmount** 계좌 결제 서비스(퀵계좌이체, 브랜드페이 계좌)의 즉시할인에서 취소된 금액입니다. * **easyPayDiscountAmount** 간편결제 서비스의 포인트, 쿠폰, 즉시할인과 같은 [적립식 결제수단](/guides/v2/easypay-response#간편결제-결제수단-타입)에서 취소된 금액입니다. * **canceledAt** 결제 취소가 일어난 날짜와 시간 정보입니다. `yyyy-MM-dd'T'HH:mm:ss±hh:mm` ISO 8601 형식입니다. (e.g. `2022-01-01T00:00:00+09:00`) * **transactionKey** 취소 건의 키값입니다. 여러 건의 취소 거래를 구분하는 데 사용됩니다. 최대 길이는 64자입니다. * **receiptKey** `nullable` 취소 건의 현금영수증 키값입니다. 최대 길이는 200자입니다. * **cancelStatus** 취소 상태입니다. `DONE`이면 결제가 성공적으로 취소된 상태입니다. * **cancelRequestId** `nullable` 취소 요청 ID입니다. 비동기 결제에만 적용되는 특수 값입니다. 일반결제, 자동결제(빌링), 페이팔 해외결제에서는 항상 `null`입니다. * **isPartialCancelable** 부분 취소 가능 여부입니다. 이 값이 `false`이면 전액 취소만 가능합니다. * **card** `nullable` [카드](/resources/glossary/card)로 결제하면 제공되는 카드 관련 정보입니다. * **amount** 카드사에 결제 요청한 금액입니다. 즉시 할인 금액(`discount.amount`)이 포함됩니다. \* [간편결제](/resources/glossary/easypay)에 등록된 카드로 결제했다면 [간편결제 응답 확인 가이드](/guides/v2/easypay-response)를 참고하세요. * **issuerCode** [카드 발급사](/resources/glossary/card#카드-매입사와-발급사-이해하기) 두 자리 코드입니다. [카드사 코드](/codes/org-codes#카드사-코드)를 참고하세요. * **acquirerCode** `nullable` [카드 매입사](/resources/glossary/card#카드-매입사와-발급사-이해하기) 두 자리 코드입니다. [카드사 코드](/codes/org-codes#카드사-코드)를 참고하세요. * **number** 카드번호입니다. 번호의 일부는 마스킹 되어 있습니다. 최대 길이는 20자입니다. * **installmentPlanMonths** 할부 개월 수입니다. 일시불이면 `0`입니다. * **approveNo** 카드사 승인 번호입니다. 최대 길이는 8자입니다. * **useCardPoint** 카드사 포인트 사용 여부입니다. \* 일반 카드사 포인트가 아닌, 특수한 포인트나 바우처를 사용하면 할부 개월 수가 변경되어 응답이 돌아오니 유의해주세요. * **cardType** 카드 종류입니다. `신용`, `체크`, `기프트`, `미확인` 중 하나입니다. 구매자가 해외 카드로 결제했거나 [간편결제](/resources/glossary/easypay)의 결제 수단을 조합해서 결제했을 때 `미확인`으로 표시됩니다. * **ownerType** 카드의 소유자 타입입니다. `개인`, `법인`, `미확인` 중 하나입니다. 구매자가 해외 카드로 결제했거나 [간편결제](/resources/glossary/easypay)의 결제 수단을 조합해서 결제했을 때 `미확인`으로 표시됩니다. * **acquireStatus** [카드 결제](/resources/glossary/card-payment)의 매입 상태입니다. 아래와 같은 상태 값을 가질 수 있습니다. \- `READY`: 아직 매입 요청이 안 된 상태입니다. \- `REQUESTED`: 매입이 요청된 상태입니다. \- `COMPLETED`: 요청된 매입이 완료된 상태입니다. \- `CANCEL_REQUESTED`: 매입 취소가 요청된 상태입니다. \- `CANCELED`: 요청된 매입 취소가 완료된 상태입니다. * **isInterestFree** 무이자 할부의 적용 여부입니다. * **interestPayer** `nullable` 할부가 적용된 결제에서 할부 수수료를 부담하는 주체입니다. `BUYER`, `CARD_COMPANY`, `MERCHANT` 중 하나입니다. \- `BUYER`: 상품을 구매한 구매자가 할부 수수료를 부담합니다. 일반적인 할부 결제입니다. \- `CARD_COMPANY`: 카드사에서 할부 수수료를 부담합니다. 무이자 할부 결제입니다. \- `MERCHANT`: 상점에서 할부 수수료를 부담합니다. 무이자 할부 결제입니다. * **virtualAccount** `nullable` [가상계좌](/resources/glossary/virtual-account)로 결제하면 제공되는 가상계좌 관련 정보입니다. * **accountType** 가상계좌 타입을 나타냅니다. `일반`, `고정` 중 하나입니다. * **accountNumber** 발급된 계좌번호입니다. 최대 길이는 20자입니다. * **bankCode** 가상계좌 은행 두 자리 코드입니다. [은행 코드](/codes/org-codes#은행-코드)와 [증권사 코드](/codes/org-codes#증권사-코드)를 참고하세요. * **customerName** 가상계좌를 발급한 구매자명입니다. 최대 길이는 100자입니다. * **depositorName** 가상계좌에 입금한 계좌의 입금자명입니다. * **dueDate** 입금 기한입니다. `yyyy-MM-dd'T'HH:mm:ss` ISO 8601 형식을 사용합니다. * **refundStatus** 환불 처리 상태입니다. 아래와 같은 상태 값을 가질 수 있습니다. \- `NONE`: 환불 요청이 없는 상태입니다. \- `PENDING`: 환불을 처리 중인 상태입니다. \- `FAILED`: 환불에 실패한 상태입니다. \- `PARTIAL_FAILED`: 부분 환불에 실패한 상태입니다. \- `COMPLETED`: 환불이 완료된 상태입니다. * **expired** 가상계좌의 만료 여부입니다. * **settlementStatus** 정산 상태입니다. 정산이 아직 되지 않았다면 `INCOMPLETED`, 정산이 완료됐다면 `COMPLETED` 값이 들어옵니다. * **refundReceiveAccount** `nullable` 결제위젯 가상계좌 환불 정보 입력 기능으로 받은 구매자의 환불 계좌 정보입니다. 은행 코드(`bankCode`), 계좌번호(`accountNumber`), 예금주 정보(`holderName`)가 담긴 객체입니다. \* 구매자의 환불계좌 정보는 결제창을 띄운 시점부터 30분 동안만 조회할 수 있습니다. 이후에는 값이 내려가지 않습니다. 더 자세한 내용은 [결제 취소 가이드](/guides/v2/cancel-payment#case-2-결제위젯-환불-계좌-확인하기)를 참고하세요. * **secret** `nullable` 웹훅을 검증하는 최대 50자 값입니다. [가상계좌 웹훅 이벤트](/reference/using-api/webhook-events#deposit_callback) 본문으로 돌아온 `secret`과 같으면 정상적인 웹훅입니다. [결제 상태 웹훅 이벤트](/reference/using-api/webhook-events#payment_status_changed)로 돌아오는 Payment 객체의 `secret`과 같으면 정상적인 웹훅입니다. * **mobilePhone** `nullable` 휴대폰으로 결제하면 제공되는 [휴대폰 결제](/resources/glossary/mobile-payment) 관련 정보입니다. * **customerMobilePhone** 구매자가 결제에 사용한 휴대폰 번호입니다. `-` 없이 숫자로만 구성된 최소 8자, 최대 15자의 문자열입니다. * **settlementStatus** 정산 상태입니다. 정산이 아직 되지 않았다면 `INCOMPLETED`, 정산이 완료됐다면 `COMPLETED` 값이 들어옵니다. * **receiptUrl** 휴대폰 결제 내역 영수증을 확인할 수 있는 주소입니다. * **giftCertificate** `nullable` [상품권](/resources/glossary/gift-certificate)으로 결제하면 제공되는 상품권 결제 관련 정보입니다. * **approveNo** 결제 승인번호입니다. 최대 길이는 8자입니다. * **settlementStatus** 정산 상태입니다. 정산이 아직 되지 않았다면 `INCOMPLETED`, 정산이 완료됐다면 `COMPLETED` 값이 들어옵니다. * **transfer** `nullable` [계좌이체](/resources/glossary/transfer-payment)로 결제했을 때 이체 정보가 담기는 객체입니다. * **bankCode** 은행 두 자리 코드입니다. [은행 코드](/codes/org-codes#은행-코드)와 [증권사 코드](/codes/org-codes#증권사-코드)를 참고하세요. * **settlementStatus** 정산 상태입니다. 정산이 아직 되지 않았다면 `INCOMPLETED`, 정산이 완료됐다면 `COMPLETED` 값이 들어옵니다. * **metadata** `nullable` 결제 요청 시 SDK에서 직접 추가할 수 있는 결제 관련 정보입니다. 최대 5개의 키-값(key-value) 쌍입니다. 키는 `[` , `]` 를 사용하지 않는 최대 40자의 문자열, 값은 최대 2000자의 문자열입니다. * **receipt** `nullable` 발행된 영수증 정보입니다. * **url** 구매자에게 제공할 수 있는 결제수단별 영수증입니다. 카드 결제는 [매출전표](/resources/glossary/sales-statement), 가상계좌는 무통장 거래 명세서, 계좌이체・휴대폰・상품권 결제는 결제 거래 내역 확인서가 제공됩니다. * **checkout** `nullable` 결제창 정보입니다. * **url** 결제창이 열리는 주소입니다. * **easyPay** `nullable` [간편결제](/resources/glossary/easypay) 정보입니다. 구매자가 선택한 결제수단에 따라 `amount`, `discountAmount`가 달라집니다. [간편결제 응답 확인 가이드](/guides/v2/easypay-response)를 참고하세요. * **provider** 선택한 [간편결제사 코드](/codes/org-codes#간편결제사-코드)입니다. * **amount** 간편결제 서비스에 등록된 계좌 혹은 현금성 포인트로 결제한 금액입니다. * **discountAmount** 간편결제 서비스의 적립 포인트나 쿠폰 등으로 즉시 할인된 금액입니다. * **easyPayAmount** `nullable` [간편결제](/resources/glossary/easypay)에 등록되어 있는 계좌로 결제한 금액입니다. * **easyPayDiscountAmount** `nullable` [간편결제](/resources/glossary/easypay) 서비스의 포인트로 결제한 금액입니다. * **country** 결제한 국가입니다. [ISO-3166의 두 자리 국가 코드](https://ko.wikipedia.org/wiki/ISO_3166-1_alpha-2) 형식입니다. * **failure** `nullable` 결제 승인에 실패하면 응답으로 받는 [에러 객체](/reference/using-api/req-res#에러-객체)입니다. 실패한 [결제를 조회](#paymentkey로-결제-조회)할 때 확인할 수 있습니다. * **code** 오류 타입을 보여주는 에러 코드입니다. * **message** 에러 메시지입니다. 에러 발생 이유를 알려줍니다. 최대 길이는 510자입니다. * **cashReceipt** `nullable` [현금영수증](/resources/glossary/cash-receipt) 정보입니다. * **type** 현금영수증의 종류입니다. `소득공제`, `지출증빙` 중 하나입니다. * **receiptKey** 현금영수증의 키값입니다. 최대 길이는 200자입니다. * **issueNumber** 현금영수증 발급 번호입니다. 최대 길이는 9자입니다. * **receiptUrl** 발행된 현금영수증을 확인할 수 있는 주소입니다. 테스트 환경에서 영수증 URL은 생성되지만 실제 데이터는 제공되지 않습니다. 영수증 샘플은 [결제 결과 안내](/guides/v2/learn/payment-results) 가이드에서 확인하세요. * **amount** 현금영수증 처리된 금액입니다. * **taxFreeAmount** 면세 처리된 금액입니다. * **cashReceipts** `nullable` [현금영수증](/resources/glossary/cash-receipt) 발행 및 취소 이력이 담기는 배열입니다. 순서는 보장되지 않습니다. 예를 들어 결제 후 부분 취소가 여러 번 일어나면 모든 결제 및 부분 취소 건에 대한 현금영수증 정보를 담고 있습니다. 퀵계좌이체를 제외한 다른 계좌이체의 결제수단의 경우, 결제 즉시 현금영수증 정보를 확인할 수 있습니다. [가상계좌](/resources/glossary/virtual-account)는 구매자가 입금을 완료하면 현금영수증 정보를 확인할 수 있습니다. \* 결제가 이미 승인된 후 [현금영수증 발급 요청 API](/reference#현금영수증-발급-요청)로 발급한 현금영수증은 먼저 처리된 결제 정보와 연결되지 않아 값이 `null`입니다. [현금영수증 조회 API](/reference#현금영수증-조회)로 조회해주세요. \* [현금영수증 가맹점](/resources/glossary/cash-receipt#현금영수증-가맹-가입-의무란)이라면 결제했을 때 바로 발급됩니다. 발급을 원하지 않는다면 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요. * **receiptKey** 현금영수증의 키값입니다. 최대 길이는 200자입니다. * **orderId** 주문번호입니다. 결제 요청에서 내 상점이 직접 생성한 영문 대소문자, 숫자, 특수문자 `-`, `_`로 이루어진 6자 이상 64자 이하의 문자열입니다. 각 주문을 식별하는 역할로, 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 `orderId`는 유지됩니다. * **orderName** 구매상품입니다. 예를 들면 `생수 외 1건 `같은 형식입니다. 최대 길이는 100자입니다. * **type** 현금영수증의 종류입니다. `소득공제`, `지출증빙` 중 하나입니다. * **issueNumber** 현금영수증 발급 번호입니다. 최대 길이는 9자입니다. * **receiptUrl** 발행된 현금영수증을 확인할 수 있는 주소입니다. 테스트 환경에서 영수증 URL은 생성되지만 실제 데이터는 제공되지 않습니다. 영수증 샘플은 [결제 결과 안내](/guides/v2/learn/payment-results) 가이드에서 확인하세요. * **businessNumber** 현금영수증을 발급한 사업자등록번호입니다. 길이는 10자입니다. * **transactionType** 현금영수증 발급 종류입니다. 현금영수증 발급(`CONFIRM`)·취소(`CANCEL`) 건을 구분합니다. * **amount** 현금영수증 처리된 금액입니다. * **taxFreeAmount** 면세 처리된 금액입니다. * **issueStatus** 현금영수증 발급 상태입니다. 발급 승인 여부는 요청 후 1-2일 뒤 조회할 수 있습니다. `IN_PROGRESS`, `COMPLETED`, `FAILED` 중 하나입니다. 각 상태의 자세한 설명은 [CashReceipt 객체](/reference#cashreceiptresultdto-issuestatus)에서 확인할 수 있습니다. * **failure** 결제 실패 객체입니다. 오류 타입을 보여주는 `code`와 에러 메시지를 보여주는 `message` 필드가 있습니다. * **customerIdentityNumber** 현금영수증 발급에 필요한 소비자 인증수단입니다. 현금영수증을 발급한 주체를 식별합니다. 최대 길이는 30자입니다. 현금영수증 종류에 따라 휴대폰 번호, 사업자등록번호, 현금영수증 카드 번호 등을 입력할 수 있습니다. * **requestedAt** 현금영수증 발급 혹은 취소를 요청한 날짜와 시간 정보입니다. `yyyy-MM-dd'T'HH:mm:ss±hh:mm` ISO 8601 형식입니다. (e.g. `2022-01-01T00:00:00+09:00`) * **discount** `nullable` 카드사 및 퀵계좌이체의 즉시 할인 프로모션 정보입니다. 즉시 할인 프로모션이 적용됐을 때만 생성됩니다. * **amount** 카드사 및 퀵계좌이체의 즉시 할인 프로모션을 적용한 결제 금액입니다. method: POST path: /v1/payments/confirm ### 결제 승인 [`paymentKey`](/reference#v1paymentsconfirmpost-paymentkey)에 해당하는 결제를 검증하고 승인합니다. [결제 인증](/guides/v2/get-started/payment-flow#요청-인증-승인)이 유효한 10분 안에 상점에서 결제 승인 API를 호출하지 않으면 해당 결제는 [만료됩니다](/reference/using-api/webhook-events#payment_status_changed). #### Request Body 파라미터 * **paymentKey** 결제의 키값입니다. 최대 길이는 200자입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다. * **orderId** 주문번호입니다. 주문한 결제를 식별합니다. 충분히 무작위한 값을 생성해서 각 주문마다 고유한 값을 넣어주세요. 영문 대소문자, 숫자, 특수문자 `-`, `_`로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. * **amount** 결제할 금액입니다. #### Response 결제 승인에 성공하면 [Payment 객체](#payment-객체)가 돌아옵니다. 사용한 결제수단 필드에 값이 제대로 들어왔는지 확인하세요. 결제 승인에 실패했다면 HTTP 상태 코드와 함께 [에러 객체](/reference/using-api/req-res#에러-객체)가 돌아옵니다. [결제 승인 API에서 발생할 수 있는 에러](/reference/error-codes#결제-승인)를 살펴보세요. method: GET path: /v1/payments/\{paymentKey} ### paymentKey로 결제 조회 승인된 결제를 [`paymentKey`](/reference#v1paymentspaymentkeyget-paymentkey)로 조회합니다. [`paymentKey`](/reference#v1paymentspaymentkeyget-paymentkey)는 SDK를 사용해 결제할 때 발급되는 고유한 키값으로 결제가 최종 승인된 후 돌아오는 [Payment 객체](#payment-객체)에 담겨있습니다. #### Path 파라미터 * **paymentKey** 결제의 키값입니다. 최대 길이는 200자입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다. #### Response 결제 조회에 성공하면 [Payment 객체](#payment-객체)가 돌아옵니다. 사용한 결제수단 필드에 값이 제대로 들어왔는지 확인하세요. 결제 조회에 실패했다면 HTTP 상태 코드와 함께 [에러 객체](/reference/using-api/req-res#에러-객체)가 돌아옵니다. [결제 조회 API에서 발생할 수 있는 에러](/reference/error-codes#결제-조회)를 살펴보세요. method: GET path: /v1/payments/orders/\{orderId} ### orderId로 결제 조회 승인된 결제를 [`orderId`](/reference#v1paymentsordersorderidget-orderid)로 조회합니다. [`orderId`](/reference#v1paymentsordersorderidget-orderid)는 SDK로 [결제를 요청](/guides/v2/get-started/payment-flow#요청-인증-승인)할 때 직접 생성한 값입니다. #### Path 파라미터 * **orderId** 주문번호입니다. 주문한 결제를 식별합니다. 충분히 무작위한 값을 생성해서 각 주문마다 고유한 값을 넣어주세요. 영문 대소문자, 숫자, 특수문자 `-`, `_`로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. #### Response 결제 조회에 성공하면 [Payment 객체](#payment-객체)가 돌아옵니다. 사용한 결제수단 필드에 값이 제대로 들어왔는지 확인하세요. 결제 조회에 실패했다면 HTTP 상태 코드와 함께 [에러 객체](/reference/using-api/req-res#에러-객체)가 돌아옵니다. [결제 조회 API에서 발생할 수 있는 에러](/reference/error-codes#결제-조회)를 살펴보세요. method: POST path: /v1/payments/\{paymentKey}/cancel ### 결제 취소 승인된 결제를 [`paymentKey`](/reference#v1paymentspaymentkeycancelpost-paymentkey)로 취소합니다. 취소 이유를 [`cancelReason`](/reference#v1paymentspaymentkeycancelpost-cancelreason)에 추가해야 합니다. 결제 금액의 일부만 부분 취소하려면 [`cancelAmount`](/reference#v1paymentspaymentkeycancelpost-cancelamount)에 취소할 금액을 추가해서 API를 요청합니다. [`cancelAmount`](/reference#v1paymentspaymentkeycancelpost-cancelamount)에 값을 넣지 않으면 전액 취소됩니다. \* [멱등키](/reference/using-api/authorization#멱등키-헤더)를 요청 헤더에 추가하면 중복 취소 없이 안전하게 처리됩니다. #### Path 파라미터 * **paymentKey** 결제의 키값입니다. 최대 길이는 200자입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다. #### Request Body 파라미터 * **cancelReason** 결제를 취소하는 이유입니다. 최대 길이는 200자입니다. * **cancelAmount** 취소할 금액입니다. 값이 없으면 전액 취소됩니다. * **refundReceiveAccount** 결제 취소 후 금액이 환불될 계좌의 정보입니다. **[가상계좌](/resources/glossary/virtual-account) 결제에만 필수입니다.** 다른 결제수단으로 이루어진 결제를 취소할 때는 사용하지 않습니다. 보낸 계좌 정보는 유효성 검사가 이뤄집니다. 유효한 계좌로 결제 취소 요청이 되었다면 환불은 취소 요청 후 2일 후에 진행됩니다. 구매자가 가상계좌에 입금을 아직 안 했다면, 결제를 취소해도 환불해야 되는 금액이 없기 때문에 이 파라미터를 추가할 필요가 없습니다. 입금 전에는 부분 취소를 할 수 없고 전체 금액 취소만 할 수 있습니다. * **bank** 취소 금액을 환불받을 계좌의 은행 코드입니다. [은행 코드](/codes/org-codes#은행-코드)와 [증권사 코드](/codes/org-codes#증권사-코드)를 참고하세요. * **accountNumber** 취소 금액을 환불받을 계좌의 계좌번호입니다. `-` 없이 숫자만 넣어야 합니다. 최대 길이는 20자입니다. * **holderName** 취소 금액을 환불받을 계좌의 예금주입니다. 최대 길이는 60자입니다. * **taxFreeAmount** 취소할 금액 중 면세 금액입니다. 값을 넣지 않으면 기본값인 `0`으로 설정됩니다. \* 면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점에는 적용되지 않습니다. 더 자세한 내용은 [세금 처리하기](/guides/v2/learn/tax)에서 살펴보세요. * **currency** 취소 통화입니다. 승인된 통화와 동일한 값을 사용해야 합니다. 일반결제는 `KRW`, `USD`, `JPY`를 지원합니다. 해외 간편결제(PayPal)는 `USD`만 지원합니다. * **refundableAmount** 현재 환불 가능한 금액입니다. 결제 취소를 안전하게 처리합니다. 환불 가능한 잔액 정보가 `refundableAmount`의 값과 다르면 취소를 처리하지 않고 에러를 내보냅니다. \* 안전하게 취소하려면 [멱등키](/reference/using-api/authorization#멱등키-헤더)와 함께 사용해주세요. #### Response 결제 취소에 성공하면 [Payment 객체](#payment-객체)의 [`cancels`](/reference#paymentdetaildto-cancels) 필드에 취소 객체가 배열로 돌아옵니다. 부분 취소를 여러 번 하면 아래와 같이 [`Payment.cancels`](#paymentdetaildto-cancels) 필드에 취소 객체가 여러 개 돌아옵니다. 각 취소 거래마다 거래를 구분하는 [`transactionKey`](#paymentdetaildto-cancelstransactionkey)를 가지고 있습니다. 결제 취소에 실패했다면 HTTP 상태 코드와 함께 [에러 객체](/reference/using-api/req-res#에러-객체)가 돌아옵니다. [결제 취소 API에서 발생할 수 있는 에러](/reference/error-codes#결제-취소)를 살펴보세요. method: POST path: /v1/payments/key-in ### 카드 번호 결제 카드 번호 결제는 직접 카드 번호를 입력해서 결제하는 비인증 결제로 '수기 결제', ['키인(Key-in) 결제'](/resources/glossary/keyin)라고 불리기도 합니다. 카드 번호 결제는 구매자가 직접 카드 번호를 입력해서 결제해야 됩니다. 토스페이먼츠와 계약에 따라 필수 파라미터가 변경될 수 있으며, 구매자의 카드번호를 저장하여 사용할 수 없습니다. > **참고**: 카드 번호 결제 API는 리스크 검토 및 추가 계약 후 사용할 수 있습니다. 도입 문의는 아래 버튼을 눌러주세요.도입 문의하기 #### Request Body 파라미터 * **amount** 결제할 금액입니다. * **orderId** 주문번호입니다. 주문한 결제를 식별합니다. 충분히 무작위한 값을 생성해서 각 주문마다 고유한 값을 넣어주세요. 영문 대소문자, 숫자, 특수문자 `-`, `_`로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. * **orderName** 구매상품입니다. 예를 들면 `생수 외 1건` 같은 형식입니다. 최대 길이는 100자입니다. 최소 1글자 이상 100글자 이하여야 합니다. * **cardNumber** 카드 번호입니다. 최대 길이는 20자입니다. * **cardExpirationYear** 카드 유효 연도입니다. * **cardExpirationMonth** 카드 유효 월입니다. * **customerIdentityNumber** 카드 소유자 정보입니다. 생년월일 6자리(`YYMMDD`) 혹은 사업자등록번호 10자리가 들어갑니다. * **cardPassword** 카드 비밀번호 앞 두 자리입니다. * **cardInstallmentPlan** 신용 카드의 할부 개월 수입니다. 값을 넣으면 해당 할부 개월 수로 결제가 진행됩니다. `2`부터 `12`사이의 값을 사용할 수 있고, 0이 들어가면 할부가 아닌 일시불로 결제됩니다. 결제 금액이 5만원 이상일 때만 할부가 적용됩니다. * **useFreeInstallmentPlan** 카드사 무이자 할부 적용 여부입니다. 기본값은 `false`입니다. 값이 `true`이면 `cardInstallmentPlan`에 지정한 할부 개월로 무이자 할부가 적용됩니다. \* 이 파라미터로 적용된 무이자 할부 비용은 상점이 부담합니다. * **useCardPoint** 카드사 포인트 사용 여부입니다. * **taxFreeAmount** 결제할 금액 중 면세 금액입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다. \* 면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점에는 적용되지 않습니다. 더 자세한 내용은 [세금 처리하기](/guides/learn/tax)에서 살펴보세요. * **customerEmail** 구매자의 이메일 주소입니다. 결제 상태가 바뀌면 이메일 주소로 결제내역이 전송됩니다. 최대 길이는 100자입니다. * **customerName** 구매자명입니다. 최대 길이는 100자입니다. * **customerIp** 구매자의 IP 주소입니다. 카드사는 이 값을 FDS([이상 거래 탐지 시스템](/resources/glossary/fds))에 활용하여 위험도를 판단합니다. 이 값을 전달하면 FDS가 신뢰할 수 있는 결제라고 판단해서 더 매끄럽게 처리됩니다. \* API 호출하는 서버의 IP 주소를 보내지 않도록 주의해 주세요. #### Response 카드 번호 결제에 성공하면 [Payment 객체](/reference#payment-객체)가 돌아옵니다. 카드 번호 결제에 실패했다면 HTTP 상태 코드와 함께 [에러 객체](/reference/using-api/req-res#에러-객체)가 돌아옵니다. [카드 번호 결제 API에서 발생할 수 있는 에러](/reference/error-codes#카드-번호-결제)를 살펴보세요. method: POST path: /v1/virtual-accounts ### 가상계좌 발급 요청 구매자가 원하는 은행의 [가상계좌](/resources/glossary/virtual-account) 발급을 요청합니다. #### Request Body 파라미터 * **amount** 결제할 금액입니다. * **orderId** 주문번호입니다. 주문한 결제를 식별합니다. 충분히 무작위한 값을 생성해서 각 주문마다 고유한 값을 넣어주세요. 영문 대소문자, 숫자, 특수문자 `-`, `_`로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. * **orderName** 구매상품입니다. 예를 들면 `생수 외 1건` 같은 형식입니다. 최대 길이는 100자입니다. 최소 1글자 이상 100글자 이하여야 합니다. * **customerName** 입금할 구매자명입니다. 최대 길이는 100자입니다. * **bank** 가상계좌를 발급할 은행입니다. 가상계좌 발급이 가능한 [은행](/codes/org-codes#은행-코드)을 참고하세요. * **validHours** 가상계좌 발급 시점으로부터 가상계좌가 유효한 시간입니다. 설정한 `validHours` 안에 구매자가 입금을 하지 않으면 주문은 취소됩니다. 설정할 수 있는 최대값은 `2160`시간(90일)입니다. 예를 들어 가상계좌 발급 후 24시간 내에 입금해야 한다면 `24`로 설정합니다. 값을 넣지 않으면 기본값 `168`시간(7일)으로 설정됩니다. `validHours`와 [`dueDate`](/reference#v1virtual-accountspost-duedate) 중 하나만 사용할 수 있습니다. * **dueDate** 가상계좌 입금 기한입니다. `dueDate`이 지난 시점에 입금을 시도하면 실패합니다. 티켓 예매 등 주문 시간과 상관없이 정해진 시점까지 결제를 받아야 할 때도 사용할 수 있습니다. 설정할 수 있는 최대값은 결제 요청일로부터 90일입니다. `yyyy-MM-dd'T'HH:mm:ss` ISO 8601 형식을 사용합니다. 예를 들어 입금 기한을 '2023년 10월 10일 자정'과 같이 특정 시점으로 설정하고 싶을 때 `2023-10-10T00:00:00`과 같이 사용하세요. [`validHours`](/reference#v1virtual-accountspost-validhours)와 `dueDate` 중 하나만 사용할 수 있습니다. * **customerEmail** 구매자의 이메일 주소입니다. 결제 상태가 바뀌면 이메일 주소로 [결제내역](/guides/v2/learn/payment-results#이메일)이 전송됩니다. 최대 길이는 100자입니다. * **customerMobilePhone** 구매자의 휴대폰 번호입니다. 가상계좌 입금 안내가 전송되는 번호입니다. `-` 없이 숫자로만 구성된 최소 8자, 최대 15자의 문자열입니다. * **taxFreeAmount** 면세 금액입니다. 값을 넣지 않으면 기본값인 `0`으로 설정됩니다. \* 면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점에는 적용되지 않습니다. 더 자세한 내용은 [세금 처리하기](/guides/v2/learn/tax)에서 살펴보세요. * **useEscrow** [에스크로](/resources/glossary/escrow) 사용 여부입니다. 값을 넣지 않으면 기본값인 `false`로 설정되고 사용자가 에스크로 결제 여부를 선택합니다. * **cashReceipt** 현금영수증 발급 정보를 담는 객체입니다. * **type** 현금영수증 발급 용도입니다. `소득공제`, `지출증빙`, `미발행` 중 하나입니다. * **registrationNumber** 현금영수증 발급에 필요한 개인 식별 번호입니다. 최대 길이는 30자입니다. 현금영수증 종류에 따라 휴대폰 번호, 사업자등록번호, 현금영수증 카드 번호 등을 입력할 수 있습니다. * **escrowProducts** 각 상품의 상세 정보를 담는 배열입니다. 예를 들어 사용자가 세 가지 종류의 상품을 구매했다면 길이가 3인 배열이어야 합니다. 에스크로 결제를 사용할 때만 필요한 파라미터입니다. * **id** 상품의 ID입니다. 이 값은 유니크해야 합니다. * **name** 상품 이름입니다. * **code** 상점에서 사용하는 상품 관리 코드입니다. * **unitPrice** 상품의 가격입니다. 전체를 합한 가격이 아닌 상품의 개당 가격입니다. * **quantity** 상품 구매 수량입니다. #### Response 가상계좌 발급 요청에 성공하면 [`virtualAccount`](/reference#paymentdetaildto-virtualaccount) 필드에 값이 있는 [Payment 객체](#payment-객체)가 돌아옵니다. 가상계좌 발급 요청에 실패했다면 HTTP 상태 코드와 함께 [에러 객체](/reference/using-api/req-res#에러-객체)가 돌아옵니다. [가상계좌 발급 요청 API에서 발생할 수 있는 에러](/reference/error-codes#가상계좌-발급-요청)를 살펴보세요. ## 자동결제 자동결제 API로 구매자의 결제수단 정보를 인증·등록한 뒤 정기 배송, 음악 스트리밍과 같은 구독형 서비스에서 사용할 수 있습니다. \* **정기 구독형 서비스가 아니라면 자동결제 사용이 제한되니 유의하세요.** 더 궁금한 점이 있다면 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요. ### Billing 객체 [자동결제](/resources/glossary/billing)에 사용할 결제수단이 인증되어 등록되었을 때 돌아오는 객체입니다. 등록된 결제수단 정보와 발급된 [`billingKey`](/reference#billingconfirmdto-billingkey)가 포함되어 있습니다. [`billingKey`](/reference#billingconfirmdto-billingkey)로 자동결제 요청 API를 호출할 수 있습니다. #### 객체 상세 * **mId** 상점아이디(MID)입니다. 토스페이먼츠에서 발급합니다. 최대 길이는 14자입니다. * **customerKey** 구매자 ID입니다. 빌링키와 연결됩니다. 다른 사용자가 이 값을 알게 되면 악의적으로 사용될 수 있습니다. 자동 증가하는 숫자 또는 이메일・전화번호・사용자 아이디와 같이 유추가 가능한 값은 안전하지 않습니다. [UUID](/resources/glossary/uuid)와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 영문 대소문자, 숫자, 특수문자 `-`, `_`, `=`, `.`, `@ `를 최소 1개 이상 포함한 최소 2자 이상 최대 300자 이하의 문자열이어야 합니다. \* `customerKey`는 [클라이언트 키](/reference/using-api/api-keys#클라이언트-키와-시크릿-키#api-키-이해하기)와 다릅니다. 클라이언트 키는 연동을 위한 기본 키로 브라우저에서 SDK를 연동할 때 '클라이언트'를 식별하며, 토스페이먼츠에서 제공합니다. * **authenticatedAt** 결제수단이 인증된 시점의 날짜와 시간 정보입니다. `yyyy-MM-dd'T'HH:mm:ss±hh:mm` ISO 8601 형식입니다. (e.g. `2022-01-01T00:00:00+09:00`) * **method** 결제수단입니다. * **billingKey** 자동결제에서 카드 정보 대신 사용되는 값입니다. [`customerKey`](/reference#billingconfirmdto-customerkey)와 연결됩니다. 최대 길이는 200자입니다. * **card** 발급된 빌링키와 연결된 카드 정보입니다. * **issuerCode** [카드 발급사](/resources/glossary/card#카드-매입사와-발급사-이해하기) 두 자리 코드입니다. [카드사 코드](/codes/org-codes#카드사-코드)를 참고하세요. * **acquirerCode** [카드 매입사](/resources/glossary/card#카드-매입사와-발급사-이해하기) 두 자리 코드입니다. [카드사 코드](/codes/org-codes#카드사-코드)를 참고하세요. * **number** 카드 번호입니다. 번호의 일부는 마스킹 되어 있습니다. 최대 길이는 20자입니다. * **cardType** 카드 종류입니다. `신용`, `체크`, `기프트` 중 하나입니다. * **ownerType** 카드의 소유자 타입입니다. `개인`, `법인` 중 하나입니다. * **transfers** 발급된 빌링키와 연동된 계좌 정보입니다. * **bankName** 은행명입니다. * **bankAccountNumber** 마스킹된 계좌번호입니다. * **cardCompany** 카드 발급사입니다. [카드사 코드](/codes/org-codes#카드사-코드)를 참고하세요. \* 버전 2024-06-01부터 응답에서 제거됐어요. [`card.issuerCode`](#billingconfirmdto-cardissuercode)를 사용해주세요. * **cardNumber** 카드 번호입니다. 번호의 일부는 마스킹 되어 있습니다. 최대 길이는 20자입니다. \* 버전 2024-06-01부터 응답에서 제거됐어요. [`card.number`](#billingconfirmdto-cardnumber)를 사용해주세요. method: POST path: /v1/billing/authorizations/issue ### 인증 정보(authKey)로 빌링키 발급 SDK(`requestBillingAuth`)로 결제창을 열어 인증을 완료한 뒤, 리다이렉트 URL로 돌아오는 [`authKey`](/reference#v1billingauthorizationsissuepost-authkey), 구매자 ID인 [`customerKey`](/reference#v1billingauthorizationsissuepost-customerkey)로 빌링키 발급을 요청합니다. #### Request Body 파라미터 * **authKey** 자동결제 등록창 호출이 성공하면 리다이렉트 URL에 쿼리 파라미터(Query Parameter)로 돌아오는 일회성 인증 키입니다. 최대 길이는 300자입니다. * **customerKey** 구매자 ID입니다. 빌링키와 연결됩니다. 다른 사용자가 이 값을 알게 되면 악의적으로 사용될 수 있습니다. 자동 증가하는 숫자 또는 이메일・전화번호・사용자 아이디와 같이 유추가 가능한 값은 안전하지 않습니다. [UUID](/resources/glossary/uuid)와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 영문 대소문자, 숫자, 특수문자 `-`, `_`, `=`, `.`, `@ `를 최소 1개 이상 포함한 최소 2자 이상 최대 300자 이하의 문자열이어야 합니다. \* `customerKey`는 [클라이언트 키](/reference/using-api/api-keys#클라이언트-키와-시크릿-키#api-키-이해하기)와 다릅니다. 클라이언트 키는 연동을 위한 기본 키로 브라우저에서 SDK를 연동할 때 '클라이언트'를 식별하며, 토스페이먼츠에서 제공합니다. #### Response 카드 자동결제 빌링키 발급 요청에 성공하면 [Billing 객체](#billing-객체)가 돌아옵니다. 카드 자동결제 빌링키 발급 요청에 실패했다면 HTTP 상태 코드와 함께 [에러 객체](/reference/using-api/req-res#에러-객체)가 돌아옵니다. [카드 자동결제 빌링키 발급 요청 API에서 발생 가능한 에러](/reference/error-codes#카드-자동결제-빌링키-발급)를 살펴보세요. method: POST path: /v1/billing/authorizations/card ### 카드 정보로 빌링키 발급 구매자의 카드 번호, 카드 유효기간, 생년월일 등 카드 정보를 직접 입력받아 [빌링키](#billing-객체)를 발급합니다. 본인인증은 직접 구현해야 합니다. #### Request Body 파라미터 * **customerKey** 구매자 ID입니다. 빌링키와 연결됩니다. 다른 사용자가 이 값을 알게 되면 악의적으로 사용될 수 있습니다. 자동 증가하는 숫자 또는 이메일・전화번호・사용자 아이디와 같이 유추가 가능한 값은 안전하지 않습니다. [UUID](/resources/glossary/uuid)와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 영문 대소문자, 숫자, 특수문자 `-`, `_`, `=`, `.`, `@ `를 최소 1개 이상 포함한 최소 2자 이상 최대 300자 이하의 문자열이어야 합니다. * **cardNumber** 카드 번호입니다. 최대 길이는 20자입니다. * **cardExpirationYear** 카드 유효 연도입니다. * **cardExpirationMonth** 카드 유효 월입니다. * **customerIdentityNumber** 카드 소유자 정보입니다. 생년월일 6자리(`YYMMDD`) 혹은 사업자등록번호 10자리가 들어갑니다. * **cardPassword** 카드 비밀번호 앞 두 자리입니다. * **customerName** 구매자명입니다. 최대 길이는 100자입니다. * **customerEmail** 구매자의 이메일 주소입니다. 결제 상태가 바뀌면 이메일 주소로 [결제내역](/guides/learn/payment-results#이메일)이 전송됩니다. 최대 길이는 100자입니다. #### Response 카드 자동결제 빌링키 발급 요청에 성공하면 [Billing 객체](#billing-객체)가 돌아옵니다. 카드 자동결제 빌링키 발급 요청에 실패했다면 HTTP 상태 코드와 함께 [에러 객체](/reference/using-api/req-res#에러-객체)가 돌아옵니다. [카드 자동결제 빌링키 발급 요청 API에서 발생 가능한 에러](/reference/error-codes#카드-자동결제-빌링키-발급)를 살펴보세요. method: POST path: /v1/billing/\{billingKey} ### 자동결제 승인 \* 자동결제 API는 추가 계약 후 사용할 수 있습니다. 추가 계약을 하고 싶다면 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요. 발급받은 [`billingKey`](/reference#v1billingbillingkeypost-billingkey)로 자동결제를 승인합니다. 자동결제 승인은 최대 60초가 소요됩니다. 타임아웃 값을 최소 60초로 설정하세요. #### Path 파라미터 * **billingKey** 발급된 빌링키 정보입니다. 구매자의 결제 정보로 사용됩니다. #### Request Body 파라미터 * **amount** 결제할 금액입니다. * **customerKey** 구매자 ID입니다. 빌링키와 연결됩니다. 다른 사용자가 이 값을 알게 되면 악의적으로 사용될 수 있습니다. 자동 증가하는 숫자 또는 이메일・전화번호・사용자 아이디와 같이 유추가 가능한 값은 안전하지 않습니다. [UUID](/resources/glossary/uuid)와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 영문 대소문자, 숫자, 특수문자 `-`, `_`, `=`, `.`, `@ `를 최소 1개 이상 포함한 최소 2자 이상 최대 300자 이하의 문자열이어야 합니다. * **orderId** 주문번호입니다. 주문한 결제를 식별합니다. 충분히 무작위한 값을 생성해서 각 주문마다 고유한 값을 넣어주세요. 영문 대소문자, 숫자, 특수문자 `-`, `_`로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. * **orderName** 구매상품입니다. 예를 들면 `생수 외 1건` 같은 형식입니다. 최대 길이는 100자입니다. * **customerEmail** 구매자의 이메일 주소입니다. 결제 상태가 바뀌면 이메일 주소로 [결제내역](/guides/v2/learn/payment-results#이메일)이 전송됩니다. 최대 길이는 100자입니다. * **customerName** 구매자명입니다. 최대 길이는 100자입니다. * **customerIp** 구매자의 IP 주소입니다. 카드사는 이 값을 FDS([이상 거래 탐지 시스템](/resources/glossary/fds))에 활용하여 위험도를 판단합니다. 이 값을 전달하면 FDS가 신뢰할 수 있는 결제라고 판단해서 더 매끄럽게 처리됩니다. \* API 호출하는 서버의 IP 주소를 보내지 않도록 주의해 주세요. * **taxFreeAmount** 면세 금액입니다. 값을 넣지 않으면 기본값인 `0`으로 설정됩니다. \* 면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점에는 적용되지 않습니다. 더 자세한 내용은 [세금 처리하기](/guides/v2/learn/tax)에서 살펴보세요. * **taxExemptionAmount** 과세를 제외한 결제 금액(컵 보증금 등)입니다. \* 과세 제외 금액이 있는 카드 결제는 부분 취소가 안 됩니다. #### Response 자동결제 승인에 성공하면 [`card`](/reference#paymentdetaildto-card) 필드에 값이 있는 [Payment 객체](#payment-객체)가 돌아옵니다. 자동결제 승인에 실패했다면 HTTP 상태 코드와 함께 [에러 객체](/reference/using-api/req-res#에러-객체)가 돌아옵니다. [자동결제 승인 API에서 발생 가능한 에러](/reference/error-codes#카드-자동결제-승인)를 살펴보세요. method: DELETE path: /v1/billing/\{billingKey} ### 빌링키 삭제 #### Path 파라미터 * **billingKey** 발급된 빌링키 정보입니다. 구매자의 결제 정보로 사용됩니다. #### Response 비어있는 body에 200 응답만 내려갑니다. code, message로 이루어진 error 객체가 내려갑니다. [자동결제 승인 API에서 발생 가능한 에러](/reference/error-codes#카드-자동결제-승인)를 살펴보세요. ## 거래 결제 한 건에서 발생하는 승인과 취소 각각이 [거래](/resources/glossary/transaction)입니다. 특정 기간에 일어난 모든 결제 승인 및 취소의 요약이 필요할 때 [거래 조회 API](/reference#거래-조회)를 사용하세요. 거래 기록을 비교하는 일을 '거래 대사'라고 부르기도 합니다. '대사'란 기록을 비교・대조해서 데이터를 검증하고 일치시키는 과정을 뜻합니다. ### Transaction 객체 [거래](/resources/glossary/transaction) 정보를 담고 있는 객체입니다. 하나의 결제 건에 여러 번의 거래가 일어날 수 있습니다. 결제 승인, 취소, 부분 취소가 이루어질 때마다 각각의 거래 정보를 담은 Transaction 객체가 만들어지고 개별 [`transactionKey`](/reference#paymenttransactiondto-transactionkey)를 가지게 됩니다. [거래 조회 API](#거래-조회)를 호출하면 지정한 기간 동안 생긴 모든 Transaction 객체들이 배열로 돌아옵니다. #### 객체 상세 * **mId** 상점아이디(MID)입니다. 토스페이먼츠에서 발급합니다. 최대 길이는 14자입니다. * **transactionKey** 거래의 키값입니다. 한 결제 건의 승인 거래와 취소 거래를 구분하는 데 사용됩니다. 최대 길이는 64자입니다. * **paymentKey** 결제의 키값입니다. 최대 길이는 200자입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 값이 유지됩니다. * **orderId** 주문번호입니다. 결제 요청에서 내 상점이 직접 생성한 영문 대소문자, 숫자, 특수문자 `-`, `_`로 이루어진 6자 이상 64자 이하의 문자열입니다. 각 주문을 식별하는 역할로, 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 `orderId`는 유지됩니다. * **method** 결제수단입니다. `카드`, `가상계좌`, `간편결제`, `휴대폰`, `계좌이체`, `문화상품권`, `도서문화상품권`, `게임문화상품권` 중 하나입니다. * **customerKey** 구매자 ID입니다. 빌링키와 연결됩니다. 다른 사용자가 이 값을 알게 되면 악의적으로 사용될 수 있습니다. 자동 증가하는 숫자 또는 이메일・전화번호・사용자 아이디와 같이 유추가 가능한 값은 안전하지 않습니다. [UUID](/resources/glossary/uuid)와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 영문 대소문자, 숫자, 특수문자 `-`, `_`, `=`, `.`, `@ `를 최소 1개 이상 포함한 최소 2자 이상 최대 300자 이하의 문자열이어야 합니다. \* `customerKey`는 [클라이언트 키](/reference/using-api/api-keys#클라이언트-키와-시크릿-키#api-키-이해하기)와 다릅니다. 클라이언트 키는 연동을 위한 기본 키로 브라우저에서 SDK를 연동할 때 '클라이언트'를 식별하며, 토스페이먼츠에서 제공합니다. * **useEscrow** [에스크로](/resources/glossary/escrow) 사용 여부입니다. * **receiptUrl** 거래 영수증을 확인할 수 있는 주소입니다. * **status** 결제 처리 상태입니다. 아래와 같은 상태 값을 가질 수 있습니다. 상태 변화 흐름이 궁금하다면 [흐름도](/reference/using-api/webhook-events#payment_status_changed)를 살펴보세요. \- `READY`: 결제를 생성하면 가지게 되는 초기 상태입니다. 인증 전까지는 `READY` 상태를 유지합니다. \- `IN_PROGRESS`: 결제수단 정보와 해당 결제수단의 소유자가 맞는지 인증을 마친 상태입니다. [결제 승인 API](#결제-승인)를 호출하면 결제가 완료됩니다. \- `WAITING_FOR_DEPOSIT`: [가상계좌](/resources/glossary/virtual-account) 결제 흐름에만 있는 상태입니다. 발급된 가상계좌에 구매자가 아직 입금하지 않은 상태입니다. \- `DONE`: 인증된 결제수단으로 요청한 결제가 승인된 상태입니다. \- `CANCELED`: 승인된 결제가 취소된 상태입니다. 가상계좌 입금 전에 결제가 취소된 경우도 이 상태로 전환됩니다. \- `PARTIAL_CANCELED`: 승인된 결제가 부분 취소된 상태입니다. \- `ABORTED`: 결제 승인에 실패한 상태입니다. \- `EXPIRED`: 요청된 결제의 유효 시간 30분이 지나 거래가 취소된 상태입니다. `IN_PROGRESS` 상태에서 [결제 승인 API](#결제-승인)를 호출하지 않으면 `EXPIRED`가 됩니다. * **transactionAt** 거래가 처리된 시점의 날짜와 시간 정보입니다. `yyyy-MM-dd'T'HH:mm:ss±hh:mm` ISO 8601 형식입니다. * **currency** 결제할 때 사용한 통화입니다. * **amount** 결제한 금액입니다. method: GET path: /v1/transactions ### 거래 조회 특정 기간의 거래 기록을 조회합니다. 거래 기록은 거래가 처리된 시점([`transactionAt`](/reference#paymenttransactiondto-transactionat))을 기준으로 조회합니다. Query 파라미터 [`startDate`](/reference#v1transactionsget-startdate)와 [`endDate`](/reference#v1transactionsget-enddate)로 지정한 날짜 정보를 사용합니다. 거래가 일어난 당일부터 거래 기록을 조회할 수 있습니다. 예를 들어 예제의 요청은 2022년 1월 1일부터 1월 2일까지 일어난 거래를 조회합니다. \* 거래 조회는 최대 60초가 소요됩니다. 타임아웃 값을 최소 60초로 설정하세요. 라이브 환경에서 비정상적으로 많은 요청을 보내면 `429 Too Many Requests` 상태 코드가 내려올 수 있습니다. #### Query 파라미터 * **startDate** 조회를 시작하고 싶은 날짜와 시간 정보입니다. `yyyy-MM-dd'T'hh:mm:ss` ISO 8601 형식입니다. 날짜 정보만 입력하면 시간은 자동으로 `00:00:00`으로 설정됩니다. (e.g. `2022-01-01T00:00:00`) * **endDate** 조회를 마치고 싶은 날짜와 시간 정보입니다. `yyyy-MM-dd'T'hh:mm:ss` ISO 8601 형식입니다. 날짜 정보만 입력하면 시간은 자동으로 `00:00:00`으로 설정됩니다. (e.g. `2022-01-02T23:59:59`) * **startingAfter** 특정 결제 건 이후의 기록을 조회할 때 사용합니다. [`transactionKey`](/reference#paymenttransactiondto-transactionkey) 값을 전달합니다. 많은 양의 기록을 페이지 단위로 나누어 처리할 때 사용할 수 있습니다. * **limit** 한 번에 응답받을 기록의 개수입니다. 기본값은 `100`이고 설정할 수 있는 최대값은 `5000`입니다. #### Response 응답으로 조회한 기간 동안의 일어난 모든 거래 정보가 [Transaction 객체](#transaction-객체)로 돌아옵니다. 같은 [`paymentKey`](#paymenttransactiondto-paymentkey)를 가지고 있는 거래 기록은 [`transactionKey`](#paymenttransactiondto-transactionkey)로 구분합니다. 거래 조회에 실패했다면 HTTP 상태 코드와 함께 [에러 객체](/reference/using-api/req-res#에러-객체)가 돌아옵니다. [거래 조회 API에서 발생할 수 있는 에러](/reference/error-codes#거래-조회)를 살펴보세요. ## 정산 매출에서 정산 주기, 수수료율 등에 따라 금액을 계산해 지급하는 것을 [정산](/resources/glossary/settlement)이라고 합니다. 정산 조회 API로 원하는 기간 동안의 정산 기록을 조회해 보세요. 조회된 정산 정보로 지급 받을 금액 및 날짜, 수수료 정보 등을 확인한 뒤 내 상점의 데이터와 일치하는지 확인할 수 있습니다. 이렇게 정산 기록을 비교하는 일을 '정산 대사'라고 부르기도 합니다. '대사'란 기록을 비교・대조해서 데이터를 검증하고 일치시키는 과정을 뜻합니다. ### Settlement 객체 [정산](/resources/glossary/settlement) 정보를 담고 있는 객체입니다. 지급 받을 금액 및 날짜, 수수료 정보 등을 상세히 확인할 수 있습니다. #### 객체 상세 * **mId** 상점아이디(MID)입니다. 토스페이먼츠에서 발급합니다. 최대 길이는 14자입니다. * **paymentKey** 결제의 키값입니다. 최대 길이는 200자입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 값이 유지됩니다. * **transactionKey** 거래의 키값입니다. 한 결제 건의 승인 거래와 취소 거래를 구분하는 데 사용됩니다. 최대 길이는 64자입니다. * **orderId** 주문번호입니다. 결제 요청에서 내 상점이 직접 생성한 영문 대소문자, 숫자, 특수문자 `-`, `_`로 이루어진 6자 이상 64자 이하의 문자열입니다. 각 주문을 식별하는 역할로, 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 `orderId`는 유지됩니다. * **currency** 결제할 때 사용한 통화입니다. * **method** 결제수단입니다. `카드`, `가상계좌`, `간편결제`, `휴대폰`, `계좌이체`, `문화상품권`, `도서문화상품권`, `게임문화상품권` 중 하나입니다. * **amount** 결제한 금액입니다. * **interestFee** 할부 수수료 금액입니다. * **fees** 결제 수수료의 상세 정보입니다. 수수료 상세 정보가 담긴 객체가 배열로 들어옵니다. * **type** 수수료의 세부 타입입니다. `BASE`: 기본 수수료 `INSTALLMENT_DISCOUNT`: 카드사 혹은 토스페이먼츠가 부담하는 무이자 할부 수수료 `INSTALLMENT`: 상점이 부담하는 무이자 할부 수수료 `POINT_SAVING`: 카드사 포인트 적립 수수료 `ETC`: 기타 수수료 * **fee** 수수료 금액입니다. * **supplyAmount** 결제 수수료의 공급가액입니다. * **vat** 결제 수수료 부가세입니다. * **payOutAmount** 지급 금액입니다. 결제 금액 [`amount`](/reference#paymentsettlementdto-amount)에서 수수료인 [`fee`](/reference#paymentsettlementdto-feesfee)를 제외한 금액입니다. * **approvedAt** 거래가 승인된 시점의 날짜와 시간 정보입니다. `yyyy-MM-dd'T'HH:mm:ss±hh:mm` ISO 8601 형식입니다. (e.g. `2022-01-01T00:00:00+09:00`) * **soldDate** 지급 금액의 [정산](/resources/glossary/settlement) 기준이 되는 정산 매출일입니다. 상점의 정산 주기에 따라 달라집니다. `yyyy-MM-dd` 형식입니다. (e.g. `2022-01-01`) \* [정산](/resources/glossary/settlement)에서 정산 매출일을 더 자세히 설명합니다. * **paidOutDate** 지급 금액을 상점에 지급할 [정산](/resources/glossary/settlement) 지급일입니다. 상점의 정산 기준일과 정산 주기에 따라 달라집니다. `yyyy-MM-dd` 형식입니다. (e.g. `2022-01-01`) \* [정산](/resources/glossary/settlement)에서 정산 지급일을 더 자세히 설명합니다. * **card** `nullable` [카드](/resources/glossary/card)로 결제하면 제공되는 카드 관련 정보입니다. * **amount** 카드사에 결제 요청한 금액입니다. 즉시 할인 금액(`discount.amount`)이 포함됩니다. \* 간편결제에 등록된 카드로 결제했다면 [간편결제 응답 확인 가이드](/guides/v2/easypay-response)를 참고하세요. * **issuerCode** [카드 발급사](/resources/glossary/card#카드-매입사와-발급사-이해하기) 두 자리 코드입니다. [카드사 코드](/codes/org-codes#카드사-코드)를 참고하세요. * **acquirerCode** `nullable` [카드 매입사](/resources/glossary/card#카드-매입사와-발급사-이해하기) 두 자리 코드입니다. [카드사 코드](/codes/org-codes#카드사-코드)를 참고하세요. * **number** 카드번호입니다. 번호의 일부는 마스킹 되어 있습니다. 최대 길이는 20자입니다. * **installmentPlanMonths** 할부 개월 수입니다. 일시불이면 `0`입니다. * **approveNo** 카드사 승인 번호입니다. 최대 길이는 8자입니다. * **useCardPoint** 카드사 포인트 사용 여부입니다. \* 일반 카드사 포인트가 아닌, 특수한 포인트나 바우처를 사용하면 할부 개월 수가 변경되어 응답이 돌아오니 유의해주세요. * **cardType** 카드 종류입니다. `신용`, `체크`, `기프트`, `미확인` 중 하나입니다. 구매자가 해외 카드로 결제했거나 [간편결제](/resources/glossary/easypay)의 결제 수단을 조합해서 결제했을 때 `미확인`으로 표시됩니다. * **ownerType** 카드의 소유자 타입입니다. `개인`, `법인`, `미확인` 중 하나입니다. 구매자가 해외 카드로 결제했거나 [간편결제](/resources/glossary/easypay)의 결제 수단을 조합해서 결제했을 때 `미확인`으로 표시됩니다. * **acquireStatus** [카드 결제](/resources/glossary/card-payment)의 매입 상태입니다. 아래와 같은 상태 값을 가질 수 있습니다. \- `READY`: 아직 매입 요청이 안 된 상태입니다. \- `REQUESTED`: 매입이 요청된 상태입니다. \- `COMPLETED`: 요청된 매입이 완료된 상태입니다. \- `CANCEL_REQUESTED`: 매입 취소가 요청된 상태입니다. \- `CANCELED`: 요청된 매입 취소가 완료된 상태입니다. * **isInterestFree** 무이자 할부의 적용 여부입니다. * **interestPayer** `nullable` 할부가 적용된 결제에서 할부 수수료를 부담하는 주체입니다. `BUYER`, `CARD_COMPANY`, `MERCHANT` 중 하나입니다. \- `BUYER`: 구매자가 할부 수수료를 부담합니다. 일반적인 할부 결제입니다. \- `CARD_COMPANY`: 카드사에서 할부 수수료를 부담합니다. 무이자 할부 결제입니다. \- `MERCHANT`: 상점에서 할부 수수료를 부담합니다. 무이자 할부 결제입니다. * **easyPay** `nullable` [간편결제](/resources/glossary/easypay) 정보입니다. 구매자가 선택한 결제수단에 따라 `amount`, `discountAmount`가 달라집니다. [간편결제 응답 확인 가이드](/guides/v2/easypay-response)를 참고하세요. * **provider** 선택한 [간편결제사 코드](/codes/org-codes#간편결제사-코드)입니다. * **amount** 간편결제 서비스에 등록된 계좌 혹은 현금성 포인트로 결제한 금액입니다. * **discountAmount** 간편결제 서비스의 적립 포인트나 쿠폰 등으로 즉시 할인된 금액입니다. * **giftCertificate** `nullable` [상품권](/resources/glossary/gift-certificate)으로 결제하면 제공되는 상품권 결제 관련 정보입니다. * **approveNo** 결제 승인번호입니다. 최대 길이는 8자입니다. * **settlementStatus** 정산 상태입니다. 정산이 아직 되지 않았다면 `INCOMPLETED`, 정산이 완료됐다면 `COMPLETED` 값이 들어옵니다. * **mobilePhone** `nullable` 휴대폰으로 결제하면 제공되는 [휴대폰 결제](/resources/glossary/mobile-payment) 관련 정보입니다. * **customerMobilePhone** 결제에 사용한 휴대폰 번호입니다. * **settlementStatus** 정산 상태입니다. 정산이 아직 되지 않았다면 `INCOMPLETED`, 정산이 완료됐다면 `COMPLETED` 값이 들어옵니다. * **receiptUrl** 휴대폰 결제 내역 영수증을 확인할 수 있는 주소입니다. * **transfer** `nullable` [계좌이체](/resources/glossary/transfer-payment)로 결제했을 때 이체 정보가 담기는 객체입니다. * **bankCode** 은행 두 자리 코드입니다. [은행 코드](/codes/org-codes#은행-코드)와 [증권사 코드](/codes/org-codes#증권사-코드)를 참고하세요. * **settlementStatus** 정산 상태입니다. 정산이 아직 되지 않았다면 `INCOMPLETED`, 정산이 완료됐다면 `COMPLETED` 값이 들어옵니다. * **virtualAccount** `nullable` [가상계좌](/resources/glossary/virtual-account)로 결제하면 제공되는 가상계좌 관련 정보입니다. * **accountType** 가상계좌 타입을 나타냅니다. `일반`, `고정` 중 하나입니다. * **accountNumber** 발급된 계좌번호입니다. 최대 길이는 20자입니다. * **bankCode** 가상계좌 은행 두 자리 코드입니다. [은행 코드](/codes/org-codes#은행-코드)와 [증권사 코드](/codes/org-codes#증권사-코드)를 참고하세요. * **customerName** 가상계좌를 발급한 구매자명입니다. 최대 길이는 100자입니다. * **dueDate** 입금 기한입니다. `yyyy-MM-dd'T'HH:mm:ss` ISO 8601 형식을 사용합니다. * **refundStatus** 환불 처리 상태입니다. 아래와 같은 상태 값을 가질 수 있습니다. \- `NONE`: 환불 요청이 없는 상태입니다. \- `PENDING`: 환불을 처리 중인 상태입니다. \- `FAILED`: 환불에 실패한 상태입니다. \- `PARTIAL_FAILED`: 부분 환불에 실패한 상태입니다. \- `COMPLETED`: 환불이 완료된 상태입니다. * **expired** 가상계좌의 만료 여부입니다. * **settlementStatus** 정산 상태입니다. 정산이 아직 되지 않았다면 `INCOMPLETED`, 정산이 완료됐다면 `COMPLETED` 값이 들어옵니다. * **refundReceiveAccount** 결제위젯 가상계좌 환불 정보 입력 기능으로 받은 구매자의 환불 계좌 정보입니다. 은행 코드(`bankCode`), 계좌번호(`accountNumber`), 예금주 정보(`holderName`)가 담긴 객체입니다. \* 구매자의 환불계좌 정보는 결제창을 띄운 시점부터 30분 동안만 조회할 수 있습니다. 이후에는 값이 내려가지 않습니다. 더 자세한 내용은 [결제 취소 가이드](/guides/v2/cancel-payment#case-2-결제위젯-환불-계좌-확인하기)를 참고하세요. * **cancel** `nullable` 결제 취소 이력이 담기는 객체입니다. * **cancelAmount** 결제를 취소한 금액입니다. * **cancelReason** 결제를 취소한 이유입니다. 최대 길이는 200자입니다. * **taxFreeAmount** 취소된 금액 중 면세 금액입니다. * **taxExemptionAmount** 취소된 금액 중 과세 제외 금액(컵 보증금 등)입니다. * **refundableAmount** 결제 취소 후 환불 가능한 잔액입니다. * **easyPayDiscountAmount** [간편결제](/resources/glossary/easypay) 서비스의 포인트, 쿠폰, 즉시할인과 같은 [적립식 결제수단](/guides/v2/easypay-response#간편결제-결제수단-타입)에서 취소된 금액입니다. * **canceledAt** 결제 취소가 일어난 날짜와 시간 정보입니다. `yyyy-MM-dd'T'HH:mm:ss±hh:mm` ISO 8601 형식입니다. (e.g. `2022-01-01T00:00:00+09:00`) * **transactionKey** 취소 건의 키값입니다. 여러 건의 취소 거래를 구분하는 데 사용됩니다. 최대 길이는 64자입니다. * **receiptKey** `nullable` 취소 건의 현금영수증 키값입니다. 최대 길이는 200자입니다. method: GET path: /v1/settlements ### 정산 조회 지정한 날짜 정보로 [정산](/resources/glossary/settlement) 기록을 조회합니다. 정산 기록은 결제가 일어난 다음 날부터 조회됩니다. 따라서 만약 오늘이 1월 11일이라면, 1월 11일 결제의 정산 기록은 다음 날인 1월 12일에 [`startDate`](/reference#v1settlementsget-startdate)를 `2024-01-11`로, [`endDate`](/reference#v1settlementsget-enddate)를 `2024-01-12`로 요청해서 확인할 수 있습니다. 많은 양의 정산 기록을 조회한다면 [`page`](/reference#v1settlementsget-page)와 [`size`](/reference#v1settlementsget-size) 파라미터를 사용해서 페이지 단위로 기록을 나누어 조회할 수 있습니다. 예를 들어 [`page`](/reference#v1settlementsget-page)를 3으로, [`size`](/reference#v1settlementsget-size)를 100으로 설정한다면 설정한 기간 동안의 전체 기록을 100개씩 나누어 보여주고, 전체 페이지 중 3페이지의 기록을 조회합니다. \* 정산 조회는 최대 60초가 소요됩니다. 타임아웃 값을 최소 60초로 설정하세요. 라이브 환경에서 비정상적으로 많은 요청을 보내면 `429 Too Many Requests` 상태 코드가 내려올 수 있습니다. #### Query 파라미터 * **startDate** 조회를 시작하고 싶은 날짜 정보입니다. `yyyy-MM-dd` ISO 8601 형식입니다. (e.g. `2022-01-01`) * **endDate** 조회를 마치고 싶은 날짜 정보입니다. `yyyy-MM-dd` ISO 8601 형식입니다. (e.g. `2022-01-01`) * **dateType** 조회 기준이 되는 날짜 타입입니다. `soldDate`(정산 매출일)나 `paidOutDate`(정산 지급일) 중 하나입니다. 결제 금액을 정산 받을 날짜 기준으로 조회하고 싶으면 `paidOutDate`를 사용하세요. 파라미터를 사용하지 않으면 `soldDate` 기준으로 조회됩니다. * **page** 조회할 페이지 값입니다. 최소값은 `1`입니다. 많은 양의 정산 기록을 조회할 때 `size` 파라미터와 함께 사용합니다. * **size** 한 페이지에서 응답으로 보여줄 정산 기록 개수를 의미합니다. 기본값은 `100`이고 설정할 수 있는 최대값은 `5000`입니다. 많은 양의 정산 기록을 조회할 때 `page` 파라미터와 함께 사용합니다. #### Response 정산 조회에 성공하면 [Settlement 객체](#settlement-객체)가 담긴 배열이 돌아옵니다. 정산 조회에 실패했다면 HTTP 상태 코드와 함께 [에러 객체](/reference/using-api/req-res#에러-객체)가 돌아옵니다. [정산 조회 API에서 발생할 수 있는 에러](/reference/error-codes#정산-조회)를 살펴보세요. method: POST path: /v1/settlements ### 수동 정산 요청 [수동 정산](/resources/glossary/manual-settlement)은 일정 기간 동안 쌓인 결제 기록 중에 한 건만 선택해서 정산 받는 방법입니다. \* 수동 정산 요청 API는 추가 계약 후 사용할 수 있습니다. 추가 계약을 하고 싶다면 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요. 매입하고 싶은 결제 건을 [`paymentKey`](/reference#v1settlementspost-paymentkey)로 특정해서 카드사에 정산을 요청합니다. #### Request Body 파라미터 * **paymentKey** 수동 정산을 요청할 결제 건을 특정하는 키값 입니다. 최대 길이는 200자입니다. #### Response 수동 정산 요청에 성공하면 `result` 값이 `true`로 돌아옵니다. [수동 정산 요청 API에서 발생할 수 있는 에러](/reference/error-codes#수동-정산)를 살펴보세요. ## 현금영수증 홈택스 접속 없이 토스페이먼츠에서 제공하는 현금영수증 API로 [현금영수증](/resources/glossary/cash-receipt)을 편리하게 발급해보세요. [현금영수증 가맹점](/resources/glossary/cash-receipt#현금영수증-가맹-가입-의무란)이라면 토스페이먼츠로 결제하지 않은 건도 발급 및 취소 요청을 할 수 있습니다. ### CashReceipt 객체 [현금영수증](/resources/glossary/cash-receipt) 정보를 담고 있는 객체입니다. #### 객체 상세 * **receiptKey** 발급 혹은 취소 요청한 현금영수증 한 건을 특정하는 키값입니다. 최대 길이는 200자입니다. [현금영수증 발급 API](#현금영수증-발급)로 요청한 발급 건을 취소하면 앞서 발급했던 건의 `receiptKey`에 prefix로 `c_`가 추가되어 돌아옵니다. * **issueNumber** 현금영수증 발급번호입니다. 최대 길이는 9자입니다. * **issueStatus** 현금영수증 발급 상태입니다. 발급 승인 여부는 요청 후 1-2일 뒤 조회할 수 있습니다. \- `IN_PROGRESS`: 현금영수증 발급이 대기 중인 상태입니다. \- `COMPLETED`: 현금영수증이 발급된 상태입니다. \- `FAILED`: 현금영수증 발급에 실패한 상태입니다. * **amount** 현금영수증 처리된 금액입니다. * **taxFreeAmount** 면세 처리된 금액입니다. * **orderId** 주문번호입니다. 결제 요청에서 내 상점이 직접 생성한 영문 대소문자, 숫자, 특수문자 `-`, `_`로 이루어진 6자 이상 64자 이하의 문자열입니다. 각 주문을 식별하는 역할로, 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 `orderId`는 유지됩니다. * **orderName** 구매상품입니다. 예를 들면 `생수 외 1건` 같은 형식입니다. 최대 길이는 100자입니다. * **type** 현금영수증의 종류입니다. `소득공제`, `지출증빙` 중 하나입니다. * **approvalNumber** 현금영수증 발급 승인번호입니다. 최대 길이는 9자입니다. * **transactionType** 현금영수증 발급 종류입니다. 현금영수증 발급·취소 건을 구분합니다. `CONFIRM` - 현금영수증을 발급했을 때 `CANCEL` - 발급된 현금영수증을 취소했을 때 * **businessNumber** 현금영수증을 발급한 사업자등록번호입니다. 길이는 10자입니다. * **customerIdentityNumber** 현금영수증 발급에 필요한 소비자 인증수단입니다. 현금영수증을 발급한 주체를 식별합니다. 최대 길이는 30자입니다. 현금영수증 종류에 따라 휴대폰 번호, 사업자등록번호, 현금영수증 카드 번호 등을 입력할 수 있습니다. * **failure** `nullable` 결제 실패 정보입니다. * **code** 오류 타입을 보여주는 에러 코드입니다. * **message** 에러 메시지입니다. 에러 발생 이유를 알려줍니다. 최대 길이는 510자입니다. * **requestedAt** 현금영수증 발급 혹은 취소를 요청한 날짜와 시간 정보입니다. `yyyy-MM-dd'T'HH:mm:ss±hh:mm` ISO 8601 형식입니다. * **approvedAt** 현금영수증이 발급된 날짜와 시간 정보입니다. `yyyy-MM-dd'T'HH:mm:ss±hh:mm` ISO 8601 형식입니다. (e.g. `2022-01-01T00:00:00+09:00`) * **canceledAt** `nullable` 현금영수증을 발급을 취소한 날짜와 시간 정보입니다. `yyyy-MM-dd'T'HH:mm:ss±hh:mm` ISO 8601 형식입니다. (e.g. `2022-01-01T00:00:00+09:00`) * **receiptUrl** 발행된 현금영수증을 확인할 수 있는 주소입니다. method: POST path: /v1/cash-receipts ### 현금영수증 발급 요청 [현금영수증](/resources/glossary/cash-receipt) 발급을 요청합니다. 현금영수증을 발급할 때는 현금영수증 발급 용도와 현금영수증 발급에 필요한 소비자 인증수단 정보가 반드시 필요합니다. 현금영수증 발급 용도를 [`type`](/reference#v1cash-receiptspost-type)에, 소비자 인증수단은 [`customerIdentityNumber`](/reference#v1cash-receiptspost-customeridentitynumber)에 추가해주세요. #### Request Body 파라미터 * **amount** 현금영수증을 발급할 금액입니다. * **orderId** 주문번호입니다. 주문한 결제를 식별합니다. 충분히 무작위한 값을 생성해서 각 주문마다 고유한 값을 넣어주세요. 영문 대소문자, 숫자, 특수문자 `-`, `_`로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. * **orderName** 구매상품입니다. 예를 들면 `생수 외 1건` 같은 형식입니다. 최대 길이는 100자입니다. * **type** 현금영수증의 종류입니다. `소득공제`, `지출증빙` 중 하나입니다. 소득 공제용 현금영수증을 발급받을 때는 소비자 인증수단으로 휴대폰 번호나 현금영수증 카드 번호가 필요하고, 지출 증빙용 현금영수증을 발급받을 때는 사업자 등록번호를 입력해야 합니다. * **customerIdentityNumber** 현금영수증 발급에 필요한 소비자 인증수단입니다. 현금영수증을 발급한 주체를 식별합니다. 최대 길이는 30자입니다. 현금영수증 종류에 따라 휴대폰 번호, 사업자등록번호, 현금영수증 카드 번호 등을 입력할 수 있습니다. 구매자의 정보가 없어도 상점에서 발급할 때 사용할 수 있는 국세청 지정 코드(010-000-1234)를 활용해 현금영수증을 발급할 수 있습니다. * **registrationNumber** 현금영수증 발급에 필요한 소비자 인증수단입니다. 현금영수증을 발급한 주체를 식별합니다. 최대 길이는 30자입니다. 현금영수증 종류에 따라 휴대폰 번호, 사업자등록번호, 현금영수증 카드 번호 등을 입력할 수 있습니다. 구매자의 정보가 없어도 상점에서 발급할 때 사용할 수 있는 국세청 지정 코드(010-000-1234)를 활용해 현금영수증을 발급할 수 있습니다. * **taxFreeAmount** 면세 금액입니다. 값을 넣지 않으면 기본값인 `0`으로 설정됩니다. 하나의 결제에 과세 상품과 면세 상품이 섞여있다면 이 파라미터로 면세 상품 금액을 보내주세요. 보낸 금액 만큼 현금영수증이 발급됩니다. \* 면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점에는 적용되지 않습니다. 더 자세한 내용은 [세금 처리하기](/guides/v2/learn/tax)에서 살펴보세요. #### Response 현금영수증 발급 요청에 성공하면 [CashReceipt 객체](#cashreceipt-객체)가 돌아옵니다. [CashReceipt 객체](#cashreceipt-객체)의 [`transactionType`](/reference#cashreceiptresultdto-transactiontype)으로 현금영수증 발급(`CONFIRM`)과 현금영수증 발급 취소(`CANCEL`)를 구분할 수 있습니다. [`issueStatus`](/reference#cashreceiptresultdto-issuestatus)는 요청의 상태를 나타냅니다. 응답의 최초 상태는 `IN_PROGRESS`로, 토스페이먼츠에 요청이 잘 전달되었음을 뜻합니다. 현금영수증 발급 요청에 실패했다면 HTTP 상태 코드와 함께 [에러 객체](/reference/using-api/req-res#에러-객체)가 돌아옵니다. [현금영수증 발급 요청 API에서 발생할 수 있는 에러](/reference/error-codes#현금영수증-발급-요청)를 살펴보세요. method: POST path: /v1/cash-receipts/\{receiptKey}/cancel ### 현금영수증 발급 취소 요청 현금영수증을 발급한 결제가 취소됐을 때 [`receiptKey`](/reference#v1cash-receiptsreceiptkeycancelpost-receiptkey)를 이용해서 현금영수증 발급을 취소합니다. [현금영수증 발급 API](/reference#현금영수증-발급)의 응답으로 받았던 [`CashReceipt.receiptKey`](/reference#cashreceiptresultdto-receiptkey)를 저장해 두었다가 Path 파라미터로 추가하세요. 부분 취소를 하려면 [`amount`](/reference#v1cash-receiptsreceiptkeycancelpost-amount) 값에 취소된 금액을 입력해서 사용합니다. [`amount`](/reference#v1cash-receiptsreceiptkeycancelpost-amount) 값이 없으면 전액 취소됩니다. #### Path 파라미터 * **receiptKey** 현금영수증의 키값입니다. 최대 길이는 200자입니다. #### Request Body 파라미터 * **amount** 현금영수증 발급을 취소할 금액입니다. 값이 따로 없으면 전액 취소됩니다. #### Response 현금영수증 발급 취소 요청에 성공하면 [CashReceipt 객체](#cashreceipt-객체)가 돌아옵니다. 현금영수증 발급 취소 요청에 실패했다면 HTTP 상태 코드와 함께 [에러 객체](/reference/using-api/req-res#에러-객체)가 돌아옵니다. [현금영수증 발급 취소 API에서 발생할 수 있는 에러](/reference/error-codes#현금영수증-발급-취소-요청)를 살펴보세요. method: GET path: /v1/cash-receipts ### 현금영수증 조회 특정 기간 동안 발급된 [현금영수증](/resources/glossary/cash-receipt)을 조회합니다. \* 현금영수증 조회 API는 버전 2022-07-27 이상에서만 지원합니다. API 버전은 [개발자센터](https://developers.tosspayments.com/my/api-keys)에서 확인·변경할 수 있습니다. \* 라이브 환경에서 비정상적으로 많은 요청을 보내면 `429 Too Many Requests` 상태 코드가 내려올 수 있습니다. #### Query 파라미터 * **requestDate** 현금영수증 발급이 요청된 날짜로 조회하고 싶을 때 사용합니다. `yyyy-MM-dd` ISO 8601 형식입니다. (e.g. `2022-01-01`) * **cursor** 특정 현금영수증 발급 건 이후의 기록을 조회할 때 사용합니다. 이전 조회에서 돌아온 `lastCursor` 값을 전달합니다. 많은 양의 기록을 페이지 단위로 나누어 처리할 때 사용할 수 있습니다. * **limit** 한 번에 응답받을 기록의 개수입니다. 기본값은 `100`이고 설정할 수 있는 최대값은 `10000`입니다. #### Response 현금영수증 조회에 성공하면 아래 값을 포함한 객체가 내려갑니다. * `hasNext`: 다음 기록을 조회할 수 있는지 여부입니다. 이 값이 `false`면 더 조회할 기록이 없습니다. * `lastCursor`: 특정 현금영수증 건 이후의 기록을 조회할 때 사용합니다. 다음 기록을 조회할 때 `cursor` 파라미터에 이 값을 사용합니다. 이 값은 `integer` 타입입니다. * `data`: 조회 요청에서 `cursor`로 특정한 현금영수증 건 이후의 기록입니다. [CashReceipt 객체](#cashreceipt-객체)가 담긴 배열이 돌아옵니다. 현금영수증 조회에 실패했다면 HTTP 상태 코드와 함께 [에러 객체](/reference/using-api/req-res#에러-객체)가 돌아옵니다. [현금영수증 조회 API에서 발생할 수 있는 에러](/reference/error-codes#현금영수증-조회)를 살펴보세요. ## 프로모션 프로모션 정보를 조회합니다. 구매자가 결제할 때 더욱 간편하게 혜택을 받을 수 있도록 혜택 기간, 금액 조건 등에 따라 할인 금액과 코드, 무이자 할부 혜택을 보여주세요. ### Promotions 객체 전체 프로모션 정보를 담고 있는 객체입니다. #### 객체 상세 * **payType** 결제 종류입니다. `NORMAL`, `BILLING`, `BRANDPAY` 중 하나입니다. * **type** 프로모션 종류입니다. 아래 네 가지 값 중 하나가 돌아옵니다. 상세 정보는 `type` 이름과 같은 객체에 들어있습니다. \- `CARD_DISCOUNT`: 카드 즉시 할인입니다. `cardDiscount` 객체에 관련 정보가 돌아옵니다. \- `CARD_INTEREST_FREE`: 카드 무이자 할부입니다. `cardInterestFree` 객체에 관련 정보가 돌아옵니다. \- `CARD_POINT`: 카드 포인트 할인입니다. `cardPoint` 객체에 관련 정보가 돌아옵니다. \- `BANK_DISCOUNT`: 계좌 할인입니다. `bankDiscount` 객체에 관련 정보가 돌아옵니다. * **cardDiscount** `nullable` 카드사의 즉시 할인 정보입니다. * **issuerCode** 프로모션을 진행하는 카드 발급사 두 자리 코드입니다. [카드사 코드](/codes/org-codes#카드사-코드)를 참고하세요. * **discountAmount** 할인되는 금액입니다. * **minimumPaymentAmount** 카드사 즉시 할인을 적용할 수 있는 최소 결제 금액입니다. * **maximumPaymentAmount** 카드사 즉시 할인을 적용할 수 있는 최대 결제 금액입니다. * **currency** 통화 정보입니다. * **discountCode** 프로모션 코드입니다. 카드사에서 만든 고유한 값으로 결제할 때 함께 넘겨야 하는 값입니다. * **dueDate** 프로모션을 마치는 시점입니다. `yyyy-MM-dd` 형식입니다. 종료일의 `23:59:59`까지 행사가 유효합니다. * **balance** 남은 프로모션 예산입니다. 값이 '0'이면 즉시 할인을 적용할 수 없습니다. * **cardInterestFree** `nullable` 카드 무이자 할부 정보입니다. * **issuerCode** 프로모션을 진행하는 카드 발급사 두 자리 코드입니다. [카드사 코드](/codes/org-codes#카드사-코드)를 참고하세요. * **minimumPaymentAmount** 무이자 할부를 적용할 수 있는 최소 결제 금액입니다. * **currency** 통화 정보입니다. * **dueDate** 프로모션을 마치는 시점입니다. `yyyy-MM-dd` 형식입니다. 종료일의 `23:59:59`까지 행사가 유효합니다. * **installmentFreeMonths** 카드 무이자 할부를 적용할 수 있는 개월 수입니다. * **cardPoint** `nullable` 카드 포인트 정보입니다. * **issuerCode** 프로모션을 진행하는 카드 발급사 두 자리 코드입니다. [카드사 코드](/codes/org-codes#카드사-코드)를 참고하세요. * **minimumPaymentAmount** 카드 포인트를 적용할 수 있는 최소 결제 금액입니다. * **currency** 통화 정보입니다. * **dueDate** 프로모션을 마치는 시점입니다. `yyyy-mm-dd` 형태입니다. 종료일의 `23:59:59`까지 행사가 유효합니다. * **bankDiscount** `nullable` 계좌 할인 정보입니다. * **type** 계좌 할인 종류입니다. `FIXED_AMOUNT`, `FIXED_RATE` 중 하나입니다. \- `FIXED_AMOUNT`: 금액할인 입니다. 결제 금액에서 정해진 금액을 할인해 줍니다. \- `FIXED_RATE`: 정률할인 입니다. 결제 금액에서 정해진 비율만큼 할인해 줍니다. * **bankCode** 프로모션을 진행하는 은행 두 자리 코드입니다. [은행 코드](/codes/org-codes#은행-코드)를 참고하세요. * **discountAmount** `nullable` 할인 금액입니다. * **discountRate** `nullable` 할인 비율입니다. 이 값은 0.01부터 0.3까지의 소수입니다. 이 필드는 `type`이 `FIXED_RATE`일 때만 값이 있습니다. `type`이 `FIXED_AMOUNT`일 때는 `null`입니다. * **minimumPaymentAmount** 계좌 할인을 적용할 수 있는 최소 결제 금액입니다. * **maximumPaymentAmount** 계좌 할인을 적용할 수 있는 최대 결제 금액입니다. * **currency** 통화 정보입니다. * **discountCode** 계좌 할인 프로모션 코드입니다. 은행에서 만든 고유한 값으로 결제할 때 함께 넘겨야 하는 값입니다. * **dueDate** 프로모션을 마치는 시점입니다. `yyyy-mm-dd` 형태입니다. 종료일의 `23:59:59`까지 행사가 유효합니다. ### CardPromotion 객체 할인 프로모션 정보와 할부 혜택 정보를 담고 있는 객체입니다. #### 객체 상세 * **discountCards** 카드사의 즉시 할인 정보입니다. * **issuerCode** 프로모션을 진행하는 카드 발급사 두 자리 코드입니다. [카드사 코드](/codes/org-codes#카드사-코드)를 참고하세요. * **discountAmount** 할인 금액입니다. * **balance** 남은 프로모션 예산입니다. 값이 '0'이면 즉시 할인을 적용할 수 없습니다. * **discountCode** 즉시 할인 코드(카드사 고유 번호)로 결제할 때 함께 넘겨야 하는 값입니다. * **dueDate** 프로모션을 마치는 시점입니다. `yyyy-MM-dd` 형식입니다. 종료일의 `23:59:59`까지 행사가 유효합니다. * **minimumPaymentAmount** 즉시 할인을 적용할 수 있는 최소 결제 금액입니다. * **maximumPaymentAmount** 즉시 할인을 적용할 수 있는 최대 결제 금액입니다. * **currency** 통화 정보입니다. * **interestFreeCards** 카드사의 무이자 할부 정보입니다. * **issuerCode** 카드사 두 자리 코드입니다. [카드사 코드](/codes/org-codes#카드사-코드)를 참고하세요. * **minimumPaymentAmount** 무이자 할부를 적용할 수 있는 최소 결제 금액입니다. * **dueDate** 프로모션을 마치는 시점입니다. `yyyy-MM-dd` 형식입니다. 종료일의 `23:59:59`까지 행사가 유효합니다. * **installmentFreeMonths** 무이자 할부를 적용할 수 있는 개월 수입니다. method: GET path: /v1/promotions ### 전체 프로모션 조회 전체 프로모션 정보를 조회합니다. #### Response 전체 프로모션 조회에 성공하면 [Promotions 객체](#promotions-객체)가 돌아옵니다. 전체 프로모션 조회에 실패했다면 HTTP 상태 코드와 함께 [에러 객체](/reference/using-api/req-res#에러-객체)가 돌아옵니다. method: GET path: /v1/promotions/card ### 카드 프로모션 조회 카드사별 혜택을 조회합니다. 즉시 할인, 무이자 정보가 내려갑니다. #### Response 카드사 혜택 조회에 성공하면 [CardPromotion 객체](#cardpromotion-객체)가 돌아옵니다. 카드사 혜택 조회에 실패했다면 HTTP 상태 코드와 함께 [에러 객체](/reference/using-api/req-res#에러-객체)가 돌아옵니다.