Create Terminal

HTTP POST

Environment	Endpoint
QA	https://onboarding-service.{instance}.qa.rubean.io/api/{acquirer}/{client}/create
PROD	https://onboarding-service.{instance}.phonepos.online/api/{acquirer}/{client}/create

CLIENT

The parameter "client" could be skipped in case a terminal is to be onboarded on an acquirer level which would mean, no portal access could be provided to the merchant.

Request

Request Message Structure
Minimal Request Message
Minimal Request(unassisted enrollment)

{
  "id" : "ID",
  "timestamp" : "TS",
  "terminal" : {
    "terminalId" : "TID",
    "hardwareId" : "",
    "entity" : {
      "type" : "COMPANY",
      "name" : "CompanyName",
      "subEntity" : {
        "type" : "BRANCH",
        "name" : "BranchName",
        "contact" : {
          "name" : "Support at Rubean AG",
          "email" : "support@rubean.com",
          "phoneNumber" : "+491510123401234",
          "address" : {
            "street" : "Kistlerhofstrasse",
            "street2" : "168",
            "city" : "Munich",
            "postalCode" : "81379",
            "countryCode" : "DE"
          }
        }
      }
    },
    "currency" : "EUR",
    "language" : "de",
    "countryCode" : "DE",
    "merchantId" : "000105000001756",
    "merchantCategoryCode" : "5610",
    "transactionTypes" : [ "PURCHASE", "REFUND", "REVERSAL" ],
    "capabilities" : {
      "PIN" : "true"
    },
    "receiptLines" : [ "RUBEAN SOFTPOS", "Kistlerhofstraße 168", "81379 München" ],
    "activationInfo" : {
      "name": "USER NAME",
      "code" : "AI_CODE",
      "smsCode" : "AI_SMS_CODE",
      "email" : "contact@mail.com",
      "phoneNumber" : "+491510123401234",
      "token" : "ACTIVATION_TOKEN",
      "sessionEnforced" : "false"
    },
    "configurations" : [ {
      "cardType" : "VISA",
      "values" : [ {
        "key" : "MCC",
        "value" : "5610"
      } ]
    }, {
      "cardType" : "UNDEFINED",
      "values" : [ {
        "key" : "BOOKING",
        "value" : "true"
      } ]
    }, {
      "cardType" : "MAESTRO",
      "values" : [ {
        "key" : "MCC",
        "value" : "5610"
      } ]
    } ]
}
}

{
  "terminal": {
    "terminalId": "TID",
    "countryCode": "DE",
    "merchantId": "000105000001756",
    "activationInfo": {
      "code": "AI_CODE",
      "email": "contact@mail.com"
    }
  }
}

{
    "terminal": {
        "merchantId": "000105000001756",
        "hardwareId": "56797fc2e88f5eec"
    }
}

info

This type of terminal onboarding and activation is intended for the merchants who distribute its phonePos app via an MDM. Such way doesn’t require manual user intervention during the activation process (e.g., entering terminalId, password and clicking on confirmation link) and terminal personalization is carried out automatically.

info

Terminal ID: In case the value is not provided by the requestor, a value will be generated by ROS and returned by onboarding service as part of the response. Otherwise, the requestor can explicitly send the desired TID in the request body.

warning

Knowing the terminal ID is crucial for subsequent operations as update/delete/reset.

Parameter	Format	Occurrence	Description
id	e.g. 6e8fb61c-e97c-4ed9-a4e5-2450058afd33	O	External Id generated and maintained by a requestor. This is used in the case that a response was not delivered by ROS in a given time (a typical time-out scenario)
terminal	collection	M	A collection of parameters required for onboarding a single terminal
terminal.terminalId	AN 8	O	The terminal can be generated by the requestor or assigned by ROS from a terminal pool for a given acquirer (configuration)
terminal.hardwareId	AN	C	MDM hardware identification. Required in case when unassisted enrollment program is used. Hardware ID is unique and can be assigned only to one terminal at particular moment of time. If during creation/update there’s another terminal with such hardwareId, that terminal will be deactivated and hardwareId will be unassigned.
terminal.entity	collection	O	This is the business entity that shall operate the terminal. The collection is required only for internal purposes. It can be replaced with the data provided for requestor. This means that a set of terminals will be created under one company. If properly populated, the data can be used for the aggregation, statistics and presentation on the portal. See Terminal.entity
terminal.currency	AN 3 (ISO currency code)	O	This is a default terminal ISO 4217 currency
terminal.language	AN 2 (ISO 639-1)	O	Language, ISO 639-1: two-letter code
terminal.merchantId	AN ..15	M	Merchant id - a contract between the acquirer and a merchant. Note: Non ISO based acquirer hosts may support extended MID length, e.g. AN 30
terminal.merchantCategoryCode	AN 4	O	Merchant Category Code (MCC) listed in ISO 18245 for financial services.
terminal.transactionTypes	list of Strings	O	[ "PURCHASE", "REFUND", "REVERSAL" ]
terminal.countryCode	A 2 (ISO 3166-1)	M	Terminal country. This is ISO 3166-1 Alpha-2 code.
terminal.receiptLines	list of Strings	O	Set of optional lines that can be printed on the receipt.
terminal.activationInfo	collection	M	At least one of the personalization methods to be provided
terminal.activationInfo.name	AN	O	User Name
terminal.activationInfo.code	ANS	O	Code / Password for terminal activation
terminal.activationInfo.email	valid email address	C	E-mail address. Required if chosen activation method includes any deliveries to email, e.g. activation link, OTP
terminal.activationInfo.phoneNumber	valid mobile phone number	C	Mobile phone number, required in case when terminal is set to use OTP method activation with code delivery via SMS
terminal.activationInfo.token	ANS	O	Can be utilized in case when unassisted enrollment program is used. Must be provided further during terminal activation as additional layer of security.If not provided during create call, it’s generated and returned in the response message.
terminal.configurations	collection	O	This is a collection of card type specific parameters that can be required for particular acquirer as MID, MCC code, etc.
terminal.configurations.cardType	ENUM	O	Supported card types: MAESTRO, MASTERCARD, VISA, UNDEFINED - terminal configuration valid for all card types
terminal.configurations.values	list of Configuration values in NVP	O	Supported configuration values: key = MCC, value = AN 4 (merchant category code) key = MID, value = merchant ID, if different for given card type key = BOOKING, value = true/false, acquirer specific, valid only for some specific gateways
terminal.capabilities	AN	O	A list with capabilities or features supported on the terminal. Supported capabilities: PIN = true/false RECEIPT_TYPE = JSON/TEXT JSON - json object with receipt data TEXT - formatted, ready to print receipt REFERENCED_REFUND = true/false

Terminal.entity

Parameter	Format	Occurance	Description
entity.type	ENUM	O	Terminal’s business entity type: COMPANY STORE BRANCH MERCHANT CLIENT
entity.name	AN ..40	CM	Name of terminal’s business entity. Required if type provided
entity.contact	collection	O	see Terminal.entity.contact
entity.subEntity	collection	O	see Terminal.entity

Terminal.entity.contact

Parameter	Fromat	Occurrence	Description
contact.name	AN	O	Name of terminal’s business entity contact.
entity.email	valid email address	O	Terminal’s owning business entity e-mail address.
contact.phoneNumber	valid phone number	O	Terminal’s business entity phone number.
contact.address	collection	O	Contact’s address
contact.address.street	AN ..50	O	Contact’s street
contact.address.street2	AN ..50	0	Contact’s street (2nd line)
contact.address.city	AN ..50	0	Contact’s City
contact.address.postalCode	AN ..10	O	Contact’s Postal Code
contact.address.countryCode	A 2 (ISO 3166-1)	O	ISO 3166-1 Alpha-2 code.

Response

Successful response message
Failed request due to a technical reason
Rejected request due to invalid data in the request

{
	"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
	"terminalId": "12345678",
	"activationCode": "1234567890123" // or "activationToken": "WdEq3p3EmvL" for unassisted
	"status": {
		"result": "COMPLETE",
		"timestamp": "2022-03-01T13:00:00Z",
		"uuid": "9a1a37a2-b779-434a-a28b-de98ec692f59",
        "description": "Terminal successfully created"
	}
}

{
	"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
	"terminalId": "12345678",
	"activationCode": "1234567890123"
	"status": {
		"result": "FAILED",
		"timestamp": "2022-03-01T13:00:00Z",
		"uuid": "9a1a37a2-b779-434a-a28b-de98ec692f59",
        "description": "System error"
	}
}

{
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "terminalId": "12345678",
    "activationCode": "1234567890123",
    "status": {
        "result": "REJECTED",
        "timestamp": "2022-03-01T13:00:00Z",
        "uuid": "9a1a37a2-b779-434a-a28b-de98ec692f59",
        "description": "Invalid request"
    }
}

Parameter	Format	Occurrence	Description
id	6e8fb61c-e97c-4ed9-a4e5-2450058afd33	M	Echoes request id as provided by requestor in onboarding request or generated by ROS in case the value was not set.
terminalId	AN 8	M	The terminal can be generated by the requestor or assigned by ROS from a terminal pool for a given acquirer (configuration)
hardwareId	AN	C	MDM hardware id. Provided if client is subscribed for unassisted enrollment program
activationCode	ANS	M	Code / Password for terminal activation. Either the one provided during onboarding or generated by Rubean
activationToken	AN	O	Returned and can be utilized in case when unassisted enrollment program is used.If not provided during create call, it’s generated and returned in the response message.
status	collection	M	This is a collection representing the result of the request consisting of a timestamp and a result description.
status.result	ENUM	M	Result code: COMPLETE REJECTED FAILED
status.timestamp	YYYY-MM-DD’T’HH24:MM:SS:TimeZone	M	e.g. 2022-03-01T13:00:00Z
status.uuid	UUID	M	Request ID as generated by Rubean (ROS).
status.description	AN	O	In case of failure contains a more detailed failure explanation.

Request​

Terminal.entity​

Terminal.entity.contact​

Response​

Request

Terminal.entity

Terminal.entity.contact

Response