결제위젯 iOS SDK

init(clientKey: String, customerKey: String, options: Options?)

• clientKey
  

  내 상점의 클라이언트 키입니다. API 키 페이지에서 확인할 수 있습니다.

• customerKey
  

  고객 ID입니다. 다른 사용자가 이 값을 알게 되면 악의적으로 사용할 수 있어 자동 증가하는 숫자는 안전하지 않습니다. UUID와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 영문 대소문자, 숫자, 특수문자 -, _, =, ., @ 를 최소 1개 이상 포함한 최소 2자 이상 최대 300자 이하의 문자열이어야 합니다. 비회원 결제에는 PaymentWidget.ANONYMOUS를 사용하세요.

• options
  

  결제위젯 Pro 플랜 기능을 설정합니다.

  struct Options {
      let brandPay: BrandPay?
  }
  
• brandpay
  

  결제위젯에 브랜드페이를 추가할 때 설정합니다. redirectUrl은 Access Token 발급 과정에서 임시 인증 코드를 받을 URL입니다.

  struct BrandPay {
      let redirectURL: String
  }
  

결제위젯을 렌더링하는 메서드입니다.

func renderPaymentMethods(
    amount: PaymentMethodWidget.Amount,
    options: PaymentMethodWidget.Options? = nil
) -> PaymentMethodWidget

• amount
  

  결제 금액 정보입니다. 결제 금액, 통화, 국가 정보가 들어가는 PaymentMethodWidget.Amount입니다.

  struct Amount: Encodable {
      let value: Double
      let currency: String?
      let country: String?
  }
  
• value
  

  결제 금액입니다.

• currency
  

  결제 통화입니다. 기본 값은 KRW입니다. PayPal에서 사용할 수 있는 통화는 USD입니다.

• country
  

  결제한 국가입니다. 기본 값은 KR입니다. ISO-3166의 두 자리 국가 코드를 모두 지원합니다.

• options
  

  결제위젯에 추가할 옵션입니다. PaymentMethodWidget.Options입니다.

  struct Options: Encodable {
      let variantKey: String?
  }
  
• variantKey
  

  멀티 결제 UI를 사용할 때 설정합니다. 렌더링하고 싶은 결제위젯의 키 값을 넣으세요.

변경된 결제 금액을 UI에 업데이트하는 메서드입니다.

func updateAmount(_ amount: Double)

• amount
  

  새로운 결제 금액입니다.

고객이 선택한 결제수단의 결제창을 띄우는 메서드입니다.

func requestPayment(info: DefaultWidgetPaymentInfo, on rootViewController: UIViewController)

• info
  

  결제 정보가 담긴 DefaultWidgetPaymentInfo 입니다.

  protocol DefaultWidgetPaymentInfo: Codable {
      var orderId: String
      var orderName: String
      var taxExemptionAmount: String?
      var appScheme: String?
      var customerName: String?
      var customerEmail: String?
      var taxFreeAmount: Double?
      var cultureExpense: Bool
      var customerMobilePhone: String?
      var showCustomerMobilePhone: String?
      var useEscrow: Bool
      var escrowProducts: [String]?
      var mobileCarrier: String?
  }
  
• orderId
  

  주문을 구분하는 ID입니다. 충분히 무작위한 값을 생성해서 각 주문마다 고유한 값을 넣어주세요. 영문 대소문자, 숫자, 특수문자 -, _, =로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.

• orderName
  

  주문명입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.

• taxExemptionAmount
  

  과세를 제외한 결제 금액(컵 보증금 등)입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다. 카드 결제 또는 간편결제로 계좌이체할 때 사용하세요.

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

• appScheme
  

  페이북/ISP 앱에서 상점 앱으로 돌아올 때 사용됩니다. 상점의 앱 스킴을 지정하면 됩니다. 예를 들면 testapp://같은 형태입니다.

• customerName
  

  고객의 이름입니다. 최대 길이는 100자입니다.

• customerEmail
  

  고객의 이메일 주소입니다. 최대 길이는 100자입니다.

• taxFreeAmount
  결제할 금액 중 면세 금액입니다. 값을 넣지 않으면 기본값인 `0` 으로 설정됩니다.

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

• cultureExpense
  

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

• customerMobilePhone
  

  고객의 휴대폰 번호입니다. 가상계좌 입금 안내가 전송되는 번호입니다.

• showCustomerMobilePhone
  

  가상계좌 결제창에서 휴대폰 번호 입력 필드 노출 여부입니다. false를 넘기면 가상계좌 결제창에서 휴대폰 번호 입력 필드를 보여주지 않습니다. 기본값은 true 입니다.

• useEscrow
  

  에스크로 사용 여부입니다. 값을 주지 않으면 결제창에서 고객이 직접 에스크로 결제 여부를 선택합니다.

• escrowProducts
  

  각 상품의 상세 정보 객체를 담는 배열입니다. 가상계좌, 계좌이체에서 에스크로를 사용하는 상점이라면 필수 파라미터입니다.

  예를 들어 사용자가 세 가지 종류의 상품을 구매했다면 길이가 3인 배열이어야 합니다.

• id string
  

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

• name string
  

  상품 이름입니다.

• code string
  

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

• unitPrice number
  

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

• quantity number
  

  상품 구매 수량입니다.

• mobileCarrier
  

  휴대폰 결제창에서 선택할 수 있는 통신사를 제한합니다. 배열에 통신사 코드를 추가하면 해당 통신사 코드만 선택할 수 있는 결제창이 뜹니다.

  값을 넣지 않으면 모든 통신사 코드를 선택할 수 있는 결제창이 뜹니다. 통신사 코드를 참고하세요.

추가 파라미터는 DefaultWidgetPaymentInfo를 구현한 객체를 선언해서 사용할 수 있습니다.

• rootViewController
  

  결제창의 UIViewController입니다.

이용약관 위젯을 렌더링하는 메서드입니다. 이용약관 위젯을 반환합니다.

func renderAgreement() -> AgreementWidget

결제 승인 결과를 알려주는 delegate입니다.

weak var delegate: TossPaymentsDelegate?

• TossPaymentsDelegate
  

  protocol TossPaymentsDelegate {
      func handleSuccessResult(_ success: TossPaymentsResult.Success)
      func handleFailResult(_ fail: TossPaymentsResult.Fail)
  }
  
• handleSuccessResult(_:)
  

  결제가 성공하면 호출되는 메서드입니다. TossPaymentsResult.Success를 전달합니다.

  TossPaymentsResult.Success로 돌아온 결제 정보를 검증하고, 결제 승인을 요청하세요.

• handleFailResult(_:)
  

  결제가 실패하면 호출되는 메서드입니다. TossPaymentsResult.Fail을 전달합니다.



• TossPaymentResult
  

  enum TossPaymentResult {
      struct Success {
          let paymentKey: String
          let orderId: String
          let amount: Double
          let additionalParmeters: [String: String]?
      }
      struct Fail {
          let errorCode: String
          let errorMessage: String
          let orderId: String
      }
  }
  
• Success
  

  결제 성공 결과 정보입니다.



• paymentKey
  

  결제를 식별하는 키 값입니다. 결제 승인, 결제 조회, 결제 취소 등 운영에 필요한 값입니다.

• orderId
  

  주문 ID입니다. 결제 요청에 담아 보낸 값입니다.

• amount
  

  결제 금액입니다.

• additionalParmeters
  

  브랜드페이를 추가하는 Pro 플랜 기능을 사용하고 있다면 필요한 파라미터입니다.

• paymentType
  

  결제 유형입니다. NORMAL, BRANDPAY 중 하나입니다.

  • NORMAL: 일반 결제입니다. 코어 결제 승인 API를 호출해서 결제를 완료하세요.
  • BRANDPAY: 브랜드페이 결제입니다. 브랜드페이 결제 승인 API를 호출해서 결제를 완료하세요.
• Fail
  

  결제 실패 결과 정보입니다.



• errorCode
  

  에러 코드입니다. SDK 에러가 돌아옵니다. failUrl로 전달되는 에러, 공통 SDK 에러, 결제위젯 SDK 에러가 모두 포함됩니다.

• errorMessage
  

  에러 메시지입니다.

• orderId
  

  주문 ID입니다. 결제 요청에 담아 보낸 값입니다.

결제위젯의 렌더링 상태를 알려주는 delegate입니다.

weak var widgetStatusDelegate: TossPaymentsWidgetStatusDelegate?

• TossPaymentsWidgetStatusDelegate
  

  protocol TossPaymentsWidgetStatusDelegate {
      func didReceivedLoad(_ name: String)
  }
  
• didReceivedLoad(_:)
  

  결제위젯 렌더링이 완료되면 호출되는 메서드입니다.

인스턴스 View의 상태 변화를 알려주는 delegate입니다.

weak var widgetUIDelegate: TossPaymentsWidgetUIDelegate?

• TossPaymentsWidgetUIDelegate
  

  protocol TossPaymentsWidgetUIDelegate {
      func didUpdateHeight(_ widget: PaymentMethodWidget, height: CGFloat)
      func didReceivedCustomRequest(_ widget: PaymentMethodWidget, paymentMethodKey: String)
      func didReceivedCustomPaymentMethodSelected(_ widget: PaymentMethodWidget, paymentMethodKey: String)
      func didReceivedCustomPaymentMethodUnselected(_ widget: PaymentMethodWidget, paymentMethodKey: String)
  }
  
• didUpdateHeight(_:height:)
  

  고객이 커스텀 결제수단으로 결제 요청을 하면 호출되는 메서드입니다.

• didReceivedCustomRequest(_:paymentMethodKey:)
  

  고객이 커스텀 결제수단으로 결제 요청을 하면 호출되는 메서드입니다.

• didReceivedCustomPaymentMethodSelected(_:paymentMethodKey:)
  

  고객이 커스텀 결제수단을 선택하면 호출되는 메서드입니다.

• didReceivedCustomPaymentMethodUnselected(_:paymentMethodKey:)
  

  고객이 커스텀 결제수단 선택을 해제하면 호출되는 메서드입니다.

이용약관 위젯 렌더링 상태를 알려주는 delegate입니다.

weak var widgetStatusDelegate: TossPaymentsWidgetStatusDelegate?

• TossPaymentsWidgetStatusDelegate
  

  protocol TossPaymentsWidgetStatusDelegate {
      func didReceivedLoad(_ name: String)
  }
  
• didReceivedLoad(_:)
  

  결제위젯 렌더링이 완료되면 호출되는 메서드입니다.

인스턴스 View의 상태 변화를 알려주는 delegate입니다.

weak var agreementUIDelegate: TossPaymentsAgreementUIDelegate?

• TossPaymentsAgreementUIDelegate
  

  protocol TossPaymentsAgreementUIDelegate {
      func didUpdateHeight(_ widget: AgreementWidget, height: CGFloat)
      func didUpdateAgreementStatus(_ widget: AgreementWidget, agreementStatus: AgreementStatus)
  }
  
• didUpdateHeight(_:height:)
  

  이용약관 View의 높이가 변경되면 호출되는 메서드입니다.

• didUpdateAgreementStatus(_:agreementStatus:)
  

  고객 이용약관 동의 상태를 알려주는 메서드입니다.



• agreementStatus
  

  class AgreementStatus: NSObject, Codable {
      let agreedRequiredTerms: Bool
      let terms: [AgreementTerm]
  }
  
• agreedRequiredTerms
  

  고객이 모든 필수 약관에 동의했는지 알려줍니다.

• terms
  

  개별 약관에 동의했는지 알려줍니다.

  struct AgreementTerm: Codable {
      let id: String
      let agreed: Bool
      let required: Bool
  }
  
• id
  

  약관의 식별자입니다.

• agreed
  

  관의 고객 동의 여부입니다.

• required
  

  약관의 필수 여부입니다.