Create Payments

Once the SDK is running and the connection with the Nayax device is established, the device is ready to handle vending and cashless transactions.

This guide shows you how to set up and manage cashless payment transactions from your peripheral’s controller using the Nayax Marshall SDK.

Pre-requisites

• Ensure your SDK is running and connected to the Nayax device indicated by the onReady() event.

Integration

If you have not finished the integration process, check the Get Started page before continuing.

Create a Payment

To perform a transaction using the Nayax Marshall SDK, follow the steps below.

1. Start by enabling the device for transactions.

   Java

   m_vmc.vend.session_start(vmc_vend_t.session_type_credit_e);
   

2. When a client presents a card and it is approved, the onSessionBegin() event is triggered. This is the signal for the peripheral, such as the vending machine, to prepare for payment approval.

   Java

   m_sessions[0] = new vmc_vend_t.vend_session_t((short) 0, 1, (byte) 0, 10);
   //the fields are (from left to right): produce code (2 bytes long, meaning value up to 65535), quantity (2 bytes), unit of measure (1 byte), price (2 bytes, meaning value up to 65535)
   

Price field

The price field is set as an integer, meaning it does not take into consideration the Decimal Place: the actual price is calculated by the device based on the Decimal place- meaning if you set a price of 50 in the SDK, the peripheral would send a price of 50 to the device, who would look at its own Decimal Place setting and would multiply the price sent by 10^(-decimal place). Meaning if the device has a Decimal Place of 2, the actual price the device would attempt to charge the consumer would be 0.50.
More on that in Decimal Place.

This means that in case the device is using a Decimal Place of 2, the highest price would be 655.35 (0XFFFF with decimal of 2).

Multi-vend Session

For a multi-vend session, when the consumer is able to select multiple items in one transaction, enable the multi_vend_support flag. The session would then include a list of products.
You can review an example of it in the demo apps.

Then, inside the onSessionBegin() callback you would send the “Vend Request” for said session (transaction):

Java

m_vmc.vend.vend_request(m_sessions[m_active_session]);

3. After the VPOS approves the vending request, the peripheral must notify the SDK that the product has been successfully delivered to the consumer. This is done by implementing the onVendApproved(...) API and returning one of the following:

• True: If the vend process is successful, the client’s credit card is charged the requested amount.
• False: For a failed vend process.

4. Whether it’s a single session or multi-session, the onReady() event will be called upon finishing the vending process, indicating that the device is ready for the next transaction.

Multi-Session

For multi-session configurations, when the session on the peripheral’s end is finished, it is up for the peripheral to close the session in order for the transaction to be settled:

Java

m_vmc.vend.session_close(m_session)

Following these steps ensures that the vending process, from card presentation to product delivery and payment, is handled efficiently and securely using the Nayax Marshall SDK.

Decimal Place

Decimal Place is a parameter in Nayax Core that the device forwards to your peripheral in the Marshall Config command, which is sent as part of the pairing process.

Your machine calculates the multiplier from it:

X = 10 ^ Decimal Place

For every transaction, multiply the price set in the SDK by that value and send the result to the device. With a Decimal Place of 2 and a price of 30 Euros, the price sent to the device is 30 × (10 ^ 2) = 3000.

Credorax only accepts transactions of 10 cents and above. A price of 1 with 2 decimal places resolves to 0.01 Euro by the time it reaches Credorax, and the transaction is declined.

Close a Session Without Charging the Consumer

When you cannot provide the goods, close the session with a status other than Status Ok, such as Failed to dispense the product. Do not close it with a price of 0 and a status of Status Ok.

A price of 0 with an ok status reads as a price calculation error on your side. Anyone looking at the virtual machine’s Last Sales would conclude that Nayax failed to settle the transaction, when in fact the flow between your peripheral and the device worked and you simply chose not to charge. Responding with Vend Failure, or closing with User cancel or Failed to dispense the product, records the real reason in Last Sales and the Dynamic Transaction Monitor.

Once the status is anything other than Status Ok, the price you send is irrelevant, because the transaction counts as cancelled.

Status	Meaning
0	Status Ok
1	User cancel
2	Failed to dispense the product
4	Vend denied

Only close a session when the device is idle. Sending Close Session during an active transaction can get that transaction stuck, because the device processes the Close Session first. Send it only once onReady has been triggered.

Handle Missing ACKs During a Transaction

Every Marshall command is answered with an ACK. When a command goes unanswered through all three attempts, what happens to the transaction depends on how far it had progressed:

• No ACKs after Vend Success: Nayax is responsible for the settlement.
• No ACKs after the authorization but before Vend Success: Nayax cancels the transaction.
• No ACKs before the authorization stage: Nayax cancels the transaction.

For the retry mechanism itself, see Link and Events Configuration.

Refunds

Marshall has no refund feature, because a refund concerns the payment rather than the communication between your machine and the device.

If you could not provide the goods, do not charge the consumer in the first place: respond with Vend Failure rather than Vend Success. For a transaction that was already charged and settled, request the refund from Nayax Core, as described in Nayax Core Operations.

See Also

Get Started

Get up and running with the Marshall SDK integration.

Methods & Functions

Find reference documentation for all methods and functions in the Marshall SDK.