Documentation Powered by ReDoc

Tender API (1.0.0)

Download OpenAPI specification:Download

The API allows you to define what tenders should be available in a given store and their respective behaviour, such as currency id, description, tender restriction rules for for specific item category etc.

Additional properties

Property key Data type Description
Pos.changeAllowed BOOL A flag indicating that change will not be returned for this tender type.
Over tendering will not be allowed or change will not be given depending
on POS configuration.
Note: The override attributes are no longer supported for this element.
Also, if this flag is false, consider setting the lock flag to prevent
the user from refunding too much using other tender.
Pos.changeThresholdAmount DOUBLE The maximum change that can be offered to a customer for this tender.
Pos.extChangeTenderTypeCode STRING The tender to use instead of cash when the 'changeThresholdAmount'
is exceeded.
Pos.checkEndorsing BOOL Indicates that endorsing is required.
Pos.copySignatureReceipt BOOL Indicates that a store copy of the signature receipt is to be printed.
Pos.default BOOL Indicates if this tender is the default tender for the classCode
(i.e. if this is the default tender subtype for the tender type).
Pos.displayDefaultAmount BOOL Indicates if a default amount (remaining total due) should be provided
to the user when starting a tender.
Pos.duplicateReceipt BOOL Indicates that duplicate receipts are to be printed.
Pos.franking BOOL Indicates that franking is required.
Pos.lock BOOL Indicates that once this tender has been succesfully entered then the
transaction can not be manipulated in any way.
Pos.overTenderAllowed BOOL If false, over tendering will not be allowed with this tender.
If set to true and the changeAllowed flag is false, the transaction
will be auto-rounded to prevent the customer from receiving change for
the over tendered amount.
Pos.personalIdentificationNumberRequired BOOL A flag that requires the customer to enter a personal identification
number (PIN) to validate the method of payment.
PINs are normally required for debit card payments.
Pos.autoTenderAllowed BOOL Indicates that the tendering may be automatic, ie the amount to tender
is not needed to be entered.
Pos.singleTender BOOL Indicates that the tender must be the only tender within a transaction.
Pos.openCashdrawer BOOL Indicates that this tender will open the cash drawer.
Pos.void BOOL Indicates that this tender can be voided.
Pos.customerAgentRequired BOOL Indicates that that a customer reference is required for the tender.
Pos.customerConfirmationRequired BOOL Customer need to confirm tender amount on customer touch point or similar.
Pos.customerSignatureRequired BOOL A flag that requires the customer to sign the tender (check) or resultant
voucher (card) in the precence of the operator.
Pos.checkBalanceAllowed BOOL Indicates that the tender support balance check requests.
Pos.autoCashoutLimit DOUBLE For tenders with 'checkBalanceAllowed', auto cash out should be performed
if the remaining balance is lower than or equal to the specified limit.
Pos.maximumBalance DOUBLE The maximum balance allowed for tenders with 'checkBalanceAllowed'.
This limit is enforced when refunding to this tender type.
Pos.promptForCashBack BOOL Indicates that the customer/cashier is to be prompted for cash back.
This flag is only considered if 'autoTenderAllowed' is set to true.
Pos.displayCashBackPromptToCashier BOOL Indicates if cashback prompts should target the cashier instead of the
customer.
Pos.cashBackFinalizationLimit DOUBLE Prevents automatic order finalization if the cash back amount is greater
than the specified limit.
Pos.allowInRefund BOOL Indicates that this tender is allowed in refunds.
Pos.allowInRefundOverride BOOL Possible with manager override to allow refund when
receipt total is negative.
Pos.allowInRefundVoidProhibited BOOL Sales advisor is not allowed to back out of the manager override dialogue
to manager override to allow refund when receipt total is negative.
Pos.auditableId STRING Identifies the audit properties for this tender.
Pos.roundingRuleTypeCode STRING Indicates the rounding rule that apply to this tender.
'Mathematical' If the value is within [1, 4] then it's rounded to 0,
or if the value is within [5, 9] it's rounded to 10.
'RoundHalfDown' If the value is within [1, 5] then it's rounded to 0,
or if the value is within [6, 9] it's rounded to 10.
'NoRounding' Indicates that no rounding is to be applied.
'Scientific' If the value is within [1, 4] then it's rounded to 0,
or if the value is within [6, 9] it's rounded to 10.
Rounds 5 to the nearest even number.
Pos.roundingPrecision DOUBLE Indicates the precision or sub-unit to which the rounding is to be done
(according to the RoundingRuleTypeCode).
Eg If 50 cents is the minimum denomination, this value will be set to 0.50.
This will round any value to a multiple of 0.50.

Maximum cash back

Property key Data type Description
Pos.maximumCashBack.n.amount DOUBLE The maximum amount allowed to overpay for a specific tender.
The amount defined will be applied together with the 'endTime'.
For example, if we want to set an amount limit for this tender of 100 that
will be valid till 13:00 and 1000 after 13:00 we need to add the following
additional properties:
{
"id": "Pos.maximumCashBack.0.amount",
"value": "100.00",
"dataType": "DOUBLE"
},
{
"id": "Pos.maximumCashBack.0.endTime",
"value": "13:00",
"dataType": "STRING"
},
{
"id": "Pos.maximumCashBack.1.amount",
"value": "1000.00",
"dataType": "DOUBLE"
},
{
"id": "Pos.maximumCashBack.1.endTime",
"value": "23:59",
"dataType": "STRING"
}

n - index number for this amount in case multiple limits are
needed during the day. It is only possible to define the limits for one day
that will be applied to all days of the week.
Pos.maximumCashBack.n.endTime STRING The time for when the amount limit with the same index will expire.
Time in HH:MM:SS - in 24 hour military time.
n - index number for this endTime
Pos.maximumCashBack.overridable BOOL Indicates that it is possible with manager override to enter a higher
amount.
Pos.maximumCashBack.voidProhibited BOOL Indicates that an operator that is not authorized to override this amount
may not back out of the function. This attribute is only of interest if
'maximumCashBack.overridable' is set to true.

Account Number

Property key Data type Description
Pos.accountNumber.accountIdMaximumLength INT Indicates a maximum length of the account identification. A value of zero
indicates that there is no limit.
Pos.accountNumber.accountIdMinimumLength INT Indicates a minimum length of the account identification.
Pos.accountNumber.accountIdentificationRequired BOOL A flag to signify that the status of the account has to be checked before
this method of tender can be accepted.
Pos.accountNumber.accountMaskingOnCustomerReceipt BOOL Indicates that the account number is to be masked (not readable) on
customer's receipt.
Pos.accountNumber.accountMaskingOnDisplay BOOL Indicates that the account number is to be masked (not readable) on
cashier and customer display.
Pos.accountNumber.accountMaskingOnStoreCopy BOOL Indicates that the account number is to be masked (not readable) on
store's copy of the receipt.
Pos.accountNumber.accountNumberPromptCashier BOOL If true the account number prompt will be shown to cashier, if false it
will be shown to the customer.
Pos.accountNumber.allowManualAccountNumber BOOL Indicates that a account number may be manually entered for this tender.
Pos.accountNumber.allowManualAccountNumberOverride BOOL Possible with manager override to allow manual entry of account number.
Pos.accountNumber.allowManualAccountNumberVoidProhibited BOOL Sales advisor is not allowed to back out of the manager override dialogue
regarding entry of account number. This attribute is only of interest if
'accountNumber.allowManualAccountNumberOverride' is set to true.
Pos.accountNumber.checkDigitElectronicVerification.verify BOOL If set to true, validation will be performed for manually entered account
numbers.
Pos.accountNumber.checkDigitElectronicVerification.validator STRING This is a name of a pre-configured software component that should be
invoked to validate the check digit. This is only applicable if the
'accountNumber.checkDigitElectronicVerification.verify' attribute is set
to true.
Pos.accountNumber.checkDigitManualVerification.verify BOOL If set to true, validation will be performed for manually entered account
numbers.
Pos.accountNumber.checkDigitManualVerification.validator STRING This is a name of a pre-configured software component that should be
invoked to validate the check digit. This is only applicable if the
'accountNumber.checkDigitManualVerification.verify' attribute is set to true.
Pos.accountNumber.checkDigitManualVerification.algorithm STRING Indicates the check digit type for entered account numbers.
Pos.accountNumber.checkDigitManualVerification.type STRING Indicates the check digit type for entered account numbers.
NoCheckDigit - Indicates that no check digit is to be used.
UserDefined - Indicates that the check digit algorithm referenced by
'accountNumber.checkDigitManualVerification.algorithm' is to be used.

Customer ID

Property key Data type Description
Pos.customerId.required BOOL A flag to signify that customer identification is required, such as
drivers license.
Pos.customerId.maximumLength DOUBLE Indicates a maximum length of the customer identification.
A value of zero indicates that there is no limit.
Pos.customerId.maximumLengthOverride BOOL Indicates that the limit is overrideable.
Pos.customerId.maximumLengthVoidProhibited BOOL Indicates that an operator that is not authorized to override this count
may not back out of the function. This attribute is only of interest if
'customerId.maximumLengthOverride' is set to true.
Pos.customerId.minimumLength DOUBLE Indicates a minimum length of the customer identification.
Pos.customerId.minimumLengthOverride BOOL Indicates that the limit is overrideable.
Pos.customerId.minimumLengthVoidProhibited BOOL Indicates that an operator that is not authorized to override this count
may not back out of the function. This attribute is only of interest if
'customerId.minimumLengthOverride' is set to true.
Pos.customerId.qualifierRequired BOOL A flag to signify that additional customer identification is required.
Pos.customerId.qualifierMaximumLength DOUBLE Indicates a maximum length of an additional customer identification.
A value of zero indicates that there is no limit.
Pos.customerId.qualifierMaximumLengthOverride BOOL Indicates that the limit is overrideable.
Pos.customerId.qualifierMaximumLengthVoidProhibited BOOL Indicates that an operator that is not authorized to override this count
may not back out of the function. This attribute is only of interest if
'customerId.qualifierMaximumLengthOverride' is set to true.
Pos.customerId.qualifierMinimumLength DOUBLE Indicates a minimum length of an additional customer identification.
Pos.customerId.qualifierMinimumLengthOverride BOOL Indicates that the limit is overrideable.
Pos.customerId.qualifierMinimumLengthVoidProhibited BOOL Indicates that an operator that is not authorized to override this count
may not back out of the function. This attribute is only of interest if
'customerId.qualifierMinimumLengthOverride' is set to true.

Expiration date

Property key Data type Description
Pos.expirationDate.configurableStartDateCount INT A number of days that will be subtracted from the end date of this tender
in order to calculate the start date.
A value of zero indicates that this is not in use.
Pos.expirationDate.expirationDateFormat STRING Indicates the date format of the expiration date for this tender.
Pos.expirationDate.expirationDateValidation BOOL Indicates that the expiration date of this tender is to be validated.
Pos.expirationDate.promptCashier BOOL If true the expiration date prompt will be shown to cashier.
If false it will be shown to the customer.

External authorization

Property key Data type Description
Pos.externalAuthorization.required BOOL Indicates that authorization needs to be carried out by an
external party.
Pos.externalAuthorization.mode STRING Indicates the type of authorization to make.
Pre-authorization (before purchase) normally reserves the money for
later withdrawal while post-authorization (after purchase) withdraws
the money directly.
Type of authorization (Pre or Post)
Pos.externalAuthorization.authorizationCodeMaximumLength INT Indicates a maximum length for an authorization code for this tender.
A value of zero indicates that there is no limit.
Pos.externalAuthorization.authorizationCodeMinimumLength INT Indicates a minimum length for an authorization for this tender.
Pos.externalAuthorization.authorizer STRING This is a name of a pre-configured software component that should be
invoked when authorizing this tender.

Fee

Property key Data type Description
Pos.fee.amount DOUBLE Indicates a flat amount to be applied as the tender fee.
Pos.fee.percentage DOUBLE Indicates that the fee is a percentage of the tender amount.
Pos.fee.override BOOL Indicates that the fee is overrideable.
Pos.fee.voidProhibited BOOL Indicates that an operator that is not authorized to override this
limit may not back out of the function. This attribute is only of
interest if 'fee.override' is set to true.
Pos.fee.prompt BOOL Indicates that the fee has to be approved by the operator.
Pos.fee.range.cumulative BOOL Indicates that all amounts for which the tender amount is below the
maximum amount are to be summed.
The default behaviour is that only the amounts for which the tender
amount is within the range are to be summed.
Pos.fee.range.n.amount DOUBLE The amount for this range fee.
n - index number for this range
Pos.fee.range.n.percentage DOUBLE The percentage for this range fee.
n - index number for this range
Pos.fee.range.n.maximumAmount DOUBLE The maximum amount for which this amount/percentage applies.
A value of zero means there is no upper limit.
n - index number for this range

Maximum refund

Property key Data type Description
Pos.maximumRefund.amount DOUBLE The maximum amount that is allowed to be refunded on this tender.
Pos.maximumRefund.amountOverride BOOL Indicates that 'maximumRefund.amount' is overrideable.
Pos.maximumRefund.amountVoidProhibited BOOL Indicates that an operator that is not authorized to override this amount
may not back out of the function. This attribute is only of interest if
'maximumRefund.amountOverride' is set to true.

Minimum refund

Property key Data type Description
Pos.minimumRefund.amount DOUBLE The minimum amount that can be refunded for this tender.
Pos.minimumRefund.amountOverride BOOL Indicates that 'minimumRefund.amount' is overrideable.
Pos.minimumRefund.amountVoidProhibited BOOL Indicates that an operator that is not authorized to override this amount
may not back out of the function. This attribute is only of interest if
'minimumRefund.amountOverride' is set to true.

Maximum per registration

Property key Data type Description
Pos.maximumPerRegistration.amount DOUBLE The maximum amount that can be accepted for this tender per registration.
Pos.maximumPerRegistration.amountOverride BOOL Indicates that 'maximumPerRegistration.amount' is overrideable.
Pos.maximumPerRegistration.amountVoidProhibited BOOL Indicates that an operator that is not authorized to override this amount
may not back out of the function. This attribute is only of interest if
'maximumPerRegistration.amountOverride' is set to true.

Maximum per transaction

Property key Data type Description
Pos.maximumPerTransaction.amount DOUBLE The maximum amount that can be accepted for this tender per transaction.
Pos.maximumPerTransaction.amountOverride BOOL Indicates that 'maximumPerTransaction.amount' is overrideable.
Pos.maximumPerTransaction.amountVoidProhibited BOOL Indicates that an operator that is not authorized to override this amount
may not back out of the function. This attribute is only of interest if
'maximumPerTransaction.amountOverride' is set to true.

Minimum per transaction

Property key Data type Description
Pos.minimumPerTransaction.amount DOUBLE The minimum amount that can be accepted for this tender per transaction.
Pos.minimumPerTransaction.amountOverride BOOL Indicates that 'minimumPerTransaction.amount' is overrideable.
Pos.minimumPerTransaction.amountVoidProhibited BOOL Indicates that an operator that is not authorized to override this amount
may not back out of the function. This attribute is only of interest if
'minimumPerTransaction.amountOverride' is set to true.

Start date

Property key Data type Description
Pos.startDate.configurableEndDateCount INT A number of days that will be added to the start date of this tender
in order to calculate the expiration date. A value of zero indicates
that this is not in use.
Pos.startDate.promptCashier BOOL If true the start date prompt will be shown to cashier, if false it will
be shown to the customer.
Pos.startDate.startDateFormat STRING Indicates the date format of the start date for this tender.
Pos.startDate.startDateValidation BOOL Indicates that the start date of this tender is to be validated.

Extra additional properties

Extra POS properties(not defined above) can be added and they need to be prefixed with Pos.extra. as in the example below

"additionalProperties": [ {
"id": "Pos.extra.myExtraProperty",
"value": true,
"dataType": "BOOL"
}]}

Authentication

ocms

Machine authentication is supported with OCMS.

Security Scheme Type OAuth2
clientCredentials OAuth Flow
Token URL: https://auth.retailsvc.com/oauth2/token
Scopes:

    tender

    Add tender

    Add tender

    Authorizations:
    ocms
    header Parameters
    Correlation-Id
    string <uuid>
    Example: fe0aded2-ba52-11eb-a075-e3d570c587ed

    Id used for tracking a request throughout the system(s).
    If not supplied, it will be automatically generated by this system.

    Request Body schema: application/json
    Array of objects (AdditionalProperty) [ items ]

    Additional custom properties can be added via this field.

    businessUnitGroupId
    required
    string

    Identifier for the business unit that this tender applies to.

    classCode
    string <= 20 characters

    The group of tenders to which this tender type belongs.

    currencyId
    required
    string <= 3 characters

    A identifier for the currency.

    description
    string <= 255 characters

    A description for this tender.

    id
    required
    string <= 4 characters

    A code which uniquely identifies the tender.
    It is also the ID referenced to identify the tender in the POSLog (i.e. the transaction data from POS).

    name
    string <= 40 characters

    A name for this tender.

    object (RestrictionRule)

    A rule that is set on a Tender to specify wich items can be purchased with this tender.

    Responses

    Request samples

    Content type
    application/json
    {
    • "businessUnitGroupId": "store-1",
    • "id": "cash",
    • "currencyId": "SEK"
    }

    Delete tender

    Delete tender

    Authorizations:
    ocms
    path Parameters
    id
    required
    string
    Example: cash

    Tender id

    query Parameters
    businessUnitGroupId
    required
    string

    Identifier for the business unit group that this tender applies to.

    classCode
    required
    string

    The group of tenders to which this tender type belongs.

    header Parameters
    Correlation-Id
    string

    An id used for tracing and verification

    Responses