Terminal Metadata
Terminal metadata is a free-form key/value table you configure on a terminal. It serves two main purposes:
- Filtering: Checkout uses it to filter which payment methods are offered based on the session's metadata.
- Acquirer Routing: Checkout forwards both the terminal's table and the session's metadata to the acquirer to drive logic, such as contract selection.
These features apply to all payment methods, including cards and ePayments.
The gateway stores and forwards metadata. Beyond validating ContractNumber (see Contract number validation), it treats these key/value pairs as opaque data. Their exact meaning is determined solely by the merchant configuring the terminal and the acquirer processing the transaction.
Terminals without a metadata table are unaffected.
Sending metadata
Pass metadata via the session context:
{
"context": {
"browser": { ... },
"metaData": [
{ "key": "contractNumber", "value": "CRF_A" },
{ "key": "department", "value": "D9" }
]
}
}
| Parameter | Description | Required |
|---|---|---|
metaData |
Key/value pairs describing this session. | No |
metaData[].key |
Metadata key, max 255 chars. | Yes |
metaData[].value |
Metadata value, max 255 chars. | Yes |
- Blank keys or values result in an
HTTP 400error. - Sending an entry keyed
ContractNumbervalidates against your terminal configuration. It returnsHTTP 400if the contract number is unknown. Ensure you use your own valid values instead of placeholders. - Duplicate keys are permitted and retain their order.
- Omitting
metaDataleaves existing entries intact. - Supplying an empty array
[]clears existing entries. context.metaDatais an array, distinct fromorder.transactionInfoandpaymentMethod.metadata.
Configuring the table
To set up the table, navigate to Merchant Interface → Terminal → Metadata. Each row typically defines one contract or routing rule. Columns are user-defined, except for these reserved names:
| Column | Meaning |
|---|---|
contractNumber |
The contract described by this row. Checkout validates it during session creation (see Contract number validation), and MarketPay Online matches it to select the row. |
scheme |
Restricts the row to a specific card brand. A blank value applies to all brands. Used by MarketPay Online. |
storeCode |
Replaces the acquirer configuration's store code when this row is selected. Used by MarketPay Online. |
- Case-Insensitivity: Column names are case-insensitive (e.g.,
ContractNumberis treated the same ascontractNumber). - Pass-through Data: Any non-reserved column is forwarded untouched.
- Fixed Project Code: The project code is fixed per terminal and cannot be overridden by metadata.
The table configuration is exposed via the Merchant API's getTerminals response, which is how Checkout reads it. If you integrate directly with the Merchant API, you can send identical metadata values on createPaymentRequest or reservation as acquirerTransactionData[metadata][contractNumber].
SDK Support
The Java SDK (sdk-java) fully supports terminal metadata:
- Retrieving metadata: The getTerminals API response parser parses a Metadatas node on each Terminal, containing the configured Metadata rows and their associated KeyValue entries.
- Sending metadata: The AcquirerTransactionData builder provides an .add(group, key, value) method. For example:
acquirerTransactionData[metadata][contractNumber]) required by the Merchant API.
Matching Rules
Checkout enforces the following rules for both payment method filtering and contract number validation:
- Keys: Trimmed and compared case-insensitively.
- Values: Trimmed but strictly case-sensitive (e.g.,
crf_adoes not matchCRF_A). - Blank Cells: Ignored during matching.
Warning
Always supply values exactly as configured. Although an acquirer might use looser matching rules, Checkout strictly enforces these rules during validation.
Payment method filtering
Checkout uses terminal metadata to determine availability:
- No Metadata Table Configured: Terminal is always offered.
- No Session Metadata Sent: Every terminal is offered.
- Metadata Table Configured: Terminal is offered if any cell in any row matches a key/value pair in the session metadata.
A single matching cell is sufficient to offer the terminal.
Contract number validation
ContractNumber is the only key interpreted directly by Checkout. If supplied, the contract number must exist on a terminal associated with the session's shop.
{
"context": {
"metaData": [
{ "key": "ContractNumber", "value": "CRF_CLCV_0009_CA_9280278_CB" },
{ "key": "ContractNumber", "value": "CRF_CLCV_0009_040130213_CBPASS" }
]
}
}
- Independent Validation: Every supplied contract number is verified independently across the available terminals.
- Shop Scope: Validated against terminals configured for
configuration.shopName. If no shop is provided, all account terminals are evaluated. - Column Strictness: Values must reside under the
ContractNumbercolumn; other columns are ignored for this validation. - Matching: Adheres strictly to the Matching Rules.
If any contract number is unconfigured, the entire request is rejected and nothing is stored:
HTTP 400
{
"errorMessage": "Invalid contract number. Please update the request before retrying again.",
"errorCode": 313012
}
This applies to session creation and updates. If an update modifies configuration.shopName, all metadata is re-validated against the new shop's terminals, potentially invalidating previously accepted contract numbers.
Metadata submitted under any other key is not validated by Checkout.
What the acquirer receives
The acquirer receives two distinct data sets:
| Set | Content | Origin |
|---|---|---|
| Session metadata | Unmodified values sent by the merchant. | Checkout API request |
| Terminal metadata | The terminal's configured table. | Terminal Configuration |
The terminal's table is evaluated fresh per request; it is not stored permanently on the payment. The acquirer determines how (or if) this data is utilized.
Contract selection
MarketPay Online utilizes metadata to dynamically select a contract row:
- Candidates: Rows where
contractNumbermatches the session's value, andschemeis either blank or matches the card brand. Rows with conflicting non-blank cells are disqualified. - Specificity: The row matching the highest number of cells wins. An explicit
schemeoutweighs a generic blank one. - Tie-breaker: If tied, the first row in the terminal configuration wins.
For ePayments, scheme is ignored and selection is based purely on contractNumber.
MarketPay Online receives the selected row's contractNumber. If present, the storeCode replaces the acquirer configuration's default. If no row matches, the default acquirer configuration is used, and the payment proceeds normally.
Reading the response
Transactions retrieved via the Merchant API's payments response may contain acquirer attributes:
<AcquirerTransactionData>
<MerchantIdentifier>123456789</MerchantIdentifier>
<Attribute key="...">...</Attribute>
</AcquirerTransactionData>
Note
These are the values returned by the acquirer. They do not reflect the metadata you submitted. You must track your submitted metadata against your own order system. Acquirer attributes are currently excluded from Checkout API responses.
Captures, refunds and subscriptions
Session metadata is persistent: captures, refunds, voids, and recurring subscription charges all inherit the metadata from the initial authorization. Assuming terminal configuration remains constant, the same contract is used for subsequent operations.
However, the terminal's table is read dynamically for each action. Modifying a terminal's metadata table between authorization and capture will expose the new table to the acquirer during the capture process.