Several IDs and other items are needed to get access to and to call the Pyxis API. When CPP personnel set you up in the system, you will receive several pieces of information from us that you will need to keep safe and secure.
Security System Credentials
In order to obtain a security token used to access the rest of the API, you will need a set of basic authentication credentials (user and password) as well as a shared secret string that is 64 characters long.
Terminal Identifiers
When calling merchant level APIs, you will pass in a terminal ID. This ID acts as a point of origin for a transaction. Terminals belong to a merchant and one merchant can have one or more terminals. A merchant can have one or more physical terminals. A merchant can also have one or more “virtual” terminals which can be used to group transactions together; for instance, front of the house transactions versus back-office transactions or recurring versus POS retail.
Virtual Terminal vs. Other Types of Terminals
The concept of a “virtual” terminal may be strange at first. In simple terms, a virtual terminal is a point of origination for a transaction when a physical or other type of terminal does not exist or for any type of card-not-present transactions. For card present interaction with a POS device or other functionality, there will be other types of terminals including a physical terminal which is exactly what it seems. So, for transactions that do not originate from or interact with a physical or other type of card present terminal, the virtual terminal ID supplies the information about the merchant and its associated partner to the Pyxis system.
So, generally speaking, a merchant will usually have at least one virtual terminal if they make any API calls for “card not present” and, in the future, any number of other types of terminals.
When you work with CPP to set up you access to Pyxis, your account contact will set up any terminals and the identifiers will be sent to you.
Physical Terminal Identifiers
Physical terminals (i.e. POS devices) will have a one to one relationship with the terminal IDs you supply to the Pyxis APIs. How the identifier works is dependent on the device manufacturer or third party gateway used by the Pyxis system to talk to that terminal. From a Pyxis API standpoint, you will use a terminal ID supplied by Pyxis for each individual terminal and Pyxis will take care of the communications with that device for you.
Partner Identifiers
When you are set up in the Pyxis system by CPP, you will be sent a Partner ID that identifies to Pyxis what partner company you represent. When calling the “partner” level APIs described below, you will use this partner ID in the request body to establish a context and point of origin for the calls in Pyxis. It may be that a partner has more than one “division” that needs to be identified. In this case, you will work with CPP personnel and you may receive multiple partner IDs and any shared system will need to keep track of the call context and use the correct partner ID for the request being made.
Merchant Identifiers
Between Partners and Terminals there exists the Merchant. A merchant represents a bank account, a tax/fee structure, and a reporting endpoint. When you are set up in Pyxis, you will receive a merchant Id for each of your merchants. The merchant Id itself is only used in a few cases when calling Partner level APIs such as one that makes adjustments. The terminal Id mentioned above establishes which merchant is relevant to the API call being made on its behalf.