Path A — Priority Terminal API

Use the Priority Terminal API when your software needs to drive a Priority-supported terminal directly — initiating transactions, polling for outcomes, and retrieving payment records through a single API surface. The API handles device communication on your behalf, so you don't integrate against the terminal vendor's SDK.

📌

Who this is for — ISVs and developers building point-of-sale software for merchants using Priority-supported terminal devices. Partners and merchants should start with Choose Your Integration Path.

Supported Devices

The Priority Terminal API currently supports the following device families:

For devices not on this list — including PAX, Clover, Ingenico, Valor, and standalone variants — see Vendor-Direct Integrations or Standalone Terminals.

Before You Begin

Environments

The Five-Step Workflow

Every Priority Terminal API transaction runs through the same five sequential steps. Each step depends on the previous step's output — store the values you receive immediately so they are available for the next call.

1. Authenticate — Obtain a JWT bearer token.
2. Retrieve terminals — Fetch the list of registered terminals and pick an enabled one.
3. Create a transaction — Send a transaction request to the terminal. Capture devicePaymentAuditId.
4. Poll for status — Poll every 2 seconds until the transaction reaches a final state.
5. Retrieve the payment record — Fetch the authoritative payment record from the Checkout API using your replayId.

Step 1 — Authenticate

Obtain a JWT bearer token using your Consumer Key and Consumer Secret. Every other Terminal API call requires this token in the Authorization header.

Endpoint

POST https://api2.mxmerchant.com/security/v1/application/authorize

Request

curl --request POST \
  --url 'https://api2.mxmerchant.com/security/v1/application/authorize' \
  --header 'content-type: application/json' \
  --data '{
    "consumerKey": "{your_consumer_key}",
    "consumerSecret": "{your_consumer_secret}"
  }'

Parameters

Store the returned token and include it as a Bearer token on every subsequent request:

Authorization: Bearer {your_jwt_token}

⚠️

JWT tokens expire. Implement token refresh logic so long-running terminal sessions don't fail mid-transaction.

Step 2 — Retrieve Available Terminals

Fetch every terminal registered to the merchant account and pick one to use for the transaction.

Endpoint

GET https://api2.mxmerchant.com/terminal/v1/merchantid/{merchantId}

Parameters

Choosing a terminal — check these fields on each record

Only terminals with enabled: true and an Active status are valid targets for a transaction.

Step 3 — Create a Transaction

Send the transaction to the terminal. The terminal prompts the customer for card entry and runs the authorization.

Endpoint

POST https://api2.mxmerchant.com/terminal/v1/transaction/merchantid/{merchantId}/terminalid/{terminalId}

Body parameters

Supported transaction types

📌

posData is auto-populated for Terminal API transactions. You do not send posData fields in the request body — the terminal supplies them automatically based on the file build. For card-present transactions without a terminal, see Card Present (Keyed) Transactions, where posData is required.

Initial response

The response returns a status of SENTTOTERMINAL and a devicePaymentAuditId.

Step 4 — Poll for Transaction Status

Poll the status endpoint every 2 seconds until the transaction reaches a final state, or until your 2-minute cap is hit.

Endpoint

GET https://api2.mxmerchant.com/terminal/v1/transaction/merchantid/{merchantId}/transactionid/{transactionId}

Parameters

Polling cadence

• Begin polling ~2 seconds after creating the transaction in Step 3.
• Poll once every 2 seconds.
• Cap at 2 minutes total. If no final state is reached, surface a timeout error and investigate via the terminal portal.

Final states — proceed to Step 5

Failed states — do not proceed

⚠️

Cancel operations are not currently implemented for Dejavoo terminals. Polling will not return a canceled state from a programmatic cancel call — only from a terminal-side or manager-initiated cancel. Plan your error handling accordingly.

Any status not listed above should be treated as in-progress — continue polling.

Step 5 — Retrieve the Payment Record

Once a final state is reached, fetch the authoritative payment record from the Checkout API. The Terminal API does not return full payment details — only status.

Endpoint

GET https://api2.mxmerchant.com/checkout/v3/payment

Parameters

Key fields in the response

Treat the Checkout API response as the system of record for the transaction.

Best Practices

Common Issues

Where to Go Next