Initiate Payments

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
)

public struct PaymentData {
    public let validateMerchantTranId: String
    public let merchantRequestId: String
    public let actorId: String
    public let machineId: String
    public let amount: Double
    public let currencyCode: String
    public let countryCode: String
    public let requestType: Int
    public let sessionExpiration: String?
    public let entryMode: Int?
    public let tokenModel: Int?
    public let showSaveCardConsent: Bool?
    public let cardHolderInfo: CardHolderInfo?
    public let additionalData: String?

    public init(
        validateMerchantTranId: String,
        merchantRequestId: String,
        actorId: String,
        machineId: String,
        amount: Double,
        currencyCode: String,
        countryCode: String,
        requestType: Int,
        sessionExpiration: String? = nil,
        entryMode: Int? = nil,
        tokenModel: Int? = nil,
        showSaveCardConsent: Bool? = nil,
        cardHolderInfo: CardHolderInfo? = nil,
        additionalData: String? = nil
    ) {
        self.validateMerchantTranId = validateMerchantTranId
        self.merchantRequestId = merchantRequestId
        self.actorId = actorId
        self.machineId = machineId
        self.amount = amount
        self.currencyCode = currencyCode
        self.countryCode = countryCode
        self.requestType = requestType
        self.sessionExpiration = sessionExpiration
        self.entryMode = entryMode
        self.tokenModel = tokenModel
        self.showSaveCardConsent = showSaveCardConsent
        self.cardHolderInfo = cardHolderInfo
        self.additionalData = additionalData
    }
}

public struct CardHolderInfo {
    public let cardHolderUniqId: String?
    public let cardholderEmail: String?

    public init(
        cardHolderUniqId: String? = nil,
        cardholderEmail: String? = nil
    ) {
        self.cardHolderUniqId = cardHolderUniqId
        self.cardholderEmail = cardholderEmail
    }
}

Key parameters include:

Parameter	Type	Description
`validateMerchantTranId` (iOS/Flutter) `validationKey` (Android)	String	Merchant-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"`
`merchantRequestId`	String	Merchant-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"`
`actorId`	String	The unique identifier for the actor/entity initiating the transaction.
`amount`	Double (Android/iOS), or equivalent numeric type	The requested transaction amount (e.g., `15.00` for $15.00).
`currencyCode`	String (Alpha-3 format, e.g., “USD”, “EUR”, “ILS”)	The currency of the transaction, adhering to ISO 4217 standards.
`countryCode`	String (2 or 3 letters, e.g., “US”, “GB”, “IL”)	The country code where the cardholder is located, typically following ISO 3166.
`machineId`	String	The Machine ID as defined and saved in the Nayax Backoffice, received as part of the onboarding process.
`requestType`	Integer	Specifies 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.)
`sessionExpiration`	String (ISO8601 format, e.g., `"2023-11-23T12:25:28Z"`) (Optional)	The session expiry date. If not provided, the default is typically 1 hour.
`entryMode`	Integer (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`.
`tokenModel`	Integer (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.
`showSaveCardConsent`	Boolean (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.
`cardHolderInfo`	Object 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 { ... }
)

Payment Callbacks

Handle the SDK’s payment result callbacks for Android and iOS.

Drop-in UI

Display a pre-configured list of payment methods anywhere on your site.

Marshall Guides

Marshall Release Notes

Payment Data

Initiate a Sale Payment (Android)

See Also

Payment Callbacks

Drop-in UI

​Payment Data

​Initiate a Sale Payment (Android)

​See Also

Payment Callbacks

Drop-in UI

Payment Data

Initiate a Sale Payment (Android)

See Also