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.
| Name | Kind | Description |
|---|---|---|
| Activation Deactivation Response | Model | The code returned when a terminal is activated or deactivated. |
| Create Amount | Model | A monetary amount: the value, its currency and an optional tip. |
| Get Payment By ID Response | Model | Full details of a single ePOS payment, including card, authorisation and currency conversion data. |
| Get Terminal Details Response | Model | Configuration, settlement and receipt settings for a single POS terminal. |
| Get Terminal Payments By TID Response | Model | A paginated page of the payments taken on one terminal. |
| Get Terminal Receipt Response | Model | Every field needed to reproduce the cardholder receipt for a terminal payment. |
| Get Terminal Response | Model | A paginated list of the merchant's POS terminals. |
| Get Terminal Transactions By ID Response | Model | The transactions carried out on one specific terminal. |
| Get Terminal Transactions Response | Model | A paginated list of transactions across all of the merchant's terminals. |
| Outlet Response | Model | An outlet, that is a physical location that terminals can be assigned to. |
| Payment Info | Model | The state of a payment once a cancellation request has been accepted. |
| Payment Refund Request | Model | Request to refund an amount from a terminal back to the cardholder. |
| Payment Request | Model | Request to create a payment and send it to a POS terminal for the cardholder to complete. |
| Payment Reversal By ID Request | Model | Request to void a payment before it has been settled. |
| Payment Reversal By ID Response | Model | The state of a payment after it has been voided. |
| Terminal Model Response | Model | A terminal hardware model and the code that identifies it. |
| Terminal Transaction | Model | A single terminal transaction, with its card, settlement and fee details. |
| Payment Response | Model | A newly created ePOS payment and its current status. |
| Terminal Refund Request | Model | Request to refund a previously referenced transaction on a specific terminal. |
| Payment Status | Enum | Current lifecycle status of an ePOS payment. |
| Problem Details | Error | The standard error payload (RFC 7807) returned when a request fails. |
| Validation Problem Details | Error | The 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.
| Attribute | Type | Description |
|---|---|---|
code | string | Activation or deactivation code to be entered on the terminal. Example: 11315157 |
Create Amount
A monetary amount: the value, its currency and an optional tip.
| Attribute | Type | Description |
|---|---|---|
value | integer (int32) | Payment amount in the smallest currency unit (e.g., for EUR: 1500 = €15.00). Example: 1500 |
currency_code | string | ISO 4217 three-letter currency code (e.g., EUR, USD). Example: EUR |
tip | integer (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.
| Attribute | Type | Description |
|---|---|---|
payment_id | string | Unique identifier of the payment. Example: 67f826f21b62d43a1f65833a |
status | Payment Status | Current status of the payment. Example: InProgress |
amount | Create Amount | Payment amount details. |
created_at | string | Timestamp when the payment was created. Example: 2025-10-27T07:35:48 |
updated_at | string | Timestamp when the payment was last updated. Example: 2025-10-27T07:35:48 |
reference_number | string | Merchant-assigned reference number for this payment. Example: REF1234567890 |
description | string | Description of the payment. Example: Test request |
expire_at | string | Timestamp when the payment request expires. Example: 2025-11-26T07:35:48 |
dcc_amount | integer | Amount in the cardholder's home currency when Dynamic Currency Conversion was applied. Example: 0 |
dcc_card_exchange_rate | integer | Exchange rate applied for Dynamic Currency Conversion. Example: 0 |
stan | string | System Trace Audit Number assigned by the terminal. Example: 000408 |
auth_code | string | Authorization code returned by the card issuer. Example: VISSIM |
transaction_date_local | string | Transaction date and time in local terminal time (format: YYMMDDHHmmss). Example: 250620165140 |
status_message | string | Descriptive status message from the payment processor. Example: TRANSACTION_SUCCESS |
dcc_available | boolean | Indicates whether Dynamic Currency Conversion was offered for this transaction. |
reference_type | string | Reference type mode for this transaction. Example: OFF |
signature_required | boolean | Indicates whether a cardholder signature was required. |
aid | string | EMV Application Identifier of the card application used (e.g., A0000000031010 for Visa). Example: A0000000031010 |
card_qualifier | string | Card scheme or brand (e.g., VISA, Mastercard). Example: VISA |
response_code | string | ISO 8583 response code. "00" indicates approval. Example: 00 |
pan | string | Masked Primary Account Number of the card used (last 4 digits visible). Example: ****6693 |
rrn | string | Retrieval Reference Number assigned by the card network. Example: 517114115174 |
Get Terminal Details Response
Configuration, settlement and receipt settings for a single POS terminal.
| Attribute | Type | Description |
|---|---|---|
terminal_name | string | Custom display name of the POS device. Example: Demo Ultra |
outlet_id | integer (int64) | Numeric identifier of the merchant outlet this terminal is assigned to. Example: 20577 |
outlet_name | string | Name of the outlet. Example: test |
device_currency | string | Default transaction currency of the terminal (ISO 4217 code). Example: EUR |
status | string | Current operational status of the terminal (e.g., Active, Inactive). Example: Active |
last_transaction_date | string | Date and time of the most recent transaction on this terminal. Example: 2025-10-13 10:12:14 |
transactions_count | integer (int32) | Total number of transactions processed by this terminal. Example: 11 |
settlement_account_number | string | Account number of the linked settlement account. Example: 50480563548 |
settlement_account_name | string | Display name of the settlement account. Example: EUR Account |
settlement_account_currency | string | Currency of the settlement account (ISO 4217 code). Example: EUR |
billing_descriptor | string | Merchant descriptor that appears on cardholders' bank statements. Example: DEMO ULTRA |
receipt_footer_row_1 | string | First custom text line printed in the footer of receipts. |
receipt_footer_row_2 | string | Second custom text line printed in the footer of receipts. |
forbidden_preauthorization | string | Whether preauthorization transactions are disabled on this terminal. Values: "True" or "False". Example: False |
forbidden_moto | string | Whether MOTO (Mail Order / Telephone Order) transactions are disabled. Values: "True" or "False". Example: True |
forbidden_reversal | string | Whether reversals are disabled on this terminal. Values: "True" or "False". Example: False |
forbidden_refund | string | Whether refunds are disabled on this terminal. Values: "True" or "False". Example: False |
forbidden_topup | string | Whether top-up transactions are disabled on this terminal. Values: "True" or "False". Example: False |
card_topup_enabled | string | Whether card top-up is enabled on this terminal. Values: "True" or "False". Example: False |
terminal_id | string | The 8-digit Terminal ID (TID) of the POS device. Example: 80026232 |
serial_number | string | Hardware serial number of the POS device. Example: N96N960WC15224 |
model | string | Model 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.
| Attribute | Type | Description |
|---|---|---|
items | array of object | List of payments for the terminal. |
page | integer | Current page number of the result set. Example: 0 |
page_size | integer | Number of items returned per page. Example: 0 |
total_pages | integer | Total number of pages available. Example: 0 |
total_count | integer | Total number of payments matching the query. Example: 0 |
has_previous_page | boolean | Indicates whether a previous page of results exists. |
has_next_page | boolean | Indicates whether a next page of results exists. |
Get Terminal Payments By TID Response › items (each item)
| Attribute | Type | Description |
|---|---|---|
payment_id | string | Unique payment identifier. Example: 67f52eb66d0295252b5ec009 |
status | Payment Status | Payment status. Example: InProgress |
amount | Create Amount | A monetary amount: the value, its currency and an optional tip. |
created_at | string | ISO 8601 timestamp when the payment was created. Example: 2025-05-02T09:38:59.4483833+03:00 |
updated_at | string | ISO 8601 timestamp when the payment was last updated. Example: 0001-01-01T00:00:00 |
reference_number | string | Merchant-assigned reference number for the payment. Example: REF1234567890 |
description | string | Optional description of the payment. Example: Test request |
expire_at | string | ISO 8601 timestamp when the payment request expires. Example: 2025-11-26T07:35:48 |
dcc_amount | integer | Dynamic Currency Conversion amount in the cardholder's home currency. Example: 0 |
dcc_card_exchange_rate | integer | Exchange rate applied for Dynamic Currency Conversion. Example: 0 |
stan | string | System Trace Audit Number assigned by the terminal. Example: 000408 |
auth_code | string | Authorization code from the card issuer. Example: VISSIM |
transaction_date_local | string | Local transaction date and time on the terminal (format: YYMMDDHHmmss). Example: 250620165140 |
status_message | string | Human-readable status message from the payment processor. Example: TRANSACTION_SUCCESS |
dcc_available | boolean | True if Dynamic Currency Conversion was available for this transaction. |
reference_type | string | Reference type indicating how the payment reference was generated. Example: OFF |
signature_required | boolean | True if a cardholder signature was required for this transaction. |
aid | string | EMV Application Identifier used in the transaction. Example: A0000000031010 |
card_qualifier | string | Card scheme or product qualifier. Example: VISA |
response_code | string | ISO 8583 response code from the card network (00 = approved). Example: 00 |
pan | string | Masked Primary Account Number of the card. Example: ****6693 |
rrn | string | Retrieval 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.
| Attribute | Type | Description |
|---|---|---|
is_declined | integer (int32) | 1 if the transaction was declined; 0 if approved. Example: 0 |
receipt_layout_version | integer (int32) | Version of the receipt layout template used. Example: 0 |
exchange_rate | string | Exchange rate applied for Dynamic Currency Conversion. Example: string |
date | string | Transaction date (format: YYYY-MM-DD). Example: 2025-04-03 |
time | string | Transaction time (format: HH:mm:ss). Example: 17:22:04 |
stan | string | System Trace Audit Number assigned by the terminal. Example: 000015 |
terminal_id | string | The 8-digit Terminal ID (TID) of the POS device. Example: 80025374 |
merchant_id | string | Merchant identifier registered with the card network. Example: 000000010625902 |
merchant_name | string | Registered merchant name. Example: DEMO |
address_line_1 | string | First line of the merchant address. Example: BULGARIA |
address_line_2 | string | Second line of the merchant address. Example: BULGARIA |
pl_card_balance | string | Prepaid or loyalty card balance (if applicable). Example: string |
pl_card_balance_currency | string | Currency of the prepaid or loyalty card balance. Example: string |
resp_code | string | Response code from the card issuer. Example: string |
reference_number | string | Merchant-assigned reference number for the transaction. Example: REF1234567890 |
application_preferred_name | string | EMV application preferred name displayed on the receipt (e.g., Visa). Example: Visa |
installment_type | string | Installment plan type (if applicable). Example: string |
installment_number | string | Number of installments (if applicable). Example: string |
installment_interest_rate | string | Interest rate for the installment plan. Example: string |
installment_first_amount | string | Amount of the first installment payment. Example: string |
installment_subseq_amount | string | Amount of subsequent installment payments. |
installment_annual_perc_rate | string | Annual percentage rate for the installment plan. Example: string |
installment_fee_rate | string | Fee rate applied to the installment plan. Example: string |
installment_total_amount | string | Total amount payable over all installments. Example: string |
transaction_preauth_code | string | Pre-authorization code (if a preauth was performed). Example: string |
card_scheme | string | Card scheme or product name. Example: Business Premium Debit |
pan | string | Masked Primary Account Number of the card. Example: "*9766 |
emboss_name | string | Cardholder name as embossed on the card. Example: string |
amount | string | Transaction amount as a formatted string. Example: 1.00 |
currency | string | ISO 4217 currency code. Example: EUR |
auth_code | string | Authorization code from the card issuer. Example: VISSIM |
rrn | string | Retrieval Reference Number assigned by the card network. Example: 509314069273 |
aid | string | EMV Application Identifier. Example: A0000000031010 |
amount_tip | string | Tip amount as a formatted string. Example: 0 |
amount_total | string | Total amount (base + tip) as a formatted string. Example: 0 |
operator_code | string | Operator or cashier code. Example: string |
dcc_amount | string | DCC amount in the cardholder's home currency. Example: string |
dcc_currency | string | Currency used for Dynamic Currency Conversion. Example: string |
tran_type | string | Transaction type code. |
sign_row_1 | string | First signature line on the receipt. Example: string |
sign_row_2 | string | Second signature line on the receipt. Example: string |
sign_row_3 | string | Third signature line on the receipt. Example: string |
exchange_rate_translation | string | Human-readable exchange rate description for DCC. |
tran_status | string | Transaction status description (e.g., Approved, Declined). Example: Approved |
receipt_footer_row_1 | string | First custom footer line. Example: string |
receipt_footer_row_2 | string | Second custom footer line. Example: string |
Get Terminal Response
A paginated list of the merchant's POS terminals.
| Attribute | Type | Description |
|---|---|---|
pagination | object | Pagination metadata for the result set. |
terminals | array of object | List of terminals matching the query. |
Get Terminal Response › pagination
Pagination metadata for the result set.
| Attribute | Type | Description |
|---|---|---|
page_size | integer | Number of items returned per page. Example: 0 |
page | integer | Current page number of the result set. Example: 0 |
total | integer | Total number of terminals matching the query. Example: 0 |
Get Terminal Response › terminals (each item)
| Attribute | Type | Description |
|---|---|---|
terminal_id | string | The 8-digit Terminal ID (TID) of the POS device. Example: 80026232 |
serial_number | string | Hardware serial number of the terminal. Example: N96N960WC15224 |
model | string | Terminal model code (e.g., N96 for myPOS Ultra). Example: N96 |
Get Terminal Transactions By ID Response
The transactions carried out on one specific terminal.
| Attribute | Type | Description |
|---|---|---|
transactions | array of Terminal Transaction | List of transactions for the specified terminal. |
Get Terminal Transactions Response
A paginated list of transactions across all of the merchant's terminals.
| Attribute | Type | Description |
|---|---|---|
pagination | object | Pagination metadata for the result set. |
transactions | array of object | List of transactions matching the query. |
Get Terminal Transactions Response › pagination
Pagination metadata for the result set.
| Attribute | Type | Description |
|---|---|---|
page_size | integer | Number of items returned per page. Example: 0 |
page | integer | Current page number of the result set. Example: 0 |
total | integer | Total number of transactions matching the query. Example: 0 |
Get Terminal Transactions Response › transactions (each item)
| Attribute | Type | Description |
|---|---|---|
terminal_id | string | The 8-digit Terminal ID (TID) of the POS device. Example: 80026232 |
date | string | Transaction date and time (format: YYYY-MM-DD HH:mm:ss). Example: 2025-10-13 10:12:06 |
terminal_name | string | Merchant-assigned name of the terminal. Example: Demo Ultra |
outlet_name | string | Name of the outlet associated with the terminal. Example: string |
tran_status | string | Transaction status description (e.g., Approved, Declined). Example: Approved |
payment_status | string | Payment status description (e.g., Paid, Reversed). Example: Paid |
amount | number (double) | Transaction amount in the terminal's currency. Example: 0.22 |
currency | string | ISO 4217 currency code of the transaction. Example: EUR |
rrn | string | Retrieval Reference Number assigned by the card network. Example: 528607108520 |
stan | string | System Trace Audit Number assigned by the terminal. Example: 000029 |
settlement_date | string | Date and time the transaction was settled. Example: 2025-10-13 10:12:16 |
settlement_amount | number (double) | Amount settled after fees and currency conversion. Example: 0.22 |
settlement_currency | string | ISO 4217 currency code used for settlement. Example: EUR |
fee | number (double) | Transaction fee charged by myPOS. Example: 0.01 |
pan | string | Masked Primary Account Number of the card. Example: *9766 |
card_scheme | string | Card scheme or product name. Example: Business Premium Debit |
payment_reference | string | Unique payment reference generated by the POS system. Example: POSA015257Y6IR59 |
billing_descriptor | string | Merchant billing descriptor appearing on the cardholder's statement. Example: DEMO ULTRA |
reference_number | string | Merchant-assigned reference number for the transaction. Example: REF1234567890 |
Outlet Response
An outlet, that is a physical location that terminals can be assigned to.
| Attribute | Type | Description |
|---|---|---|
outlet_id | integer (int64) | Unique identifier of the outlet. Example: 20577 |
name | string | Name of the outlet. Example: DEMO DEMO |
Payment Info
The state of a payment once a cancellation request has been accepted.
| Attribute | Type | Description |
|---|---|---|
request_id | string | Unique identifier of the delete (cancel) request. Example: 67f7d0a2f7151530e5996a0d |
status | Payment Status | Payment status after the cancellation request. Example: InProgress |
app_name | string | Name of the application that initiated the cancellation. Example: CashApp |
app_version | string | Version of the application that initiated the cancellation. Example: 1.0.0 |
operator_code | string | Operator or cashier code. Example: 10 |
reference_number | string | Merchant-assigned reference number for the payment. Example: REF1234567890 |
description | string | Description 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.
| Attribute | Type | Description |
|---|---|---|
amount | Create Amount | Amount to refund. |
description | string | Optional reason or description for the refund. Example: Refund issued due to customer complaint |
terminal_id | string | The 8-digit Terminal ID (TID) of the POS device processing the refund. Example: 80123457 |
app_name | string | Name of the application initiating the refund. Example: RefundApp |
app_version | string | Version 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.
| Attribute | Type | Description |
|---|---|---|
reference_number | string | Merchant-assigned reference number for the payment. Maximum 50 characters. |
amount | Create Amount | Payment amount and currency. |
description | string | Optional description of the payment. |
terminal_id | string | The 8-digit Terminal ID (TID) of the POS device to process the payment. |
app_name | string | Name of the application initiating the payment. |
app_version | string | Version of the application initiating the payment. |
operator_code | string | Operator or cashier code. Maximum 4 characters. |
Payment Reversal By ID Request
Request to void a payment before it has been settled.
| Attribute | Type | Description |
|---|---|---|
description | string | Optional reason or description for the reversal. Example: Customer requested reversal due to duplicate transaction |
terminal_id | string | The 8-digit Terminal ID (TID) of the POS device processing the reversal. Example: 80123457 |
app_name | string | Name of the application initiating the reversal. Example: MyPOSApp |
app_version | string | Version 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.
| Attribute | Type | Description |
|---|---|---|
payment_id | string | Unique payment identifier of the reversed payment. Example: 67f82b071b62d43a1f65833b |
status | Payment Status | Payment status after the reversal. Example: InProgress |
amount | Create Amount | Original payment amount. |
created_at | string | ISO 8601 timestamp when the payment was created. Example: 2025-10-27T07:56:24 |
updated_at | string | ISO 8601 timestamp when the payment was last updated. Example: 2025-10-27T07:56:24 |
reference_number | string | Merchant-assigned reference number for the payment. Example: REF1234567890 |
description | string | Description provided at the time of payment creation. Example: Test request |
expire_at | string | ISO 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.
| Attribute | Type | Description |
|---|---|---|
code | string | Terminal model code. Example: N96 |
description | string | Human-readable name of the terminal model. Example: myPOS Ultra |
Terminal Transaction
A single terminal transaction, with its card, settlement and fee details.
| Attribute | Type | Description |
|---|---|---|
terminal_id | string | The 8-digit Terminal ID (TID) of the POS device. Example: 80026232 |
date | string | Transaction date and time (format: YYYY-MM-DD HH:mm:ss). Example: 2025-10-13 10:12:06 |
terminal_name | string | Merchant-assigned name of the terminal. Example: Demo Ultra |
outlet_name | string | Name of the outlet associated with the terminal. Example: string |
tran_status | string | Transaction status description (e.g., Approved, Declined). Example: Approved |
payment_status | string | Payment status description (e.g., Paid, Reversed). Example: Paid |
amount | number (double) | Transaction amount in the terminal's currency. Example: 0.22 |
currency | string | ISO 4217 currency code of the transaction. Example: EUR |
rrn | string | Retrieval Reference Number assigned by the card network. Example: 528607108520 |
stan | string | System Trace Audit Number assigned by the terminal. Example: 000029 |
settlement_date | string | Date and time the transaction was settled. Example: 2025-10-13 10:12:16 |
settlement_amount | number (double) | Amount settled after fees and currency conversion. Example: 0.22 |
settlement_currency | string | ISO 4217 currency code used for settlement. Example: EUR |
fee | number (double) | Transaction fee charged by myPOS. Example: 0.01 |
pan | string | Masked Primary Account Number of the card. Example: *9766 |
card_scheme | string | Card scheme or product name. Example: Business Premium Debit |
payment_reference | string | Unique payment reference generated by the POS system. Example: POSA015257Y6IR59 |
billing_descriptor | string | Merchant billing descriptor appearing on the cardholder's statement. Example: DEMO ULTRA |
reference_number | string | Merchant-assigned reference number for the transaction. Example: REF1234567890 |
Payment Response
A newly created ePOS payment and its current status.
| Attribute | Type | Description |
|---|---|---|
payment_id | string | Unique payment identifier. Example: 68ff25a853659f6448da0eba |
status | Payment Status | Payment status. Example: InProgress |
amount | Create Amount | Payment amount and currency. |
created_at | string | ISO 8601 timestamp when the payment was created. Example: 2025-10-27T09:56:24 |
updated_at | string | ISO 8601 timestamp when the payment was last updated. Example: 2025-10-27T09:56:24 |
reference_number | string | Merchant-assigned reference number for the payment. Example: REF1234567890 |
description | string | Optional description of the payment. Example: Test request |
expire_at | string | ISO 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.
| Attribute | Type | Description |
|---|---|---|
reference_number | string | Reference number of the original payment to refund. Example: REF1234567890 |
amount | number (double) | Refund amount. Example: 0.22 |
Enumerations
Payment Status
Current lifecycle status of an ePOS payment.
| Value | Description |
|---|---|
InProgress | The payment has been created and sent to the terminal, and the cardholder has not completed it yet. |
Success | The payment was authorised by the card issuer and completed successfully. |
Canceled | The payment was cancelled before it was completed, either by the merchant or because it expired. |
Failed | The payment could not be processed because of a technical or processing error. |
Reversed | A previously successful payment was voided before settlement. |
Rejected | The 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.
| Attribute | Type | Description |
|---|---|---|
type | string | A URI reference identifying the problem type. |
title | string | A short human-readable summary of the problem type. |
status | integer | The HTTP status code. |
detail | string | A human-readable explanation specific to this occurrence of the problem. |
instance | string | A URI reference that identifies the specific occurrence of the problem. |
additionalProp1 | string | Additional extension member. |
additionalProp2 | string | Additional extension member. |
additionalProp3 | string | Additional extension member. |
Validation Problem Details
The error payload returned when a request fails validation, adding a per-field errors map.
| Attribute | Type | Description |
|---|---|---|
type | string | A URI reference identifying the problem type. |
title | string | A short human-readable summary of the problem type. |
status | integer | The HTTP status code. |
detail | string | A human-readable explanation specific to this occurrence of the problem. |
instance | string | A URI reference that identifies the specific occurrence of the problem. |
errors | object | Map of field names to their validation error messages. |
additionalProp1 | string | Additional extension member. |
additionalProp2 | string | Additional extension member. |
additionalProp3 | string | Additional extension member. |
Validation Problem Details › errors
Map of field names to their validation error messages.
| Attribute | Type | Description |
|---|---|---|
additionalProp1 | array of string | — |
additionalProp2 | array of string | — |
additionalProp3 | array of string | — |