# Standards

The Solaris API incorporates the following international standards:

## ISO codes

The Solaris API standardizes the format of the following types of values according to ISO standards:

- Country codes: [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) alpha-2 codes (e.g., `CH` for Switzerland).
- Currency codes: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) (e.g., `EUR` for Euro).
- German state codes: [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2:DE) (e.g., `BE` for Berlin).
- Times and dates: [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).


## SEPA characters

The European Payments Council (EPC) has defined the [EPC217-08 standard](https://www.europeanpaymentscouncil.eu/sites/default/files/KB/files/EPC217-08%20Draft%20Best%20Practices%20SEPA%20Requirements%20for%20Character%20Set%20v1.1.pdf) for limiting the characters allowed in SEPA transactions. Solaris enforces this standard on the following fields:

- For SEPA Direct Debits:
  - `end_to_end_id`
  - `description`
  - Within the `mandate` property: `reference`, `debtor_name`
- For SEPA Credit Transfers:
  - `recipient_name`
  - `end_to_end_id`
  - `description`


You may only use the following characters for these fields:

- Upper case letters: `A B C D E F G H I J K L M N O P Q R S T U V W X Y Z`
- Lower case letters: `a b c d e f g h i j k l m n o p q r s t u v w x y z`
- Numbers: `0 1 2 3 4 5 6 7 8 9`
- Special characters: `/ - ? : ( ) . , ' +`
- With the exception of `reference` (within `mandate`) and `end_to_end_id`, all fields may contain spaces (but no leading spaces).


Additionally, the following guidelines apply to the structure of text fields:

- The string may not contain two or more consecutive forward slashes (`/`).
- The string may not start or end with a forward slash (`/`).


Solaris is required to escape specific characters with dedicated representations. In this case, Solaris will count the representation as multiple characters. Therefore, your solution must consider this when checking the length of a string in one of the above character-restricted properties.

| Character | Representation | Character Count |
|  --- | --- | --- |
| `'` **(single quotation)** | `'` | 6 |


### Extended character conversion

In cases where a customer's name contains extended Latin characters (e.g.,
letters with a diaeresis ¨ or accent ´), Solaris will convert the character to a
SEPA-standard representation according to [this table provided by the European
Payments
Council](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best?documents_id=332).

For example, `ö` will be converted to `o:`.

## Merchant category codes

The Solaris API uses the merchant category codes (MCCs) referred to in the [Visa Merchant Data Standards Manual](https://usa.visa.com/content/dam/VCOM/download/merchants/visa-merchant-data-standards-manual.pdf) and the [Master Card MCCs Reference Booklet](https://www.mastercard.us/content/dam/public/mastercardcom/na/global-site/documents/quick-reference-booklet-merchant.pdf). These documents contain requirements for merchant/payment, facilitator/marketplace classification, location, and various other data elements, including merchant location, merchant category codes (MCC), and other VisaNet data formats.

## Character encoding

The Solaris API uses UTF-8 encoding with a Unicode charset according to the JSON standard.

## Other standards

- Mobile numbers follow the [E.164 recommendation](https://en.wikipedia.org/wiki/E.164). Mobile numbers must start with a `+`, followed by 7 to 15 digits. The API will strip whitespaces and any of `/_-` before validation.
- Return codes for SEPA follow general EPC guidance on reason codes for R-transactions, e.g., [EPC173-14](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/epc-guidance-reason-codes-sepa-direct-debit-r-transactions).
- Solaris only accepts **UTF-8 Latin characters** for all fields related to customer data. Submitting any other types of characters will cause the KYC flow to fail.


## Money type

For all properties containing a money amount, Solaris uses a standard money schema. This applies to the following types of properties:

- `amount`
- `balance`
- `fee`
- `charge`


The standard money schema contains the following properties:

| Parameter | Type | Description |
|  --- | --- | --- |
| `value` | integer | The actual amount of money. |
| `currency` | string | The currency in which the amount is represented. Currently, Solaris only supports `EUR`. |
| `unit` | string | The unit of currency represented in the amount. Currently, Solaris only supports `cents`. |
| `precision` | integer | The accuracy of the value. This is only available for `items`, `transactions`, and `charges`. |


**Example payload with a `money` type:**


```json
{
  "reference": "reference",
  "amount": {
    "value": 1000,
    "unit": "cents",
    "currency": "EUR",
    "precision": 2
  },
  "description": "See the money type above",
  "recipient_iban": "DE32110101001000000029",
  "recipient_name": "Money Type"
}
```

The `amount` in this example represents 10 Euros (i.e., 1000 Euro cents).