Quick Start: Accept Your First Card Payment

This tutorial walks you through integrating the Payrails Android SDK from scratch. By the end, you'll have a working card payment form in a Compose screen.

Time: ~15 minutes Prerequisites: Android project with Jetpack Compose, JDK 17, minSdk 21, compileSdk 34

Step 1: Add Dependencies

The SDK is distributed via Maven Central
In your app-level build.gradle.kts:

dependencies {
    implementation("com.payrails.checkout:android-sdk:<version>")
    implementation("com.payrails.android:cse:<version>")
}

Sync your project.

Step 2: Fetch an Init Payload From Your Backend

The SDK requires an initialization payload from the Payrails API. Your backend should call the Payrails client-init endpoint and return the version and data fields.

// Replace with your actual backend call
data class InitPayload(val version: String, val data: String)

suspend fun fetchInitPayloadFromBackend(): InitPayload {
    // Call your backend → Payrails client-init endpoint
    // Return the version and data from the response
    TODO("Implement your backend call")
}

Step 3: Initialize the SDK Session

Create a session before rendering any payment UI. This is typically done in your Activity or ViewModel.

import com.payrails.sdk.Configuration
import com.payrails.sdk.InitData
import com.payrails.sdk.Options
import com.payrails.sdk.Payrails

suspend fun initializePayrails(): Session {
    val payload = fetchInitPayloadFromBackend()
    val configuration = Configuration(
        initData = InitData(version = payload.version, data = payload.data),
        option = Options()
    )
    return Payrails.createSession(configuration)
}

Step 4: Build the Card Payment Screen

Create a Composable that renders a card form and a pay button:

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.ui.unit.dp
import com.payrails.sdk.*

@Composable
fun CardPaymentScreen(activity: Activity) {
    // 1. Create a payment presenter for 3DS handling
    val presenter = remember(activity) {
        Payrails.createBrowserPaymentPresenter(activity)
    }

    // 2. Create the card form
    val cardForm = remember {
        Payrails.createCardForm(
            config = CardFormConfig(
                showCardHolderName = true,
                showSingleExpiryDateField = true
            )
        )
    }

    // 3. Create the pay button
    val payButton = remember {
        Payrails.createCardPaymentButton(
            translations = CardPaymenButtonTranslations(label = "Pay Now")
        )
    }

    // 4. Wire up the presenter and delegate
    payButton.presenter = presenter
    payButton.delegate = object : PayrailsCardPaymentButtonDelegate {
        override fun onPaymentButtonClicked(button: CardPaymentButton) {
            // Payment started
        }
        override fun onAuthorizeSuccess(button: CardPaymentButton) {
            // Payment succeeded — show confirmation
        }
        override fun onThreeDSecureChallenge(button: CardPaymentButton) {
            // 3DS challenge opened in browser
        }
        override fun onAuthorizeFailed(button: CardPaymentButton) {
            // Payment failed — show error
        }
    }

    // 5. Render the UI
    Column(verticalArrangement = Arrangement.spacedBy(12.dp)) {
        cardForm.Render()
        payButton.Render()
    }
}

Step 5: Handle Payment Results

The delegate callbacks tell you what happened:

Callback	Meaning	What to do
`onPaymentButtonClicked`	User tapped "Pay Now"	Show loading state (SDK handles button state automatically)
`onAuthorizeSuccess`	Payment authorized	Navigate to confirmation screen, verify on your backend
`onThreeDSecureChallenge`	3DS challenge started	Browser opens automatically — no action needed
`onAuthorizeFailed`	Payment failed	Show error message, allow retry

Step 6: Test It

Use your Payrails sandbox environment and test card numbers to verify the integration. The card form validates input automatically — you'll see inline error messages for invalid card numbers, expiry dates, and CVV codes.