SDK 추가
PaymentWidget
AgreementWidget
- widgetStatusDelegate
- agreementUIDelegate

결제위젯 iOS SDK

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

샘플 프로젝트토스페이먼츠 iOS SDK 샘플 프로젝트를 확인하세요.

SDK 추가

요구 사항

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

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

CocoaPods로 설치하기

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

Podfile

pod 'TossPayments'

Swift Package Manager(SPM)로 설치하기

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 섹션에 결제위젯 패키지가 추가된 것을 확인하세요.

PaymentWidget

토스페이먼츠 결제위젯입니다.

init(clientKey:customerKey:)

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

파라미터

clientKey
API 키 메뉴에서 확인할 수 있는 결제위젯 연동 키 > 클라이언트 키입니다.
customerKey
고객 ID입니다. 다른 사용자가 이 값을 알게 되면 악의적으로 사용될 수 있습니다. 자동 증가하는 숫자 또는 이메일・전화번호・사용자 아이디와 같이 유추가 가능한 값은 안전하지 않습니다. UUID와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 영문 대소문자, 숫자, 특수문자 -, _, =, ., @ 를 최소 1개 이상 포함한 최소 2자 이상 최대 50자 이하의 문자열이어야 합니다.
비회원 결제에는 PaymentWidget.ANONYMOUS를 사용하세요.

options

결제위젯 옵션입니다.

struct Options {
    let brandPay: BrandPay?
}

brandpay
결제위젯에 브랜드페이를 추가할 때 설정합니다. redirectUrl은 Access Token 발급 과정에서 임시 인증 코드를 받을 URL입니다.
```
struct BrandPay {
    let redirectURL: String
}
```

renderPaymentMethods(amount:options:)

결제 UI를 렌더링하는 메서드입니다.

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의 키 값을 넣으세요.

updateAmount(_:)

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

func updateAmount(_ amount: Double)

파라미터

amount
새로운 결제 금액입니다.

getSelectedPaymentMethod()

결제위젯에서 선택된 결제수단을 확인하는 메서드입니다.

getSelectedPaymentMethod() -> WidgetPaymentMethod?

응답

public struct WidgetPaymentMethod: Codable {
    let type: PaymentMethodType
    let method: PaymentMethod
    let easyPay: EasyPay?
    let paymentMethodKey: String?
}

type
결제 타입 정보입니다. NORMAL(일반결제), BRANDPAY(브랜드페이), KEYIN(키인 결제), CUSTOM(커스텀 결제수단) 중 하나입니다.
method
결제수단입니다. 카드, 가상계좌, 간편결제, 휴대폰, 계좌이체, 문화상품권, 도서문화상품권, 게임문화상품권 중 하나입니다.
easyPay
결제수단이 간편결제일 때 반환되는 간편결제 정보입니다.
provider
선택한 간편결제사 코드입니다.
paymentMethodKey
결제 타입이 CUSTOM일 때 반환되는 커스텀 결제수단 키입니다.

requestPayment(info:)

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

func requestPayment(info: DefaultWidgetPaymentInfo)

파라미터

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를 구현한 객체를 선언해서 사용할 수 있습니다.

renderAgreement()

이용약관 UI를 렌더링하는 메서드입니다. 이용약관 UI에는 토스페이먼츠의 필수 이용약관이 있습니다. 결제위젯 어드민에서 내 상점의 필수 약관, 회원·비회원 약관, 영문 약관 등 약관을 자유롭게 커스터마이징할 수 있습니다. 이용약관 위젯을 반환합니다.

func renderAgreement() -> AgreementWidget

delegate

결제 승인 결과를 알려주는 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
브랜드페이를 사용하고 있다면 필요한 파라미터입니다.
paymentType
결제 유형입니다. NORMAL, BRANDPAY, KEYIN 중 하나입니다.
- NORMAL: 일반 결제입니다. 코어 결제 승인 API를 호출해서 결제를 완료하세요.
- BRANDPAY: 브랜드페이 결제입니다. 브랜드페이 결제 승인 API를 호출해서 결제를 완료하세요.
- KEYIN: 키인 결제입니다. 코어 결제 승인 API를 호출해서 결제를 완료하세요.
Fail
결제 실패 결과 정보입니다.
errorCode
에러 코드입니다. SDK 에러가 돌아옵니다. failUrl로 전달되는 에러, 공통 SDK 에러, 결제위젯 SDK 에러가 모두 포함됩니다.
errorMessage
에러 메시지입니다.
orderId
주문 ID입니다. 결제 요청에 담아 보낸 값입니다.

widgetStatusDelegate

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

weak var widgetStatusDelegate: TossPaymentsWidgetStatusDelegate?

TossPaymentsWidgetStatusDelegate

protocol TossPaymentsWidgetStatusDelegate {
    func didReceivedLoad(_ name: String)
    func didReceiveFail(_ name: String, fail: TossPaymentsResult.Fail)
}

didReceivedLoad(_:)
결제 UI 렌더링이 완료되면 호출되는 메서드입니다.
didReceiveFail(_:)
구매자가 결제 정보(카드사 선택, 계좌번호 등)를 입력하지 않으면 호출되는 메서드입니다. NEED_CARD_PAYMENT_DETAIL, NEED_REFUND_ACCOUNT_DETAIL 에러를 안내합니다.
결제 UI에 자동으로 에러 안내가 나타나지만 세로로 긴 화면에서는 구매자가 문제를 인식하기 어렵습니다. 반드시 해당 메서드를 사용해서 구매자에게 에러를 안내해주세요.

widgetUIDelegate

인스턴스 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:)
고객이 커스텀 결제수단 선택을 해제하면 호출되는 메서드입니다.

AgreementWidget

이용약관 UI입니다.

widgetStatusDelegate

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

weak var widgetStatusDelegate: TossPaymentsWidgetStatusDelegate?

TossPaymentsWidgetStatusDelegate

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

didReceivedLoad(_:)
결제 UI 렌더링이 완료되면 호출되는 메서드입니다.

agreementUIDelegate

인스턴스 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
약관의 필수 여부입니다.

.css-p1o082{width:calc(0.8em + 8px);height:0.8em;position:absolute;top:calc(50% - 0.4em);left:calc(-0.8em - 8px);padding-right:8px;opacity:0;-webkit-transition:opacity 0.2s ease-in-out;-webkit-transition:opacity 0.2s ease-in-out;transition:opacity 0.2s ease-in-out;}결제위젯 iOS SDK

요구 사항

CocoaPods로 설치하기

Swift Package Manager(SPM)로 설치하기

PaymentWidget

init(clientKey:customerKey:)

파라미터

renderPaymentMethods(amount:options:)

파라미터

updateAmount(_:)

파라미터

getSelectedPaymentMethod()

응답

requestPayment(info:)

파라미터

renderAgreement()

delegate

TossPaymentsDelegate

TossPaymentResult

widgetStatusDelegate

TossPaymentsWidgetStatusDelegate

widgetUIDelegate

TossPaymentsWidgetUIDelegate

AgreementWidget

widgetStatusDelegate

TossPaymentsWidgetStatusDelegate

agreementUIDelegate

결제위젯 iOS SDK