# Technical and Security Aspects

## Security Considerations

* All API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure). Calls made over plain HTTP will fail. 
* API requests without [Authentication](https://docs.pandablue.com/api-documentation/bank-accounts-validation-api/technical-and-security-aspects/calculating-the-signature) will also fail.
* You will be able to hit our APIs only from the IPs you have [previously whitelisted](#ip-whitelisting) on the Merchant Panel.

## Environments

All the integration must be performed on our **TEST environment**, where you can perform your tests freely without risks of any kind.

When you sign up with us, we will generate you an account on our STG environment where you will be able to:

* See the transactions created
* Approve and cancel transactions
* Retrieve your API Keys
* Whitelist your IPs, and more

### Endpoint domains

Each environment has its own domain. The path of the [endpoints ](https://docs.pandablue.com/api-documentation/bank-accounts-validation-api/bank-account-validation-endpoint)doesn't change.

| Environment | Domain                                 |
| ----------- | -------------------------------------- |
| Testing     | `https://api-stg.directa24.com/`       |
| Production  | Provided once you complete the testing |

{% hint style="info" %}
Notes:

* You will use the STG endpoints to integrate.
* The STG and PROD environments are not communicated in any way. 
* No transaction created on the STG environment will be reflected on the PROD environment or vice versa. 
* The API Keys and configurations between environments are also different.
  {% endhint %}

## API Keys

Our Bank Accounts Validation APIs uses API Keys in all of the requests to authenticate. Your API Keys can be retrieved from the Merchant Panel by going to Settings -> API Access -> Cashouts Credentials.

{% hint style="info" %}

* The API Keys on the STG and PROD environments are different.
  {% endhint %}

Authentication to the API is performed via [HTTP Basic Auth](http://en.wikipedia.org/wiki/Basic_access_authentication). You must provide your API Key in all the requests as the basic auth username value. You do not need to provide a password.

Your API Key must be sent in all the API calls using the X-Login field on the header of the request.

Your API Keys, along with your [IP Addresses](#ip-whitelisting) are your way to authenticate yourself, therefore, do not share your secret API keys in publicly accessible areas such as GitHub, client-side code and so forth.

## Headers

All the requests sent through the API of Deposits v3 must have the following headers.

| Header        | Format | Mandatory | Description                                                              |
| ------------- | :----: | :-------: | ------------------------------------------------------------------------ |
| Authorization | String |    Yes    | `"D24 "` plus a hash HMAC256 to verify request integrity                 |
| X-Login       | String |    Yes    | Merchant Cashout `API Key`                                               |
| X-Date        | String |    Yes    | ISO8601 Datetime: `yyyy-MM-dd'T'HH:mm:ssZ`. E.g.: `2020-06-21T12:33:20Z` |
| Content-Type  | String |    Yes    | `application/json`                                                       |

###

### Authorization Signature

All the requests you send must contain the `Authorization` header with an HMAC256 control string signature using your own API Signature. This is used to verify the request integrity as we will calculate the same Signature and compare it with the one you send. In case of mismatch we will decline the request. You can retrieve your API Signature from our backoffice by going to Settings -> API Access -> Cashout API Signature

Check the following page for instructions on how to calculate the Control Signature.

{% content-ref url="technical-and-security-aspects/calculating-the-signature" %}
[calculating-the-signature](https://docs.pandablue.com/api-documentation/bank-accounts-validation-api/technical-and-security-aspects/calculating-the-signature)
{% endcontent-ref %}

### X-Login

All the requests you send must contain the header `X-Login` with your own API Key value used to authenticate yourself. Check [API Keys](#api-keys).

### X-Date

All the requests you send must contain the header `X-Date` with the time in which the request was created. The format is in ISO8601 Datetime: `yyyy-MM-dd'T'HH:mm:ssZ`. E.g.: `2020-06-21T12:33:20Z`. 

{% hint style="warning" %}
Make sure you use UTC as the timezone specified and not your client's local timezone.
{% endhint %}

If the date you send differs in **more than 5 seconds** with the time in our servers, we will block the request for security reasons.

#### Example of how to generate the correct X-Date value

{% tabs %}
{% tab title="Java" %}
{% code title="source: JAVA SDK > src/main/java/com/directa24/client/util/ClientUtils.java" %}

```java
import java.time.LocalDateTime;
import java.time.ZoneOffset;
import java.time.format.DateTimeFormatter;

public class ClientUtils {

   private static final String DATE_PATTERN = "yyyy-MM-dd'T'HH:mm:ss'Z'";

   private static final DateTimeFormatter DATE_TIME_FORMATTER = DateTimeFormatter.ofPattern(DATE_PATTERN);


   public static String now() {
      return LocalDateTime.now(ZoneOffset.UTC).format(DATE_TIME_FORMATTER);
   }

}

```

{% endcode %}
{% endtab %}

{% tab title="PHP" %}
{% code title="source: PHP SDK > src/util/Helpers.php" %}

```php
<?php

namespace Directa24\util;

class Helpers 
{
    private static $DATE_TIME_FORMATTER = "Y-m-d\TH:i:s\Z";

    public static function getCurrentDate()
    {
        date_default_timezone_set('UTC');
        return date(self::$DATE_TIME_FORMATTER);
    }
}

print(Helpers::getCurrentDate());

```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="success" %}
Check our SDK in [JAVA](https://docs.pandablue.com/deposits-tools/java-sdk) and [PHP](https://docs.pandablue.com/deposits-tools/php-sdk) for the full code of how to generate the X-Date and the full request.
{% endhint %}

### Content-Type

This API is designed to receive and respond the information in JSON format.

This header won't change across the requests, and shall always be: `application/json`

## IP Whitelisting

For security purposes, you need to whitelist the IPs from where you will call our API.

In order to whitelist your IPs and make the process as smoother as possible, you should go to **Settings -> API Access** and add the list of IPs you will possibly use under the **Cashout IP Address** section.

Reach out to <integration@d24.com> if you need to whitelist **our servers IPs** on your firewall.&#x20;

## Best Practices

We recommend you follow this list of technical and security practices to maximize the security of the information end-to-end.

1. Always ensure to verify the Signatures control string sent in the notifications to validate its veracity.
2. We convert all the data we receive to UTF-8. Make sure you are also converting it into UTF-8 to make sure both parties have the same details.&#x20;

Go to the next page to learn how to generate the requests signatures control string to verify the requests' you send and receive integrity.