Skip to main content
POST
/
initialize
Initialize an E-commerce Transaction
curl --request POST \
  --url https://api.nayax.com/sdk/initialize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "basicInfo": {
    "sessionExpiration": "2025-12-31T23:59:59Z",
    "redirectURL": "https://your-merchant.com/callback",
    "amount": 15,
    "currency": "USD",
    "countryCode": "US",
    "requestType": 0,
    "entryMode": 0,
    "tokenModel": 0,
    "platform": 0,
    "isStoredCard": false,
    "merchantRequestId": "MERCHANT_REQ_12345"
  },
  "machineInfo": {
    "machineId": "0434334921100366"
  },
  "cardHolderInfo": {
    "cardholderCountry": "US",
    "paymentPageLan": "en",
    "cardholderEmail": "test@example.com",
    "cardHolderUniqId": "unique_customer_id_123"
  },
  "additionalInfo": {
    "additionalData": "{\"channel\": \"iOS\", \"someOtherData\": \"value\"}",
    "additionalReceiptData": "[{\"key\":\"orderId\", \"value\":\"ORD98765\"},{\"key\":\"customerLoyalty\", \"value\":\"GOLD\"}]"
  },
  "validationKey": "X305dITNTAw2vHsxE+taVcn6UvgBC3fdI6QbqeABgHbo8CKsoZhqISJfslehCiA+L7XYrqvKFci7C6BNj/trBuNJwBEjgBzKhhgpJ5ggnw=",
  "browserInfo": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1.1 Mobile/15E148 Safari/604.1"
}
'
{
  "status": {
    "verdict": "Approved",
    "code": 0,
    "statusMessage": "Transaction initialized successfully."
  },
  "paymentInfo": {
    "amount": 15,
    "currency": "USD",
    "nayaxTokenId": "NAYAXTOK12345",
    "siteId": 1,
    "decimalPlace": 2
  },
  "sessionInfo": {
    "nayaxSessionId": "ABCDEF123456",
    "expirationDate": "2025-12-31T23:59:59Z",
    "additionalSessionData": "{\"providerData\": \"some_session_info\"}"
  },
  "appInfo": {
    "billingProviderId": 1,
    "appVersion": "1.0.0"
  }
}
Initiates an e-commerce transaction by sending a request to the Nayax Ecom SDK. This call is the beginning of a transaction and requests a payment page or prepares for a token-based charge. It supports various entry modes like ECOM, COF, or MOTO. Authentication: The request requires a JWT RSA token in the header for authentication of both VAS integrator and VAS ECOM provider. Timeout Recommendation: It is highly recommended to implement a timeout of 60 seconds on the client side. If no callback or response is received, retry the same /InitializeTransaction request. The EcomTransactionId is valid for 5 minutes from the /StartAuthentication response. Initiates an e-commerce transaction by sending a request to the Nayax Ecom SDK. This call initiates a transaction and either displays a payment page or prepares for a token-based charge.
Integration URLWhen performing your integration to the API use the stable URL, such as:
  • https://stable-sdk-api.nayax.com/initialize

Authorizations

​
Authorization
string
header
required

JWT RSA token required for authentication. The token should be included in the Authorization header as Bearer <token>. Nayax will issue tokens to the VAS, signed by a private key, and decrypt them using a public key.

Body

application/json

Request to initialize a new transaction.

Request body for initializing a new transaction.

​
basicInfo
object

Basic transaction details.

​
machineInfo
object

Information about the machine/terminal.

​
validationKey
string | null

The result of the authentication flow (from /validate-merchant).

Example:

"X305dITNTAw2vHsxE+taVcn6UvgBC3fdI6QbqeABgHbo8CKsoZhqISJfslehCiA+L7XYrqvKFci7C6BNj/trBuNJwBEjgBzKhhgpJ5ggnw="

​
cardHolderInfo
object

Cardholder details.

​
additionalInfo
object

Additional information for the transaction and receipt.

​
browserInfo
string | null

Browser information (user-agent string) for payment page rendering.

Example:

"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.88 Safari/537.36"

Response

Success

Response body for initializing a new transaction.

​
status
object

Transaction status.

​
paymentInfo
object

Payment-related information.

​
sessionInfo
object

Session-related information.

​
appInfo
object

Application and billing provider information.