The Priority Terminal API lets your software take a card-present payment on a Priority-managed terminal. You send a transaction to a terminal, the terminal prompts the customer to tap, insert, or swipe, and Priority runs the authorization and returns the result. Priority handles all device communication, so you never integrate a vendor SDK or handle raw card data.

Common use cases

Retail and quick-service checkout at a fixed or wireless terminal
Mobile and field-service collection on a handheld device
Any counter where staff drive the sale from your POS and the customer pays at the device

Before you begin

You'll need:

An active Priority merchant account (MID).
An x-api-key for authentication, sent as a request header.
A registered terminal that shows as enabled on your MID.
A stable network on the terminal (Wi-Fi or Ethernet).

📘
You don't create terminals through the API. Terminals are provisioned and enabled for you. To order, register, or enable a device on your MID, contact your PCE team. Your integration only retrieves the terminals already on your account (Step 1). Once a device shows enabled: true, it's ready to transact.

How it works

Every terminal transaction runs through the same four steps. Each step feeds the next, so store the identifiers as you receive them.

sequenceDiagram
    participant POS as Your software
    participant API as Priority Terminal API
    participant Terminal as Terminal
    participant Customer as Customer
    POS->>API: 1. GET terminals for merchant
    API-->>POS: enabled terminals
    POS->>API: 2. POST terminal transaction (amount, type, replayId)
    API->>Terminal: prompt for payment
    Customer-->>Terminal: tap / insert / swipe
    API-->>POS: status SENTTOTERMINAL + devicePaymentAuditId
    POS->>API: 3. GET poll by devicePaymentAuditId
    API-->>POS: status APPROVED / FAILED / CANCELED
    POS->>API: 4. GET payment by merchantId + replayId
    API-->>POS: full payment record

Step 1: Retrieve available terminals

List the terminals registered to your merchant account and pick one that is enabled. Use GET /terminal/v1/merchantid/{merchantId}.

Query parameter	Description
`status`	Filter by `enabled` or `disabled`.
`freeTextSearch`	Search by terminal name or description.
`limit`	Number of records to return.
`offset`	Starting position in the result set (for pagination).

GET /terminal/v1/merchantid/1000016337?status=enabled

[
  {
    "id": "E11B42E6-D934-49D7-AECE-D4B543CBD29A",
    "name": "Terminal 01",
    "description": "Dejavoo Z8 Semi-Integrated",
    "merchantId": 1000016337,
    "uniqueIdentifier": "4542001",
    "providerKey": "dejavoo",
    "enabled": true,
    "isVirtual": false
  }
]

Pick a terminal where enabled is true, and use its id as the terminalId in Step 2.

Step 2: Create a terminal transaction

Send the transaction to the chosen terminal with POST /terminal/v1/transaction/merchantid/{merchantId}/terminalid/{terminalId}. The terminal then prompts the customer to present their card.

Body parameter	Required	Description
`amount`	✓	Transaction amount.
`type`	✓	Transaction type: `Sale`, `Authorization`, `Refund`, `Return`, `Void`, `Reversal`, `SaleCompletion`, `Adjustment`, `Balance`, or `PaymentTransaction`.
`replayId`	✓	A unique, merchant-generated identifier. It is the only value that links this transaction to its final payment record in Step 4 — store it immediately.
`paymentType`	Optional	`Credit`, `Debit`, `EBT_Food`, or `EBT_Cash`.
`customerId`	Optional	Associate the transaction with a stored customer.
`originalReference`	Optional	Reference to the original transaction (for a `Void`, `Refund`, or `Reversal`).
`vaultCard`	Optional	Set to `true` to store the card during the transaction for later reuse.

POST /terminal/v1/transaction/merchantid/1000016337/terminalid/E11B42E6-D934-49D7-AECE-D4B543CBD29A

{
  "amount": 150.00,
  "type": "Sale",
  "replayId": "505194196764199"
}

The response confirms the transaction was dispatched to the device. Read devicePaymentAuditId from prioritypaymentsystems.mxmerchant.merchant — you need it to poll in Step 3.

{
  "message": "A transaction was sent to the terminal.",
  "prioritypaymentsystems": {
    "mxmerchant": {
      "merchant": {
        "devicePaymentAuditId": "4D0FE7A8-8C1A-4E01-B33B-761F5DB9A6D1"
      },
      "transaction": {}
    }
  },
  "provider": {
    "key": "dejavoo",
    "name": "Dejavoo",
    "transaction": {
      "message": "A transaction was sent to the terminal."
    }
  },
  "status": "SENTTOTERMINAL"
}

status: SENTTOTERMINAL means the transaction reached the device. It is not a final state — move on to polling.

📘
The terminal captures the card and supplies the entry mode (chip, contactless, or swipe) and point-of-sale data for you. You don't send card details or posData on a terminal transaction.

Step 3: Poll for transaction status

Poll GET /terminal/v1/transaction/merchantid/{merchantId}/transactionid/{devicePaymentAuditId} until the transaction reaches a final state, passing the devicePaymentAuditId from Step 2.

GET /terminal/v1/transaction/merchantid/1000016337/transactionid/4D0FE7A8-8C1A-4E01-B33B-761F5DB9A6D1

{
  "prioritypaymentsystems": {
    "mxmerchant": {
      "merchant": {
        "devicePaymentAuditId": "4D0FE7A8-8C1A-4E01-B33B-761F5DB9A6D1"
      },
      "transaction": {}
    }
  },
  "provider": {
    "key": "dejavoo",
    "name": "Dejavoo",
    "transaction": {
      "message": "A transaction was sent to the terminal."
    }
  },
  "status": "APPROVED",
  "message": "Approved or completed successfully"
}

`status`	Meaning	Next step
`SENTTOTERMINAL`	Still at the device, waiting on the customer. Keep polling.	Continue polling
`APPROVED`	The transaction completed at the device.	Retrieve the record
`FAILED`	The transaction did not complete.	Stop; inspect record
`CANCELED`	The transaction was canceled at the device.	Stop

Keep polling while the status is SENTTOTERMINAL; stop once it reaches APPROVED, FAILED, or CANCELED.

Step 4: Retrieve the transaction

The Terminal API confirms the device outcome but not the full payment detail. Fetch the authoritative record from the Checkout API with GET /checkout/v3/payment, using your merchantId and the replayId from Step 2.

Query parameter	Required	Description
`merchantId`	✓	Your merchant account identifier.
`replayId`	✓	The exact `replayId` you sent in Step 2.

GET /checkout/v3/payment?merchantId=1000016337&replayId=505194196764199

{
  "id": 4100000000917751,
  "created": "2026-01-29T17:32:20.973Z",
  "paymentToken": "PQEEaLyH5zygcXt06KnTXE8RLkuivYoF",
  "replayId": 505194196764199,
  "merchantId": 1000016337,
  "device": "Deja0001",
  "batch": "Z0000",
  "tenderType": "Card",
  "amount": "150",
  "cardAccount": {
    "cardType": "MasterCard",
    "entryMode": "Keyed",
    "last4": "8210",
    "token": "PQEEaLyH5zygcXt06KnTXE8RLkuivYoF",
    "cardPresent": false
  },
  "authCode": "PPS8ba",
  "status": "Approved",
  "authMessage": "Approved or completed successfully",
  "type": "Sale",
  "source": "Terminal",
  "responseCode": 0,
  "IssuerResponseCode": "00"
}

Use this record as the source of truth for the outcome. Check status (Approved, Declined, Settled) and responseCode (0 is success); see Payment Response Codes for the full list. Store id and paymentToken for any follow-on action.

Statuses

There are two layers of status, and they answer different questions:

Terminal status (Step 3) tells you whether the transaction finished at the device: SENTTOTERMINAL → APPROVED / FAILED / CANCELED.
Payment status (Step 4) is the authorization outcome and lifecycle of the payment itself: Approved, Declined, Settled, Voided. This is what you reconcile against.

The full payment lifecycle is shared with online payments — see Payment Lifecycle.

Best practices

Practice	Why
Generate a new `replayId` per transaction	It's the only link to the final payment record. Reusing one mis-routes retrieval.
Store `devicePaymentAuditId` from the Step 2 response	You can't poll without it, and it isn't recoverable later.
Check `enabled: true` before sending	A disabled terminal returns an immediate failure.
Always retrieve the record in Step 4	The Terminal API only confirms device state; the payment object lives in Checkout.
Don't auto-retry a declined card	Prompt the operator for another payment method instead.

Go live

Merchant account approved and live x-api-key in place.
Target terminal shows enabled: true via Step 1.
A unique replayId is generated per transaction.
devicePaymentAuditId is stored from the Step 2 response.
Polling stops on a final state and surfaces a timeout if none is reached.
The payment record is retrieved from the Checkout API after every final state.
Approved, failed, and canceled flows are all validated in sandbox.

Troubleshooting

Symptom	Likely cause	Action
`401 Unauthorized`	Missing or wrong `x-api-key`	Send a valid `x-api-key` for the correct environment.
Terminal missing from Step 1	Device not provisioned or not linked to this MID	Contact your PCE team.
`enabled: false` on the terminal	Device is inactive	Contact your PCE team.
Stuck on `SENTTOTERMINAL`	Device offline or customer hasn't presented a card	Confirm the terminal is ready and on the network; surface a timeout.
`CANCELED` immediately	Terminal rejected the request before card entry	Verify `terminalId` is correct and the device is powered on.
Step 4 returns no record	`replayId` doesn't match Step 2	Confirm the `replayId` was stored and passed unchanged.

Next steps

Supported Terminal Devices

Confirm your device is available on the Priority Terminal API.

In-Person Payments

Prerequisites and real-world scenarios — retail, restaurant, mobile, and kiosk.

Before you begin

How it works

Step 1: Retrieve available terminals

Step 2: Create a terminal transaction

Step 3: Poll for transaction status

Step 4: Retrieve the transaction

Statuses

Best practices

Go live

Troubleshooting

Next steps

See also