Terminal Setup

Completing the PCE Terminal setup gives you a registered, configured terminal device ready to process card-present payments — connected to your merchant account and authenticated through the PCE Terminal API.

Before You Begin

Integration Overview

Terminal setup follows six sequential steps. Complete each step before proceeding to the next.

1. Onboard your merchant account — Complete merchant onboarding and receive account approval.
2. Order your terminal device — Submit a device order through your Partner or directly from Priority.
3. Configure your terminal — Priority builds the configuration file for your terminal based on your environment (retail or restaurant).
4. Authenticate with the Terminal API — Obtain a JWT bearer token using your Consumer Key and Consumer Secret.
5. Verify your terminal — Confirm the device is registered and in ENABLED status via the Terminal API.
6. Test your integration — Run end-to-end transaction tests in the sandbox environment before going live.

Step 1: Onboard Your Merchant Account

Before ordering or activating a terminal device, your merchant account must be fully onboarded and approved on PCE.

📌

Note — Terminal device ordering and activation cannot proceed until the merchant account status is Approved. Contact the PCE Account Management team to confirm account status.

Step 2: Order Your Terminal Device

Once the merchant account is approved, a terminal device can be ordered through one of two pathways:

Order process:

1. The merchant contacts their Partner to request a terminal device.
2. The Partner submits an Equipment Order Form to the Priority team.
3. The Priority team reviews and approves the order.
4. The terminal is shipped to the designated delivery address.

Once the order is approved, Priority configures the terminal's encryption keys, payment applications, and connection settings before shipment. You do not need to configure these manually.

Step 3: Configure Your Terminal

Terminal devices are configured by Priority during the file build process. The configuration is based on your business environment:

📌

Note — Tip collection must be enabled during the file build process. It cannot be activated after the terminal has been configured and shipped. Confirm your environment type with the PCE Account Management team before submitting the order.

Step 4: Authenticate with the Terminal API

All PCE Terminal API endpoints require a valid JWT bearer token in the Authorization header. Obtain your token using your Consumer Key and Consumer Secret before making any Terminal API calls.

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}"
     }'

Store the returned JWT bearer token and pass it in the Authorization header of every Terminal API request:

Authorization: Bearer {your_jwt_token}

JWT tokens expire after a set period. Implement token refresh logic in your integration to prevent authentication failures during active terminal sessions.

Step 5: Verify Your Terminal

Before processing transactions, confirm that your terminal device is registered and in ENABLED status under your merchant account.

1. Make a GET request to /terminal/v1/merchantid/{merchantId} to retrieve all registered terminals.

{
  "records": [
    {
      "id": "TRM-001",
      "name": "Front Counter Terminal",
      "status": "Active",
      "enabled": true,
      "merchantId": "1000156763",
      "device": "MXMAPI01"
    }
  ]
}

2. Confirm the following fields in the response before proceeding:

Step 6: Test Your Integration

Validate your complete terminal workflow in the sandbox environment before going live.

Sandbox environments:

Test the following scenarios before going live:

Go Live Checklist

Troubleshooting