Android SDK Initialization and Configuration

payabl. Android SDK is initialized through the PayablSDK class using a PBLConfiguration object. The values provided by your (merchant) server during initialization phase are essential for a secure payment session.

PBLConfiguration Parameters

• session_id (string): a unique identifier form the merchant sever used to track and secure the user' payment session.
• ephemeralKey(string): a temporary key valide for 15 minutes. It is used to sign a subsequent API request, replacing the static merchant secret.
• userId (string): a unique identifier referencing the user for customer data management (for example, storing tokens for saved cards).
• environment (string): determines the backend; use production or sandbox appropriately.

Example Initialization:

val payableSdk = PayableSDK.init(
    PBLConfiguration(
        sessionId = "your-session-id",
        ephemeralKey = "your-ephemeral-key",
        userId = "your-user-id",
        environment = "sandbox" // or "production"
    )
)

📘

Note

Once a session is initiated, these parameters remain fixed. A new instance must be created for each distinct payment session.

Detailed Integration Workflow Diagram

The following diagram details the data exchange between a Merchant Android App, Android SDK, Merchant Server and payabl. Payment Gateway.

Payment Flow & Merchant Server Coordination

The complete payment process involves close coordination between the merchant server, the Mobile SDK (within your Android app), and the Payment Gateway. The merchant server is responsible for initializing the payment session and ensuring secure communication via the backend APIs.

Merchant Server Role

1. Session Initialization:
   • Endpoint: POST/mobile/init
   • The merchant server sends a request with details such as merchant_id, amount, currency, email, and signed signature (using the merchant ID's secret).
   • Response: Returns a session_id, an ephemeralKey, and a transaction_id — all of whih are critical for further interactions.
2. Coordinated Payment Process
   • Once the merchant server completes the initialization, the Android app proceeds to initialize the SDK with the returned session_id and ephemeralKey.
   • The payment flow continues with the SDK launching the payment UI, handling user inputs, and displaying the appropriate status (competed, canceled or error).

Launching the Payment Flow

The payment process within the Android app is initiated through the SDK's start() method using the Fragment API.

payableSdk.start(supportFragmentManager) { result ->
    when(result) {
        is PBLPaymentResult.Completed -> {
            // Process the successful payment result (access status and transactionStatus)
        }
        PBLPaymentResult.Canceled -> {
            // Handle cancellation scenario
        }
        is PBLPaymentResult.Failed -> {
            // Process error cases, e.g., network or configuration issues.
        }
    }
}