Models & Types

Every request and response model, enumeration and error type used by the myPOS ePOS API. Any property whose type is itself a model links to that model’s section on this page, and the endpoint pages link back here.

NameKindDescription
Activation Deactivation ResponseModelThe code returned when a terminal is activated or deactivated.
Create AmountModelA monetary amount: the value, its currency and an optional tip.
Get Payment By ID ResponseModelFull details of a single ePOS payment, including card, authorisation and currency conversion data.
Get Terminal Details ResponseModelConfiguration, settlement and receipt settings for a single POS terminal.
Get Terminal Payments By TID ResponseModelA paginated page of the payments taken on one terminal.
Get Terminal Receipt ResponseModelEvery field needed to reproduce the cardholder receipt for a terminal payment.
Get Terminal ResponseModelA paginated list of the merchant's POS terminals.
Get Terminal Transactions By ID ResponseModelThe transactions carried out on one specific terminal.
Get Terminal Transactions ResponseModelA paginated list of transactions across all of the merchant's terminals.
Outlet ResponseModelAn outlet, that is a physical location that terminals can be assigned to.
Payment InfoModelThe state of a payment once a cancellation request has been accepted.
Payment Refund RequestModelRequest to refund an amount from a terminal back to the cardholder.
Payment RequestModelRequest to create a payment and send it to a POS terminal for the cardholder to complete.
Payment Reversal By ID RequestModelRequest to void a payment before it has been settled.
Payment Reversal By ID ResponseModelThe state of a payment after it has been voided.
Terminal Model ResponseModelA terminal hardware model and the code that identifies it.
Terminal TransactionModelA single terminal transaction, with its card, settlement and fee details.
Payment ResponseModelA newly created ePOS payment and its current status.
Terminal Refund RequestModelRequest to refund a previously referenced transaction on a specific terminal.
Payment StatusEnumCurrent lifecycle status of an ePOS payment.
Problem DetailsErrorThe standard error payload (RFC 7807) returned when a request fails.
Validation Problem DetailsErrorThe error payload returned when a request fails validation, adding a per-field errors map.

Models

Activation Deactivation Response

The code returned when a terminal is activated or deactivated.

AttributeTypeDescription
codestringActivation or deactivation code to be entered on the terminal.
Example: 11315157

Create Amount

A monetary amount: the value, its currency and an optional tip.

AttributeTypeDescription
valueinteger (int32)Payment amount in the smallest currency unit (e.g., for EUR: 1500 = €15.00).
Example: 1500
currency_codestringISO 4217 three-letter currency code (e.g., EUR, USD).
Example: EUR
tipinteger (int32)Optional tip amount in the smallest currency unit.
Example: 500

Get Payment By ID Response

Full details of a single ePOS payment, including card, authorisation and currency conversion data.

AttributeTypeDescription
payment_idstringUnique identifier of the payment.
Example: 67f826f21b62d43a1f65833a
statusPayment StatusCurrent status of the payment.
Example: InProgress
amountCreate AmountPayment amount details.
created_atstringTimestamp when the payment was created.
Example: 2025-10-27T07:35:48
updated_atstringTimestamp when the payment was last updated.
Example: 2025-10-27T07:35:48
reference_numberstringMerchant-assigned reference number for this payment.
Example: REF1234567890
descriptionstringDescription of the payment.
Example: Test request
expire_atstringTimestamp when the payment request expires.
Example: 2025-11-26T07:35:48
dcc_amountintegerAmount in the cardholder's home currency when Dynamic Currency Conversion was applied.
Example: 0
dcc_card_exchange_rateintegerExchange rate applied for Dynamic Currency Conversion.
Example: 0
stanstringSystem Trace Audit Number assigned by the terminal.
Example: 000408
auth_codestringAuthorization code returned by the card issuer.
Example: VISSIM
transaction_date_localstringTransaction date and time in local terminal time (format: YYMMDDHHmmss).
Example: 250620165140
status_messagestringDescriptive status message from the payment processor.
Example: TRANSACTION_SUCCESS
dcc_availablebooleanIndicates whether Dynamic Currency Conversion was offered for this transaction.
reference_typestringReference type mode for this transaction.
Example: OFF
signature_requiredbooleanIndicates whether a cardholder signature was required.
aidstringEMV Application Identifier of the card application used (e.g., A0000000031010 for Visa).
Example: A0000000031010
card_qualifierstringCard scheme or brand (e.g., VISA, Mastercard).
Example: VISA
response_codestringISO 8583 response code. "00" indicates approval.
Example: 00
panstringMasked Primary Account Number of the card used (last 4 digits visible).
Example: ****6693
rrnstringRetrieval Reference Number assigned by the card network.
Example: 517114115174

Get Terminal Details Response

Configuration, settlement and receipt settings for a single POS terminal.

AttributeTypeDescription
terminal_namestringCustom display name of the POS device.
Example: Demo Ultra
outlet_idinteger (int64)Numeric identifier of the merchant outlet this terminal is assigned to.
Example: 20577
outlet_namestringName of the outlet.
Example: test
device_currencystringDefault transaction currency of the terminal (ISO 4217 code).
Example: EUR
statusstringCurrent operational status of the terminal (e.g., Active, Inactive).
Example: Active
last_transaction_datestringDate and time of the most recent transaction on this terminal.
Example: 2025-10-13 10:12:14
transactions_countinteger (int32)Total number of transactions processed by this terminal.
Example: 11
settlement_account_numberstringAccount number of the linked settlement account.
Example: 50480563548
settlement_account_namestringDisplay name of the settlement account.
Example: EUR Account
settlement_account_currencystringCurrency of the settlement account (ISO 4217 code).
Example: EUR
billing_descriptorstringMerchant descriptor that appears on cardholders' bank statements.
Example: DEMO ULTRA
receipt_footer_row_1stringFirst custom text line printed in the footer of receipts.
receipt_footer_row_2stringSecond custom text line printed in the footer of receipts.
forbidden_preauthorizationstringWhether preauthorization transactions are disabled on this terminal. Values: "True" or "False".
Example: False
forbidden_motostringWhether MOTO (Mail Order / Telephone Order) transactions are disabled. Values: "True" or "False".
Example: True
forbidden_reversalstringWhether reversals are disabled on this terminal. Values: "True" or "False".
Example: False
forbidden_refundstringWhether refunds are disabled on this terminal. Values: "True" or "False".
Example: False
forbidden_topupstringWhether top-up transactions are disabled on this terminal. Values: "True" or "False".
Example: False
card_topup_enabledstringWhether card top-up is enabled on this terminal. Values: "True" or "False".
Example: False
terminal_idstringThe 8-digit Terminal ID (TID) of the POS device.
Example: 80026232
serial_numberstringHardware serial number of the POS device.
Example: N96N960WC15224
modelstringModel code of the POS device (e.g., N96, D200).
Example: N96

Get Terminal Payments By TID Response

A paginated page of the payments taken on one terminal.

AttributeTypeDescription
itemsarray of objectList of payments for the terminal.
pageintegerCurrent page number of the result set.
Example: 0
page_sizeintegerNumber of items returned per page.
Example: 0
total_pagesintegerTotal number of pages available.
Example: 0
total_countintegerTotal number of payments matching the query.
Example: 0
has_previous_pagebooleanIndicates whether a previous page of results exists.
has_next_pagebooleanIndicates whether a next page of results exists.

Get Terminal Payments By TID Responseitems (each item)

AttributeTypeDescription
payment_idstringUnique payment identifier.
Example: 67f52eb66d0295252b5ec009
statusPayment StatusPayment status.
Example: InProgress
amountCreate AmountA monetary amount: the value, its currency and an optional tip.
created_atstringISO 8601 timestamp when the payment was created.
Example: 2025-05-02T09:38:59.4483833+03:00
updated_atstringISO 8601 timestamp when the payment was last updated.
Example: 0001-01-01T00:00:00
reference_numberstringMerchant-assigned reference number for the payment.
Example: REF1234567890
descriptionstringOptional description of the payment.
Example: Test request
expire_atstringISO 8601 timestamp when the payment request expires.
Example: 2025-11-26T07:35:48
dcc_amountintegerDynamic Currency Conversion amount in the cardholder's home currency.
Example: 0
dcc_card_exchange_rateintegerExchange rate applied for Dynamic Currency Conversion.
Example: 0
stanstringSystem Trace Audit Number assigned by the terminal.
Example: 000408
auth_codestringAuthorization code from the card issuer.
Example: VISSIM
transaction_date_localstringLocal transaction date and time on the terminal (format: YYMMDDHHmmss).
Example: 250620165140
status_messagestringHuman-readable status message from the payment processor.
Example: TRANSACTION_SUCCESS
dcc_availablebooleanTrue if Dynamic Currency Conversion was available for this transaction.
reference_typestringReference type indicating how the payment reference was generated.
Example: OFF
signature_requiredbooleanTrue if a cardholder signature was required for this transaction.
aidstringEMV Application Identifier used in the transaction.
Example: A0000000031010
card_qualifierstringCard scheme or product qualifier.
Example: VISA
response_codestringISO 8583 response code from the card network (00 = approved).
Example: 00
panstringMasked Primary Account Number of the card.
Example: ****6693
rrnstringRetrieval Reference Number assigned by the card network.
Example: 517114115174

Get Terminal Receipt Response

Every field needed to reproduce the cardholder receipt for a terminal payment.

AttributeTypeDescription
is_declinedinteger (int32)1 if the transaction was declined; 0 if approved.
Example: 0
receipt_layout_versioninteger (int32)Version of the receipt layout template used.
Example: 0
exchange_ratestringExchange rate applied for Dynamic Currency Conversion.
Example: string
datestringTransaction date (format: YYYY-MM-DD).
Example: 2025-04-03
timestringTransaction time (format: HH:mm:ss).
Example: 17:22:04
stanstringSystem Trace Audit Number assigned by the terminal.
Example: 000015
terminal_idstringThe 8-digit Terminal ID (TID) of the POS device.
Example: 80025374
merchant_idstringMerchant identifier registered with the card network.
Example: 000000010625902
merchant_namestringRegistered merchant name.
Example: DEMO
address_line_1stringFirst line of the merchant address.
Example: BULGARIA
address_line_2stringSecond line of the merchant address.
Example: BULGARIA
pl_card_balancestringPrepaid or loyalty card balance (if applicable).
Example: string
pl_card_balance_currencystringCurrency of the prepaid or loyalty card balance.
Example: string
resp_codestringResponse code from the card issuer.
Example: string
reference_numberstringMerchant-assigned reference number for the transaction.
Example: REF1234567890
application_preferred_namestringEMV application preferred name displayed on the receipt (e.g., Visa).
Example: Visa
installment_typestringInstallment plan type (if applicable).
Example: string
installment_numberstringNumber of installments (if applicable).
Example: string
installment_interest_ratestringInterest rate for the installment plan.
Example: string
installment_first_amountstringAmount of the first installment payment.
Example: string
installment_subseq_amountstringAmount of subsequent installment payments.
installment_annual_perc_ratestringAnnual percentage rate for the installment plan.
Example: string
installment_fee_ratestringFee rate applied to the installment plan.
Example: string
installment_total_amountstringTotal amount payable over all installments.
Example: string
transaction_preauth_codestringPre-authorization code (if a preauth was performed).
Example: string
card_schemestringCard scheme or product name.
Example: Business Premium Debit
panstringMasked Primary Account Number of the card.
Example: "*9766
emboss_namestringCardholder name as embossed on the card.
Example: string
amountstringTransaction amount as a formatted string.
Example: 1.00
currencystringISO 4217 currency code.
Example: EUR
auth_codestringAuthorization code from the card issuer.
Example: VISSIM
rrnstringRetrieval Reference Number assigned by the card network.
Example: 509314069273
aidstringEMV Application Identifier.
Example: A0000000031010
amount_tipstringTip amount as a formatted string.
Example: 0
amount_totalstringTotal amount (base + tip) as a formatted string.
Example: 0
operator_codestringOperator or cashier code.
Example: string
dcc_amountstringDCC amount in the cardholder's home currency.
Example: string
dcc_currencystringCurrency used for Dynamic Currency Conversion.
Example: string
tran_typestringTransaction type code.
sign_row_1stringFirst signature line on the receipt.
Example: string
sign_row_2stringSecond signature line on the receipt.
Example: string
sign_row_3stringThird signature line on the receipt.
Example: string
exchange_rate_translationstringHuman-readable exchange rate description for DCC.
tran_statusstringTransaction status description (e.g., Approved, Declined).
Example: Approved
receipt_footer_row_1stringFirst custom footer line.
Example: string
receipt_footer_row_2stringSecond custom footer line.
Example: string

Get Terminal Response

A paginated list of the merchant's POS terminals.

AttributeTypeDescription
paginationobjectPagination metadata for the result set.
terminalsarray of objectList of terminals matching the query.

Get Terminal Responsepagination

Pagination metadata for the result set.

AttributeTypeDescription
page_sizeintegerNumber of items returned per page.
Example: 0
pageintegerCurrent page number of the result set.
Example: 0
totalintegerTotal number of terminals matching the query.
Example: 0

Get Terminal Responseterminals (each item)

AttributeTypeDescription
terminal_idstringThe 8-digit Terminal ID (TID) of the POS device.
Example: 80026232
serial_numberstringHardware serial number of the terminal.
Example: N96N960WC15224
modelstringTerminal model code (e.g., N96 for myPOS Ultra).
Example: N96

Get Terminal Transactions By ID Response

The transactions carried out on one specific terminal.

AttributeTypeDescription
transactionsarray of Terminal TransactionList of transactions for the specified terminal.

Get Terminal Transactions Response

A paginated list of transactions across all of the merchant's terminals.

AttributeTypeDescription
paginationobjectPagination metadata for the result set.
transactionsarray of objectList of transactions matching the query.

Get Terminal Transactions Responsepagination

Pagination metadata for the result set.

AttributeTypeDescription
page_sizeintegerNumber of items returned per page.
Example: 0
pageintegerCurrent page number of the result set.
Example: 0
totalintegerTotal number of transactions matching the query.
Example: 0

Get Terminal Transactions Responsetransactions (each item)

AttributeTypeDescription
terminal_idstringThe 8-digit Terminal ID (TID) of the POS device.
Example: 80026232
datestringTransaction date and time (format: YYYY-MM-DD HH:mm:ss).
Example: 2025-10-13 10:12:06
terminal_namestringMerchant-assigned name of the terminal.
Example: Demo Ultra
outlet_namestringName of the outlet associated with the terminal.
Example: string
tran_statusstringTransaction status description (e.g., Approved, Declined).
Example: Approved
payment_statusstringPayment status description (e.g., Paid, Reversed).
Example: Paid
amountnumber (double)Transaction amount in the terminal's currency.
Example: 0.22
currencystringISO 4217 currency code of the transaction.
Example: EUR
rrnstringRetrieval Reference Number assigned by the card network.
Example: 528607108520
stanstringSystem Trace Audit Number assigned by the terminal.
Example: 000029
settlement_datestringDate and time the transaction was settled.
Example: 2025-10-13 10:12:16
settlement_amountnumber (double)Amount settled after fees and currency conversion.
Example: 0.22
settlement_currencystringISO 4217 currency code used for settlement.
Example: EUR
feenumber (double)Transaction fee charged by myPOS.
Example: 0.01
panstringMasked Primary Account Number of the card.
Example: *9766
card_schemestringCard scheme or product name.
Example: Business Premium Debit
payment_referencestringUnique payment reference generated by the POS system.
Example: POSA015257Y6IR59
billing_descriptorstringMerchant billing descriptor appearing on the cardholder's statement.
Example: DEMO ULTRA
reference_numberstringMerchant-assigned reference number for the transaction.
Example: REF1234567890

Outlet Response

An outlet, that is a physical location that terminals can be assigned to.

AttributeTypeDescription
outlet_idinteger (int64)Unique identifier of the outlet.
Example: 20577
namestringName of the outlet.
Example: DEMO DEMO

Payment Info

The state of a payment once a cancellation request has been accepted.

AttributeTypeDescription
request_idstringUnique identifier of the delete (cancel) request.
Example: 67f7d0a2f7151530e5996a0d
statusPayment StatusPayment status after the cancellation request.
Example: InProgress
app_namestringName of the application that initiated the cancellation.
Example: CashApp
app_versionstringVersion of the application that initiated the cancellation.
Example: 1.0.0
operator_codestringOperator or cashier code.
Example: 10
reference_numberstringMerchant-assigned reference number for the payment.
Example: REF1234567890
descriptionstringDescription provided at the time of payment creation.
Example: Client cancelled the order

Payment Refund Request

Request to refund an amount from a terminal back to the cardholder.

AttributeTypeDescription
amountCreate AmountAmount to refund.
descriptionstringOptional reason or description for the refund.
Example: Refund issued due to customer complaint
terminal_idstringThe 8-digit Terminal ID (TID) of the POS device processing the refund.
Example: 80123457
app_namestringName of the application initiating the refund.
Example: RefundApp
app_versionstringVersion of the application initiating the refund.
Example: 2.1.0

Payment Request

Request to create a payment and send it to a POS terminal for the cardholder to complete.

AttributeTypeDescription
reference_numberstringMerchant-assigned reference number for the payment. Maximum 50 characters.
amountCreate AmountPayment amount and currency.
descriptionstringOptional description of the payment.
terminal_idstringThe 8-digit Terminal ID (TID) of the POS device to process the payment.
app_namestringName of the application initiating the payment.
app_versionstringVersion of the application initiating the payment.
operator_codestringOperator or cashier code. Maximum 4 characters.

Payment Reversal By ID Request

Request to void a payment before it has been settled.

AttributeTypeDescription
descriptionstringOptional reason or description for the reversal.
Example: Customer requested reversal due to duplicate transaction
terminal_idstringThe 8-digit Terminal ID (TID) of the POS device processing the reversal.
Example: 80123457
app_namestringName of the application initiating the reversal.
Example: MyPOSApp
app_versionstringVersion of the application initiating the reversal.
Example: 1.0.3

Payment Reversal By ID Response

The state of a payment after it has been voided.

AttributeTypeDescription
payment_idstringUnique payment identifier of the reversed payment.
Example: 67f82b071b62d43a1f65833b
statusPayment StatusPayment status after the reversal.
Example: InProgress
amountCreate AmountOriginal payment amount.
created_atstringISO 8601 timestamp when the payment was created.
Example: 2025-10-27T07:56:24
updated_atstringISO 8601 timestamp when the payment was last updated.
Example: 2025-10-27T07:56:24
reference_numberstringMerchant-assigned reference number for the payment.
Example: REF1234567890
descriptionstringDescription provided at the time of payment creation.
Example: Test request
expire_atstringISO 8601 timestamp when the payment request expires.
Example: 2025-11-26T07:35:48

Terminal Model Response

A terminal hardware model and the code that identifies it.

AttributeTypeDescription
codestringTerminal model code.
Example: N96
descriptionstringHuman-readable name of the terminal model.
Example: myPOS Ultra

Terminal Transaction

A single terminal transaction, with its card, settlement and fee details.

AttributeTypeDescription
terminal_idstringThe 8-digit Terminal ID (TID) of the POS device.
Example: 80026232
datestringTransaction date and time (format: YYYY-MM-DD HH:mm:ss).
Example: 2025-10-13 10:12:06
terminal_namestringMerchant-assigned name of the terminal.
Example: Demo Ultra
outlet_namestringName of the outlet associated with the terminal.
Example: string
tran_statusstringTransaction status description (e.g., Approved, Declined).
Example: Approved
payment_statusstringPayment status description (e.g., Paid, Reversed).
Example: Paid
amountnumber (double)Transaction amount in the terminal's currency.
Example: 0.22
currencystringISO 4217 currency code of the transaction.
Example: EUR
rrnstringRetrieval Reference Number assigned by the card network.
Example: 528607108520
stanstringSystem Trace Audit Number assigned by the terminal.
Example: 000029
settlement_datestringDate and time the transaction was settled.
Example: 2025-10-13 10:12:16
settlement_amountnumber (double)Amount settled after fees and currency conversion.
Example: 0.22
settlement_currencystringISO 4217 currency code used for settlement.
Example: EUR
feenumber (double)Transaction fee charged by myPOS.
Example: 0.01
panstringMasked Primary Account Number of the card.
Example: *9766
card_schemestringCard scheme or product name.
Example: Business Premium Debit
payment_referencestringUnique payment reference generated by the POS system.
Example: POSA015257Y6IR59
billing_descriptorstringMerchant billing descriptor appearing on the cardholder's statement.
Example: DEMO ULTRA
reference_numberstringMerchant-assigned reference number for the transaction.
Example: REF1234567890

Payment Response

A newly created ePOS payment and its current status.

AttributeTypeDescription
payment_idstringUnique payment identifier.
Example: 68ff25a853659f6448da0eba
statusPayment StatusPayment status.
Example: InProgress
amountCreate AmountPayment amount and currency.
created_atstringISO 8601 timestamp when the payment was created.
Example: 2025-10-27T09:56:24
updated_atstringISO 8601 timestamp when the payment was last updated.
Example: 2025-10-27T09:56:24
reference_numberstringMerchant-assigned reference number for the payment.
Example: REF1234567890
descriptionstringOptional description of the payment.
Example: Test request
expire_atstringISO 8601 timestamp when the payment request expires.
Example: 2025-11-27T09:56:24

Terminal Refund Request

Request to refund a previously referenced transaction on a specific terminal.

AttributeTypeDescription
reference_numberstringReference number of the original payment to refund.
Example: REF1234567890
amountnumber (double)Refund amount.
Example: 0.22

Enumerations

Payment Status

Current lifecycle status of an ePOS payment.

ValueDescription
InProgressThe payment has been created and sent to the terminal, and the cardholder has not completed it yet.
SuccessThe payment was authorised by the card issuer and completed successfully.
CanceledThe payment was cancelled before it was completed, either by the merchant or because it expired.
FailedThe payment could not be processed because of a technical or processing error.
ReversedA previously successful payment was voided before settlement.
RejectedThe payment was declined by the card issuer or by risk rules.

Error responses

Failed requests return a Problem Details object (RFC 7807). Validation failures (400 Bad Request) return Validation Problem Details, which adds a per-field errors map.

Problem Details

The standard error payload (RFC 7807) returned when a request fails.

AttributeTypeDescription
typestringA URI reference identifying the problem type.
titlestringA short human-readable summary of the problem type.
statusintegerThe HTTP status code.
detailstringA human-readable explanation specific to this occurrence of the problem.
instancestringA URI reference that identifies the specific occurrence of the problem.
additionalProp1stringAdditional extension member.
additionalProp2stringAdditional extension member.
additionalProp3stringAdditional extension member.

Validation Problem Details

The error payload returned when a request fails validation, adding a per-field errors map.

AttributeTypeDescription
typestringA URI reference identifying the problem type.
titlestringA short human-readable summary of the problem type.
statusintegerThe HTTP status code.
detailstringA human-readable explanation specific to this occurrence of the problem.
instancestringA URI reference that identifies the specific occurrence of the problem.
errorsobjectMap of field names to their validation error messages.
additionalProp1stringAdditional extension member.
additionalProp2stringAdditional extension member.
additionalProp3stringAdditional extension member.

Validation Problem Detailserrors

Map of field names to their validation error messages.

AttributeTypeDescription
additionalProp1array of string
additionalProp2array of string
additionalProp3array of string