결제위젯 iOS SDK

결제위젯 iOS SDK는 iOS 환경에서 사용할 수 있는 결제위젯 메서드를 제공합니다. SDK를 추가하고 메서드를 사용하는 방법을 알아봅니다.

결제위젯 iOS SDK를 설치하기 전에 최소 요구 사항을 확인하세요.

• iOS 11.0 이상
• Swift 5.0 이상
• Xcode 12.5.1 이상

프로젝트 폴더에 있는 Podfile에 아래와 같이 토스페이먼츠 결제위젯 iOS SDK를 추가하세요. Podfile을 저장하고 pod install 커맨드를 실행하세요.

pod 'TossPayments'

Xcode 프로젝트에서 1. Project Target > 2. Package Dependencies로 이동하세요. Packages 섹션 하단에 있는 3. + 버튼을 누르세요.

패키지를 추가하는 창이 열리면 아래 URL로 4. 결제위젯 패키지를 검색하세요. 패키지를 확인하고 5. Add Packages 버튼을 누르세요.

https://github.com/tosspayments/payment-sdk-ios.git

결제위젯 iOS SDK가 설치되었습니다. Packages 섹션에 결제위젯 패키지가 추가된 것을 확인하세요.

토스페이먼츠 위젯입니다. iOS SDK는 결제위젯 이용약관 메서드를 제공하지 않습니다.

class PaymentWidget : WKWebView 

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

• clientKey
  

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

• customerKey
  

  고객 ID입니다. 충분히 무작위한 값을 직접 생성해서 사용하세요. 비회원 결제에는 PaymentWidget.ANONYMOUS를 사용하세요.

• options
  

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

• brandpay
  

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

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

weak var delegate: TossPaymentsDelegate?

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

weak var widgetUIDelegate: TossPaymentsWidgetUIDelegate?

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

func renderPaymentMethods(amount: Double)

• amount
  

  결제할 금액입니다.

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

func updateAmount(_ amount: Double)

• amount
  

  새로운 결제 금액입니다.

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

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

• info
  

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

• rootViewController
  

  결제창의 UIViewController입니다.

PaymentWidget의 delegate입니다. 결제 승인 결과를 알려줍니다.

protocol TossPaymentsDelegate {
    func handlePaymentSuccessResult(_ success: TossPaymentsResult.Success)
    func handlePaymentFailResult(_ fail: TossPaymentsResult.Fail)
}

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

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

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

protocol TossPaymentsWidgetUIDelegate {
    func didUpdateHeight(_ widget: PaymentWidget, height: CGFloat)
}

결제위젯 View의 높이가 변경되면 호출되는 메서드입니다.

requestPayment() 메서드의 파라미터로 사용되는 결제 정보 Codable입니다.

protocol WidgetPaymentInfo: Codable {
    var orderId: String
    var orderName: String
    var customerName: String?
    var customerEmail: String?
    var taxFreeAmount: Double?
}

• orderId
  

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

• orderName
  

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

• customerKey
  

  고객 ID입니다. 충분히 무작위한 값을 직접 생성해서 사용하세요. 빌링키와 연결됩니다. 영문 대소문자, 숫자, 특수문자 -, _, =, ., @로 이루어진 최소 2자 이상 최대 300자 이하의 문자열입니다.

• customerName
  

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

• customerEmail
  

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

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

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

결제 결과 정보를 담고 있는 Enumeration입니다.

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
    }
}

• paymentKey
  

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

• orderId
  

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

• amount
  

  결제 금액입니다.

• additionalParmeters
  

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

• paymentType
  

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

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

• errorCode
  

  에러 코드입니다.

• errorMessage
  

  에러 메시지입니다.

• orderId
  

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