Configuration

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 https //mgmt api torogateway dev/v1/docs and https //mgmt api torogateway dev/v1/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