API & SDK

코어 API

토스페이먼츠 API 엔드포인트(Endpoint)와 객체 정보, 파라미터, 요청 및 응답 예제를 살펴보세요.

목차
API 키

API를 사용하기 전에 버전 정책을 확인하세요. API 응답이나 웹훅 이벤트 본문에 새로운 필드가 추가와 같이 하위 호환을 지원하는 변경 사항은 버전 릴리즈 없이 기존 API에 반영되니 유의하세요. 자세한 내용은 요청·응답 본문을 참고하세요.

결제에 관한 모든 API와 결제 API의 응답으로 돌아오는 Payment 객체, Cancel 객체를 살펴봅니다.

Payment 객체

결제 정보를 담고 있는 객체입니다. 결제 한 건의 결제 상태, 결제 취소 기록, 매출 전표, 현금영수증 정보 등을 자세히 알 수 있습니다.

결제가 승인됐을 때 응답은 Payment 객체로 항상 동일합니다. 객체의 구성은 결제수단(카드, 가상계좌, 간편결제 등)에 따라 조금씩 달라집니다.

객체 상세

  • version string

    Payment 객체의 응답 버전입니다. 버전 2022-06-08부터 날짜 기반 버저닝을 사용합니다.

  • paymentKey string

    결제의 키 값입니다. 최대 길이는 200자입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 값이 유지됩니다. 결제 승인, 결제 조회, 결제 취소 API에 사용합니다.

  • type string

    결제 타입 정보입니다. NORMAL(일반결제), BILLING(자동결제), BRANDPAY(브랜드페이) 중 하나입니다.

  • orderId string

    주문번호입니다. 결제 요청에서 가맹점이 직접 생성한 영문 대소문자, 숫자, 특수문자 -, _로 이루어진 6자 이상 64자 이하의 문자열입니다. 각 주문을 식별하는 역할로, 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 orderId는 유지됩니다.

  • orderName string

    구매상품입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.

  • mId string

    상점아이디(MID)입니다. 토스페이먼츠에서 발급합니다. 최대 길이는 14자입니다.

  • currency string

    결제할 때 사용한 통화입니다.

  • method nullable · string

    결제수단입니다. 카드, 가상계좌, 간편결제, 휴대폰, 계좌이체, 문화상품권, 도서문화상품권, 게임문화상품권 중 하나입니다.

  • totalAmount number

    총 결제 금액입니다. 결제가 취소되는 등 결제 상태가 변해도 최초에 결제된 결제 금액으로 유지됩니다.

  • balanceAmount number

    취소할 수 있는 금액(잔고)입니다. 이 값은 결제 취소나 부분 취소가 되고 나서 남은 값입니다. 결제 상태 변화에 따라 vat, suppliedAmount, taxFreeAmount, taxExemptionAmount와 함께 값이 변합니다.

  • status string

    결제 처리 상태입니다. 아래와 같은 상태 값을 가질 수 있습니다. 상태 변화 흐름이 궁금하다면 흐름도를 살펴보세요.

    - READY: 결제를 생성하면 가지게 되는 초기 상태입니다. 인증 전까지는 READY 상태를 유지합니다.

    - IN_PROGRESS: 결제수단 정보와 해당 결제수단의 소유자가 맞는지 인증을 마친 상태입니다. 결제 승인 API를 호출하면 결제가 완료됩니다.

    - WAITING_FOR_DEPOSIT: 결제 흐름에만 있는 상태입니다. 발급된 가상계좌에 구매자가 아직 입금하지 않은 상태입니다.

    - DONE: 인증된 결제수단으로 요청한 결제가 승인된 상태입니다.

    - CANCELED: 승인된 결제가 취소된 상태입니다.

    - PARTIAL_CANCELED: 승인된 결제가 부분 취소된 상태입니다.

    - ABORTED: 결제 승인이 실패한 상태입니다.

    - EXPIRED: 결제 유효 시간 30분이 지나 거래가 취소된 상태입니다. IN_PROGRESS 상태에서 결제 승인 API를 호출하지 않으면 EXPIRED가 됩니다.

  • requestedAt string

    결제가 일어난 날짜와 시간 정보입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.

    (e.g. 2022-01-01T00:00:00+09:00)

  • approvedAt nullable · string

    결제 승인이 일어난 날짜와 시간 정보입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.

    (e.g. 2022-01-01T00:00:00+09:00)

  • useEscrow boolean

    사용 여부입니다.

  • lastTransactionKey nullable · string

    마지막 거래의 키 값입니다. 한 결제 건의 승인 거래와 취소 거래를 구분하는 데 사용됩니다. 예를 들어 결제 승인 후 부분 취소를 두 번 했다면 마지막 부분 취소 거래의 키 값이 할당됩니다. 최대 길이는 64자입니다.

  • transactionKey nullable · string

    마지막 거래의 키 값입니다. 한 결제 건의 승인 거래와 취소 거래를 구분하는 데 사용됩니다. 예를 들어 결제 승인 후 부분 취소를 두 번 했다면 마지막 부분 취소 거래의 키 값이 할당됩니다. 최대 길이는 64자입니다.

  • suppliedAmount number

    공급가액입니다. 결제 취소 및 부분 취소가 되면 공급가액도 일부 취소되어 값이 바뀝니다.

  • vat number

    부가세입니다. 결제 취소 및 부분 취소가 되면 부가세도 일부 취소되어 값이 바뀝니다. (결제 금액 amount - 면세 금액 taxFreeAmount) / 11 후 소수점 첫째 자리에서 반올림해서 계산합니다.

    (e.g. 결제 금액이 10,000원이고, 면세 금액이 3,000원이라면 부가세는 (10000-3000)/11 = 636.3636..을 반올림한 값 636원입니다.)

    더 자세한 내용은 세금 처리하기에서 살펴보세요.

  • cultureExpense boolean

    문화비(도서, 공연 티켓, 박물관·미술관 입장권 등) 지출 여부입니다. , 결제에만 적용됩니다.

    * 카드 결제는 항상 false로 돌아옵니다. 카드 결제 문화비는 카드사에 문화비 소득공제 전용 가맹점번호로 등록하면 자동으로 처리됩니다.

  • taxFreeAmount number

    결제 금액 중 면세 금액입니다. 결제 취소 및 부분 취소가 되면 면세 금액도 일부 취소되어 값이 바뀝니다.

    * 일반 상점일 때는 면세 금액으로 0이 돌아옵니다. 면세 상점, 복합 과세 상점일 때만 면세 금액이 돌아옵니다. 더 자세한 내용은 세금 처리하기에서 살펴보세요.

  • taxExemptionAmount integer

    과세를 제외한 결제 금액(컵 보증금 등)입니다. 이 값은 결제 취소 및 부분 취소가 되면 과세 제외 금액도 일부 취소되어 값이 바뀝니다.

    * 과세 제외 금액이 있는 카드 결제는 부분 취소가 안 됩니다.

  • cancels nullable · array

    결제 취소 이력입니다.

    • cancelAmount number

      결제를 취소한 금액입니다.

    • cancelReason string

      결제를 취소한 이유입니다. 최대 길이는 200자입니다.

    • taxFreeAmount number

      취소된 금액 중 면세 금액입니다.

    • taxExemptionAmount integer

      취소된 금액 중 과세 제외 금액(컵 보증금 등)입니다.

    • refundableAmount number

      결제 취소 후 환불 가능한 잔액입니다.

    • easyPayDiscountAmount number

      간편결제 서비스의 포인트, 쿠폰, 즉시할인과 같은 적립식 결제수단에서 취소된 금액입니다.

    • canceledAt string

      결제 취소가 일어난 날짜와 시간 정보입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.

      (e.g. 2022-01-01T00:00:00+09:00)

    • transactionKey string

      취소 건의 키 값입니다. 여러 건의 취소 거래를 구분하는 데 사용됩니다. 최대 길이는 64자입니다.

    • receiptKey nullable · string

      취소 건의 현금영수증 키 값입니다. 최대 길이는 200자입니다.

    • cancelStatus string

      취소 상태입니다. DONE이면 결제가 성공적으로 취소된 상태입니다.

    • cancelRequestId nullable · string

      취소 요청 ID입니다. 비동기 결제에만 적용되는 특수 값입니다. 일반결제, 자동결제(빌링), 페이팔 해외결제에서는 항상 null입니다.

  • isPartialCancelable boolean

    부분 취소 가능 여부입니다. 이 값이 false이면 전액 취소만 가능합니다.

  • card nullable · object

    로 결제하면 제공되는 카드 관련 정보입니다.

    • amount number

      카드사에 결제 요청한 금액입니다. 즉시 할인 금액(discount.amount)이 포함됩니다.

      * 에 등록된 카드로 결제했다면 간편결제 응답 확인 가이드를 참고하세요.

    • issuerCode string

      두 자리 코드입니다. 카드사 코드를 참고하세요.

    • acquirerCode nullable · string

      두 자리 코드입니다. 카드사 코드를 참고하세요.

    • number string

      카드번호입니다. 번호의 일부는 마스킹 되어 있습니다. 최대 길이는 20자입니다.

    • installmentPlanMonths integer

      할부 개월 수입니다. 일시불이면 0입니다.

    • approveNo string

      카드사 승인 번호입니다. 최대 길이는 8자입니다.

    • useCardPoint boolean

      카드사 포인트 사용 여부입니다.

      * 일반 카드사 포인트가 아닌, 특수한 포인트나 바우처를 사용하면 할부 개월 수가 변경되어 응답이 돌아오니 유의해주세요.

    • cardType string

      카드 종류입니다. 신용, 체크, 기프트, 미확인 중 하나입니다. 구매자가 해외 카드로 결제했거나 의 결제 수단을 조합해서 결제했을 때 미확인으로 표시됩니다.

    • ownerType string

      카드의 소유자 타입입니다. 개인, 법인, 미확인 중 하나입니다. 구매자가 해외 카드로 결제했거나 의 결제 수단을 조합해서 결제했을 때 미확인으로 표시됩니다.

    • acquireStatus string

      의 매입 상태입니다. 아래와 같은 상태 값을 가질 수 있습니다.

      - READY: 아직 매입 요청이 안 된 상태입니다.

      - REQUESTED: 매입이 요청된 상태입니다.

      - COMPLETED: 요청된 매입이 완료된 상태입니다.

      - CANCEL_REQUESTED: 매입 취소가 요청된 상태입니다.

      - CANCELED: 요청된 매입 취소가 완료된 상태입니다.

    • isInterestFree boolean

      무이자 할부의 적용 여부입니다.

    • interestPayer nullable · string

      할부가 적용된 결제에서 할부 수수료를 부담하는 주체입니다. BUYER, CARD_COMPANY, MERCHANT 중 하나입니다.

      - BUYER: 상품을 구매한 구매자가 할부 수수료를 부담합니다. 일반적인 할부 결제입니다.

      - CARD_COMPANY: 카드사에서 할부 수수료를 부담합니다. 무이자 할부 결제입니다.

      - MERCHANT: 상점에서 할부 수수료를 부담합니다. 무이자 할부 결제입니다.

  • virtualAccount nullable · object

    로 결제하면 제공되는 가상계좌 관련 정보입니다.

    • accountType string

      가상계좌 타입을 나타냅니다. 일반, 고정 중 하나입니다.

    • accountNumber string

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

    • bankCode string

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

    • customerName string

      가상계좌를 발급한 구매자명입니다. 최대 길이는 100자입니다.

    • dueDate string

      입금 기한입니다. yyyy-MM-dd'T'HH:mm:ss ISO 8601 형식을 사용합니다.

    • refundStatus string

      환불 처리 상태입니다. 아래와 같은 상태 값을 가질 수 있습니다.

      - NONE: 환불 요청이 없는 상태입니다.

      - PENDING: 환불을 처리 중인 상태입니다.

      - FAILED: 환불에 실패한 상태입니다.

      - PARTIAL_FAILED: 부분 환불에 실패한 상태입니다.

      - COMPLETED: 환불이 완료된 상태입니다.

    • expired boolean

      가상계좌의 만료 여부입니다.

    • settlementStatus string

      정산 상태입니다. 정산이 아직 되지 않았다면 INCOMPLETED, 정산이 완료됐다면 COMPLETED 값이 들어옵니다.

    • refundReceiveAccount nullable · object

      결제위젯 가상계좌 환불 정보 입력 기능으로 받은 구매자의 환불 계좌 정보입니다. 은행 코드(bankCode), 계좌번호(accountNumber), 예금주 정보(holderName)가 담긴 객체입니다.

      * 구매자의 환불계좌 정보는 결제창을 띄운 시점부터 30분 동안만 조회할 수 있습니다. 이후에는 값이 내려가지 않습니다. 더 자세한 내용은 결제 취소 가이드를 참고하세요.

  • secret nullable · string

    웹훅을 검증하는 최대 50자 값입니다. 가상계좌 웹훅 이벤트 본문으로 돌아온 secret과 같으면 정상적인 웹훅입니다. 결제 상태 웹훅 이벤트로 돌아오는 Payment 객체의 secret과 같으면 정상적인 웹훅입니다.

  • mobilePhone nullable · object

    휴대폰으로 결제하면 제공되는 관련 정보입니다.

    • customerMobilePhone string

      구매자가 결제에 사용한 휴대폰 번호입니다. - 없이 숫자로만 구성된 최소 8자, 최대 15자의 문자열입니다.

    • settlementStatus string

      정산 상태입니다. 정산이 아직 되지 않았다면 INCOMPLETED, 정산이 완료됐다면 COMPLETED 값이 들어옵니다.

    • receiptUrl string

      휴대폰 결제 내역 영수증을 확인할 수 있는 주소입니다.

  • giftCertificate nullable · object

    으로 결제하면 제공되는 상품권 결제 관련 정보입니다.

    • approveNo string

      결제 승인번호입니다. 최대 길이는 8자입니다.

    • settlementStatus string

      정산 상태입니다. 정산이 아직 되지 않았다면 INCOMPLETED, 정산이 완료됐다면 COMPLETED 값이 들어옵니다.

  • transfer nullable · object

    로 결제했을 때 이체 정보가 담기는 객체입니다.

    • bankCode string

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

    • settlementStatus string

      정산 상태입니다. 정산이 아직 되지 않았다면 INCOMPLETED, 정산이 완료됐다면 COMPLETED 값이 들어옵니다.

  • metadata object

    결제 요청 시 직접 추가할 수 있는 결제 관련 정보입니다. 최대 5개의 키-값(key-value) 쌍입니다. 키는 [ , ] 를 사용하지 않는 최대 40자의 문자열, 값은 최대 500자의 문자열입니다.

  • receipt nullable · object

    발행된 영수증 정보입니다.

    • url string

      구매자에게 제공할 수 있는 결제수단별 영수증입니다. 카드 결제는 , 가상계좌는 무통장 거래 명세서, 계좌이체・휴대폰・상품권 결제는 결제 거래 내역 확인서가 제공됩니다.

  • checkout nullable · object

    결제창 정보입니다.

    • url string

      결제창이 열리는 주소입니다.

  • easyPay nullable · object

    정보입니다. 구매자가 선택한 결제수단에 따라 amount, discountAmount가 달라집니다. 간편결제 응답 확인 가이드를 참고하세요.

    • provider string

      선택한 간편결제사 코드입니다.

    • amount number

      간편결제 서비스에 등록된 계좌 혹은 현금성 포인트로 결제한 금액입니다.

    • discountAmount number

      간편결제 서비스의 적립 포인트나 쿠폰 등으로 즉시 할인된 금액입니다.

  • easyPayAmount nullable · number

    에 등록되어 있는 계좌로 결제한 금액입니다.

  • easyPayDiscountAmount nullable · number

    서비스의 포인트로 결제한 금액입니다.

  • country string

    결제한 국가입니다. ISO-3166의 두 자리 국가 코드 형식입니다.

  • failure nullable · object

    결제 승인에 실패하면 응답으로 받는 에러 객체입니다. 실패한 결제를 조회할 때 확인할 수 있습니다.

    • code string

      오류 타입을 보여주는 에러 코드입니다.

    • message string

      에러 메시지입니다. 에러 발생 이유를 알려줍니다. 최대 길이는 510자입니다.

  • cashReceipt nullable · object

    정보입니다.

    • type string

      현금영수증의 종류입니다. 소득공제, 지출증빙 중 하나입니다.

    • receiptKey string

      현금영수증의 키 값입니다. 최대 길이는 200자입니다.

    • issueNumber string

      현금영수증 발급 번호입니다. 최대 길이는 9자입니다.

    • receiptUrl string

      발행된 현금영수증을 확인할 수 있는 주소입니다.

    • amount number

      현금영수증 처리된 금액입니다.

    • taxFreeAmount number

      면세 처리된 금액입니다.

  • cashReceipts nullable · array

    발행 및 취소 이력이 담기는 배열입니다. 순서는 보장되지 않습니다. 예를 들어 결제 후 부분 취소가 여러 번 일어나면 모든 결제 및 부분 취소 건에 대한 현금영수증 정보를 담고 있습니다.

    계좌이체는 결제 즉시 현금영수증 정보를 확인할 수 있습니다. 는 구매자가 입금을 완료하면 현금영수증 정보를 확인할 수 있습니다.

    * 결제가 이미 승인된 후 현금영수증 발급 요청 API로 발급한 현금영수증은 먼저 처리된 결제 정보와 연결되지 않아 값이 null입니다. 현금영수증 조회 API로 조회해주세요.

    * 이라면 결제했을 때 바로 발급됩니다. 발급을 원하지 않는다면 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.

    • receiptKey string

      현금영수증의 키 값입니다. 최대 길이는 200자입니다.

    • orderId string

      주문번호입니다. 결제 요청에서 가맹점이 직접 생성한 영문 대소문자, 숫자, 특수문자 -, _로 이루어진 6자 이상 64자 이하의 문자열입니다. 각 주문을 식별하는 역할로, 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 orderId는 유지됩니다.

    • orderName string

      구매상품입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.

    • type string

      현금영수증의 종류입니다. 소득공제, 지출증빙 중 하나입니다.

    • issueNumber string

      현금영수증 발급 번호입니다. 최대 길이는 9자입니다.

    • receiptUrl string

      발행된 현금영수증을 확인할 수 있는 주소입니다.

    • businessNumber string

      현금영수증을 발급한 사업자등록번호입니다. 길이는 10자입니다.

    • transactionType string

      현금영수증 발급 종류입니다. 현금영수증 발급(CONFIRM)·취소(CANCEL) 건을 구분합니다.

    • amount integer

      현금영수증 처리된 금액입니다.

    • taxFreeAmount integer

      면세 처리된 금액입니다.

    • issueStatus string

      현금영수증 발급 상태입니다. 발급 승인 여부는 요청 후 1-2일 뒤 조회할 수 있습니다. IN_PROGRESS, COMPLETED, FAILED 중 하나입니다. 각 상태의 자세한 설명은 CashReceipt 객체에서 확인할 수 있습니다.

    • failure object

      결제 실패 객체입니다. 오류 타입을 보여주는 code와 에러 메시지를 보여주는 message 필드가 있습니다.

    • customerIdentityNumber string

      현금영수증 발급에 필요한 소비자 인증수단입니다. 현금영수증을 발급한 주체를 식별합니다. 최대 길이는 30자입니다. 현금영수증 종류에 따라 휴대폰 번호, 사업자등록번호, 현금영수증 카드 번호 등을 입력할 수 있습니다.

    • requestedAt string

      현금영수증 발급 혹은 취소를 요청한 날짜와 시간 정보입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다. (e.g. 2022-01-01T00:00:00+09:00)

  • discount nullable · object

    카드사 및 퀵계좌이체의 즉시 할인 프로모션 정보입니다. 즉시 할인 프로모션이 적용됐을 때만 생성됩니다.

    • amount integer

      카드사 및 퀵계좌이체의 즉시 할인 프로모션을 적용한 결제 금액입니다.

결제 승인

POST /v1/payments/confirm

paymentKey에 해당하는 결제를 검증하고 승인합니다. 결제 인증이 유효한 10분 안에 상점에서 결제 승인 API를 호출하지 않으면 해당 결제는 만료됩니다.

API 직접 실행해보기

Request Body 파라미터

  • paymentKey 필수 · string

    결제의 키 값입니다. 최대 길이는 200자입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다.

  • orderId 필수 · string

    주문번호입니다. 주문한 결제를 식별합니다. 충분히 무작위한 값을 생성해서 각 주문마다 고유한 값을 넣어주세요. 영문 대소문자, 숫자, 특수문자 -, _로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다.

  • amount 필수 · number

    결제할 금액입니다.

Response

성공

결제 승인에 성공하면 Payment 객체가 돌아옵니다. 사용한 결제수단 필드에 값이 제대로 들어왔는지 확인하세요.

실패

결제 승인에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

결제 승인 API에서 발생할 수 있는 에러를 살펴보세요.

paymentKey로 결제 조회

GET /v1/payments/{paymentKey}

승인된 결제를 paymentKey로 조회합니다. paymentKey는 SDK를 사용해 결제할 때 발급되는 고유한 키 값으로 결제가 최종 승인된 후 돌아오는 Payment 객체에 담겨있습니다.

API 직접 실행해보기

Path 파라미터

  • paymentKey 필수 · string

    결제의 키 값입니다. 최대 길이는 200자입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다.

Response

성공

결제 조회에 성공하면 Payment 객체가 돌아옵니다. 사용한 결제수단 필드에 값이 제대로 들어왔는지 확인하세요.

실패

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

결제 조회 API에서 발생할 수 있는 에러를 살펴보세요.

orderId로 결제 조회

GET /v1/payments/orders/{orderId}

승인된 결제를 orderId로 조회합니다. orderId는 SDK로 결제를 요청할 때 가맹점에서 만들어서 사용한 값입니다.

API 직접 실행해보기

Path 파라미터

  • orderId 필수 · string

    주문번호입니다. 주문한 결제를 식별합니다. 충분히 무작위한 값을 생성해서 각 주문마다 고유한 값을 넣어주세요. 영문 대소문자, 숫자, 특수문자 -, _로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다.

Response

성공

결제 조회에 성공하면 Payment 객체가 돌아옵니다. 사용한 결제수단 필드에 값이 제대로 들어왔는지 확인하세요.

실패

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

결제 조회 API에서 발생할 수 있는 에러를 살펴보세요.

결제 취소

POST /v1/payments/{paymentKey}/cancel

승인된 결제를 paymentKey로 취소합니다. 취소 이유를 cancelReason에 추가해야 합니다.

결제 금액의 일부만 부분 취소하려면 cancelAmount에 취소할 금액을 추가해서 API를 요청합니다. cancelAmount에 값을 넣지 않으면 전액 취소됩니다.

* 멱등키를 요청 헤더에 추가하면 중복 취소 없이 안전하게 처리됩니다.

API 직접 실행해보기

Path 파라미터

  • paymentKey 필수 · string

    결제의 키 값입니다. 최대 길이는 200자입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다.

Request Body 파라미터

  • cancelReason 필수 · string

    결제를 취소하는 이유입니다. 최대 길이는 200자입니다.

  • cancelAmount number

    취소할 금액입니다. 값이 없으면 전액 취소됩니다.

  • refundReceiveAccount object

    결제 취소 후 금액이 환불될 계좌의 정보입니다. 결제에만 필수입니다. 다른 결제수단으로 이루어진 결제를 취소할 때는 사용하지 않습니다. 보낸 계좌 정보는 유효성 검사가 이뤄집니다. 유효한 계좌로 결제 취소 요청이 되었다면 환불은 취소 요청 후 2일 후에 진행됩니다. 구매자가 가상계좌에 입금을 아직 안 했다면, 결제를 취소해도 환불해야 되는 금액이 없기 때문에 이 파라미터를 추가할 필요가 없습니다. 입금 전에는 부분 취소를 할 수 없고 전체 금액 취소만 할 수 있습니다.

    • bank 필수 · string

      취소 금액을 환불받을 계좌의 은행 코드입니다. 은행 코드증권사 코드를 참고하세요.

    • accountNumber 필수 · string

      취소 금액을 환불받을 계좌의 계좌번호입니다. - 없이 숫자만 넣어야 합니다. 최대 길이는 20자입니다.

    • holderName 필수 · string

      취소 금액을 환불받을 계좌의 예금주입니다. 최대 길이는 60자입니다.

  • taxFreeAmount number

    취소할 금액 중 면세 금액입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다.

    * 면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점에는 적용되지 않습니다. 더 자세한 내용은 세금 처리하기에서 살펴보세요.

  • currency string

    취소 통화입니다. PayPal 해외간편결제 부분 취소에는 필수 값입니다. PayPal에서 사용할 수 있는 통화는 USD입니다.

  • refundableAmount number

    현재 환불 가능한 금액입니다. 결제 취소를 안전하게 처리합니다.

    환불 가능한 잔액 정보가 refundableAmount의 값과 다르면 취소를 처리하지 않고 에러를 내보냅니다.

    * 이 파라미터는 더 이상 사용을 권장하지 않습니다. 안전하게 취소하려면 멱등키를 대신 사용해주세요.

Response

성공

결제 취소에 성공하면 Payment 객체cancels 필드에 취소 객체가 배열로 돌아옵니다.

부분 취소를 여러 번 하면 아래와 같이 Payment.cancels 필드에 취소 객체가 여러 개 돌아옵니다. 각 취소 거래마다 거래를 구분하는 transactionKey를 가지고 있습니다.

실패

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

결제 취소 API에서 발생할 수 있는 에러를 살펴보세요.

가상계좌 발급 요청

POST /v1/virtual-accounts

구매자가 원하는 은행의 발급을 요청합니다.

API 직접 실행해보기

Request Body 파라미터

  • amount 필수 · integer

    결제할 금액입니다.

  • orderId 필수 · string

    주문번호입니다. 주문한 결제를 식별합니다. 충분히 무작위한 값을 생성해서 각 주문마다 고유한 값을 넣어주세요. 영문 대소문자, 숫자, 특수문자 -, _로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다.

  • orderName 필수 · string

    구매상품입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다. 최소 1글자 이상 100글자 이하여야 합니다.

  • customerName 필수 · string

    입금할 구매자명입니다. 최대 길이는 100자입니다.

  • bank 필수 · string

    가상계좌를 발급할 은행입니다. 가상계좌 발급이 가능한 은행을 참고하세요.

  • validHours integer

    가상계좌 발급 시점으로부터 가상계좌가 유효한 시간입니다. 설정한 validHours 안에 구매자가 입금을 하지 않으면 주문은 취소됩니다. 설정할 수 있는 최대값은 2160시간(90일)입니다.

    예를 들어 가상계좌 발급 후 24시간 내에 입금해야 한다면 24로 설정합니다. 값을 넣지 않으면 기본값 168시간(7일)으로 설정됩니다.

    validHoursdueDate 중 하나만 사용할 수 있습니다.

  • dueDate string

    가상계좌 입금 기한입니다. dueDate이 지난 시점에 입금을 시도하면 실패합니다. 티켓 예매 등 주문 시간과 상관없이 정해진 시점까지 결제를 받아야 할 때도 사용할 수 있습니다. 설정할 수 있는 최대값은 결제 요청일로부터 90일입니다. yyyy-MM-dd'T'HH:mm:ss ISO 8601 형식을 사용합니다.

    예를 들어 입금 기한을 '2023년 10월 10일 자정'과 같이 특정 시점으로 설정하고 싶을 때 2023-10-10T00:00:00과 같이 사용하세요.

    validHoursdueDate 중 하나만 사용할 수 있습니다.

  • customerEmail string

    구매자의 이메일 주소입니다. 결제 상태가 바뀌면 이메일 주소로 결제내역이 전송됩니다. 최대 길이는 100자입니다.

  • customerMobilePhone string

    구매자의 휴대폰 번호입니다. 가상계좌 입금 안내가 전송되는 번호입니다. - 없이 숫자로만 구성된 최소 8자, 최대 15자의 문자열입니다.

  • taxFreeAmount integer

    면세 금액입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다.

    * 면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점에는 적용되지 않습니다. 더 자세한 내용은 세금 처리하기에서 살펴보세요.

  • useEscrow boolean

    사용 여부입니다. 값을 넣지 않으면 기본값인 false로 설정되고 사용자가 에스크로 결제 여부를 선택합니다.

  • cashReceipt object

    현금영수증 발급 정보를 담는 객체입니다.

    • type string

      현금영수증 발급 용도입니다. 소득공제, 지출증빙, 미발행 중 하나입니다.

    • registrationNumber string

      현금영수증 발급에 필요한 개인 식별 번호입니다. 최대 길이는 30자입니다. 현금영수증 종류에 따라 휴대폰 번호, 사업자등록번호, 현금영수증 카드 번호 등을 입력할 수 있습니다.

  • escrowProducts array

    각 상품의 상세 정보를 담는 배열입니다. 예를 들어 사용자가 세 가지 종류의 상품을 구매했다면 길이가 3인 배열이어야 합니다. 에스크로 결제를 사용할 때만 필요한 파라미터입니다.

    • id 필수 · string

      상품의 ID입니다. 이 값은 유니크해야 합니다.

    • name 필수 · string

      상품 이름입니다.

    • code 필수 · string

      상점에서 사용하는 상품 관리 코드입니다.

    • unitPrice 필수 · integer

      상품의 가격입니다. 전체를 합한 가격이 아닌 상품의 개당 가격입니다.

    • quantity 필수 · integer

      상품 구매 수량입니다.

Response

성공

가상계좌 발급 요청에 성공하면 virtualAccount 필드에 값이 있는 Payment 객체가 돌아옵니다.

실패

가상계좌 발급 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

가상계좌 발급 요청 API에서 발생할 수 있는 에러를 살펴보세요.

자동결제

자동결제 API로 구매자의 결제수단 정보를 인증·등록한 뒤 정기 배송, 음악 스트리밍과 같은 구독형 서비스에서 사용할 수 있습니다.

* 정기 구독형 서비스가 아니라면 자동결제 사용이 제한되니 유의하세요. 더 궁금한 점이 있다면 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.

Billing 객체

에 사용할 결제수단이 인증되어 등록되었을 때 돌아오는 객체입니다.

등록된 카드 정보와 발급된 billingKey가 포함되어 있습니다. billingKey로 자동결제 요청 API를 호출할 수 있습니다.

객체 상세

  • mId string

    상점아이디(MID)입니다. 토스페이먼츠에서 발급합니다. 최대 길이는 14자입니다.

  • customerKey string

    구매자 ID입니다. 빌링키와 연결됩니다. 다른 사용자가 이 값을 알게 되면 악의적으로 사용될 수 있습니다. 자동 증가하는 숫자 또는 이메일・전화번호・사용자 아이디와 같이 유추가 가능한 값은 안전하지 않습니다. 와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 영문 대소문자, 숫자, 특수문자 -, _, =, ., @ 를 최소 1개 이상 포함한 최소 2자 이상 최대 300자 이하의 문자열이어야 합니다.

    * customerKey클라이언트 키와 다릅니다. 클라이언트 키는 연동을 위한 기본 키로 브라우저에서 SDK를 연동할 때 '클라이언트'를 식별하며, 토스페이먼츠에서 제공합니다.

  • authenticatedAt string

    결제수단이 인증된 시점의 날짜와 시간 정보입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다. (e.g. 2022-01-01T00:00:00+09:00)

  • method string

    결제수단입니다. 현재 자동결제는 카드만 지원하기 때문에 카드로 값이 고정되어 돌아옵니다.

  • billingKey string

    자동결제에서 카드 정보 대신 사용되는 값입니다. customerKey와 연결됩니다. 최대 길이는 200자입니다.

  • card object

    발급된 빌링키와 연결된 카드 정보입니다.

    • issuerCode string

      두 자리 코드입니다. 카드사 코드를 참고하세요.

    • acquirerCode string

      두 자리 코드입니다. 카드사 코드를 참고하세요.

    • number string

      카드 번호입니다. 번호의 일부는 마스킹 되어 있습니다. 최대 길이는 20자입니다.

    • cardType string

      카드 종류입니다. 신용, 체크, 기프트 중 하나입니다.

    • ownerType string

      카드의 소유자 타입입니다. 개인, 법인 중 하나입니다.

  • cardCompany string

    카드 발급사입니다. 카드사 코드를 참고하세요.

  • cardNumber string

    카드 번호입니다. 번호의 일부는 마스킹 되어 있습니다. 최대 길이는 20자입니다.

customerKey로 카드 빌링키 발급

* 빌링키 발급 API는 신규 계약을 받지 않는 서비스입니다. 자세한 내용은 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.

POST /v1/billing/authorizations/card

구매자를 특정하는 customerKey와 연결할 빌링키 발급을 요청합니다.

API 직접 실행해보기

Request Body 파라미터

  • customerKey 필수 · string

    구매자 ID입니다. 빌링키와 연결됩니다. 다른 사용자가 이 값을 알게 되면 악의적으로 사용될 수 있습니다. 자동 증가하는 숫자 또는 이메일・전화번호・사용자 아이디와 같이 유추가 가능한 값은 안전하지 않습니다. 와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 영문 대소문자, 숫자, 특수문자 -, _, =, ., @ 를 최소 1개 이상 포함한 최소 2자 이상 최대 300자 이하의 문자열이어야 합니다.

    * customerKey클라이언트 키와 다릅니다. 클라이언트 키는 연동을 위한 기본 키로 브라우저에서 SDK를 연동할 때 '클라이언트'를 식별하며, 토스페이먼츠에서 제공합니다.

  • cardNumber 필수 · string

    카드 번호입니다. 최대 길이는 20자입니다.

  • cardExpirationYear 필수 · string

    카드 유효 연도입니다.

  • cardExpirationMonth 필수 · string

    카드 유효 월입니다.

  • customerIdentityNumber 필수 · string

    카드 소유자 정보입니다. 생년월일 6자리(YYMMDD) 혹은 사업자등록번호 10자리가 들어갑니다.

  • cardPassword object

    카드 비밀번호 앞 두 자리입니다.

  • customerName string

    구매자명입니다. 최대 길이는 100자입니다.

  • customerEmail string

    구매자의 이메일 주소입니다. 결제 상태가 바뀌면 이메일 주소로 결제내역이 전송됩니다. 최대 길이는 100자입니다.

  • vbv object

    해외 카드 결제의 3DS 인증에 사용합니다. 3DS 인증 결과를 전송해야 되면 필수입니다.

    • cavv object

      3D Secure 인증 세션의 인증 값입니다.

    • xid object

      트랜잭션 ID입니다.

    • eci object

      3DS 인증 결과의 코드 값입니다.

Response

성공

customerKey로 카드 자동결제 요청에 성공하면 Billing 객체가 돌아옵니다.

실패

customerKey로 카드 자동결제 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

카드 자동결제 빌링키 발급 요청 API에서 발생 가능한 에러를 살펴보세요.

authKey로 카드 빌링키 발급

* 빌링키 발급 API는 신규 계약을 받지 않는 서비스입니다. 자세한 내용은 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.

POST /v1/billing/authorizations/issue

requestBillingAuth 호출 후 쿼리 파라미터로 돌아오는 authKey, 구매자 ID인 customerKey로 빌링키 발급을 요청합니다.

API 직접 실행해보기

Request Body 파라미터

  • authKey 필수 · string

    자동결제 등록창 호출이 성공하면 리다이렉트 URL에 쿼리 파라미터(Query Parameter)로 돌아오는 일회성 인증 키입니다. 최대 길이는 300자입니다.

  • customerKey 필수 · string

    구매자 ID입니다. 빌링키와 연결됩니다. 다른 사용자가 이 값을 알게 되면 악의적으로 사용될 수 있습니다. 자동 증가하는 숫자 또는 이메일・전화번호・사용자 아이디와 같이 유추가 가능한 값은 안전하지 않습니다. 와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 영문 대소문자, 숫자, 특수문자 -, _, =, ., @ 를 최소 1개 이상 포함한 최소 2자 이상 최대 300자 이하의 문자열이어야 합니다.

    * customerKey클라이언트 키와 다릅니다. 클라이언트 키는 연동을 위한 기본 키로 브라우저에서 SDK를 연동할 때 '클라이언트'를 식별하며, 토스페이먼츠에서 제공합니다.

Response

성공

카드 자동결제 빌링키 발급 요청에 성공하면 Billing 객체가 돌아옵니다.

실패

카드 자동결제 빌링키 발급 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

카드 자동결제 빌링키 발급 요청 API에서 발생 가능한 에러를 살펴보세요.

카드 자동결제 승인

* 자동결제 API는 추가 계약 후 사용할 수 있습니다. 추가 계약을 하고 싶다면 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.

POST /v1/billing/{billingKey}

발급받은 billingKey로 카드 자동결제를 승인합니다. 카드 자동결제 승인은 최대 30초가 소요됩니다. 타임아웃 값을 최소 30초로 설정하세요.

API 직접 실행해보기

Path 파라미터

  • billingKey 필수 · string

    발급된 빌링키 정보입니다. 구매자의 결제 정보로 사용됩니다.

Request Body 파라미터

  • amount 필수 · integer

    결제할 금액입니다.

  • customerKey 필수 · string

    구매자 ID입니다. 빌링키와 연결됩니다. 다른 사용자가 이 값을 알게 되면 악의적으로 사용될 수 있습니다. 자동 증가하는 숫자 또는 이메일・전화번호・사용자 아이디와 같이 유추가 가능한 값은 안전하지 않습니다. 와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 영문 대소문자, 숫자, 특수문자 -, _, =, ., @ 를 최소 1개 이상 포함한 최소 2자 이상 최대 300자 이하의 문자열이어야 합니다.

  • orderId 필수 · string

    주문번호입니다. 주문한 결제를 식별합니다. 충분히 무작위한 값을 생성해서 각 주문마다 고유한 값을 넣어주세요. 영문 대소문자, 숫자, 특수문자 -, _로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다.

  • orderName 필수 · string

    구매상품입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.

  • cardInstallmentPlan integer

    신용 카드의 할부 개월 수입니다. 값을 넣으면 해당 할부 개월 수로 결제가 진행됩니다. 2부터 12사이의 값을 사용할 수 있고, 0이 들어가거나 값을 넣지 않으면 할부가 아닌 일시불로 결제됩니다.

  • customerEmail string

    구매자의 이메일 주소입니다. 결제 상태가 바뀌면 이메일 주소로 결제내역이 전송됩니다. 최대 길이는 100자입니다.

  • customerName string

    구매자명입니다. 최대 길이는 100자입니다.

  • taxFreeAmount integer

    면세 금액입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다.

    * 면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점에는 적용되지 않습니다. 더 자세한 내용은 세금 처리하기에서 살펴보세요.

  • taxExemptionAmount integer

    과세를 제외한 결제 금액(컵 보증금 등)입니다.

    * 과세 제외 금액이 있는 카드 결제는 부분 취소가 안 됩니다.

Response

성공

카드 자동결제 승인에 성공하면 card 필드에 값이 있는 Payment 객체가 돌아옵니다.

실패

카드 자동결제 승인에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

카드 자동결제 승인 API에서 발생 가능한 에러를 살펴보세요.

거래

결제 한 건에서 발생하는 승인과 취소 각각이 입니다. 특정 기간에 일어난 모든 결제 승인 및 취소의 요약이 필요할 때 거래 조회 API를 사용하세요.

거래 기록을 비교하는 일을 '거래 대사'라고 부르기도 합니다. '대사'란 기록을 비교・대조해서 데이터를 검증하고 일치시키는 과정을 뜻합니다.

Transaction 객체

정보를 담고 있는 객체입니다.

하나의 결제 건에 여러 번의 거래가 일어날 수 있습니다. 결제 승인, 취소, 부분 취소가 이루어질 때마다 각각의 거래 정보를 담은 Transaction 객체가 만들어지고 개별 transactionKey를 가지게 됩니다.

거래 조회 API를 호출하면 지정한 기간 동안 생긴 모든 Transaction 객체들이 배열로 돌아옵니다.

객체 상세

  • mId string

    상점아이디(MID)입니다. 토스페이먼츠에서 발급합니다. 최대 길이는 14자입니다.

  • transactionKey string

    거래의 키 값입니다. 한 결제 건의 승인 거래와 취소 거래를 구분하는 데 사용됩니다. 최대 길이는 64자입니다.

  • paymentKey string

    결제의 키 값입니다. 최대 길이는 200자입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 값이 유지됩니다.

  • orderId string

    주문번호입니다. 최소 길이는 6자, 최대 길이는 64자입니다. 주문한 결제를 식별하는 역할로, 결제를 요청할 때 가맹점에서 만들어서 사용합니다. 결제 상태가 변해도 값이 유지됩니다.

  • method string

    결제수단입니다. 카드, 가상계좌, 간편결제, 휴대폰, 계좌이체, 문화상품권, 도서문화상품권, 게임문화상품권 중 하나입니다.

  • customerKey string

    구매자 ID입니다. 빌링키와 연결됩니다. 다른 사용자가 이 값을 알게 되면 악의적으로 사용될 수 있습니다. 자동 증가하는 숫자 또는 이메일・전화번호・사용자 아이디와 같이 유추가 가능한 값은 안전하지 않습니다. 와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 영문 대소문자, 숫자, 특수문자 -, _, =, ., @ 를 최소 1개 이상 포함한 최소 2자 이상 최대 300자 이하의 문자열이어야 합니다.

    * customerKey클라이언트 키와 다릅니다. 클라이언트 키는 연동을 위한 기본 키로 브라우저에서 SDK를 연동할 때 '클라이언트'를 식별하며, 토스페이먼츠에서 제공합니다.

  • useEscrow boolean

    사용 여부입니다.

  • receiptUrl string

    거래 영수증을 확인할 수 있는 주소입니다.

  • status string

    결제 처리 상태입니다. 아래와 같은 상태 값을 가질 수 있습니다. 상태 변화 흐름이 궁금하다면 흐름도를 살펴보세요.

    - READY: 결제를 생성하면 가지게 되는 초기 상태입니다. 인증 전까지는 READY 상태를 유지합니다.

    - IN_PROGRESS: 결제수단 정보와 해당 결제수단의 소유자가 맞는지 인증을 마친 상태입니다. 결제 승인 API를 호출하면 결제가 완료됩니다.

    - WAITING_FOR_DEPOSIT: 결제 흐름에만 있는 상태입니다. 발급된 가상계좌에 구매자가 아직 입금하지 않은 상태입니다.

    - DONE: 인증된 결제수단으로 요청한 결제가 승인된 상태입니다.

    - CANCELED: 승인된 결제가 취소된 상태입니다.

    - PARTIAL_CANCELED: 승인된 결제가 부분 취소된 상태입니다.

    - ABORTED: 결제 승인에 실패한 상태입니다.

    - EXPIRED: 요청된 결제의 유효 시간 30분이 지나 거래가 취소된 상태입니다. IN_PROGRESS 상태에서 결제 승인 API를 호출하지 않으면 EXPIRED가 됩니다.

  • transactionAt string

    거래가 처리된 시점의 날짜와 시간 정보입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.

  • currency string

    결제할 때 사용한 통화입니다.

  • amount number

    결제한 금액입니다.

거래 조회

GET /v1/transactions

특정 기간의 거래 기록을 조회합니다. 거래 기록은 거래가 처리된 시점(transactionAt)을 기준으로 조회합니다.

Query 파라미터 startDateendDate로 지정한 날짜 정보를 사용합니다. 거래가 일어난 당일부터 거래 기록을 조회할 수 있습니다. 예를 들어 예제의 요청은 2022년 1월 1일부터 1월 2일까지 일어난 거래를 조회합니다.

* 거래 조회는 최대 60초가 소요됩니다. 타임아웃 값을 최소 60초로 설정하세요. 라이브 환경에서 비정상적으로 많은 요청을 보내면 429 Too Many Requests 상태 코드가 내려올 수 있습니다.

API 직접 실행해보기

Query 파라미터

  • startDate 필수 · string

    조회를 시작하고 싶은 날짜와 시간 정보입니다. yyyy-MM-dd'T'hh:mm:ss ISO 8601 형식입니다.

    날짜 정보만 입력하면 시간은 자동으로 00:00:00으로 설정됩니다.

    (e.g. 2022-01-01T00:00:00)

  • endDate 필수 · string

    조회를 마치고 싶은 날짜와 시간 정보입니다. yyyy-MM-dd'T'hh:mm:ss ISO 8601 형식입니다.

    날짜 정보만 입력하면 시간은 자동으로 00:00:00으로 설정됩니다.

    (e.g. 2022-01-02T23:59:59)

  • startingAfter string

    특정 결제 건 이후의 기록을 조회할 때 사용합니다. transactionKey 값을 전달합니다. 많은 양의 기록을 페이지 단위로 나누어 처리할 때 사용할 수 있습니다.

  • limit integer

    한 번에 응답받을 기록의 개수입니다. 기본값은 100이고 설정할 수 있는 최대값은 5000입니다.

Response

성공

응답으로 조회한 기간 동안의 일어난 모든 거래 정보가 Transaction 객체로 돌아옵니다.

같은 paymentKey를 가지고 있는 거래 기록은 transactionKey로 구분합니다.

실패

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

거래 조회 API에서 발생할 수 있는 에러를 살펴보세요.

정산

매출에서 정산 주기, 수수료율 등에 따라 금액을 계산해 지급하는 것을 이라고 합니다. 정산 조회 API로 원하는 기간 동안의 정산 기록을 조회해 보세요.

조회된 정산 정보로 지급 받을 금액 및 날짜, 수수료 정보 등을 확인한 뒤 내 상점의 데이터와 일치하는지 확인할 수 있습니다. 이렇게 정산 기록을 비교하는 일을 '정산 대사'라고 부르기도 합니다. '대사'란 기록을 비교・대조해서 데이터를 검증하고 일치시키는 과정을 뜻합니다.

Settlement 객체

정보를 담고 있는 객체입니다. 지급 받을 금액 및 날짜, 수수료 정보 등을 상세히 확인할 수 있습니다.

객체 상세

  • mId string

    상점아이디(MID)입니다. 토스페이먼츠에서 발급합니다. 최대 길이는 14자입니다.

  • paymentKey string

    결제의 키 값입니다. 최대 길이는 200자입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 값이 유지됩니다.

  • transactionKey string

    거래의 키 값입니다. 한 결제 건의 승인 거래와 취소 거래를 구분하는 데 사용됩니다. 최대 길이는 64자입니다.

  • orderId string

    주문번호입니다. 최소 길이는 6자, 최대 길이는 64자입니다. 주문한 결제를 식별하는 역할로, 결제를 요청할 때 가맹점에서 만들어서 사용합니다. 결제 상태가 변해도 값이 유지됩니다.

  • currency string

    결제할 때 사용한 통화입니다.

  • method string

    결제수단입니다. 카드, 가상계좌, 간편결제, 휴대폰, 계좌이체, 문화상품권, 도서문화상품권, 게임문화상품권 중 하나입니다.

  • amount number

    결제한 금액입니다.

  • interestFee number

    할부 수수료 금액입니다.

  • fees array

    결제 수수료의 상세 정보입니다. 수수료 상세 정보가 담긴 객체가 배열로 들어옵니다.

    • type string

      수수료의 세부 타입입니다.

      BASE: 기본 수수료

      INSTALLMENT_DISCOUNT: 카드사 혹은 토스페이먼츠가 부담하는 무이자 할부 수수료

      INSTALLMENT: 상점이 부담하는 무이자 할부 수수료

      POINT_SAVING: 카드사 포인트 적립 수수료

      ETC: 기타 수수료

    • fee number

      수수료 금액입니다.

  • supplyAmount number

    결제 수수료의 공급가액입니다.

  • vat number

    결제 수수료 부가세입니다.

  • payOutAmount number

    지급 금액입니다. 결제 금액 amount에서 수수료인 fee를 제외한 금액입니다.

  • approvedAt string

    거래가 승인된 시점의 날짜와 시간 정보입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.

    (e.g. 2022-01-01T00:00:00+09:00)

  • soldDate string

    지급 금액의 기준이 되는 정산 매출일입니다. 상점의 정산 주기에 따라 달라집니다. yyyy-MM-dd 형식입니다. (e.g. 2022-01-01)

    * 에서 정산 매출일을 더 자세히 설명합니다.

  • paidOutDate string

    지급 금액을 상점에 지급할 지급일입니다. 상점의 정산 기준일과 정산 주기에 따라 달라집니다. yyyy-MM-dd 형식입니다. (e.g. 2022-01-01)

    * 에서 정산 지급일을 더 자세히 설명합니다.

  • card nullable · object

    로 결제하면 제공되는 카드 관련 정보입니다.

    • amount number

      카드사에 결제 요청한 금액입니다. 즉시 할인 금액(discount.amount)이 포함됩니다.

      * 간편결제에 등록된 카드로 결제했다면 간편결제 응답 확인 가이드를 참고하세요.

    • issuerCode string

      두 자리 코드입니다. 카드사 코드를 참고하세요.

    • acquirerCode nullable · string

      두 자리 코드입니다. 카드사 코드를 참고하세요.

    • number string

      카드번호입니다. 번호의 일부는 마스킹 되어 있습니다. 최대 길이는 20자입니다.

    • installmentPlanMonths integer

      할부 개월 수입니다. 일시불이면 0입니다.

    • approveNo string

      카드사 승인 번호입니다. 최대 길이는 8자입니다.

    • useCardPoint boolean

      카드사 포인트 사용 여부입니다.

      * 일반 카드사 포인트가 아닌, 특수한 포인트나 바우처를 사용하면 할부 개월 수가 변경되어 응답이 돌아오니 유의해주세요.

    • cardType string

      카드 종류입니다. 신용, 체크, 기프트, 미확인 중 하나입니다. 구매자가 해외 카드로 결제했거나 의 결제 수단을 조합해서 결제했을 때 미확인으로 표시됩니다.

    • ownerType string

      카드의 소유자 타입입니다. 개인, 법인, 미확인 중 하나입니다. 구매자가 해외 카드로 결제했거나 의 결제 수단을 조합해서 결제했을 때 미확인으로 표시됩니다.

    • acquireStatus string

      의 매입 상태입니다. 아래와 같은 상태 값을 가질 수 있습니다.

      - READY: 아직 매입 요청이 안 된 상태입니다.

      - REQUESTED: 매입이 요청된 상태입니다.

      - COMPLETED: 요청된 매입이 완료된 상태입니다.

      - CANCEL_REQUESTED: 매입 취소가 요청된 상태입니다.

      - CANCELED: 요청된 매입 취소가 완료된 상태입니다.

    • isInterestFree boolean

      무이자 할부의 적용 여부입니다.

    • interestPayer nullable · string

      할부가 적용된 결제에서 할부 수수료를 부담하는 주체입니다. BUYER, CARD_COMPANY, MERCHANT 중 하나입니다.

      - BUYER: 구매자가 할부 수수료를 부담합니다. 일반적인 할부 결제입니다.

      - CARD_COMPANY: 카드사에서 할부 수수료를 부담합니다. 무이자 할부 결제입니다.

      - MERCHANT: 상점에서 할부 수수료를 부담합니다. 무이자 할부 결제입니다.

  • easyPay nullable · object

    정보입니다. 구매자가 선택한 결제수단에 따라 amount, discountAmount가 달라집니다. 간편결제 응답 확인 가이드를 참고하세요.

    • provider string

      선택한 간편결제사 코드입니다.

    • amount number

      간편결제 서비스에 등록된 계좌 혹은 현금성 포인트로 결제한 금액입니다.

    • discountAmount number

      간편결제 서비스의 적립 포인트나 쿠폰 등으로 즉시 할인된 금액입니다.

  • giftCertificate nullable · object

    으로 결제하면 제공되는 상품권 결제 관련 정보입니다.

    • approveNo string

      결제 승인번호입니다. 최대 길이는 8자입니다.

    • settlementStatus string

      정산 상태입니다. 정산이 아직 되지 않았다면 INCOMPLETED, 정산이 완료됐다면 COMPLETED 값이 들어옵니다.

  • mobilePhone nullable · object

    휴대폰으로 결제하면 제공되는 관련 정보입니다.

    • customerMobilePhone string

      결제에 사용한 휴대폰 번호입니다.

    • settlementStatus string

      정산 상태입니다. 정산이 아직 되지 않았다면 INCOMPLETED, 정산이 완료됐다면 COMPLETED 값이 들어옵니다.

    • receiptUrl string

      휴대폰 결제 내역 영수증을 확인할 수 있는 주소입니다.

  • transfer nullable · object

    로 결제했을 때 이체 정보가 담기는 객체입니다.

    • bankCode string

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

    • settlementStatus string

      정산 상태입니다. 정산이 아직 되지 않았다면 INCOMPLETED, 정산이 완료됐다면 COMPLETED 값이 들어옵니다.

  • virtualAccount nullable · object

    로 결제하면 제공되는 가상계좌 관련 정보입니다.

    • accountType string

      가상계좌 타입을 나타냅니다. 일반, 고정 중 하나입니다.

    • accountNumber string

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

    • bankCode string

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

    • customerName string

      가상계좌를 발급한 구매자명입니다. 최대 길이는 100자입니다.

    • dueDate string

      입금 기한입니다. yyyy-MM-dd'T'HH:mm:ss ISO 8601 형식을 사용합니다.

    • refundStatus string

      환불 처리 상태입니다. 아래와 같은 상태 값을 가질 수 있습니다.

      - NONE: 환불 요청이 없는 상태입니다.

      - PENDING: 환불을 처리 중인 상태입니다.

      - FAILED: 환불에 실패한 상태입니다.

      - PARTIAL_FAILED: 부분 환불에 실패한 상태입니다.

      - COMPLETED: 환불이 완료된 상태입니다.

    • expired boolean

      가상계좌의 만료 여부입니다.

    • settlementStatus string

      정산 상태입니다. 정산이 아직 되지 않았다면 INCOMPLETED, 정산이 완료됐다면 COMPLETED 값이 들어옵니다.

    • refundReceiveAccount object

      결제위젯 가상계좌 환불 정보 입력 기능으로 받은 구매자의 환불 계좌 정보입니다. 은행 코드(bankCode), 계좌번호(accountNumber), 예금주 정보(holderName)가 담긴 객체입니다.

      * 구매자의 환불계좌 정보는 결제창을 띄운 시점부터 30분 동안만 조회할 수 있습니다. 이후에는 값이 내려가지 않습니다. 더 자세한 내용은 결제 취소 가이드를 참고하세요.

  • cancel nullable · object

    결제 취소 이력이 담기는 객체입니다.

    • cancelAmount number

      결제를 취소한 금액입니다.

    • cancelReason string

      결제를 취소한 이유입니다. 최대 길이는 200자입니다.

    • taxFreeAmount number

      취소된 금액 중 면세 금액입니다.

    • taxExemptionAmount integer

      취소된 금액 중 과세 제외 금액(컵 보증금 등)입니다.

    • refundableAmount number

      결제 취소 후 환불 가능한 잔액입니다.

    • easyPayDiscountAmount number

      서비스의 포인트, 쿠폰, 즉시할인과 같은 적립식 결제수단에서 취소된 금액입니다.

    • canceledAt string

      결제 취소가 일어난 날짜와 시간 정보입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.

      (e.g. 2022-01-01T00:00:00+09:00)

    • transactionKey string

      취소 건의 키 값입니다. 여러 건의 취소 거래를 구분하는 데 사용됩니다. 최대 길이는 64자입니다.

    • receiptKey nullable · string

      취소 건의 현금영수증 키 값입니다. 최대 길이는 200자입니다.

정산 조회

GET /v1/settlements

지정한 날짜 정보로 기록을 조회합니다.

정산 기록은 결제가 일어난 다음 날부터 조회됩니다. 따라서 만약 오늘이 1월 11일이라면, 1월 11일 결제의 정산 기록은 다음 날인 1월 12일에 startDate2024-01-11로, endDate2024-01-12로 요청해서 확인할 수 있습니다.

많은 양의 정산 기록을 조회한다면 pagesize 파라미터를 사용해서 페이지 단위로 기록을 나누어 조회할 수 있습니다. 예를 들어 page를 3으로, size를 100으로 설정한다면 설정한 기간 동안의 전체 기록을 100개씩 나누어 보여주고, 전체 페이지 중 3페이지의 기록을 조회합니다.

* 정산 조회는 최대 60초가 소요됩니다. 타임아웃 값을 최소 60초로 설정하세요. 라이브 환경에서 비정상적으로 많은 요청을 보내면 429 Too Many Requests 상태 코드가 내려올 수 있습니다.

Query 파라미터

  • startDate 필수 · string

    조회를 시작하고 싶은 날짜 정보입니다. yyyy-MM-dd ISO 8601 형식입니다.

    (e.g. 2022-01-01)

  • endDate 필수 · string

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

    (e.g. 2022-01-01)

  • dateType string

    조회 기준이 되는 날짜 타입입니다. soldDate(정산 매출일)나 paidOutDate(정산 지급일) 중 하나입니다.

    결제 금액을 정산 받을 날짜 기준으로 조회하고 싶으면 paidOutDate를 사용하세요. 파라미터를 사용하지 않으면 soldDate 기준으로 조회됩니다.

  • page integer

    조회할 페이지 값입니다. 최소값은 1입니다. 많은 양의 정산 기록을 조회할 때 size 파라미터와 함께 사용합니다.

  • size integer

    한 페이지에서 응답으로 보여줄 정산 기록 개수를 의미합니다. 기본값은 100이고 설정할 수 있는 최대값은 5000입니다. 많은 양의 정산 기록을 조회할 때 page 파라미터와 함께 사용합니다.

Response

성공

정산 조회에 성공하면 Settlement 객체가 담긴 배열이 돌아옵니다.

실패

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

정산 조회 API에서 발생할 수 있는 에러를 살펴보세요.

수동 정산 요청

은 일정 기간 동안 쌓인 카드 결제 기록 중에 한 건만 선택해서 정산 받는 방법입니다.

* 수동 정산 요청 API는 추가 계약 후 사용할 수 있습니다. 추가 계약을 하고 싶다면 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.

POST /v1/settlements

매입하고 싶은 결제 건을 paymentKey로 특정해서 카드사에 정산을 요청합니다.

API 직접 실행해보기

Request Body 파라미터

  • paymentKey 필수 · string

    수동 정산을 요청할 결제 건을 특정하는 키 값 입니다. 최대 길이는 200자입니다.

Response

성공

수동 정산 요청에 성공하면 result 값이 true로 돌아옵니다.

현금영수증

홈택스 접속 없이 토스페이먼츠에서 제공하는 현금영수증 API로 을 편리하게 발급해보세요. 이라면 토스페이먼츠로 결제하지 않은 건도 발급 및 취소 요청을 할 수 있습니다.

CashReceipt 객체

정보를 담고 있는 객체입니다.

객체 상세

  • receiptKey string

    발급 혹은 취소 요청한 현금영수증 한 건을 특정하는 키 값입니다. 최대 길이는 200자입니다.

    현금영수증 발급 API로 요청한 발급 건을 취소하면 앞서 발급했던 건의 receiptKey에 prefix로 c_가 추가되어 돌아옵니다.

  • issueNumber string

    현금영수증 발급번호입니다. 최대 길이는 9자입니다.

  • issueStatus string

    현금영수증 발급 상태입니다. 발급 승인 여부는 요청 후 1-2일 뒤 조회할 수 있습니다.

    - IN_PROGRESS: 현금영수증 발급이 대기 중인 상태입니다.

    - COMPLETED: 현금영수증이 발급된 상태입니다.

    - FAILED: 현금영수증 발급에 실패한 상태입니다.

  • amount integer

    현금영수증 처리된 금액입니다.

  • taxFreeAmount integer

    면세 처리된 금액입니다.

  • orderId string

    주문번호입니다. 최소 길이는 6자, 최대 길이는 64자입니다. 주문한 결제를 식별하는 역할로, 결제를 요청할 때 가맹점에서 만들어서 사용한 값입니다. 결제 상태가 변해도 값이 유지됩니다.

  • orderName string

    구매상품입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.

  • type string

    현금영수증의 종류입니다. 소득공제, 지출증빙 중 하나입니다.

  • approvalNumber string

    현금영수증 발급 승인번호입니다. 최대 길이는 9자입니다.

  • transactionType string

    현금영수증 발급 종류입니다. 현금영수증 발급·취소 건을 구분합니다.

    CONFIRM - 현금영수증을 발급했을 때

    CANCEL - 발급된 현금영수증을 취소했을 때

  • businessNumber string

    현금영수증을 발급한 사업자등록번호입니다. 길이는 10자입니다.

  • customerIdentityNumber string

    현금영수증 발급에 필요한 소비자 인증수단입니다. 현금영수증을 발급한 주체를 식별합니다. 최대 길이는 30자입니다.

    현금영수증 종류에 따라 휴대폰 번호, 사업자등록번호, 현금영수증 카드 번호 등을 입력할 수 있습니다.

  • failure nullable · object

    결제 실패 정보입니다.

    • code string

      오류 타입을 보여주는 에러 코드입니다.

    • message string

      에러 메시지입니다. 에러 발생 이유를 알려줍니다. 최대 길이는 510자입니다.

  • requestedAt string

    현금영수증 발급 혹은 취소를 요청한 날짜와 시간 정보입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.

  • approvedAt string

    현금영수증이 발급된 날짜와 시간 정보입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.

    (e.g. 2022-01-01T00:00:00+09:00)

  • canceledAt nullable · string

    현금영수증을 발급을 취소한 날짜와 시간 정보입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.

    (e.g. 2022-01-01T00:00:00+09:00)

  • receiptUrl string

    발행된 현금영수증을 확인할 수 있는 주소입니다.

현금영수증 발급 요청

POST /v1/cash-receipts

발급을 요청합니다. 현금영수증을 발급할 때는 현금영수증 발급 용도와 현금영수증 발급에 필요한 소비자 인증수단 정보가 반드시 필요합니다. 현금영수증 발급 용도를 type에, 소비자 인증수단은 customerIdentityNumber에 추가해주세요.

API 직접 실행해보기

Request Body 파라미터

  • amount 필수 · integer

    현금영수증을 발급할 금액입니다.

  • orderId 필수 · string

    주문번호입니다. 주문한 결제를 식별합니다. 충분히 무작위한 값을 생성해서 각 주문마다 고유한 값을 넣어주세요. 영문 대소문자, 숫자, 특수문자 -, _로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다.

  • orderName 필수 · string

    구매상품입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.

  • type 필수 · string

    현금영수증의 종류입니다. 소득공제, 지출증빙 중 하나입니다. 소득 공제용 현금영수증을 발급받을 때는 소비자 인증수단으로 휴대폰 번호나 현금영수증 카드 번호가 필요하고, 지출 증빙용 현금영수증을 발급받을 때는 사업자 등록번호를 입력해야 합니다.

  • customerIdentityNumber 필수 · string

    현금영수증 발급에 필요한 소비자 인증수단입니다. 현금영수증을 발급한 주체를 식별합니다. 최대 길이는 30자입니다. 현금영수증 종류에 따라 휴대폰 번호, 사업자등록번호, 현금영수증 카드 번호 등을 입력할 수 있습니다.

    구매자의 정보가 없어도 상점에서 발급할 때 사용할 수 있는 국세청 지정 코드(010-000-1234)를 활용해 현금영수증을 발급할 수 있습니다.

  • registrationNumber 필수 · string

    현금영수증 발급에 필요한 소비자 인증수단입니다. 현금영수증을 발급한 주체를 식별합니다. 최대 길이는 30자입니다. 현금영수증 종류에 따라 휴대폰 번호, 사업자등록번호, 현금영수증 카드 번호 등을 입력할 수 있습니다.

    구매자의 정보가 없어도 상점에서 발급할 때 사용할 수 있는 국세청 지정 코드(010-000-1234)를 활용해 현금영수증을 발급할 수 있습니다.

  • taxFreeAmount integer

    면세 금액입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다. 하나의 결제에 과세 상품과 면세 상품이 섞여있다면 이 파라미터로 면세 상품 금액을 보내주세요. 보낸 금액 만큼 현금영수증이 발급됩니다.

    * 면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점에는 적용되지 않습니다. 더 자세한 내용은 세금 처리하기에서 살펴보세요.

Response

성공

현금영수증 발급 요청에 성공하면 CashReceipt 객체가 돌아옵니다.

CashReceipt 객체transactionType으로 현금영수증 발급(CONFIRM)과 현금영수증 발급 취소(CANCEL)를 구분할 수 있습니다. issueStatus는 요청의 상태를 나타냅니다. 응답의 최초 상태는 IN_PROGRESS로, 토스페이먼츠에 요청이 잘 전달되었음을 뜻합니다.

실패

현금영수증 발급 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

현금영수증 발급 요청 API에서 발생할 수 있는 에러를 살펴보세요.

현금영수증 발급 취소 요청

POST /v1/cash-receipts/{receiptKey}/cancel

현금영수증을 발급한 결제가 취소됐을 때 receiptKey를 이용해서 현금영수증 발급을 취소합니다.

현금영수증 발급 API의 응답으로 받았던 CashReceipt.receiptKey를 저장해 두었다가 Path 파라미터로 추가하세요.

부분 취소를 하려면 amount 값에 취소된 금액을 입력해서 사용합니다. amount 값이 없으면 전액 취소됩니다.

API 직접 실행해보기

Path 파라미터

  • receiptKey 필수 · string

    현금영수증의 키 값입니다. 최대 길이는 200자입니다.

Request Body 파라미터

  • amount integer

    현금영수증 발급을 취소할 금액입니다. 값이 따로 없으면 전액 취소됩니다.

Response

성공

현금영수증 발급 취소 요청에 성공하면 CashReceipt 객체가 돌아옵니다.

실패

현금영수증 발급 취소 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

현금영수증 발급 취소 API에서 발생할 수 있는 에러를 살펴보세요.

현금영수증 조회

GET /v1/cash-receipts

특정 기간 동안 발급된 을 조회합니다.

* 현금영수증 조회 API는 버전 2022-07-27 이상에서만 지원합니다. API 버전은 개발자센터에서 확인·변경할 수 있습니다.

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

API 직접 실행해보기

Query 파라미터

  • requestDate 필수 · string

    현금영수증 발급이 요청된 날짜로 조회하고 싶을 때 사용합니다. yyyy-MM-dd ISO 8601 형식입니다. (e.g. 2022-01-01)

  • cursor integer

    특정 현금영수증 발급 건 이후의 기록을 조회할 때 사용합니다. 이전 조회에서 돌아온 lastCursor 값을 전달합니다. 많은 양의 기록을 페이지 단위로 나누어 처리할 때 사용할 수 있습니다.

  • limit integer

    한 번에 응답받을 기록의 개수입니다. 기본값은 100이고 설정할 수 있는 최대값은 10000입니다.

Response

성공

현금영수증 조회에 성공하면 아래 값을 포함한 객체가 내려갑니다.

  • hasNext: 다음 기록을 조회할 수 있는지 여부입니다. 이 값이 false면 더 조회할 기록이 없습니다.
  • lastCursor: 특정 현금영수증 건 이후의 기록을 조회할 때 사용합니다. 다음 기록을 조회할 때 cursor 파라미터에 이 값을 사용합니다. 이 값은 integer 타입입니다.
  • data: 조회 요청에서 cursor로 특정한 현금영수증 건 이후의 기록입니다. CashReceipt 객체가 담긴 배열이 돌아옵니다.
실패

현금영수증 조회에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

현금영수증 조회 API에서 발생할 수 있는 에러를 살펴보세요.

지급대행

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

토스페이먼츠와 직접 계약하지 않은 셀러에게 토스페이먼츠가 정산금을 보내야 되기 때문에 등 리스크 검토 절차가 있습니다. 그리고 연동 측면에서도 더 강화된 보안을 요구합니다. 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

    오픈마켓 상점에서 직접 등록하는 셀러의 고유 식별자입니다. 연동 중에 참고할 수 있는 값입니다. 등록 이후에 수정할 수 없고, 삭제된 셀러의 refSellerId는 다시 사용할 수 없습니다.

  • 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

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

  • metadata nullable · object

    셀러와 관련된 추가 정보를 key-value 쌍으로 담고 있는 객체입니다. 최대 5개의 키-값(key-value) 쌍입니다. 키는 [ , ] 를 사용하지 않는 최대 40자의 문자열, 값은 최대 500자의 문자열입니다.

셀러 등록

POST /v2/sellers

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

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

Request Body 파라미터

  • refSellerId 필수 · string

    오픈마켓 상점에서 발급하는 셀러의 고유 식별자입니다. 연동 중에 참고할 수 있는 값입니다. 등록 이후에 수정할 수 없고, 삭제된 셀러의 refSellerId는 다시 사용할 수 없습니다.

  • businessType 필수 · string

    사업자 유형입니다. INDIVIDUAL(개인), INDIVIDUAL_BUSINESS(개인사업자), CORPORATE(법인사업자) 중 하나입니다.

  • company object

    법인사업자 또는 개인사업자 셀러 정보입니다. businessTypeINDIVIDUAL_BUSINESS 또는 CORPORATE이면 필수입니다.

    • name 필수 · string

      사업자명입니다.

    • representativeName 필수 · string

      대표자명입니다.

    • businessRegistrationNumber 필수 · string

      사업자번호입니다. - 없이 10자리 사업자번호 숫자만 입력해주세요.

    • email 필수 · string

      이메일입니다

    • phone 필수 · string

      사업자 전화번호입니다. - 없이 숫자만 입력해주세요.

  • individual object

    개인 셀러 정보입니다. businessTypeINDIVIDUAL이면 필수입니다.

    • name 필수 · string

      개인의 이름입니다.

    • email 필수 · string

      이메일입니다

    • phone 필수 · string

      전화번호입니다. - 없이 숫자만 입력해주세요.

  • account 필수 · object

    셀러가 정산 금액을 지급받을 계좌 정보입니다.

    • bankCode 필수 · string

      계좌의 은행 코드입니다. 은행 코드증권사 코드를 참고해서 두 자리 코드 또는 세 자리 코드를 사용해주세요.

    • accountNumber 필수 · string

      계좌번호입니다. - 없이 숫자만 입력해주세요. 최대 길이는 20자입니다.

    • holderName 필수 · string

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

  • metadata object

    셀러와 관련된 추가 정보를 key-value 쌍으로 담고 있는 JSON 객체입니다. 최대 5개의 키-값(key-value) 쌍입니다. 키는 [ , ] 를 사용하지 않는 최대 40자의 문자열, 값은 최대 500자의 문자열입니다.

Response

성공

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

실패

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

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

셀러 수정

POST /v2/sellers/{id}

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

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

Path 파라미터

  • id 필수 · string

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

Request Body 파라미터

  • company object

    법인사업자 또는 개인사업자 셀러 정보입니다.

    • name 필수

      사업자명입니다.

    • representativeName 필수

      대표자명입니다.

    • email 필수

      사업자 이메일입니다.

    • phone 필수

      사업자 전화번호입니다. - 없이 숫자만 입력해주세요.

  • individual object

    개인 셀러 정보입니다.

    • email 필수

      이메일입니다.

    • phone 필수

      전화번호입니다. - 없이 숫자만 입력해주세요.

  • account object

    셀러에서 정산 금액을 지급받을 계좌 정보입니다.

    • bankCode 필수

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

    • accountNumber 필수

      계좌번호입니다. - 없이 숫자만 입력해주세요. 최대 길이는 20자입니다.

    • holderName 필수

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

  • metadata 필수

    셀러와 관련된 추가 정보를 key-value 쌍으로 담고 있는 JSON 객체입니다. 최대 5개의 키-값(key-value) 쌍입니다. 키는 [ , ] 를 사용하지 않는 최대 40자의 문자열, 값은 최대 500자의 문자열입니다.

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: 지급 요청이 취소된 상태입니다.

  • error nullable · object

    지급대행 요청에서 일어난 에러 객체입니다.

  • metadata nullable · object

    셀러와 관련된 추가 정보를 key-value 쌍으로 담고 있는 객체입니다. 최대 5개의 키-값(key-value) 쌍입니다. 키는 [ , ] 를 사용하지 않는 최대 40자의 문자열, 값은 최대 500자의 문자열입니다.

지급대행 요청

POST /v2/payouts

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

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

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

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

* 지급대행 요청 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자의 문자열, 값은 최대 500자의 문자열입니다.

Response

성공

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

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

실패

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

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

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

지급대행 요청 취소

POST /v2/payouts/{id}/cancel

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

Path 파라미터

  • id 필수 · string

    취소하고 싶은 Payout 객체의 id입니다.

Response

성공

지급대행 요청 취소에 성공하면 statusCANCELED로 바뀐 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 객체 목록입니다.

실패

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

프로모션

프로모션 정보를 조회합니다. 구매자가 결제할 때 더욱 간편하게 혜택을 받을 수 있도록 혜택 기간, 금액 조건 등에 따라 할인 금액과 코드, 무이자 할부 혜택을 보여주세요.

Promotions 객체

전체 프로모션 정보를 담고 있는 객체입니다.

객체 상세

  • payType string

    결제 종류입니다. NORMAL, BILLING, BRANDPAY 중 하나입니다.

  • type string

    프로모션 종류입니다. 아래 네 가지 값 중 하나가 돌아옵니다. 상세 정보는 type 이름과 같은 객체에 들어있습니다.

    - CARD_DISCOUNT: 카드 즉시 할인입니다. cardDiscount 객체에 관련 정보가 돌아옵니다.

    - CARD_INTEREST_FREE: 카드 무이자 할부입니다. cardInterestFree 객체에 관련 정보가 돌아옵니다.

    - CARD_POINT: 카드 포인트 할인입니다. cardPoint 객체에 관련 정보가 돌아옵니다.

    - BANK_DISCOUNT: 계좌 할인입니다. bankDiscount 객체에 관련 정보가 돌아옵니다.

  • cardDiscount nullable · object

    카드사의 즉시 할인 정보입니다.

    • issuerCode string

      프로모션을 진행하는 카드 발급사 두 자리 코드입니다. 카드사 코드를 참고하세요.

    • discountAmount number

      할인되는 금액입니다.

    • minimumPaymentAmount number

      카드사 즉시 할인을 적용할 수 있는 최소 결제 금액입니다.

    • maximumPaymentAmount number

      카드사 즉시 할인을 적용할 수 있는 최대 결제 금액입니다.

    • currency string

      통화 정보입니다.

    • discountCode string

      프로모션 코드입니다. 카드사에서 만든 고유한 값으로 결제할 때 함께 넘겨야 하는 값입니다.

    • dueDate string

      프로모션을 마치는 시점입니다. yyyy-MM-dd 형식입니다. 종료일의 23:59:59까지 행사가 유효합니다.

    • balance number

      남은 프로모션 예산입니다. 값이 '0'이면 즉시 할인을 적용할 수 없습니다.

  • cardInterestFree nullable · object

    카드 무이자 할부 정보입니다.

    • issuerCode string

      프로모션을 진행하는 카드 발급사 두 자리 코드입니다. 카드사 코드를 참고하세요.

    • minimumPaymentAmount number

      무이자 할부를 적용할 수 있는 최소 결제 금액입니다.

    • currency string

      통화 정보입니다.

    • dueDate string

      프로모션을 마치는 시점입니다. yyyy-MM-dd 형식입니다. 종료일의 23:59:59까지 행사가 유효합니다.

    • installmentFreeMonths array

      카드 무이자 할부를 적용할 수 있는 개월 수입니다.

  • cardPoint nullable · object

    카드 포인트 정보입니다.

    • issuerCode string

      프로모션을 진행하는 카드 발급사 두 자리 코드입니다. 카드사 코드를 참고하세요.

    • minimumPaymentAmount number

      카드 포인트를 적용할 수 있는 최소 결제 금액입니다.

    • currency string

      통화 정보입니다.

    • dueDate string

      프로모션을 마치는 시점입니다. yyyy-mm-dd 형태입니다. 종료일의 23:59:59까지 행사가 유효합니다.

  • bankDiscount nullable · object

    계좌 할인 정보입니다.

    • type string

      계좌 할인 종류입니다. FIXED_AMOUNT, FIXED_RATE 중 하나입니다.

      - FIXED_AMOUNT: 금액할인 입니다. 결제 금액에서 정해진 금액을 할인해 줍니다.

      - FIXED_RATE: 정률할인 입니다. 결제 금액에서 정해진 비율만큼 할인해 줍니다.

    • bankCode string

      프로모션을 진행하는 은행 두 자리 코드입니다. 은행 코드를 참고하세요.

    • discountAmount nullable · number

      할인 금액입니다.

    • discountRate nullable · number

      할인 비율입니다. 이 값은 0.01부터 0.3까지의 소수입니다. 이 필드는 typeFIXED_RATE일 때만 값이 있습니다. typeFIXED_AMOUNT일 때는 null입니다.

    • minimumPaymentAmount number

      계좌 할인을 적용할 수 있는 최소 결제 금액입니다.

    • maximumPaymentAmount number

      계좌 할인을 적용할 수 있는 최대 결제 금액입니다.

    • currency string

      통화 정보입니다.

    • discountCode string

      계좌 할인 프로모션 코드입니다. 은행에서 만든 고유한 값으로 결제할 때 함께 넘겨야 하는 값입니다.

    • dueDate string

      프로모션을 마치는 시점입니다. yyyy-mm-dd 형태입니다. 종료일의 23:59:59까지 행사가 유효합니다.

CardPromotion 객체

할인 프로모션 정보와 할부 혜택 정보를 담고 있는 객체입니다.

객체 상세

  • discountCards array

    카드사의 즉시 할인 정보입니다.

    • issuerCode string

      프로모션을 진행하는 카드 발급사 두 자리 코드입니다. 카드사 코드를 참고하세요.

    • discountAmount number

      할인 금액입니다.

    • balance number

      남은 프로모션 예산입니다. 값이 '0'이면 즉시 할인을 적용할 수 없습니다.

    • discountCode string

      즉시 할인 코드(카드사 고유 번호)로 결제할 때 함께 넘겨야 하는 값입니다.

    • dueDate string

      프로모션을 마치는 시점입니다. yyyy-MM-dd 형식입니다. 종료일의 23:59:59까지 행사가 유효합니다.

    • minimumPaymentAmount number

      즉시 할인을 적용할 수 있는 최소 결제 금액입니다.

    • maximumPaymentAmount number

      즉시 할인을 적용할 수 있는 최대 결제 금액입니다.

    • currency string

      통화 정보입니다.

  • interestFreeCards array

    카드사의 무이자 할부 정보입니다.

    • issuerCode string

      카드사 두 자리 코드입니다. 카드사 코드를 참고하세요.

    • minimumPaymentAmount number

      무이자 할부를 적용할 수 있는 최소 결제 금액입니다.

    • dueDate string

      프로모션을 마치는 시점입니다. yyyy-MM-dd 형식입니다. 종료일의 23:59:59까지 행사가 유효합니다.

    • installmentFreeMonths array

      무이자 할부를 적용할 수 있는 개월 수입니다.

전체 프로모션 조회

GET /v1/promotions

전체 프로모션 정보를 조회합니다.

API 직접 실행해보기

Response

성공

전체 프로모션 조회에 성공하면 Promotions 객체가 돌아옵니다.

실패

전체 프로모션 조회에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

카드 프로모션 조회

GET /v1/promotions/card

카드사별 혜택을 조회합니다. 즉시 할인, 무이자 정보가 내려갑니다.

API 직접 실행해보기

Response

성공

카드사 혜택 조회에 성공하면 CardPromotion 객체가 돌아옵니다.

실패

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