코어 API

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

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

결제가 승인됐을 때 응답은 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
  DEPRECATED
  
  

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

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

  • transferDiscountAmount 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
  

  결제 요청 시 SDK에서 직접 추가할 수 있는 결제 관련 정보입니다. 최대 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
  DEPRECATED
  
  

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

• easyPayDiscountAmount nullable · number
  DEPRECATED
  
  

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

• 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
    

    발행된 현금영수증을 확인할 수 있는 주소입니다. 테스트 환경에서 영수증 URL은 생성되지만 실제 데이터는 제공되지 않습니다. 영수증 샘플은 결제 결과 안내 가이드에서 확인하세요.

  • 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
    

    발행된 현금영수증을 확인할 수 있는 주소입니다. 테스트 환경에서 영수증 URL은 생성되지만 실제 데이터는 제공되지 않습니다. 영수증 샘플은 결제 결과 안내 가이드에서 확인하세요.

  • 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
    

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

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

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

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

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

• mId string
  

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

• customerKey string
  

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

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

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

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

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

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

• mId string
  

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

• transactionKey string
  

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

• paymentKey string
  

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

• orderId string
  

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

• method string
  

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

• customerKey string
  

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

  결제한 금액입니다.

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

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

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

• mId string
  

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

• paymentKey string
  

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

• transactionKey string
  

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

• orderId string
  

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

• 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자입니다.

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

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

• 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자 이하의 문자열입니다. 각 주문을 식별하는 역할로, 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 orderId는 유지됩니다.

• orderName string
  

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

• type string
  

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

• approvalNumber string
  DEPRECATED
  
  

  현금영수증 발급 승인번호입니다. 최대 길이는 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
  DEPRECATED
  
  

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

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

• canceledAt nullable · string
  DEPRECATED
  
  

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

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

• receiptUrl string
  

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

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

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

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

• pendingAmount object
  

  셀러에게 지급할 수 없는 잔액 정보입니다. 발생한 매출이 정산 주기 2일 전에 pendingAmount 금액으로 업데이트됩니다. 토스페이먼츠 정산 주기가 지난 금액은 availableAmount로 전환됩니다.

  • currency string
    

    통화입니다. 현재는 KRW만 지원합니다.

  • value number
    

    잔액입니다.

• availableAmount object
  

  셀러에게 지급할 수 있는 잔액 정보입니다.

  • currency string
    

    통화입니다. 현재는 KRW만 지원합니다.

  • value number
    

    잔액입니다.

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

• 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자의 문자열입니다.

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

• 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자의 문자열입니다.

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

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

• 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까지의 소수입니다. 이 필드는 type이 FIXED_RATE일 때만 값이 있습니다. type이 FIXED_AMOUNT일 때는 null입니다.

  • minimumPaymentAmount number
    

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

  • maximumPaymentAmount number
    

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

  • currency string
    

    통화 정보입니다.

  • discountCode string
    

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

  • dueDate string
    

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

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

• 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
    

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