HomeDocumentationRecipesAPI ReferenceChangelog
Platform OverviewDemoContactImprintLog In
API Reference
Platform OverviewDemoContactImprint

Create settlement item

post
https://api.instellix.io/v2/merchant-payment-accounts//settlement-reports//settlement-items

Create a new settlement item. Every settlement item must be a part of a settlement report, created beforehand
with 'Settlement Report' endpoint. New settlement item creation results in an automatic creation of a new
Payment Transaction in a SETTLED status.

Path Params
string
required

Merchant payment account ident.

string
required

Settlement report ident.

Body Params

Create Settlement Item request body.

baseAmount
object
required

The gross transaction amount in the settlement currency (= the currency in which the merchant receives the payout). This represents the full payment amount before fee deduction. Fees are reported separately in the fees[] array but are already included in baseAmount.

Example: A customer payment of EUR 148.26 with EUR 2.91 total fees -> baseAmount = 148.26 EUR, fees are listed separately.

baseAmount is not the net payout amount. It is the gross amount in the settlement currency.

batchItems
array of objects | null

Sub items that are batched together in this settlement item. If specified, their sum must match the settlement
item.

batchItems
date-time
required

The date of the account transaction. ISO 8601 date time format. E.g. 2021-03-19T13:34:01Z+01:00.
When no offset is provided (e.g. 2021-03-19T13:34:01), UTC is automatically used.
Must not be null.

date-time | null

The date of a creation of a settlement item. ISO 8601 date time format. E.g. 2021-03-19T13:34:01Z+01:00.

string
required

Indicates whether a settlement item is a DEBIT or CREDIT.
Must not be null.
Must be one of:

CREDIT
DEBIT
number | null
0 to 100000000000000

The conversion factor from originalAmount.currency -> baseAmount.currency.

Formula: originalAmount.amount / exchangeRate ~= baseAmount.amount

Mandatory when originalAmount.currency != baseAmount.currency

Set to 1.000000000000 when both currencies are the same

Scale: 12 decimal places

Example: Customer pays 108.27 DKK, merchant settles in EUR -> exchangeRate = 7.560750000000 (meaning 1 EUR = 7.560750000000 DKK), baseAmount = 14.32 EUR, originalAmount = 108.27 DKK.

This is the rate from original currency to settlement currency (how many units of original currency equal 1 unit of settlement currency).
Must be greater than or equal to 0.
Must be less than or equal to 100000000000000.
Must be a number with up to 14 integral digits and up to 12 fractional digits.

string
required
length between 1 and 255
^\S(.*\S)?$

A settlement item identifier, unique within a payment account. May be provided by a PSP.
Must not be null.
Size must be between 1 and 255.
Must match with the regular expression '^\S(.*\S)?$'.

fees
array of objects | null

Fee currency must match baseAmount.currency (settlement currency).
Fees are already included in baseAmount - they are reported separately for transparency but should not be subtracted from baseAmount.

fees
string | null
[a-zA-Z0-9_.~-]*

Unique identifier of a settlement item, autogenerated by Nitrobox if omitted.
Size must be between 1 and 100.
Must match with the regular expression '[a-zA-Z0-9_.~-]*'.

originalAmount
object | null

The transaction amount in the original transaction currency (= the currency the customer paid in). If no currency conversion applies, originalAmount equals baseAmount.
If the customer paid in a foreign currency (e.g. DKK) and the merchant settles in EUR, then originalAmount contains the DKK value and baseAmount the EUR equivalent.

Required when the transaction involves currency conversion. If omitted and baseAmount is set, the system assumes both are identical.

string | null
Defaults to UNCATEGORISED
deprecated

DEPRECATED.
The payment category to which a newly created payment - settled by this settlement item - is classified. This does not apply to existing payments.
Must be one of the categories defined in Nitrobox, otherwise the settlement item will be rejected.
Size must be between 0 and 255.

string | null

An identifier of a payment transaction which is settled with this settlement item if it is not SETTLED yet. If the transaction is already settled a new payment transaction will be created.
Size must be between 0 and 255.

properties
array of objects | null

Key-value-pairs of properties of a settlement - i.e. 'GVC':'166'

properties
string | null

Information about the recipient of a settled payment.
Size must be between 0 and 255.

string | null

Information about the sender of a settled payment.
Size must be between 0 and 255.

string | null

In case the settlement report which is a source of this settlement item, is of a more complex format (e.g. XML file),
the settlement item identifier should allow to unambiguously specify a place of a settlement item in this
document.
Size must be between 0 and 255.

int32 | null
≥ 1

In case the settlement report which is a source of this settlement item, is a simple entry based document (e.g. CSV
file), the settlement line number should specify a particular line where the settlement item is placed in
the file.
Must be greater than or equal to 1.

string | null

Any additional information about a settlement item like purpose, description, payment title, etc.
Size must be between 0 and 1400.

date-time | null

The date on which the account transaction takes effect. ISO 8601 date time format. E.g. 2021-03-19T13:34:01Z+01:00.
When no offset is provided (e.g. 2021-03-19T13:34:01), UTC is automatically used.

Responses

Updated 3 months ago

Did this page help you?
Language
Credentials
OAuth2
Missing 1 required scope
LoadingLoading…
Response
Choose an example:
application/json

Updated 3 months ago

Did this page help you?