SDK API Reference

val initData = InitData(version = "...", data = "...")
val configuration = Configuration(initData = initData, option = Options())

// Suspend API
val session = Payrails.createSession(configuration)

// Callback API
Payrails.createSession(configuration) { result ->
    result.onSuccess { /* session ready */ }
    result.onFailure { /* initialization failed */ }
}

// Java — use the callback API (suspend functions are not callable from Java)
InitData initData = new InitData("...", "...");
Configuration configuration = new Configuration(initData, new Options());

Payrails.createSession(configuration, result -> {
    if (result.isSuccess()) {
        Session session = result.getOrNull();
        // session ready
    } else {
        // initialization failed
    }
    return kotlin.Unit.INSTANCE;
});

val configuration = Configuration(
    initData = initData,
    option = Options(
        redirectSessionLifecycle = RedirectSessionLifecycle(
            onSessionExpired = {
                // Merchant callback: run your client-init call and return fresh init payload
                val refreshed = fetchInitPayloadFromBackend()
                InitData(version = refreshed.version, data = refreshed.data)
            }
        )
    )
)

val session = Payrails.createSession(configuration)
val instruments = session.getStoredInstruments()
val cardInstruments = session.getStoredInstruments(forType = PaymentMethod.card)

fun <T> query(key: PayrailsQuery<T>): T

val executionId: String? = session.query(PayrailsQuery.ExecutionId)
val amount: PayrailsAmount? = session.query(PayrailsQuery.Amount)
val cardConfig: PayrailsPaymentMethodConfig? =
    session.query(PayrailsQuery.PaymentMethodConfig("card"))

data class PayrailsAmount(
    val value: String,
    val currency: String
)

data class PayrailsLink(
    val href: String?,
    val method: String?
)

data class PayrailsPaymentMethodConfig(
    val paymentMethodCode: String,
    val description: String?,
    val displayName: String?,
    val flow: String?,
    val supportsSaveInstrument: Boolean?,
    val supportsBillingInfo: Boolean?
)

fun update(changes: PayrailsUpdate)

session.update(
    PayrailsUpdate(
        amount = AmountUpdate(value = "54.98", currency = "EUR")
    )
)
cardPaymentButton.pay() // uses the updated amount

data class PayrailsUpdate(
    val amount: AmountUpdate? = null
)

suspend fun isGooglePayAvailable(context: Context): Boolean

sealed class ActionResult {
    data object Success : ActionResult()
    data class Failed(val failure: AuthorizationFailure) : ActionResult()
}

data class AuthorizationFailure(
    val code: AuthorizationFailureReason,
    val message: String,
    val rawError: Throwable? = null,
)

enum class AuthorizationFailureReason(val code: String) {
    AUTHORIZATION_ERROR, AUTHENTICATION_ERROR, USER_CANCELLED, UNKNOWN_ERROR, VALIDATION_FAILED
}

fun getPaymentMethodConfig(
    filter: PaymentMethodFilter = PaymentMethodFilter.All
): List<PayrailsPaymentOption>

sealed class PaymentMethodFilter {
    object All : PaymentMethodFilter()
    object Redirect : PaymentMethodFilter()
    data class Specific(val paymentMethodCode: String) : PaymentMethodFilter()
}

val redirects = session.getPaymentMethodConfig(PaymentMethodFilter.Redirect)
redirects.forEach { option ->
    // option.paymentMethodCode, option.displayName
}

data class AmountUpdate(
    val value: String,
    val currency: String
)

class PayrailsPaymentLauncher {
    fun authorize(
        type: PaymentMethod,
        paymentMethodCode: String? = null,
        saveInstrument: Boolean = false
    )

    fun authorize(storedInstrument: StoredInstrument)

    fun authorize(
        encryptedCardData: String,
        saveInstrument: Boolean = false
    )
}

@Composable
fun rememberPayrailsPaymentLauncher(
    session: Session,
    onResult: (ActionResult) -> Unit
): PayrailsPaymentLauncher

fun Payrails.createPaymentLauncher(
    activity: ComponentActivity,
    session: Session,
    onResult: (ActionResult) -> Unit
): PayrailsPaymentLauncher

@Composable
fun CheckoutScreen(session: Session) {
    var status by remember { mutableStateOf<ActionResult?>(null) }
    val launcher = rememberPayrailsPaymentLauncher(session) { status = it }

    Button(onClick = { launcher.authorize(PaymentMethod.googlePay) }) { Text("Pay with Google Pay") }
}

typealias RequestStartHandler = suspend (RequestStartContext) -> RequestStartDecision

sealed interface RequestStartDecision {
    data object Proceed : RequestStartDecision
    data class Refuse(val message: String? = null) : RequestStartDecision
}

data class RequestStartContext(
    val executionId: String?,
    val paymentMethodCode: String,
    val action: Action,
) {
    enum class Action(val code: String) { AUTHORIZE, TOKENIZE }
}

val configuration = Configuration(
    initData = initData,
    option = Options(collectMetadata = false)
)

adb shell setprop log.tag.PayrailsSDK DEBUG

adb logcat -s PayrailsSDK:D

adb shell setprop log.tag.PayrailsSDK INFO

val cardForm = Payrails.createCardForm(
    config = CardFormConfig(
        showCardHolderName = true,
        showStoreInstrumentCheckbox = true
    )
)

val payButton = Payrails.createCardPaymentButton(
    translations = CardPaymenButtonTranslations(label = "Pay Now")
)

payButton.delegate = object : PayrailsCardPaymentButtonDelegate {
    override fun onPaymentButtonClicked(button: CardPaymentButton) {}
    override fun onAuthorizeSuccess(button: CardPaymentButton) {}
    override fun onThreeDSecureChallenge(button: CardPaymentButton) {}
    override fun onAuthorizeFailed(button: CardPaymentButton) {}
}

// In Compose
cardForm.Render()
payButton.Render()

payButton.setDelegate(new PayrailsCardPaymentButtonDelegate() {
    @Override
    public void onPaymentButtonClicked(CardPaymentButton button) {}
    @Override
    public void onAuthorizeSuccess(CardPaymentButton button) {}
    @Override
    public void onThreeDSecureChallenge(CardPaymentButton button) {}
    @Override
    public void onAuthorizeFailed(CardPaymentButton button) {}
});

CardFormConfig(
    showCardIcon = true,
    cardFieldIcons = CardFieldIcons(
        cardholderName = "https://example.com/my-name.png",  // adds a custom cardholder icon (no default)
        cardNumber = "https://example.com/my-card.png",      // replaces default card icon (network icons still show when detected)
        cvv = "https://example.com/my-cvv.png",              // replaces default CVV icon
        expiryDate = "https://example.com/my-expiry.png"     // replaces default expiry icon
    )
)

val cardForm = Payrails.createCardForm()
val button = Payrails.createCardPaymentButton(
    translations = CardPaymenButtonTranslations("Pay")
)
button.setStoredInstrument(instrument)

suspend fun Session.tokenize(
    request: TokenizationRequest,
    options: TokenizeOptions = TokenizeOptions(),
): SaveInstrumentResponse

val response = session.tokenize(
    TokenizationRequest.Card(cardForm),
    TokenizeOptions(storeInstrument = true, futureUsage = FutureUsage.CardOnFile),
)
val instrumentId = response.id

fun Session.tokenize(
    request: TokenizationRequest,
    options: TokenizeOptions = TokenizeOptions(),
    onSuccess: (SaveInstrumentResponse) -> Unit,
    onFailed: (PayrailsError) -> Unit,
    onCancelled: () -> Unit,
)

session.tokenize(
    request = TokenizationRequest.Card(cardForm),
    onSuccess = { instrument -> /* instrument.id */ },
    onFailed = { error -> /* show error */ },
    onCancelled = { /* cancelled */ },
)

sealed interface TokenizationRequest {
    data class Card(val cardForm: CardForm) : TokenizationRequest
    data class GooglePay(val presenter: GooglePayPresenter) : TokenizationRequest
}

interface GooglePayPresenter

@Composable
fun rememberGooglePayPresenter(session: Session): GooglePayPresenter

val presenter = rememberGooglePayPresenter(session)
// later, from a coroutine:
val response = session.tokenize(
    TokenizationRequest.GooglePay(presenter),
    TokenizeOptions(storeInstrument = true),
)

@Composable
fun GooglePayTokenizeButton(
    session: Session,
    options: TokenizeOptions = TokenizeOptions(),
    style: GooglePayButtonStyle = GooglePayButtonStyle(),
    modifier: Modifier = Modifier,
    onSuccess: (SaveInstrumentResponse) -> Unit,
    onFailed: (PayrailsError) -> Unit,
    onCancelled: () -> Unit,
)

GooglePayTokenizeButton(
    session = session,
    options = TokenizeOptions(storeInstrument = true),
    onSuccess = { instrument -> /* instrument.id */ },
    onFailed = { error -> /* show error */ },
    onCancelled = { /* dismissed */ },
)

suspend fun tokenize(options: TokenizeOptions = TokenizeOptions()): SaveInstrumentResponse

val response = cardForm.tokenize(
    options = TokenizeOptions(
        storeInstrument = true,
        futureUsage = FutureUsage.CardOnFile
    )
)
val instrumentId = response.id

data class TokenizeOptions(
    val storeInstrument: Boolean = false,
    val futureUsage: FutureUsage = FutureUsage.CardOnFile
)

enum class FutureUsage(val value: String) {
    CardOnFile("CardOnFile"),
    Subscription("Subscription"),
    UnscheduledCardOnFile("UnscheduledCardOnFile")
}

@Serializable
data class SaveInstrumentResponse(
    val id: String,
    val createdAt: String,
    val holderId: String,
    val paymentMethod: String,
    val status: String,
    val data: InstrumentResponseData,
    val fingerprint: String? = null,
    val futureUsage: String? = null
)

sealed class InstrumentAPIResponse {
    data class Delete(val response: DeleteInstrumentResponse) : InstrumentAPIResponse()
    data class Update(val response: UpdateInstrumentResponse) : InstrumentAPIResponse()
    data class Save(val response: SaveInstrumentResponse) : InstrumentAPIResponse()
}

val googlePayButton = Payrails.createGooglePayButton(
    style = GooglePayButtonStyle(),
    translations = GooglePayButtonTranslations(),
    showStoreInstrumentCheckbox = false
)

googlePayButton.delegate = object : PayrailsGooglePayButtonDelegate {
    override fun onGooglePayAvailable(button: GooglePayButton) {
        // Google Pay is supported on this device
    }
    override fun onPaymentButtonClicked(button: GooglePayButton) {
        // User tapped the Google Pay button
    }
    override fun onAuthorizeSuccess(button: GooglePayButton) {
        // Payment succeeded
    }
    override fun onThreeDSecureChallenge(button: GooglePayButton) {
        // 3DS challenge started
    }
    override fun onAuthorizeFailed(button: GooglePayButton) {
        // Payment failed
    }
}

// In Compose
googlePayButton.Render()

googlePayButton.setDelegate(new PayrailsGooglePayButtonDelegate() {
    @Override
    public void onGooglePayAvailable(GooglePayButton button) {}
    @Override
    public void onPaymentButtonClicked(GooglePayButton button) {}
    @Override
    public void onAuthorizeSuccess(GooglePayButton button) {}
    @Override
    public void onThreeDSecureChallenge(GooglePayButton button) {}
    @Override
    public void onAuthorizeFailed(GooglePayButton button) {}
});

val googlePayButton = Payrails.createGooglePayButton(
    showStoreInstrumentCheckbox = true,
    translations = GooglePayButtonTranslations(storeInstrument = "Save for next time")
)

val payPalButton = Payrails.createPayPalButton(
    style = PayPalButtonStyle(height = 45.dp, width = 200.dp),
    translations = PayPalButtonTranslations()
)

payPalButton.delegate = object : PayrailsPayPalButtonDelegate {
    override fun onPaymentButtonClicked(button: PayPalButton) {
        // User tapped the PayPal button
    }
    override fun onAuthorizeSuccess(button: PayPalButton) {
        // Payment succeeded
    }
    override fun onAuthorizeFailed(button: PayPalButton) {
        // Payment failed or was rejected
    }
    override fun onPaymentSessionExpired(button: PayPalButton) {
        // Session is no longer usable — fetch a new init payload and call Payrails.createSession()
    }
}

// In Compose
payPalButton.Render()

val redirectMethods: List<PayrailsPaymentOption> =
    session.getPaymentMethodConfig(PaymentMethodFilter.Redirect)

val button = Payrails.createGenericRedirectButton(
    translations = CardPaymenButtonTranslations(label = "Pay with iDEAL"),
    paymentMethodCode = "iDeal",
    buttonStyle = CardButtonStyle(/* optional styling */)
)

button.delegate = object : GenericRedirectPaymentButtonDelegate {
    override fun onPaymentButtonClicked(button: GenericRedirectButton) {}
    override fun onAuthorizeSuccess(button: GenericRedirectButton) {}
    override fun onAuthorizeFailed(button: GenericRedirectButton) {}
    override fun onPaymentSessionExpired(button: GenericRedirectButton) {}
    override fun onStateChanged(button: GenericRedirectButton, state: ButtonState) {}
}

// In Compose
button.Render()

button.setDelegate(new GenericRedirectPaymentButtonDelegate() {
    @Override
    public void onPaymentButtonClicked(GenericRedirectButton button) {}
    @Override
    public void onAuthorizeSuccess(GenericRedirectButton button) {}
    @Override
    public void onAuthorizeFailed(GenericRedirectButton button) {}
    // onPaymentSessionExpired and onStateChanged have default no-ops
});

val instruments = session.getStoredInstruments()
val cardInstruments = session.getStoredInstruments(forType = PaymentMethod.card)

// Set a stored instrument on the card payment button
payButton.setStoredInstrument(cardInstruments.first())

List<StoredInstrument> instruments = session.getStoredInstruments(null);
List<StoredInstrument> cardInstruments = session.getStoredInstruments(PaymentMethod.card);

payButton.setStoredInstrument(cardInstruments.get(0));

// Delete an instrument
val deleteResult: InstrumentAPIResponse.Delete = session.deleteInstrument(instrumentId)

// Update an instrument
val updateResult: InstrumentAPIResponse.Update = session.updateInstrument(
    instrumentId,
    UpdateInstrumentBody(default = true)
)

suspend fun binLookup(bin: String): BinLookupResponse?

val result = session.binLookup("529741")
if (result?.localNetwork != null) { /* co-branded */ }

val onPreferredSchemeChanged: ((PreferredSchemeChange) -> Unit)? = null