Complex types

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


Item

Simple item description for mCASH 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.

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.

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 : Money : optional : default=null
Captured part of amount.
additional_amount : Money : 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 : Money : optional : default=null
Refunded part of amount.
additional_amount : Money : optional : default=null
Refunded part of additional amount

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 mCASH
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 : Money : optional : default="0.00"
Permission fee to be deducted from settlement
report_id : String : optional : default=null
The Report that this authorization is included in
report_uri : String : optional : default=null
  • Optional
  • URL
Endpoint for the report that contains the state of the permission request.
ledger_id : String : optional : default=null
  • Optional
DEPRECATED, do not pass
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)
The POS this request originates from, used for informing user about origin
pos_tid : String : required
  • Data required (new or existing on update)
Local transaction id for POS. This must be unique for the POS
rid : String : required
  • Data required (new or existing on update)
mCASH request id
user_info : Json : optional : default=null
User Info

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.

MerchantProfile

address : String : optional : default=null
Address of merchant

PubKey

Field for public key

mCASH 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.

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
vat : String : required
  • Data required (new or existing on update)
Total vat for the line item
quantity : String : required
  • Data required (new or existing on update)
Quantity of the item
item_cost : String : required
  • Data required (new or existing on update)
Cost pr item or base quantity of product in line item
total : String : 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+://([^/:]+|([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

Fee

The sum of fees of the given type in amount of money.

type : String : optional : default=null
Fee category.
amount : String : optional : default=null
The sum of fees of given type in amount of money.

ReportSummary

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

gross : Money : optional : default=null
The gross sum of the money transactions contained in the Report.
amount_total : Money : optional : default=null
  • Optional
The sum of the amount fields of the transactions contained in the Report.
additional_amount_total : Money : optional : default=null
  • Optional
The sum of the additional_amount fields of the transactions contained in the Report.
transaction_fee : Money : optional : default=null
DEPRECATED. The same information can be found in the fees property.
scope_fee : Money : optional : default=null
DEPRECATED. The same information can be found in the fees property.
fees[] : Fee : optional : default=null
List of fees that are subtracted from gross. See summary-fees for a full description.
interchange : Money : 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 : Money : optional : default=null
The net amount after subtracting all fees from gross.

SettlementSummary

mCASH generates this in during the settlement from the settlement logs. This is the same as ReportSummary with the addition of settlement_fee and taxcode.

gross : Money : optional : default=null
The gross sum of the money transactions contained in the Report.
amount_total : Money : optional : default=null
  • Optional
The sum of the amount fields of the transactions contained in the Report.
additional_amount_total : Money : optional : default=null
  • Optional
The sum of the additional_amount fields of the transactions contained in the Report.
transaction_fee : Money : optional : default=null
DEPRECATED. The same information can be found in the fees property.
scope_fee : Money : optional : default=null
DEPRECATED. The same information can be found in the fees property.
fees[] : Fee : optional : default=null
List of fees that are subtracted from gross. See summary-fees for a full description.
interchange : Money : 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 : Money : 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"
settlement_fee : Money : optional : default=null
DEPRECATED. The same information can be found in the fees property.

PayoutDetail

mCASH 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 : Money : optional : default=null
The accumulated sum of unsettled fees prior to settlement.
unsettled_fees_after : Money : optional : default=null
The accumulated sum of unsettled fees after settlement.
payout : Money : optional : default=null
Money paid out at this settlement.
net : Money : optional : default=null
The net amount after subtracting all fees from gross.
gross : Money : optional : default=null
The gross sum of the money transactions contained in the Report.
billed : Money : optional : default=null
The mount of money billed.
invoice_id : String : optional : default=null
Invoice identifier.