Terminal Transaction

Processing a terminal transaction lets you accept card-present payments through a registered physical device. PCE handles real-time authorization, end-to-end encrypted card capture, and returns a complete payment record through a single authenticated API workflow.

PCE's Terminal API connects your point-of-sale system to registered devices across multiple terminal providers — supporting EMV, NFC, and magnetic stripe entry modes within a single integration.

Before initiating any transaction, ensure the following conditions are met:

Prerequisites

Requirement	Details	Where to get it
Active PCE Merchant Account	The merchant must be fully onboarded, underwritten, and approved.	PCE Account Management team
Registered Terminal Device	A Terminal device must be registered and in `ENABLED` status under the merchant account.	PCE Account Management team
Correct POS Data	Every card-present transaction must include accurate POS data fields to ensure network approval and correct interchange classification.	See POS Data and Network Authorization below

⚠️
Important — Transactions submitted with incorrect or missing POS data may be declined by the card network or processed at a higher interchange rate.

Terminal Setup

Before processing terminal transactions, you must be fully onboarded on PCE. Terminals can be configured for both retail and restaurant environments, with restaurant builds supporting tip collection at the point of sale.

📌
Note — Contact the PCE Account Management team to initiate the terminal setup process for your account.

POS Data and Network Authorization

Every card-present transaction must include accurate POS (Point of Sale) data — contextual information about the terminal device and the environment from which the transaction is initiated. The card network uses this data to authenticate the transaction and assess fraud risk. The key fields required for every terminal transaction are:

Field	Accepted Values	Impact if Incorrect
`panCaptureMethod`	`Manual`, `Swipe`, `Chip`, `ContactlessChip`, `Fallback`	Wrong interchange classification, potential downgrade to a higher rate
`cardPresent`	`true`, `false`	Incorrect fee tier applied — card-not-present rates charged for card-present transactions
`cardholderPresence`	`Present`, `NotPresent`, `Phone`, `Ecom`	Network compliance violations, transaction declined
`deviceAttendance`	`Attended`, `Unattended`	Incorrect liability assignment in chargeback disputes
`deviceLocation`	`OnPremise`, `OffPremise`	Incorrect network routing
`deviceInputCapability`	`KeyedOnly`, `Swipe`, `ChipSwipe`, `ChipSwipeKeyed`	Interchange downgrade, transaction declined
`partialApprovalSupport`	`Supported`, `NotSupported`	Transaction failures for partially approved amounts
`transactionStatus`	`Normal`, `Preauthorization`, `Deferred`	Incorrect processing path, authorization failures

How it Works

Processing a terminal transaction involves four sequential steps. Each step must be completed in order before proceeding to the next.

Step 1: Retrieve Available Terminals

Retrieve the list of terminals registered to your merchant account and identify an active terminal for transaction initiation.

Make a GET request to /terminal/v1/merchantid/{merchantId} endpoint with required parameters.

Parameter	Required	Description
`merchantId`	✓	string

From the response, identify a terminal to use for the transaction. Check the following fields:

Field	Description
`terminalId`	Unique identifier for the registered terminal. Required for transaction creation in Step 2.
`enabled`	Indicates whether the terminal is available for transactions. Must be `true` before proceeding.

Each terminal returned in the response represents a registered device available for transactions. Only terminals with enabled: true can be used for transaction creation.

Step 2: Create a Terminal Transaction

Initiate a transaction on the selected terminal using the terminalId retrieved in Step 1.

Make a POST request to /terminal/v1/transaction/merchantid/{merchantId}/terminalid/{terminalId}endpoint with required parameters.

Parameter	Required	Type	Description
`merchantId`	✓	string	Your unique merchant identifier.
`terminalId`	✓	string	The ID of the active terminal selected in Step 1. Must have `enabled: true`.
`replayId`	✓	string	A client-generated UUID used for idempotency. Required to retrieve the final payment record in Step 4. Store it immediately — it cannot be recovered if lost.
`amount`	✓	number	Transaction amount in USD.
`transactionType`	✓	string	Type of transaction to initiate. Accepted values: `Sale`, `Refund`, `Authorization`.

📘
Transaction Type Reference — Use Sale to immediately authorize and capture the transaction amount. Use Refund to return funds to the cardholder, or Authorization to reserve funds without capturing.

The initial response returns a status of SENTTOTERMINAL, confirming the transaction request has been dispatched to the terminal.
Store the devicePaymentAuditId from the response — this becomes the transactionId used during polling in Step 3.

SENTTOTERMINAL is not a final state. Do not treat it as a completed transaction. Proceed to Step 3 to monitor the transaction outcome.

Step 3: Poll for Transaction Status

Monitor the transaction by polling the status endpoint until a final state is reached.

Begin polling approximately 2 seconds after transaction creation. Make a GET request to /terminal/v1/transaction/merchantid/{merchantId}/transactionid/{transactionId}endpoint with required parameters.

Parameter	Required	Type	Description
`merchantId`	✓	string	Your unique merchant identifier.
`transactionId`	✓	string	The `devicePaymentAuditId` returned in Step 2.

Poll every 2 seconds for up to 2 minutes, or until a final state is returned in the status field.

Successful Final States — Proceed to Step 4

Status	Description
`approved`	Transaction completed successfully.
`declined`	Transaction was declined by the issuer.
`error`	A processing error occurred.

Failed States — Do Not Proceed

Status	Description
`canceled` / `cancelled`	Transaction was canceled. Check the `message` field for details.
`failed`	Transaction failed. Check the `message` field for details.

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

Step 4: Retrieve Final Transaction Details

Once a final state is reached in Step 3, retrieve the complete payment record from the Checkout API. Payment details are not returned by terminal endpoints.

Make a GET request to /checkout/v3/paymentendpoint with required parameters.

Parameter	Required	Type	Description
`merchantId`	✓	string	Your unique merchant identifier.
`replayId`	✓	string	The UUID submitted during transaction creation in Step 2. Must match the original value exactly.

The response returns the complete payment object. Treat this as the authoritative transaction record.

Field	Description
`approvalStatus`	Final approval status of the transaction.
`paymentType`	The payment method used (e.g., credit, debit).
`amount`	Final transaction amount.
`cardInformation`	Tokenized card details. Raw card data is never returned.
`authorizationDetails`	Authorization code and network response details.
`timestamps`	Transaction creation and completion timestamps.
`metadata`	Additional transaction metadata.

Best Practices

Practice	Description
Implement token refresh logic	JWT tokens expire after a set period. Build token refresh logic to prevent authentication failures during active sessions.
Validate terminal status before transacting	Always check `enabled: true` before selecting a terminal in Step 1. Initiating a transaction on a disabled terminal will result in a failed request.
Use the Checkout API for payment records	The Terminal API does not return complete payment details. Always retrieve the authoritative record from `GET /checkout/v3/payment` after a final state is reached.
Test in sandbox first	Validate the complete workflow in the sandbox environment before going live.