Shift4 Dynamic Terminal Support

9 min

Overview

Shift4's Dynamic Terminal functionality allows Payment Facilitators to add new POS devices as part of the financial transaction flow without requiring separate device setup requests in advance. The Toro platform supports this feature by automatically including the required Shift4 parameters during transaction processing.

Important: The Toro platform does not directly interact with the Shift4 Immediate Setup API. Payment Facilitators must complete the sub-merchant setup process through Shift4's Immediate Setup flow before configuring dynamic terminal parameters in Toro. Additionally, Dynamic Terminal functionality requires specific authorization from the Shift4 team - contact your Shift4 Solution Architect to ensure your account has the necessary permissions. For detailed information on the Immediate Setup process, refer to the Shift4 Payment Facilitator Immediate Setup Specifications.

Configuration

Dynamic Terminal configuration involves setting these parameters through the Management API:

Parameter	Shift4 Field	Toro Configuration	Required
POS Device Address	h5	location or location_id (POI)	Yes
Card Present Device Code	h13	acquirer_device_code (Configuration)	Yes
Dynamic Terminal Enable	N/A	immediate_setup_dynamic_terminal(Configuration)	Yes

Note: The acquirer_terminal_id field in Toro configuration corresponds to Shift4's b17 parameter (Card Acceptor Terminal ID), which is required for all Card Present transactions.

Card Present Device Code (h13)

The Shift4 h13 parameter (card present device code) identifies the specific make and model of the POS device. This 3-digit code must be configured in the Shift4 configuration, which will then be linked to POIs.

Configuration Location

The device code is set via the acquirer_device_code field in either:

shift4_config: For standard Shift4 processing

shift4_amex_config: For American Express processing via Shift4

Additionally, the immediate_setup_dynamic_terminal boolean field must be set to true to enable Dynamic Terminal functionality. This field is specific to the Toro platform and controls whether the system includes the h5 and h13 parameters in transaction requests.

Important: The device code must be obtained from Shift4 and corresponds to the certified device make and model. If the code is padded with leading zeros to make it 3 digits (e.g., '003'), include the leading zeros in the configuration.

Configuration Examples

Shift4 Dynamic Terminal

curl --request POST \
  --url https://mgmt-api.torogateway.dev/v1/configurations \
  --header 'API-Key: <KEY>' \
  --header 'content-type: application/json' \
  --data '{
    "shift4_config": {
      "acquirer": "shift4",
      "acquirer_merchant_id": "MERCHANT001",
      "acquirer_device_code": "123",
      "acquirer_terminal_id": "TERM001",
      "immediate_setup_dynamic_terminal": true,
      "supported_card_entry_modes": [
        "integrated_circuit_card",
        "magnetic_stripe"
      ],
      "online_pin_supported": true,
      "partial_approval_supported": false
    }
  }'

Shift4 American Express Dynamic Terminal

curl --request POST \
  --url https://mgmt-api.torogateway.dev/v1/configurations \
  --header 'API-Key: <KEY>' \
  --header 'content-type: application/json' \
  --data '{
    "shift4_amex_config": {
      "acquirer": "shift4_amex",
      "acquirer_merchant_id": "AMEXMERCH001",
      "acquirer_device_code": "003",
      "acquirer_terminal_id": "AMEXTERM001",
      "immediate_setup_dynamic_terminal": true
    }
  }'

POS Device Address Configuration (h5)

The Shift4 h5 parameter (POS device address) is configured through the POI (Point of Interaction) location settings and linked to the configuration created above.

Configuration Methods

You can specify the device location using either approach:

Direct Location Object: Provide address details directly in the POI create/update request

Location Reference: Reference an existing address using location_id

Note: Do not provide both location and location_id in the same request. Use only one method.

Create POI with Address Example

curl --request POST \
  --url https://mgmt-api.torogateway.dev/v1/pois \
  --header 'API-Key: <KEY>' \
  --header 'content-type: application/json' \
  --data '{
    "merchant_id": "merchant_123",
    "is_active": true,
    "manufacturer_id": "device_12345",
    "label_id": "POS-001",
    "model": "Miura M20",
    "location": {
      "line_1": "123 High Street",
      "postal_code": "SW1A 1AA",
      "city": "London",
      "country_code": "GBR"
    },
    "configuration_id": "cfg_b07fa17ed2530939ae0f24"
  }'

Summary

Once the configuration and POI setup is complete, the Toro platform will automatically include the required Shift4 Dynamic Terminal parameters (h5 and h13) in transaction requests when immediate_setup_dynamic_terminal is enabled. This allows new POS devices to be processed without requiring separate device setup requests to Shift4.