Solaris API Overview

Introduction

The Solaris APIs use resource-oriented URLs and HTTP based response codes to indicate API responses. API functionality is grouped into "controllers", each providing a set of methods to perform related actions. The controllers a partner can access will depend upon their specific integration requirements. A full overview of the Solaris APIs can be found in the API reference.

Environments

Two environments are available for integration. You will be provided environment specific credentials (a username and password) for accessing the respective environment.

Production

• The production environment is used to run your live system.
• Access to this environment requires a PKI based integration (recommended), or a dedicated VPN connection.
• Disaster Recovery is available in this environment.

Sandbox

• The sandbox environment is used for development and for testing purposes only.
• This environment does not require PKI or VPN based connectivity.
• This environment supports the load testing of funds.
• The sandbox provides a demo card program, for initial testing and integration.

Base sandbox API URLs are as follows:

• VPN - https://sandboxapi.contis.com
• PKI - https://betaopenapi.contis.com/V2

Encryption

There are two primary scenarios requiring encryption when interfacing with the API.

1. Encryption of sensitive card-related fields such as the card PAN, PIN, CVV numbers etc. sent between your system and the API. This is mandatory for both VPN and PKI integrations.
2. PKI integration specific encryption, required to:
   • Protect API-usage related fields (such as your password, and encryption keys received from the API).
   • Digitally sign requests made to the API.

Encryption of sensitive card fields

To protect sensitive card-related information such as the card PAN, PIN, CVV numbers etc. AES-256 symmetric encryption is used. Symmetric encryption uses the same key to encrypt and decrypt data.

When authenticating, the response from a successful login request will include a Contis_SecurityKey field. This contains a key to encrypt/decrypt sensitive card fields. It is a 96-character string constituted as follows:

• The first 32 characters contain the Initialization Vector (IV).
• The last 64 characters contain the Key.

Example security key usage

As an example, in order to retrieve a card's PIN via the Card/ViewPIN method, the Contis_SecurityKey is used to:

• Encrypt the Card CVV included in the API request (via the EncryptedCVV field).
• Decrypt the EncryptedPin value returned in the corresponding API response.

Additional encryption requirements for PKI integrations

As well as the AES-256 symmetric encryption referenced above, for partners using a PKI based integration there are two additional requirements, both of which employ RSA PKCS#1 asymmetric encryption (using a public and private key pair):

1. To protect sensitive API usage-related fields sent to/from the API, for example:
   • Encrypting your password when making a Login request .
   • Decrypting the Contis_SecurityKey received in the corresponding login response.
2. To digitally sign HTTPS requests to the API.

Full PKI integration requirements, including encryption, are detailed in the PKI integration guide.

Authentication

Retrieving an access token

Access to the API requires an access token. To retrieve an access token, you must make a call to the security/login method. The URL for this method in the sandbox environment is:

POST https://sandboxapi.contis.com/security/login        // VPN
POST https://betaopenapi.contis.com/V2/security/login    // PKI

When making a login request:

• The Content-Type of the request should be of type application/x-www-form-urlencoded
• The request payload should include a GRANT_TYPE of "password" and your environment specific credentials ( UserName and Password ) as in the example below:

GRANT_TYPE=password&UserName=<partner-username>&Password=<partner-password>

Login response

For a valid login request, the response will contain a payload including the following fields:

• access_token – an access token in JWT format used to authenticate requests made to the API.
• Contis_SecurityKey – a security key used for encryption and decryption of sensitive card fields.
• .issued and .expires fields denoting the time of token issuance and expiration respectively.

Making requests

Access token usage

An access token must be included in all requests to the API, and should be provided as a request header in the following form:

Authorization: Bearer <access_token>

Please note tokens have an expiration of 2 hours in the sandbox environment and 12 hours in the production environment.

Provision should be made to refresh tokens as required. In cases of a missing, invalid, or expired token, a 401 Unauthorized response will be received. In such cases, a new token should be generated using the method above.

Logging and tracking requests

For the purposes of logging, tracking or auditing, API requests can include an optional ClientRequestReference header. This can contain up to 50 characters. It is advised you provide a unique value for every request. If included in a request, it will be returned in the respective response payload. Please note Solaris performs no validation on this field (e.g. for uniqueness). Include this header in the following form:

ClientRequestReference: <unique-request-reference>

Responses

For valid requests, the response payload will include the following fields:

• Description - Denotes if the request was successful, or any issues/errors with the request.
• ResponseCode - Contains the respective response code for the request. For successful requests this will be "000".
• ResponseDateTime - The date and time of the response.
• ClientRequestReference - Your own reference included in the request, if one was provided.
• RequestID - The unique identifier of the API request, generated by Solaris.

Successful requests

For successful requests:

• The API will return a 200 OK HTTP response.
• The Description field will contain "Success", ResponseCode will contain "000".

The example response below shows a transfer that has been successfully requested via the API:

{
    "BankTransferReferenceID": 321207,
    "SCARes": null,
    "Description": "Success",
    "ResponseCode": "000",
    "ResponseDateTime": "2023-10-02T09:46:50.251",
    "ClientRequestReference": "ffefbdfb-b5ec-47d7-8141-bab410fd678e",
    "RequestID": 627264152702809689
}

Invalid requests

If a request contains invalid input, or parameters required for the request are missing:

• The API will return a 400 Bad Request HTTP response.
• The response body will contain an Errors array detailing the issues with the request, as shown below:

{
    "Errors": [
        {
            "Status": "3242",
            "Detail": "\"PassportNumber\" Passport number is invalid."
        }
    ]
}

Requests requiring Strong Customer Authentication (SCA)

In certain scenarios, Strong Customer Authentication (SCA) will need to be performed in order to action a request. This requires the customer authenticates themselves using Two-Factor Authentication (2FA), for example when making a transfer or payment over a certain value threshold. In these situations, where the request is valid but SCA is required:

• The API will return a 200 OK HTTP response.
• The Description field will read "SCA needs to be performed".
• The ResponseCode field will contain a code of "900".
• The SCARes object will contain a Title field denoting the SCA event which requires 2FA.

The example response below details a payment request requiring SCA be performed - note the Title of "Payment":

{
    "BankTransferReferenceID": 0,
    "SCARes": {
        "SCAReferenceNumber": "514c0a64-390d-4f21-b713-5e932e26365c",
        // ... Excluded for brevity ...
        "Title": "Payment"
      },
    "Description": "SCA needs to be performed.",
    "ResponseCode": "900",
    "ResponseDateTime": "2023-10-03T09:31:01.657",
    "ClientRequestReference": "56c0aca6-3778-49b5-9bf3-9d58fb138c32",
    "RequestID": 538348141618587881
}

Webhooks

The Solaris API provides partners with webhook functionality so they can receive notifications when certain events occur within the API or wider Solaris system. For a more detailed overview of this and for a full list of notifications available, please see the webhooks guide.