Configuration

7 min

Introduction

POIs, POI Groups, Merchants, and Merchant Groups can all have Configurations associated with them. There is also a 'default' configuration for each integrator's account, which includes admin-only settings such as whether PlainCardData elements are accepted. The configurations for each entity type have the same format, to allow for flexibility in how the integrators structure their own data.

The design of the system is such that the configurations will coalesce with this hierarchy: POI < POI Groups < Merchant < Merchant Groups < Default. This allows the integrator to have different configurations for different parts of their terminal estate, and to override the configuration as needed. For example:

// POI Config:
{  dba_name: "John's Airport Taxi Kiosk" }
// Merchant Config:
{
  dba_name: "John's Taxis",
  shift4_config: {
    acquirer_merchant_id: '12345',
    acquirer_terminal_id: null
  }
}
// Merchant Group Config:
{
  shift4_config: {
    acquirer_terminal_id: '0780'
  }
}

// Coalesced Config used to process transactions:
{
  dba_name: "John's Airport Taxi Kiosk",
  shift4_config: {
    acquirer_merchant_id: '12345',
    acquirer_terminal_id: '0780'
  }
}

Usage

For the request and response schemas, please refer to the OpenAPI JSON schema and Swagger UI documentation.

The configuration object includes three types of fields - please refer to the 'Update Configuration' schema for the full list:

Generated fields like id and updated_at

Fields which are editable via the API, like dba_name (Doing-Business-As name)

Fields which are only editable by a system administrator - this includes security settings and permitted message types. These are visible to the user for reference but cannot be updated - please get in touch directly if you need these to be changed.

Where a configuration parameter conflicts with the contents of a message - for example an AuthorisationRequest being sent with the PINQ flag when shift4_config.pin_request_supported is false - the message will be considered invalid and an error response will be returned. The options set in your configurations will never override the actual contents of a message. When multiple acquirers are configured these options will, however, inform the routing of a transaction; an error will response will only be returned if there is no acquirer available that supports the request.

Validation is currently a work in progress - in some cases the gateway may attempt to process a transaction even if there is a conflicting value.

Some configuration options correspond to fields in ISO-20022 AcceptorConfigurationUpdate messages. These have been prefixed with nexo_ for easy identification. These only support a subset of the options indicated in the Nexo specification; the available options will be indicated in the API schema.

Toro Parameters and Acquirer Configuration

The configuration contains a toro_parameters object. This contains the requirements for message format and content, which comprise an extended subset of the AcquirerParameters element of an ISO-20022 AcceptorConfigurationUpdate message.

This is complemented by acquirer-specific configuration (e.g. shift4_config), which is used for defining acquirer-specific values. For example, Shift4 requires terminals (i.e. POIs) to be enroled with them, and requests to Shift4 must include their ID for the terminal. This should be set on the shift4_config.acquirer_terminal_id field.

Updating or changing the acquirer-specific configuration is handled through the /configurations endpoint as a nested property of the configuration object; please consult our OpenAPI schemas for the structure of the request.

Coalescing Configurations

When a transaction is processed, the gateway will retrieve the 'coalesced' configuration associated with the POI - this means a merged object comprising the configurations going up the hierarchy from the POI to the account-wide default.

For example:

// POI Config:
{  dba_name: "John's Airport Taxi Kiosk" }
// Merchant Config:
{
  dba_name: "John's Taxis",
  shift4_config: {
    acquirer_merchant_id: '12345',
    acquirer_terminal_id: null,
    submerchant_address: {
      line_1: '1 A Street',
      line_2: null,
      postal_code: 'AB1 1DH',
      city: 'Samplefield',
      country_name: null
    }
  }
}
// Merchant Group Config:
{
  shift4_config: {
    acquirer_terminal_id: '0780',
    submerchant_address: {
      line_1: '99 B Road',
      line_2: 'Apt 1',
      postal_code: 'XY7 9AB',
      city: 'Different City',
      country_name: 'Uzbekistan'
    }
  }
}

// Coalesced Config used to process transactions:
{
  dba_name: "John's Airport Taxi Kiosk",
  shift4_config: {
    acquirer_merchant_id: '12345',
    acquirer_terminal_id: '0780',
    submerchant_address: {
      line_1: '1 A Street',
      line_2: null,
      postal_code: 'AB1 1DH',
      city: 'Samplefield',
      country_name: null
    }
  }
}

The configurations system is intended to be flexible and support the integrator's requirements. It is perfectly acceptable, for example, to set all relevant configuration fields at the POI level and ignore the potential hierarchy of configuration objects.

Configurations as a property of POIs etc.

GET requests for a specific POI, Merchant, POI Group or Merchant Group can be made with the query parameter config=fragment or config=coalesced. The fragment option will return with the entity the Configuration associated with it; the coalesced option will return the coalesced configuration with the entity.

For example, the request GET mgmt-api.torogateway.dev/merchants/mer_abc123?config=coalesced will return a Merchant with an additional property configuration, which is coalesced from (1) the Merchant's own Configuration, (2) the chain of parent Merchant Groups' Configurations, and (3) the account-wide default Configuration. This is useful for checking what is set at a given point in the hierarchy if you implement a complex structure.

Requirements & Limitations

There is a limit of 99 POI Groups and 99 Merchant Groups in a chain.

Entities do not need to have an associated Configuration - as long as all required fields are set it would be valid for a POI to be the only entity in the hierarchy with a Configuration.

The following fields need to be present at some point in the hierarchy in order to successfully process a transaction via Shift4: - dba_name - Doing-Business-As name - shift4_config.acquirer_merchant_id - The merchant ID set up with Shift4 - shift4_config.acquirer_submerchant_id - the 'submerchant ID' set up with Shift4 (Note: This requirement is due to be reviewed) - shift4_config.acquirer_submerchant_address - The address associated with the Shift4 submerchant (NB when creating a Configuration you can instead provide an address ID to use an address already present in the management API database) - shift4_config.acquirer_terminal_id - The ID the POI is registered with with Shift4