Skip to content

Terminal Metadata

Terminal metadata is a free-form key/value table you configure on a terminal. It serves two main purposes:

  1. Filtering: Checkout uses it to filter which payment methods are offered based on the session's metadata.
  2. 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 400 error.
  • Sending an entry keyed ContractNumber validates against your terminal configuration. It returns HTTP 400 if the contract number is unknown. Ensure you use your own valid values instead of placeholders.
  • Duplicate keys are permitted and retain their order.
  • Omitting metaData leaves existing entries intact.
  • Supplying an empty array [] clears existing entries.
  • context.metaData is an array, distinct from order.transactionInfo and paymentMethod.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., ContractNumber is treated the same as contractNumber).
  • 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:

request.getAcquirerTransactionData()
    .add("metadata", "contractNumber", "CRF_A");
This automatically serializes to the correct query parameter format (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_a does not match CRF_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 ContractNumber column; 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:

  1. Candidates: Rows where contractNumber matches the session's value, and scheme is either blank or matches the card brand. Rows with conflicting non-blank cells are disqualified.
  2. Specificity: The row matching the highest number of cells wins. An explicit scheme outweighs a generic blank one.
  3. 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.