결제위젯 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 섹션에 결제위젯 패키지가 추가된 것을 확인하세요.
토스페이먼츠 결제위젯입니다.
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}
결제 UI를 렌더링하는 메서드입니다.
func renderPaymentMethods(
amount: PaymentMethodWidget.Amount,
options: PaymentMethodWidget.Options? = nil
) -> PaymentMethodWidget
- amount
결제 금액 정보입니다. 결제 금액, 통화, 국가 정보가 들어가는
PaymentMethodWidget.Amount
입니다.struct Amount: Encodable {let value: Doublelet 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의 키 값을 넣으세요.
변경된 결제 금액을 UI에 업데이트하는 메서드입니다.
func updateAmount(_ amount: Double)
- amount
새로운 결제 금액입니다.
결제위젯에서 선택된 결제수단을 확인하는 메서드입니다.
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
일 때 반환되는 커스텀 결제수단 키입니다.
고객이 선택한 결제수단의 결제창을 띄우는 메서드입니다.
func requestPayment(info: DefaultWidgetPaymentInfo)
- info
결제 정보가 담긴
DefaultWidgetPaymentInfo
입니다.protocol DefaultWidgetPaymentInfo: Codable {var orderId: Stringvar orderName: Stringvar taxExemptionAmount: String?var appScheme: String?var customerName: String?var customerEmail: String?var taxFreeAmount: Double?var cultureExpense: Boolvar customerMobilePhone: String?var showCustomerMobilePhone: String?var useEscrow: Boolvar 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
를 구현한 객체를 선언해서 사용할 수 있습니다.
이용약관 UI를 렌더링하는 메서드입니다. 이용약관 UI에는 토스페이먼츠의 필수 이용약관이 있습니다. 결제위젯 어드민에서 내 상점의 필수 약관, 회원·비회원 약관, 영문 약관 등 약관을 자유롭게 커스터마이징할 수 있습니다. 이용약관 위젯을 반환합니다.
func renderAgreement() -> AgreementWidget
결제 승인 결과를 알려주는 delegate입니다.
weak var delegate: TossPaymentsDelegate?
protocol TossPaymentsDelegate {
func handleSuccessResult(_ success: TossPaymentsResult.Success)
func handleFailResult(_ fail: TossPaymentsResult.Fail)
}
- handleSuccessResult(_:)
결제가 성공하면 호출되는 메서드입니다.
TossPaymentsResult.Success
를 전달합니다.TossPaymentsResult.Success
로 돌아온 결제 정보를 검증하고, 결제 승인을 요청하세요. - handleFailResult(_:)
결제가 실패하면 호출되는 메서드입니다.
TossPaymentsResult.Fail
을 전달합니다.
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입니다. 결제 요청에 담아 보낸 값입니다.
결제위젯의 렌더링 상태를 알려주는 delegate입니다.
weak var widgetStatusDelegate: 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에 자동으로 에러 안내가 나타나지만 세로로 긴 화면에서는 구매자가 문제를 인식하기 어렵습니다. 반드시 해당 메서드를 사용해서 구매자에게 에러를 안내해주세요.
인스턴스 View의 상태 변화를 알려주는 delegate입니다.
weak var widgetUIDelegate: 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:)
고객이 커스텀 결제수단 선택을 해제하면 호출되는 메서드입니다.
이용약관 UI입니다.
이용약관 UI 렌더링 상태를 알려주는 delegate입니다.
weak var widgetStatusDelegate: TossPaymentsWidgetStatusDelegate?
protocol TossPaymentsWidgetStatusDelegate {
func didReceivedLoad(_ name: String)
}
- didReceivedLoad(_:)
결제 UI 렌더링이 완료되면 호출되는 메서드입니다.
인스턴스 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: Boollet terms: [AgreementTerm]}
- agreedRequiredTerms
고객이 모든 필수 약관에 동의했는지 알려줍니다.
- terms
개별 약관에 동의했는지 알려줍니다.
struct AgreementTerm: Codable {let id: Stringlet agreed: Boollet required: Bool} - id
약관의 식별자입니다.
- agreed
약관의 고객 동의 여부입니다.
- required
약관의 필수 여부입니다.