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 Settlement
This request can also perform partial settlements.

Request

The Settlement request uses the same endpoint as the initial /charge-token request. The API determines it's a settlement based on the RequestType value within the BasicInfo object.

Note the key differences from a /charge-token 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	Cryptographic key (HMAC) to authenticate this specific settlement request.	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.

Updated about 8 hours ago