Terminal

PCE Terminal enables merchants to accept in-person card payments through a registered point-of-sale device, fully integrated with the Priority Commerce Engine for real-time authorization and unified transaction reporting.

In-person payments — also referred to as card-present (CP) transactions — take place when the customer physically presents their payment card at the point of sale. This includes swiping, inserting, or tapping the card into a Terminal device. From an API perspective, in-person payments are primarily facilitated through Terminal devices, though merchants may also build web applications that enable walk-in customers to complete payments directly in-store.

PCE supports Terminal setup and card-present transactions for merchants. Terminals are set up on the merchant's registered business location, and PCE provides end-to-end support across Terminal setup, merchant onboarding, and card-present transaction processing.

Key Capabilities

In-Person Payment Methods

PCE Terminal supports a broad range of in-person payment methods to accommodate different business environments, customer preferences, and hardware configurations. The table below provides an at-a-glance comparison:

Keyed

A keyed payment is when the full card number, expiration date, and security code are manually entered to charge the card. No physical card reader is required.

Use Cases

• The merchant does not have access to the physical card and receives card details directly from the cardholder (e.g., telephone orders or MOTO transactions).
• A customer enters card information directly into a web-based POS application.
• The card reader (swiper, chip, or NFC) fails and keyed entry is required as a fallback.
• Low-volume merchants seeking a cost-effective integration without hardware investment.

Presentment Types

⚠️

Note — Keyed transactions carry the highest processing fees and the greatest risk of fraud among all payment methods. They should be used only when card-reading hardware is unavailable or a fallback is required.

Swiped (Magnetic Stripe)

Swipe transactions use magstripe data to capture encrypted card information from the magnetic strip on the back of the card, rather than manually entering card details.

Use Cases

• The merchant has the physical card and a compatible magstripe reader.
• The card does not have a chip, or the merchant's setup only supports swipe.
• EMV chip read fails and the terminal prompts a swipe as a fallback.
• Any card-present scenario where chip or NFC is unavailable.

Key Considerations

• Faster and simpler from a customer experience standpoint than EMV.
• Typically results in lower processing fees than keyed transactions since the card is physically present.
• Requires a compatible magstripe card reader.

EMV (Chip)

EMV — also known as chip card payments — uses a small computer chip embedded in the card to authenticate and secure the transaction. The customer inserts the card into the chip reader and leaves it until prompted to remove.

Use Cases

• In-person transactions where the merchant has EMV-capable equipment and the customer presents a chip card.
• Environments where swiped transactions are also supported, with EMV as the preferred method.
• Retail, hospitality, and service environments prioritizing fraud prevention.

Key Considerations

• EMV transactions take slightly longer than swipe due to chip-to-reader communication.
• Significantly more secure than keyed and swiped transactions, with proven reduction in fraud.
• Typically results in the lowest processing fees due to the security provided and card-present nature of the transaction.
• Requires at least one EMV-capable card reader.

NFC (Tap / Contactless)

NFC — Near Field Communication — enables customers to securely transmit card data by tapping their card or mobile wallet against the NFC-enabled reader. These are commonly referred to as tap payments.

Use Cases

• A customer taps an NFC-enabled physical card against the reader.
• A customer pays using a mobile wallet such as Apple Pay, Google Pay, or Samsung Pay.
• Customer-facing POS environments — such as retail — where speed and contactless experience are priorities.

Key Considerations

• The payment data structure is identical to EMV — the only difference is the card capture method (tap vs. chip insert).
• Fastest method at the point of sale, reducing queue times.
• Not typically used in environments where cards are processed behind a counter (e.g., restaurants or bars).
• Requires NFC-enabled card reader hardware.

Cash

Cash is a supported tender type within the PCE Checkout API, for reporting and reconciliation purposes only. No funds are moved electronically — the merchant must manually deposit collected cash into their bank account.

Use Cases

• Merchants who want to record cash transactions alongside digital payments within the PCE reporting dashboard.
• Businesses offering cash as an additional payment option alongside card payments.

📌

Note — Cash transactions are not processed through the card network. Recording a cash transaction in PCE creates a ledger entry for reconciliation purposes only. The merchant is responsible for physically depositing cash.

Checks

Check payments are a manual payment method where the customer physically hands the merchant a written check. Similar to cash, check transactions in PCE are for reporting purposes only — the merchant must take the check to the bank for deposit.

Use Cases

• Merchants who want to record check transactions within PCE for reconciliation.
• Business-to-business (B2B) transactions and large-value payments where checks are preferred.

⚠️

Note — Check transactions carry inherent risks including delayed fraud notification, the possibility of insufficient funds, and the customer's ability to issue a stop payment after goods or services have been delivered.

ACH

ACH (Automated Clearing House) payments are electronic bank transfers that can be used in in-person contexts, particularly in service-based or B2B environments. Unlike checks, ACH payments are processed electronically — no physical bank visit is required.

Use Cases

• Service-based businesses collecting payment at the time of service via bank transfer.
• Merchants who want to offer bank account payment as an alternative to card payments.
• Large-value transactions where card processing fees are a concern.

For full ACH integration details, refer to the PCE ACH documentation.

POS Data and Network Authorization

⚠️

Action Required — Merchants must provide accurate POS data with every card-present transaction. Incorrect or missing POS data can result in transactions being charged at a higher interchange rate or declined by the card network.

POS (Point of Sale) data refers to the contextual information about the Terminal device and environment from which a card-present transaction is initiated. The card network uses this data to authenticate the transaction, determine the appropriate interchange rate, and assess fraud risk.

Providing accurate POS data ensures that your transactions:

• Are routed correctly through the card network.
• Qualify for the lowest applicable interchange rate (card-present pricing).
• Pass network-level fraud and compliance checks.

The following POS data fields must be configured correctly for every Terminal transaction:

POS Data by Payment Method

Terminal Device Ordering

Once a merchant is successfully underwritten and has an active Passport account, Terminal devices can be requested through the following process:

1. The merchant contacts their Partner to request a Terminal device.
2. The Partner submits an Equipment Order Form on behalf of the merchant.
3. The completed form is submitted to the Priority Team for evaluation and approval.
4. Upon approval, the Terminal is shipped to the designated delivery address.

📌

Note — Terminal devices are available upon successful merchant underwriting and account activation. Contact the PCE Account Management team to initiate a device order.

Merchant Onboarding & Terminal Setup

Merchant Onboarding

Before processing Terminal transactions, the merchant must be onboarded and approved through the following steps:

1. Onboard a direct-funded merchant on MX Connect using the MFA flow. Ensure that TSYS, MX Merchant, and Passport products are added for each merchant application by default.
2. The merchant completes the MFA verification process.
3. The underwriting team conducts a background check. Upon successful verification, the merchant status is marked as Approved.
4. The merchant receives access to the Passport customer portal and an email notification to set a password for the Passport banking portal.

Terminal Setup

Once the merchant is onboarded, the Terminal device is configured through one of the following equipment pathways:

• Equipment Order from Priority — The merchant requests shipment of a POS terminal directly from Priority. Priority ships the device, builds the configuration file, and assists with setup.
• Equipment Order from a Supplier — The Partner orders the terminal from a third-party vendor and submits a file build request to Priority for configuration.

Terminal devices can be configured for both retail and restaurant use cases. For restaurant environments, terminals are configured to support tip collection at the point of sale.

📌

Note — Once the terminal setup process is complete, merchants can begin initiating card-present transactions through the Passport system.

Prerequisites and Limitations

• Prerequisites: You must have an active PCE merchant account and a registered Terminal device before processing in-person transactions.
• Limitations: ACH and bank account payments are not supported directly through the Terminal at this time. Terminal processes card-present transactions only via Keyed, Swiped, EMV, NFC, Cash, and Check tender types.

Terminal Management

The PCE Terminal API is a dedicated API, separate from the Checkout API, that allows merchants to interact with physical Terminal devices and process card-present transactions through them. The system supports terminals from multiple providers.

The Terminal API uses the same JWT-based authentication as the PCE Checkout API. All requests must include a valid token in the Authorization header, obtained via the PCE Security API using Username/Password or Consumer/Secret Keys.

Environments

Retrieve All Terminals

Returns a list of all Terminal devices registered to the specified merchant account. Use this endpoint to retrieve the Terminal ID (tid) required to initiate a transaction.

GET v1/customer/id/{customerId}/merchant/id/{merchantId}/terminal

Path Parameters

Example Response

[
  {
    "tid": "DA08333B-CBA7-440A-943D-49813C51C793",
    "description": "Dejavoo Z8 Semi-Integrated",
    "name": "179800015474",
    "status": "ENABLED"
  }
]

Response Fields

Terminal Transactions

The Terminal Transaction endpoints send payment transactions to a registered Terminal device. Upon receiving a transaction request, the Terminal presents an on-screen prompt to the customer to complete payment by dipping, tapping, or swiping their card.

📌

Note — A Terminal device must be registered, active, and in ENABLED status before initiating any transaction requests. Use the Retrieve All Terminals endpoint to confirm device status and retrieve the tid before creating a transaction.

Create Terminal Transaction

Sends a new payment transaction to the specified Terminal device. The POS application calls this endpoint to initiate a checkout request, which is routed via Passport and forwarded to the Priority Terminal for customer completion.

POST v1/customer/id/{customerId}/transaction

Request Body

Example Request

{
  "isAutoCapture": "true",
  "externalId": "EID132904944443484",
  "amount": "15.03",
  "method": "CARD",
  "processingDetail": {
    "statementDescriptor": "Descriptor",
    "merchant": {
      "id": "4007497"
    }
  },
  "purpose": "Terminal Work Purpose",
  "source": {
    "terminal": {
      "id": "DA08333B-CBA7-440A-943D-49813C51C793"
    }
  },
  "type": "REGULAR"
}

Transaction States

Processing a Terminal Transaction

Step 1: Retrieve the Terminal ID

Call the Retrieve All Terminals endpoint to obtain the tid of the target device. Confirm the device status is ENABLED before proceeding.

Step 2: Initiate the Transaction

The POS application sends a transaction request to the PCE Terminal API via POST v1/customer/id/{customerId}/transaction, passing the Terminal tid in the source.terminal.id field along with accurate POS data.

Step 3: Customer Presents Payment

The transaction is routed through Passport and forwarded to the Priority Terminal. The Terminal displays the payment details on-screen and prompts the customer to present their card:

• Insert their chip card into the card slot (EMV).
• Tap their contactless card or mobile wallet against the NFC reader.
• Swipe their magnetic stripe card through the card reader.

Step 4: Authorization

The Terminal transmits the encrypted card data to the card network for real-time authorization. An approval or decline response is returned within seconds.

Step 5: Webhook Notification

Upon successful payment, a webhook notification is sent to the merchant. Configure your webhook endpoint to receive and process Terminal transaction events in real time.

Step 6: Verify the Transaction Status

Confirm the transaction outcome via the incoming webhook or by querying the transaction record:

• Completed — The transaction was authorized and processed successfully.
• Failed — The transaction was declined. The Terminal displays the decline reason and the customer may retry with a different payment method.

📌

Note — To retrieve the full transaction record in the create response, supply echo=true as a URL parameter (e.g., POST /transaction?echo=true) to avoid a separate GET request.

Things to Keep in Mind

• POS Data Accuracy — Always provide correct and complete POS data with every Terminal transaction. Incorrect POS data can result in transactions being charged at a higher interchange rate or declined by the card network entirely.

• End-to-End Encryption — Sensitive card data is encrypted at the point of capture and is never stored on the Terminal device. Data remains protected throughout transmission to the card network.

• PCI DSS Compliance — The semi-integrated Terminal architecture is designed to reduce merchant PCI compliance scope. No additional certification is required for standard card-present transactions.

• Connectivity — Terminal requires an active internet connection to process and authorize transactions in real time. Ensure stable Wi-Fi or Ethernet connectivity at the point of sale prior to initiating a transaction.

• Chargeback Risk — Card-present transactions (EMV and NFC) carry a significantly lower chargeback risk compared to keyed or card-not-present transactions. Merchants remain responsible for following chargeback dispute procedures outlined in the PCE merchant agreement.

• Device Registration — Each Terminal device must be registered and linked to the merchant account before it can process transactions. Devices with a status other than ENABLED will be declined at the authorization stage.

• Webhook Configuration — Terminal transactions trigger webhook notifications upon completion. Ensure your webhook endpoint is configured and active to receive real-time transaction events.

• Cash and Check Transactions — Cash and check tender types are for reporting and reconciliation purposes only. No funds are moved electronically. Merchants are responsible for manual cash deposits and physical check processing.

📌

Note — Before activating your Terminal device, ensure your merchant profile is fully configured and approved. Contact the PCE Account Management team to confirm Terminal activation for your account.