Instrukcja konfiguracji SDK mobile Tpay dla systemu iOS

Ostatnia aktualizacja: 29.03.2025

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:

Example:
Skopiuj link do tej sekcji
Skopiuj kod
import Tpay

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

  1. Przy użyciu Swift Package Manager
    Example:
    Skopiuj link do tej sekcji
    Skopiuj kod
    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
    Example:
    Skopiuj link do tej sekcji
    Skopiuj kod
    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*
    Example:
    Skopiuj link do tej sekcji
    Skopiuj kod
    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:

    Example:
    Skopiuj link do tej sekcji
    Skopiuj kod
    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:

    Example:
    Skopiuj link do tej sekcji
    Skopiuj kod
    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.

    Example:
    Skopiuj link do tej sekcji
    Skopiuj kod
    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.
    Example:
    Skopiuj link do tej sekcji
    Skopiuj kod
    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.
    Example:
    Skopiuj link do tej sekcji
    Skopiuj kod
    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.
    Example:
    Skopiuj link do tej sekcji
    Skopiuj kod
    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.
    Example:
    Skopiuj link do tej sekcji
    Skopiuj kod
    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:)
    Example:
    Skopiuj link do tej sekcji
    Skopiuj kod
    [

TpayModule.configure(sslCertificatesProvider: sslProvider)
  9. Przed dalszą implementacją zalecamy użycie metody sprawdzającej poprawność konfiguracji. Możesz łączyć ze sobą wiele metod konfiguracji.
    Example:
    Skopiuj link do tej sekcji
    Skopiuj kod
    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.
    Example:
    Skopiuj link do tej sekcji
    Skopiuj kod
    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.

    Example:
    Skopiuj link do tej sekcji
    Skopiuj kod
    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

    Example:
    Skopiuj link do tej sekcji
    Skopiuj kod
    let paymentSheet = Payment.Sheet(transaction: transaction, delegate: delegate)

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

    Example:
    Skopiuj link do tej sekcji
    Skopiuj kod
    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ę

    Example:
    Skopiuj link do tej sekcji
    Skopiuj kod
    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
    Example:
    Skopiuj link do tej sekcji
    Skopiuj kod
    let addCardSheet = AddCard.Sheet(payer: payer, delegate: delegate)

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

    Example:
    Skopiuj link do tej sekcji
    Skopiuj kod
    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ę
    Example:
    Skopiuj link do tej sekcji
    Skopiuj kod
    dismiss()

paymentSheet.dismiss()
  4. Dodaj widok za pośrednictwem SwiftUI.
    Example:
    Skopiuj link do tej sekcji
    Skopiuj kod
    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.
    Example:
    Skopiuj link do tej sekcji
    Skopiuj kod
    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ą

    Example:
    Skopiuj link do tej sekcji
    Skopiuj kod
    Merchant.BlikConfiguration
    Example:
    Skopiuj link do tej sekcji
    Skopiuj kod
    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.
    Example:
    Skopiuj link do tej sekcji
    Skopiuj kod
    let blikAlias = RegisteredBlikAlias(value: .uid(retrievedAlias))
let payerContext = PayerContext(
payer: payer,
     automaticPaymentMethods: .init(registeredBlikAlias: blikAlias))

Chcesz o coś zapytać?

Odpowiemy na Twoje pytanie najszybciej jak to możliwe.

+48 61 66 82 778
info@tpay.com
Skontaktuj się