Skip to main content

Documentation Index

Fetch the complete documentation index at: https://devzone.nayax.com/llms.txt

Use this file to discover all available pages before exploring further.

The startPayment method is the primary entry point for initiating a payment flow within your application using the Nayax eCom SDK. The method internally handles the calls to validateMerchant and initialize (the Nayax eCom API calls, not the SDK initialization). This means that you do not need to explicitly make these API calls before initiating a payment. The SDK will do the following:
  • Perform the necessary validateMerchant call to authenticate the transaction securely.
  • Execute the initialize call to set up the payment session with Nayax servers and the billing provider.
  • Trigger the Drop-In UI for the user to complete the payment.
This allows you to focus on providing the PaymentData and handling the payment results, while the SDK takes care of the communication and security protocols.

​
Payment Data

The startPayment method requires a PaymentData object that encapsulates all the necessary details for the transaction. 
data class PaymentData(
    val validationKey: String,
    val merchantRequestId: String,
    val actorId: String,
    val amount: Double,
    val currencyCode: String,
    val countryCode: String,
    val machineId: String,
    val requestType: Int,
    val sessionExpiration: String? = null,
    val entryMode: Int? = null,
    val tokenModel: Int? = null,
    val showSaveCardConsent: Boolean? = null,
    val cardHolderInfo: CardHolderInfo? = null,
    val additionalData: String? = null
)
Key parameters include:
ParameterTypeDescription
validateMerchantTranId (iOS/Flutter)
validationKey (Android)		StringMerchant-generated. Required. A unique 36-character GUID (UUID v4 format) that you generate per payment session. The SDK uses this value internally for the /validate-merchant authentication step. Generate a new UUID for each startPayment() call. Example: "550e8400-e29b-41d4-a716-446655440000"
merchantRequestIdStringMerchant-generated. Required. Your own unique transaction correlation ID. Nayax echoes this value back in webhook notifications as MerchantRequestId. Use it to match webhooks to your internal transactions. Example: "req-2026-03-31-001"
actorIdStringThe unique identifier for the actor/entity initiating the transaction.
amountDouble (Android/iOS), or equivalent numeric typeThe requested transaction amount (e.g., 15.00 for $15.00).
currencyCodeString (Alpha-3 format, e.g., “USD”, “EUR”, “ILS”)The currency of the transaction, adhering to ISO 4217 standards.
countryCodeString (2 or 3 letters, e.g., “US”, “GB”, “IL”)The country code where the cardholder is located, typically following ISO 3166.
machineIdStringThe Machine ID as defined and saved in the Nayax Backoffice, received as part of the onboarding process.
requestTypeIntegerSpecifies the desired transaction type. Common values include: 0: Sale (Authorization + automatic Capture), 1: Auth (Authorization only), 2: Capture (for pre-authorized transactions). (Refer to the full API documentation for a comprehensive list of requestType values, including void, refund, incremental auth, etc.)
sessionExpirationString (ISO8601 format, e.g., "2023-11-23T12:25:28Z") (Optional)The session expiry date. If not provided, the default is typically 1 hour.
entryModeInteger (Optional)Indicates the cardholder entry mode (e.g., COF for Card On File, ECOM for E-Commerce, MIT for Merchant Initiated Transaction, CIT for Customer Initiated Transaction). Default is ECOM.
tokenModelInteger (Conditional)If entryMode is COF, indicates the token model (e.g., subscription, top-up, Stored.card). Token Type Behavior: A token’s type (subscription/COF/top-up) is set during its initial creation and stored in our system. If a subsequent Charge Token request includes a different token type parameter, it is ignored. The system always uses the original token type from the initialization request, regardless of what is provided in later charge requests.
showSaveCardConsentBoolean (Conditional)If entryMode is COF, determines whether the “Ask for Consent” question appears on the payment page for saving card details. Important: Cardholder approval is mandatory for a valid Nayax token. This parameter is strictly for credit card-only flows; if other payment methods are available, the transaction will be automatically declined.
cardHolderInfoObject containing cardHolderUniqId and cardholderEmail (Optional)Provides cardholder details, especially relevant for tokenized transactions.
You generate both of these values yourself:
  • validationKey (Android) / validateMerchantTranId (iOS/Flutter) is the same field, named differently per platform. Pass a freshly generated UUID for every startPayment() call. The SDK uses it to authenticate the session with Nayax.
  • merchantRequestId is your own reference ID for the transaction. Nayax returns it in webhook notifications, so use a value that lets you match the webhook back to the correct order or record in your system.

​
Initiate a Sale Payment (Android)

The following example shows how to construct a PaymentData object for a standard sale transaction and pass it to startPayment():
Kotlin
val paymentData = PaymentData(
    validationKey = UUID.randomUUID().toString(),       // 36-char GUID (Android)
    merchantRequestId = UUID.randomUUID().toString(),   // Your correlation ID
    actorId = "2007905102",
    machineId = "1001621751",
    amount = 25.00,
    currencyCode = "USD",
    countryCode = "US",
    requestType = 0  // 0 = Sale, 1 = Auth
)

NayaxEcomSDK.startPayment(
    context = context,
    paymentData = paymentData,
    callback = object : PaymentResultCallback { ... }
)

​
See Also

Handle Payment Results

Drop-In UI