API Documentation

# IFrame Integration / Form Integration

# Introduction

Both iframe and form integration are very similar. The main difference is while form integration redirects the customer directly to the payment page, iframe integration only redirects the iframe, keeping the top level domain the same.

Upon submitting the form, the customer will be redirected to a Nayax secured page to complete the transaction.

# Example form for direct/iframe

A list of mandatory and optional fields will be given in a sidebar link to the left.

This example is for one stage of the transaction:

  • Initiate transaction on merchant website
  • Customer submits the form on merchant website
  • Merchant gets the submitted data and adds their signature and other mandatory or optional parameters
  • Merchant redirects the customer to a given URL after signature and other parameters are added
  • Customer finishes the transaction on a Nayax secure payment form
  • Nayax redirects customer back to redirect URL given in API call or set up via the merchant dashboard

The example above is the basic template required for merchants. A full parameters list will be given in the sidebar to the left, but keep in mind that this is just an example for written clarity.

After you receive the data that the customer has submitted, you have to modify it to match the Nayax API. You can use our SDK to do this or keep reading to learn more about the full API endpoint and parameter list.

# Parameters To Hosted Payment Page API

Field Description Max Length Required
merchantID Your 7 digit merchant number - ####### 7 Yes
trans_amount Transaction amount 20 Yes
trans_currency Currency of transaction - list of available currencies on left sidebar 3 Yes
trans_type 0 = Debit Transaction (Default when field is empty)
1 = Authorization only		 1 Yes
trans_installments Number of installments, 1 for regular transaction 2 Yes
trans_refNum Merchant’s unique transaction number 100 No
trans_comment Your comments for the transactions 255 No
trans_storePm 1 to save the payment method for future use if the transaction was a success 1 No
disp_payFor Text shown to buyer in payment window, usually description of purchase (Cart description, Product name) 40 No
disp_paymentType List of payment types that are available to the client.
Available values listed on left sidebar.
If more than one, use commas to separate the values. (example: CC,ED)		 80 No
disp_lng The default language for the UI text in the window. If omitted, language is taken from user's browser settings.
ex: en-US		 5 No
notification_url The URL for notifying your system of the transaction result.
This can be configured via this parameter of the merchant dashboard.		 255 No
url_redirect The URL for redirecting a customer after a transaction.
This can be configured via this parameter or the merchant dashboard.		 255 No
skin_no The skin number to apply to the window opened by the request.
The skins can be configured in the page.		 2 No
signature Signature for verifying the authenticity of the request parameters. 30 Yes

It is also possible to auto-fill some form values to be pre-filled on the payment page.

# Automatic filling of form data

parameter description max length required/optional
client_fullName Cardholder full name 50 Optional
client_email Cardholder email address 50 Optional
client_phoneNum Cardholder phone number 15 Optional
client_idNum Government issued ID number 9 Optional
client_billAddress1 Client billing address line 1 50 Optional
client_billAddress2 Client billing address line 2 50 Optional
client_billCity Client billing city 20 Optional
client_billZipcode Client billing zip code 20 Optional
client_billState Client billing state in 2 char ISO code 2 Optional
client_billCountry Client billing country in 2 char ISO code 2 Optional

# Currencies Available

  • ILS = Israel New Shekel
  • USD = US Dollar
  • EUR = Euro
  • GBP = UK Pound Sterling
  • AUD = Australian Dollar
  • CAD = Canadian Dollar
  • JPY = Japanese Yen
  • NOK = Norwegian Krone
  • PLN = Polski Zloty
  • MXN = Mexican Peso
  • ZAR = South African Rand
  • RUB = Russian Ruble
  • TRY = Turkish Lira
  • CHF = Swiss Franc
  • INR = Indian Rupee
  • DKK = Danish Krone
  • SEK = Swedish Krona
  • CNY = Chinese Yuan
  • HUF = Hungarian Forint
  • NZD = New Zealand Dollar
  • HKD = Hong Kong Dollar
  • KRW = South Korean Won
  • SGD = Singapore Dollar
  • THB = Thai Baht
  • BSD = Bahamian Dollar

# Languages Available

  • he-IL = עברית (ישראל)
  • en-US = English (United States)
  • fr-FR = Français (France)
  • es-ES = Español (España, alfabetización internacional)
  • lt-LT= Lietuvių (Lietuva)
  • ru-RU = русский (Россия)
  • de-DE = Deutsch (Deutschland)
  • zh = 中文

# Payment Options And Types

ID Name Abbreviation
0 Other OP
1 Credit Card CC
2 ACH (Electronic Checks) EC
3 Instant Online Bank Transfer ID
4 European Direct Debit DD
6 Micropay PD
7 Online Bank Transfer OB
8 Wallet CS
9 Prepaid PP
10 External prepaid EP

# Signature calculation

SHA256 is used to validate the integrity of the data. The signature from the previous example should be calculated as follows:

Concatenate the required parameter values - the list of required parameters can be found in the signature field of your chosen API. Add your private hash to the end of the concatenated string. Apply SHA256 hash to the string. Convert the hash result to Base64. URL encodes the Base64 result if using GET mode. Now that you have a signature, include the result as a value of the signature field in the request.

Example in a couple of languages while having this data in mind:

  • CompanyNum = 1234567
  • TransType = 1
  • TypeCredit = 1
  • Amount = 5.4
  • Currency = 1
  • CardNum = 4580000000000000
  • RefTransID = 1234
  • PersonalHashKey = AU7E468HNF

CompanyNum + TransType + TypeCredit + Amount + Currency + CardNum + RefTransID + PersonalHashKey "1234567" + "1" + "1" + "5.4" + "1" + "4580000000000000" + "1234" + "AU7E468HNF"

Base64(SHA256("1234567115.4145800000000000001234AU7E468HNF")) Result: "PTpzX9OACBC+V3Fd9+TNCehnwIfqMaXmnUtsZMSRyVo="

Attention Required

if you are to use GET and not POST method, be sure to url encode the result from previous action of the base 64 encoding

Signature Function Example:

Usage:

← Notification Handling →