Instrukcja konfiguracji SDK mobile Tpay dla systemu iOS

Ostatnia aktualizacja: 21.11.2024

WSTĘP

Biblioteka mobilna dla systemu iOS umożliwia wykonanie płatności wewnątrz aplikacji mobilnej sklepu bez konieczności przełączania użytkownika między aplikacją a przeglądarką lub inną aplikacją. 

W bibliotece dostępne są następujące metody płatności: 

  1. Przelewy bankowe 
  2. Karty płatnicze
  3. Apple Pay
  4. BLIK

INSTALACJA 

Upewnij się, że framework Tpay został zaimportowany do twojego projektu. Możesz to zrobić, dodając wiersz na górze pliku Swift:

import Tpay

Instalacji możesz dokonać na trzy różne sposoby: 

 

  1. Przy użyciu Swift Package Manager
    File > Swift Packages > Add Package Dependency
Add https://github.com/tpay-com/tpay-sdk-ios.git
Select "Up to Next Major" with "1.0.0"
  2. Przy użyciu CocoaPods
    use_frameworks!
target :MyTarget do
pod 'Tpay'
end

    Po utworzeniu pliku użyj komendypod install.

  3. Ręcznie, pobierając pliki z naszego repozytorium na GitHub

    Plik Tpay.xcframeworkumieść wFrameworks, Libraries and Embedded Content w swoim projekcie.

     

UPRAWNIENIA

Moduł Tpay umożliwia użytkownikowi automatyczne wypełnienie formularza karty płatniczych za pośrednictwem aparatu fotograficznego, w celu bezpiecznego przetwarzania płatności. Ta funkcja wymaga skonfigurowania opcji Prywatność — opis użycia aparatu w pliku Info.plist aplikacji.

 

Ważne, aby użytkownik nadał te uprawnienia w swoim urządzeniu. 

 

  1. Otwórz plik Info.plistw swoim projekcie. 
  2. Dodaj wartość klucza do uprawnienia Privacy - Camera Usage Description w celu dostępu do kamery. Należy wyraźnie zaznaczyć, że kamera służy do automatycznego wypełniania formularza kart płatniczych w celu bezpiecznego przetwarzania płatności.

KONFIGURACJA 

  1. Utwórz instancjęMerchant.Authorizationwraz z danymi Sprzedawcy* 
    let authorization = Merchant.Authorization(clientId: "your_client_id", clientSecret: "your_client_secret")

    * dane znajdziesz w Panelu Akceptanta w zakładce Integracje -> API w sekcji Klucze do nowego Open API.

  2. Utwórz instancjęMerchant, łącząc z innymi opcjonalnymi konfiguracjami, np. CardsConfiguration, blikConfiguration.

    Oto przykład tworzenia podstawowej konfiguracji sprzedawcy:

    let merchant = Merchant(authorization: authorization)

    Instancję Merchantmożesz dostosować dowolnie na podstawie wymagań swojej aplikacji.

     

    Użyj metodyconfigure(merchant:), aby ustawić konfigurację sprzedawcy w ramach Tpay SDK:

    do {
    try TpayModule.configure(merchant: merchant)
    // Configuration successful
} catch {
    // Handle configuration errors
}

     

  3. Utwórz typ zgodny z protokołemMerchantDetailsProvider, implementując jego wymagane metody. Podaj lokalizację dla każdej informacji. 

    Dane pojawią się na ekranie modułu Tpay i są niezbędne do spełnienia wymogów RODO. 

    class MyMerchantDetailsProvider: MerchantDetailsProvider {
    func merchantDisplayName(for language: Language) -> String {
        // Return the merchant's display name based on the specified language
    }

    func merchantHeadquarters(for language: Language) -> String? {
        // Return the merchant's headquarters location based on the specified language
    }

    func regulationsLink(for language: Language) -> URL {
        // Return the URL to the regulations page based on the specified language
    }
}

     

  4. Użyj metodyconfigure(merchantDetailsProvider:), aby skonfigurować dane Sprzedawcy.
    TpayModule.configure(merchantDetailsProvider: myMerchantDetailsProvider)

     

  5. Stwórz tablice z wybranymi metodami płatności. 

    Ustaw metody płatności, które chcesz oferować swoim klientom.  
    let paymentMethods: [PaymentMethod] = [.card, .blik, .digitalWallet(.applePay)]

    Co oznaczają poszczególne pola?

    • .card–karty płatnicze
    • .blik– blik LVL 0
    • .digitalWallet(.applePay) – portfele wirtualne np. Apple Pay
  6. Użyj metody configure(paymentMethods:), aby skonfigurować wybrane metody płatności. 
    do {
    try TpayModule.configure(paymentMethods: paymentMethods)
    // Configuration successful
} catch {
    // Handle configuration errors
}

    Ważne: SDK domyślnie ustawia wszystkie metody płatności jako dostępne. 

  7. Użyj metodyconfigure(preferredLanguage:supportedLanguages:)  w celu skonfigurowania języka. 
    do {
    try TpayModule.configure(preferredLanguage: .en, supportedLanguages: .allCases)
    // Configuration successful
} catch {
    // Handle configuration errors
}

    Moduł obsługuje język polski (jako domyślny) i angielski.

  8. Aby zwiększyć poziom bezpieczeństwa, przypnij certyfikat SSL. Utwórz protokół SSLCertificatesProvider, następnie dodaj go do metody configure(sslCertificatesProvider:) 
    [

TpayModule.configure(sslCertificatesProvider: sslProvider)
  9. Przed dalszą implementacją zalecamy użycie metody sprawdzającej poprawność konfiguracji. Możesz łączyć ze sobą wiele metod konfiguracji. 
    do {
    try TpayModule.configure(merchant: merchant)
        .configure(paymentMethods: paymentMethods)
        .configure(sslCertificatesProvider: sslProvider)
        .configure(merchantDetailsProvider: detailsProvider)
        .configure(preferredLanguage: .en, supportedLanguages: [.en, .pl])
    // Configuration chain completed successfully
} catch {
    // Handle configuration errors
}

let configurationCheckResult = TpayModule.checkConfiguration()

switch configurationCheckResult {
case .valid:
    // Configuration is complete and valid, proceed with payment processes
case .invalid(let error):
    // Configuration is invalid, handle the specific error accordingly
}

    Po poprawnej weryfikacji konfiguracji możesz przejść do implementacji płatności. 

PŁATNOŚCI

  1. Utwórz transakcje wykorzystując strukturę SingleTransaction  określając jej kwotę oraz opis. 
    let singleTransaction = SingleTransaction(amount: 50.0, description: "Product Purchase")
    • automaticPaymentMethods - do automatycznych metod płatności możesz użyć zarejestrowanego alias BLIK lub tokenizacji karty. Jeśli chcesz wykonać standardową płatność, użyj wartości: nil.Do transakcji możesz dodać dane płatnika oraz automatyczne metody płatności. Te dane możesz przesłać podczas generowania transakcji. 

  2. Jeśli zamierzasz przyjmować cykliczne płatności kartami płatniczymi, utwórz instancję RecursiveTransactionwraz z określeniem parametrów tj. częstotliwość, ilość i data ważności. 

    let recursiveTransaction = RecursiveTransaction(
wrapping: singleTransaction,
frequency: .monthly,
quantity: .count(5),
expiryDate: futureDate)

    Co oznaczają poszczególne pola?

    • wrapping- singleTransaction
    • frequency- częstotliwość: daily / monthly / quarterly / weekly / yearly
    • quantity- ilość przyjmowanych płatności 
    • expiryDate- data wygaśnięcia płatności 

     

  3. Zaprezentuj metody płatności w swoim projekcie za pomocą klasySheet

    Utwórz instancję klasySheet, następnie zainicjuj ją obiektemTransactionoraz PaymentDelegate

    let paymentSheet = Payment.Sheet(transaction: transaction, delegate: delegate)

    Użyj metodypresent(from:) do zaprezentowania metod płatności

    do {
    try paymentSheet.present(from: presentingViewController)
} catch {
    // Handle configuration errors or other exceptions
}

    W celu zamknięcia prezentacji metod płatności, wywołaj metodę

    dismiss()

paymentSheet.dismiss()
  4. Dodaj widok za pośrednictwem SwiftUI.

TOKENIZACJA KART PŁATNICZYCH

Tokenizacja kart jest konieczna do rejestracji karty płatniczych bez inicjalizacji transakcji płatniczej, dzięki czemu klienci mogą dokonywać kolejnych płatności w sklepie bez ponownego podawania danych kart lub rozpocząć cykliczne płatności w sklepie. 

 

  1. Utwórz instancję klasySheet, następnie zainicjuj ją obiektemPayeroraz AddCardDelegate
    let addCardSheet = AddCard.Sheet(payer: payer, delegate: delegate)

  2. Użyj metody present(from:)do zaprezentowania metod płatności

    do {
    try addCardSheet.present(from: presentingViewController)
} catch {
    // Handle configuration errors or other exceptions
}
  3. W celu zamknięcia prezentacji metod płatności, wywołaj metodę 
    dismiss()

paymentSheet.dismiss()
  4. Dodaj widok za pośrednictwem SwiftUI.
    struct ContentView: View {
    @State private var isTokenizationSheetPresented = false

    var body: some View {
        Button("Add Card") {
            isTokenizationSheetPresented.toggle()
        }
        .presentCardTokenizationSheet(isPresented: $isTokenizationSheetPresented) {
            // Handle card tokenization completed
        } onTokenizationCancelled: {
            // Handle card tokenization cancelled
        } onErrorOccured: { error in
            // Handle tokenization error
        }
    }
}

PŁATNOŚCI AUTOMATYCZNE

Płatność OneClick kartą płatniczą

 

Tpay SDK umożliwia rejestrację karty płatniczych bez inicjalizacji transakcji płatniczej, dzięki czemu klienci mogą dokonywać kolejnych płatności w sklepie bez ponownego podawania danych kart lub rozpocząć cykliczne płatności w sklepie. 

Do obsługi tej funkcjonalności konieczne jest poprawnie przyjmowanie powiadomień z systemu Tpay. Szczegóły jak poprawnie odbierać powiadomienia znajdziesz w dokumentacji OpenAPI.

 

  1. Do tokenizowanej karty każdego płatnika utwórz instancjęCardTokeni przekaż ją za pomocąPayerContext.
    let card = CardToken(
token: token, 
cardTail: tail, 
brand: brand)
let payerContext = PayerContext(
payer: payer,
     automaticPaymentMethods: .init(tokenizedCards: [card]))

 

Płatność OneClick BLIK

Aby udostępnić swoim klientom funkcjonalność BLIK OneClick, w pierwszej kolejności  zdefiniuj alias, który będzie rejestrowany w systemie BLIK, gdy użytkownik wyrazi na to zgodę.

  1. Dane podaj konfigurując swojego Sprzedawcę za pomocą

    Merchant.BlikConfiguration
    let blikConfiguration = Merchant.BlikConfiguration(aliasToBeRegistered: .init(value: .uid("myBlikAlias")))
let merchant = Merchant(authorization: authorization, blikConfiguration: blikConfiguration)

    Co oznacza to pole?

    • myBlikAlias - wartość aliasu BLIK
  2. Po otrzymaniu powiadomienia rejestracji aliasu (sekcja Powiadomienia w dokumentacji OpenAPI) możesz przekazać te dane wraz zPayerContext.
    let blikAlias = RegisteredBlikAlias(value: .uid(retrievedAlias))
let payerContext = PayerContext(
payer: payer,
     automaticPaymentMethods: .init(registeredBlikAlias: blikAlias))