Complex types

Not all data can be easily described with simple data structures. This page lists all the complex data structures that our Settle API is using.


Item

Simple item description for Settle item lists.

item_name : String : optional : default=null
Item text, e.g. "Spaghetti-Cod"
quantity : String : optional : default=null
Quantity of the item.
measurement_unit : String : optional : default=null
Unit of the quantity. e.g. kg, m, m2, m3, pcs and so on.
item_gross_total : String : optional : default=null
Price price the quantity of the item, VAT included.
tax_percent : String : optional : default=null
  • Optional
  • number == None
VAT in percent.
item_id : String : optional : default=null
Item identifier. Preferred in the order from left to right: EAN, UPC, ISBN, commodity code, serial number, other identifiers."

Store

Information about the store or business that is receiving the payment. Used for e-receipts.

store_id : String : optional : default=null
Unique store id, for example GLN
name : String : optional : default=null
Name of the Store
address : String : optional : default=null
Store address
postal_code : String : optional : default=null
Postal code
postal_place : String : optional : default=null
Postal place
country : String : optional : default=null
Country
phone_number : String : optional : default=null
Phone number
organization_number : String : optional : default=null
Organization number
chain_name : String : optional : default=null
Name of the Store Chain
longitude : String : optional : default=null
Longitude
latitude : String : optional : default=null
Latitude

ReceiptItem

Thorough item description for e-receipts.

item_name : String : optional : default=null
Item text, e.g. "Spaghetti with Cod"
item_group : String : optional : default=null
Item Group.
quantity : String : optional : default=null
Quantity of the item.
measurement_unit : String : optional : default=null
Unit of the quantity. e.g. kg, m, m2, m3, pcs and so on.
item_net_price : String : optional : default=null
Price of one single item, VAT excluded.
item_gross_price : String : optional : default=null
Price of one single item, VAT included.
item_net_total : String : optional : default=null
Price of the quantity of the item, VAT excluded.
item_gross_total : String : optional : default=null
Price price the quantity of the item, VAT included.
discount : String : optional : default=null
Discount on the item, VAT included.
taxes : String : optional : default=null
VAT in currency.
tax_percent : String : optional : default=null
  • Optional
  • number == None
VAT in percent.
commodity_code : String : optional : default=null
Item number, e.g. Varenummer, ISBN.
ean : String : optional : default=null
International Article Number (EAN).
serial_number : String : optional : default=null
Item serial number.

ReceiptPayment

payment_type : String : optional : default=null
  • Value in mcash, card, cash, giftcard, check
Payment type for the (partial) payment
amount : String : optional : default=null
Amount paid using this payment type
currency : String : optional : default=null
Currency of the payment

Currency

In schemas where a Currency field occurs it's value determines the currency used for the Money fields in the same schema. If the schema has a nested structure, the Currency field only affects the Money fields at the same nesting level. The Currency field takes a string of 3 chars representing a currency code according to the ISO 4217 standard.

MoneyInteger

Type that represents a monetary amount as an integer. In schemas where one or more Money fields appears there will always be a Currency field present, that determines the currency of the Money fields.

Capture

The list of captures done for the payment request.

id : String : optional : default=null
Local capture id. Null if the full amount in the payment request is captured in one step.
amount : MoneyInteger : optional : default=null
Captured part of amount.
additional_amount : MoneyInteger : optional : default=null
Captured part of additional amount

Refund

The list of refunds done for the payment request.

id : String : optional : default=null
Local refund id. Null if the full amount in the payment request is refunded in one step.
amount : MoneyInteger : optional : default=null
Refunded part of amount.
additional_amount : MoneyInteger : optional : default=null
Refunded part of additional amount
chat_message_data_text : String : optional : default=null
Given text reason for refund

PersonIdentifier

DateTime

UTC date and time as a string. The format is YYYY-MM-DD hh:mm:ss (24h time).

Json

AccessTokenResponse

access_token : String : optional : default=null
  • Optional
Access token
id_token : String : optional : default=null
  • Optional
A JWT that contains identity information about the user that is digitally signed by Settle
token_type : String : required
  • Data required (new or existing on update)
Type of access token, at this time it will always be Bearer
expires_in : Integer : optional : default=null
  • Optional
Lifetime in seconds of the access token
refresh_token : String : optional : default=null
  • Optional
Refresh token used to issue new access token after expiration
scope : String : optional : default=null
  • Optional
  • Value in address, bankid, email, fodselsnummer, openid, phone, profile, shipping_address
Space-delimited list of scopes. Any of: "openid" (static id, "address" (user preferred address), "profile" (name), "phone", "email", "shipping_address", "fodselsnummer"
currency : Currency : optional : default=null
  • Optional
  • length == 3
Currency for fee
transaction_fee : MoneyInteger : optional : default=null
Permission fee to be deducted from settlement
status : String : optional : default=null
Permission request status
status_code : Integer : optional : default=null
Permission request status code
pos_id : String : required
  • Data required (new or existing on update)
  • length <= 64
  • Regexp: ^[a-zA-Z0-9.-]+$
The POS this request originates from, used for informing user about origin
pos_tid : String : required
  • Data required (new or existing on update)
  • length <= 64
  • Regexp: ^[a-zA-Z0-9.-]+$
Local transaction id for POS. This must be unique for the POS
rid : String : required
  • Data required (new or existing on update)
Settle request id
user_info : Json : optional : default=null
User Info

NdbKey

MerchantProfileRegistration

first_address_line : String : optional : default=""
  • Optional
  • length <= 100
First Address Line
second_address_line : String : optional : default=""
  • Optional
  • length <= 100
Second Address Line
postal_code : String : optional : default=""
  • Optional
  • 4 <= length <= 5
Postal Code
country : String : optional : default=null
Country
description : String : optional : default=null
Description
phone_number : String : optional : default=""
  • Optional
  • MSISDNValidator
Phone Number
email : String : optional : default=""
  • Optional
  • Email (regexp: ^.+@[^.].*.[a-z]{2,10}$)
Email
url : String : optional : default=""
  • Optional
  • length <= 100
  • Regexp: ^w+://([^/:]+.[a-z]{2,10}|([0-9]{1,3}.){3}[0-9]{1,3})(:[0-9]+)?(/.*)?$
Url
twitter : String : optional : default=null
Twitter
facebook : String : optional : default=null
Facebook
hours : String : optional : default=null
Hours
settlement_receivers : String : optional : default=""
  • Optional
  • Email (regexp: ^.+@[^.].*.[a-z]{2,10}$)
Please write emails of people who should receive settlement files for this store.
settlement_email_xls : Boolean : optional : default=false
Settlement Email Xls
logo_url : String : optional : default=null
Logo Url

BusinessApplication

status : String : optional : default=null
Status
comment : String : optional : default=null
Comment

BusinessDocument

gs_object_name : String : optional : default=null
Gs Object Name
description : String : optional : default=null
Description

PubKey

Field for public key

Settle accepts the following formats:

  • OpenSSH public key format (the format in ~/.ssh/authorized_keys)
  • PEM format

Max bit size: 4096.

The validator will try to add a BEGIN/END wrapper if the key lacks one. If the wrapper provided is wrong, the validation will fail.

Location

A geographical point, specified by floating-point latitude and longitude coordinates together with an accuracy measurement in meters.

latitude : Float : optional : default=null
Latitude
longitude : Float : optional : default=null
Longitude
accuracy : Float : optional : default=null
Accuracy in meters.

LineItemMetadata

key : String : required
  • Data required (new or existing on update)
key
value : String : required
  • Data required (new or existing on update)
value

LineItem

product_id : String : required
  • Data required (new or existing on update)
External id for the product in the line item
description : String : optional : default=null
  • Optional
Description of the line item
metadata[] : LineItemMetadata : optional : default=null
List of product metadata
vat_rate : String : required
  • Data required (new or existing on update)
VAT rate for the line item
quantity : String : required
  • Data required (new or existing on update)
Quantity of the item
vat : MoneyInteger : optional : default=null
  • NonNegative
Total vat for the line item
item_cost : MoneyInteger : required
  • Data required (new or existing on update)
Cost pr item or base quantity of product in line item
total : MoneyInteger : required
  • Data required (new or existing on update)
Total cost, including vat, for line item

PaymentRequestLink

Link to be displayed for this payment request.

uri : String : optional : default=null
  • Optional
  • Regexp: (^|^w+://(localhost|[^/:]+|([0-9]{1,3}.){3}[0-9]{1,3})?(:[0-9]+)?)(/.*)?$
These links will be displayed in the app during the whole payment process: from before auth until after capture.
caption : String : optional : default=null
This text will be displayed in a button in the web to open the respective link.
show_on[] : String : optional : default=null
  • Value in pending, ok, fail (case insensitive)
This define on what states the link will be shown.

Scope

Cursor

SelectMultiple

PaymentRequestListItem

tid : String : optional : default=null
Tid
created : DateTime : optional : default=null
Created
total : MoneyInteger : optional : default=null
Total
message : String : optional : default=null
Message
status : String : optional : default=null
Status
currency : String : optional : default=null
Currency
link : String : optional : default=null
Link

Date

Select

Time

SalesSummaryProduct

product_id : String : optional : default=null
Product Id
description : String : optional : default=null
Description
reserved_vat[] : Integer : optional : default=null
Reserved Vat
capture_vat[] : Integer : optional : default=null
Capture Vat
refund_vat[] : Integer : optional : default=null
Refund Vat
reserved_quantity[] : Float : optional : default=null
Reserved Quantity
capture_quantity[] : Float : optional : default=null
Capture Quantity
refund_quantity[] : Float : optional : default=null
Refund Quantity
reserved_total[] : Integer : optional : default=null
Reserved Total
capture_total[] : Integer : optional : default=null
Capture Total
refund_total[] : Integer : optional : default=null
Refund Total
currency : String : optional : default=null
Currency
vat_rate : Integer : optional : default=null
Vat Rate

Fee

Fees and their corresponding VAT amounts for summaries of merchant settlements

scope_fee : MoneyInteger : optional : default=null
Scope Fee
scope_fee_vat : MoneyInteger : optional : default=null
Scope Fee Vat
settlement_fee : MoneyInteger : optional : default=null
Settlement Fee
settlement_fee_vat : MoneyInteger : optional : default=null
Settlement Fee Vat
transaction_fee : MoneyInteger : optional : default=null
Transaction Fee
transaction_fee_vat : MoneyInteger : optional : default=null
Transaction Fee Vat

ReportSummary

A summary of the set of transactions carried out in the same Report. Settle generates this after a report is closed.

gross : MoneyInteger : optional : default=null
The gross sum of the money transactions contained in the Report.
amount_total : MoneyInteger : optional : default=null
  • Optional
The sum of the amount fields of the transactions contained in the Report.
additional_amount_total : MoneyInteger : optional : default=null
  • Optional
The sum of the additional_amount fields of the transactions contained in the Report.
fees : Fee : optional : default=null
List of fees that are subtracted from gross. See Report summaries for a full description.
interchange : MoneyInteger : optional : default=null
The sum of interchange fees for credit card transactions.
currency : Currency : optional : default=null
The currency of the Money fields in this summary.
net : MoneyInteger : optional : default=null
The net amount after subtracting all fees from gross.
taxcode : String : optional : default=null
Tax laws that apply for this part of the summary, e.g., "NO:2013"

PayoutDetail

Settle generates this during settlement based on the settlement logs and previously unsettled fees.

currency : Currency : optional : default=null
The currency of the Money fields in this payout.
unsettled_fees_before : MoneyInteger : optional : default=null
The accumulated sum of unsettled fees prior to settlement.
unsettled_fees_after : MoneyInteger : optional : default=null
The accumulated sum of unsettled fees after settlement.
payout : MoneyInteger : optional : default=null
Money paid out at this settlement.
net : MoneyInteger : optional : default=null
The net amount after subtracting all fees from gross.
gross : MoneyInteger : optional : default=null
The gross sum of the money transactions contained in the Report.
billed : MoneyInteger : optional : default=null
The mount of money billed.
invoice_id : String : optional : default=null
Invoice identifier.

SettlementAccountFrequency

TimeDelta

SettlementListItem

index : String : optional : default=null
Index
start_date : DateTime : optional : default=null
Start Date
end_date : DateTime : optional : default=null
End Date
gross : MoneyInteger : optional : default=null
Gross
fixed_fees : MoneyInteger : optional : default=null
Fixed Fees
variable_fees : MoneyInteger : optional : default=null
Variable Fees
payout : MoneyInteger : optional : default=null
Payout

SettlementListSummary

settlement_account_id : String : optional : default=null
Settlement Account Id
num_settlements : Integer : optional : default=null
Num Settlements
currency : Currency : optional : default=null
Currency
payout : MoneyInteger : optional : default=null
Payout
neg_payout : MoneyInteger : optional : default=null
Neg Payout
balance_before : MoneyInteger : optional : default=null
Balance Before
balance_after : MoneyInteger : optional : default=null
Balance After
sales : MoneyInteger : optional : default=null
Sales
gross : MoneyInteger : optional : default=null
Gross
fixed_fees : MoneyInteger : optional : default=null
Fixed Fees
variable_fees : MoneyInteger : optional : default=null
Variable Fees
refunds : MoneyInteger : optional : default=null
Refunds
capture_count : Integer : optional : default=null
Capture Count
refund_count : Integer : optional : default=null
Refund Count

Sum

total : MoneyInteger : optional : default=null
Total
vat : MoneyInteger : optional : default=null
Vat

QuantitySum

total : MoneyInteger : optional : default=null
Total
vat : MoneyInteger : optional : default=null
Vat
qty : Integer : optional : default=null
Qty

RunningSum

refund : QuantitySum : optional : default=null
Refund
capture : QuantitySum : optional : default=null
Capture

SettlementPayout

account : String : optional : default=null
Account
amount : MoneyInteger : optional : default=null
Amount
id : Integer : optional : default=null
Id
text : String : optional : default=null
Text

Product

total : MoneyInteger : optional : default=null
Total
vat : MoneyInteger : optional : default=null
Vat
qty : Integer : optional : default=null
Qty
description : String : optional : default=null
Description

ProductSalesTableEntry

product_id : String : optional : default=null
Product Id
product : Product : optional : default=null
Product

ProductSalesTable

refund : ProductSalesTableEntry : optional : default=null
Refund
capture : ProductSalesTableEntry : optional : default=null
Capture

VatSalesTableEntry

vat_rate : String : optional : default=null
Vat Rate
entry : QuantitySum : optional : default=null
Entry

VatSalesTable

refund : VatSalesTableEntry : optional : default=null
Refund
capture : VatSalesTableEntry : optional : default=null
Capture

NullableBoolean

SettlementListReportContext

from_date : String : optional : default=null
From Date
to_date : String : optional : default=null
To Date
include_sales : Boolean : optional : default=null
Include Sales
show_sale_refund : Boolean : optional : default=null
Show Sale Refund
total_sum : Sum : optional : default=null
Total Sum
running_sum : RunningSum : optional : default=null
Running Sum
unspecified : RunningSum : optional : default=null
Unspecified
settlement_payouts[] : SettlementPayout : optional : default=null
Settlement Payouts
product_sales_table : ProductSalesTable : optional : default=null
Product Sales Table
vat_sales_table : VatSalesTable : optional : default=null
Vat Sales Table
single_format : NullableBoolean : optional : default=false
Single Format
single_payout : SettlementPayout : optional : default=null
Single Payout

Name

given_name : String : required
  • Data required (new or existing on update)
Given Name
family_name : String : required
  • Data required (new or existing on update)
Family Name
middle_name : String : optional : default=null
Middle Name

NameResponse

given_name : String : optional : default=null
Given Name
family_name : String : optional : default=null
Family Name
middle_name : String : optional : default=null
Middle Name

Money

Type that represents a monetary amount as a string using period as the decimal separator (e.g. "12.50"). In schemas where one or more Money fields appears there will always be a Currency field present, that determines the currency of the Money fields. The value string of the Money field must have the correct number of decimal places for the currency that has been supplied in the same schema. E,g, if the currency is "USD", "12.50" is a valid Money value, while "12.5" and "12.500" are not.