Settlement

This request is used to finalize or capture funds from a previously authorized transaction. It uses the same endpoint as the initial charge/authorization, but the request body includes the details of the transaction being settled.

Partial SettlementThis request can also perform partial settlements.

Request

The Settlement request uses the same endpoint as the initial /close-transaction request. The API determines it’s a settlement based on the RequestType value within the BasicInfo object. Note the key differences from a /close-transaction request:

The RequestType will be set to the value for Settlement/Capture, which is 2.
The request includes the original Transaction ID (transactionId) and the original Merchant Request ID (merchantRequestId) from the authorization phase.

See the example below:

{
  "basicInfo": {
    "requestType": 2,          // Example: 2 for Settlement/Capture
    "entryMode": 1,
    "amount": 25.00,           // The amount to capture (must be <= authorized amount)
    "currency": "EUR",
    "countryCode": "DE",
    "tokenModel": 1,
    "cvc": null,
    "token": null,
    "merchantRequestId": "ORIGINAL_MERCH_REQ_001", // ID from the original Auth
    "transactionId": "ORIGINAL_NAYAX_TRX_98765", // ID from the original Auth response
    "transactionTimeUtc": "2025-08-28T10:30:00Z", // Time from the original Auth response
    "isSaveTokenWithoutConsent": false
  },
  "machineInfo": {
    "machineId": "0434334921100366"
  },
  "cardHolderInfo": {},  // Empty or minimal data needed
  "paymentInfo": {},     // Empty or minimal data needed
  "additionalInfo": {},
  "validationKey": "AUTH_VALID_KEY_XYZ"
}

Request Parameters

The following table highlights the critical fields used to define a Settlement request:

Parameter	Location	Type	Description	Required for Settlement
`requestType`	basicInfo	Int32	Must be the value for ‘Settlement’ or ‘Capture’ (e.g., 2).	Yes
`amount`	basicInfo	Decimal	The amount being captured. Must be less than or equal to the amount initially authorized.	Yes
`merchantRequestId`	basicInfo	String	The unique ID from the original authorization request.	Yes
`transactionId`	basicInfo	String	The unique Nayax ID returned in the original authorization response.	Yes
`transactionTimeUtc`	basicInfo	DateTime	The UTC timestamp is returned in the original authorization response.	Yes
`paymentInfo`	Root	Object	Typically left empty or minimal, as payment details are referenced by `transactionId`.	No
`validationKey`	Root	String	The key obtained from the `/validate-merchant` response, used to authenticate all subsequent API calls within the same transaction session.	Yes

Response

A successful validation returns a 200 OK status and a body containing the validated merchant details:

{
  "status": {
    "verdict": "Approved",
    "code": 0,
    "statusMessage": "Payment processed successfully."
  },
  "basicInfo": {
    "amount": 25.5,
    "currency": "EUR",
    "merchantRequestId": "MERCHANT_MIT_001",
    "transactionId": "NAYAXTRANS98765",
    "transactionTimeUtc": "2025-08-28T10:30:00Z"
  },
  "paymentInfo": {
    "amount": 25.5,
    "currency": "EUR",
    "nayaxTokenId": "NAYAXTOK12345",
    "siteId": 1,
    "providerTransactionId": "PSP_TRANS_ABC",
    "decimalPlace": 2
  }
}

Response Parameters

The table below describes the parameters of the response:

Parameter	Location	Type	Description
`verdict`	status	String	’Approved’ or ‘Declined’. The final decision.
`code`	status	Int32	Response code: 0 for Approved, otherwise the relevant decline code.
`statusMessage`	status	String	A descriptive message about the transaction outcome.
`amount`	basicInfo	Decimal	The transaction amount processed.
`currency`	basicInfo	String	The currency of the transaction.
`merchantRequestId`	basicInfo	String	The unique ID from the original request.
`transactionId`	basicInfo	String	The unique transaction ID assigned by the Nayax system.
`transactionTimeUtc`	basicInfo	DateTime	The UTC timestamp when the transaction was completed.
`nayaxTokenId`	paymentInfo	String	The token ID used for the charge.
`siteId`	paymentInfo	Int32	The site ID associated with the payment.
`providerTransactionId`	paymentInfo	String	The unique ID assigned by the Payment Service Provider (PSP).
`decimalPlace`	paymentInfo	Int32	The number of decimal places used for the currency/amount.

Marshall Guides

Marshall Release Notes

Request

Request Parameters

Response

Response Parameters

​Request

​Request Parameters

​Response

​Response Parameters

Request

Request Parameters

Response

Response Parameters