> ## 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.
# 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.
```kotlin Kotlin theme={null}
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
)
```
```swift Swift theme={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](/reference/ecom/payments/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 Kotlin theme={null}
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 the SDK's payment result callbacks for Android and iOS.
Display a pre-configured list of payment methods anywhere on your site.