Skip to content

README.md

Latest commit

 

History

History
253 lines (212 loc) · 9 KB

README.md

File metadata and controls

253 lines (212 loc) · 9 KB

SwiftUI Client App for Gr4vy Swift SDK

Platforms Build Status

Summary

A SwiftUI sample application demonstrating integration with the Gr4vy Swift SDK. This app provides a testing interface for the SDK endpoints with persistent configuration management, including comprehensive 3DS authentication support with customizable UI themes. A UIKit client app is also available.

Architecture

The app uses modern SwiftUI patterns with async/await for API calls calling the Gr4vy Swift SDK directly and @AppStorage for persistent configuration across app sessions.

App Structure

Tab Navigation

  • Home Tab: Main navigation to API endpoint screens
  • Admin Tab: Configuration management panel

API Screens (4 Endpoints)

  1. Payment Options - POST /payment-options

    • Configure metadata, country, currency, amount, locale, and cart items
    • Dynamic metadata key-value pairs
    • Cart items with detailed product information

  2. Card Details - GET /card-details

    • Test card BIN lookup and payment method validation
    • Supports intent, subsequent payments, and merchant-initiated transactions

  3. Payment Methods - GET /buyers/{buyer_id}/payment-methods

    • Retrieve stored payment methods for buyers
    • Sorting and filtering options
    • Buyer identification by ID or external identifier

  4. Tokenize - PUT /tokenize

    • Tokenize payment methods (card or stored payment method ID)
    • 3DS authentication support
    • Test card selection for frictionless and challenge flows
    • Customizable 3DS UI themes (light/dark mode support)
    • SDK timeout configuration
    • Secure payment method storage

Admin Panel

The Admin tab provides centralized configuration for all API calls:

Core Configuration

  • gr4vyId - Your Gr4vy merchant identifier (required)
  • token - API authentication token (required)
  • server - Environment selection (sandbox/production)
  • timeout - Request timeout in seconds (optional)
  • merchantId - Used in payment options requests

How Configuration Works

  • All settings persist across app restarts using @AppStorage
  • Empty timeout field uses SDK default timeout
  • Configuration is shared across all API screens
  • Switch between sandbox and production environments instantly

Key Features

3DS Authentication Support

The Tokenize screen includes comprehensive 3DS authentication features:

  • Authentication Toggle: Enable/disable 3DS authentication
  • Test Cards: Pre-configured test cards for both flows:
    • Frictionless Flow: Cards that complete authentication without challenge (Visa, Mastercard, Amex, Diners, JCB)
    • Challenge Flow: Cards that trigger authentication challenge screens (Visa, Mastercard, Amex, Diners, JCB)
  • UI Customization: Three built-in themes for 3DS challenge screens:
    • Red/Blue theme
    • Orange/Purple theme
    • Green/Yellow theme
    • Each theme supports both light and dark modes
  • Timeout Configuration: Configurable SDK max timeout (in seconds)
  • Enhanced Response Data: Returns authentication details including:
    • tokenized: Whether the payment method was successfully tokenized
    • authentication.attempted: Whether 3DS authentication was attempted
    • authentication.user_cancelled: Whether the user cancelled the authentication
    • authentication.timed_out: Whether the authentication timed out
    • authentication.type: The type of authentication performed
    • authentication.transaction_status: The final status of the 3DS transaction

Async/Await Implementation

All API calls use modern Swift concurrency:

Button("GET") {
    Task {
        await sendRequest()
    }
}

Error Handling

  • SDK error type handling including 3DS-specific errors:
    • threeDSError: 3DS authentication failures
    • uiContextError: UI context-related issues
  • Network error detection and visual messages
  • HTTP status code display with detailed error responses
  • Tappable error messages show full JSON error details

Response Handling

  • Pretty-printed JSON responses
  • Copy/share functionality for debugging
  • Separate navigation for success and error responses

Data Persistence

  • Form data persists between app launches
  • Admin settings stored securely in UserDefaults
  • Complex data structures (metadata, cart items) serialized automatically

Setup Instructions

1. Configure Admin Settings

  • Open the Admin tab
  • Enter your gr4vyId and optional token
  • Select environment
  • Optionally set custom timeout

2. Test API Endpoints

  • Navigate through the Home tab to each API screen
  • Fill in required fields (marked with validation)
  • For Tokenize: Select test cards for 3DS testing (frictionless or challenge flows), choose a theme, and configure authentication settings
  • Tap the action button (GET/POST/PUT) to make requests
  • View responses with authentication details (for 3DS-enabled requests)

3. Development Usage

  • Use as reference implementation for SDK integration
  • Test various parameter combinations
  • Debug API responses with detailed error information

Customization

Adding New Endpoints

  1. Create new view following existing patterns
  2. Add admin settings storage with @AppStorage
  3. Implement async request function with error handling
  4. Add navigation link in HomeView.swift

Modifying UI

  • All views use standard SwiftUI form patterns
  • Consistent styling with ButtonView component
  • Error states handled with red background styling
  • Loading states with ProgressView indicators

3DS UI Customization

The app demonstrates comprehensive 3DS UI theming capabilities:

private func buildRedBlueTheme() -> Gr4vyThreeDSUiCustomizationMap {
    let light = Gr4vyThreeDSUiCustomization(
        label: .init(
            textFontName: "HelveticaNeue",
            textFontSize: 16,
            textColorHex: "#1c1c1e",
            headingTextFontName: "HelveticaNeue-Bold",
            headingTextFontSize: 24,
            headingTextColorHex: "#0a0a0a"
        ),
        toolbar: .init(
            textFontName: "AvenirNext-DemiBold",
            textFontSize: 17,
            textColorHex: "#ffffff",
            backgroundColorHex: "#007aff",
            headerText: "Secure Checkout",
            buttonText: "Cancel"
        ),
        // ... additional customizations
    )
    // Separate dark mode customization
    let dark = Gr4vyThreeDSUiCustomization(...)
    
    return Gr4vyThreeDSUiCustomizationMap(default: light, dark: dark)
}

Customizable elements include:

  • Labels (text font, size, color for both body and heading)
  • Toolbar (font, colors, button text, header text)
  • Text boxes (font, colors, border width, corner radius)
  • View backgrounds (challenge and progress views)
  • Buttons (submit, continue, next, resend, etc. - each with individual styling)

SDK Integration

Basic SDK initialization:

let server: Gr4vyServer = serverEnvironment == "production" ? .production : .sandbox
let timeoutInterval = TimeInterval(Double(timeout) ?? 30.0)

guard let gr4vy = try? Gr4vy(
    gr4vyId: gr4vyID,
    token: trimmedToken, 
    server: server,
    timeout: timeoutInterval,
    debugMode: true
) else {
    errorMessage = "Failed to configure Gr4vy SDK"
    return
}

Tokenize with 3DS authentication:

gr4vy.tokenize(
    checkoutSessionId: checkoutSessionId,
    cardData: cardData,
    sdkMaxTimeoutMinutes: 5,
    authenticate: true,
    uiCustomization: customTheme
) { result in
    switch result {
    case .success(let tokenizeResult):
        // Access tokenizeResult.tokenized and tokenizeResult.authentication
    case .failure(let error):
        // Handle error
    }
}

Requirements

  • iOS 16.0+
  • Xcode 16.0+
  • Swift 5.7+
  • Gr4vy Swift SDK