> For the complete documentation index, see [llms.txt](https://docs.pandablue.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pandablue.com/v1/deposits-api/streamline-api/deposit-creation-endpoint.md).

# Deposit Creation Endpoint

Learn how to generate deposits by using the Streamline API

### Streamline Deposit Creation

<mark style="color:green;">`POST`</mark> `https://api-stg.directa24.com/api_curl/streamline/NewInvoice`

The New Invoice API creates a new Deposit transaction and returns a URL to redirect the customer to his preferred payment method's page, where the payment can be confirmed.

**Headers**

| Name         | Type   | Description                       |
| ------------ | ------ | --------------------------------- |
| Content-Type | string | application/x-www-form-urlencoded |

**Request Body**

| Name            | Type    | Description                                                                                                                                        |
| --------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| x\_login        | string  | Your Easy Cashouts API DEPOSITS API Key, found on the Merchant Panel by going to Settings -> API Access -> Deposit Credentials                     |
| x\_trans\_key   | string  | Your Easy Cashouts API DEPOSITS API Passphrase, found on the Merchant Panel by going to Settings -> API Access -> Deposit Credentials              |
| x\_invoice      | string  | Unique identification for the transaction in your end                                                                                              |
| x\_amount       | number  | Transaction's amount in the currency specified in the field “x\_currency” (if none is sent USD will be assumed)                                    |
| x\_country      | string  | User's country ISO Code                                                                                                                            |
| x\_bank         | string  | Payment method code                                                                                                                                |
| x\_iduser       | string  | Unique user ID in your side                                                                                                                        |
| x\_cpf          | string  | User’s personal identification number                                                                                                              |
| x\_name         | string  | User’s full name (name and lastname)                                                                                                               |
| x\_email        | string  | User's valid email address                                                                                                                         |
| x\_return       | string  | URL specified to redirect the customers once they finish the deposits. It has to be a valid URL over HTTPS                                         |
| control         | string  | Control string encoded using HMAC-SHA-256 (RFC 2104) to ensure integrity                                                                           |
| x\_mobile       | string  | User’s mobile phone number                                                                                                                         |
| x\_confirmation | string  | URL used to receive notifications. Should be provided if the confirmation URL needs to be different from the one registered in your panel settings |
| x\_currency     | string  | Transaction currency in ISO 4217. If not sent, USD will be assumed.                                                                                |
| x\_description  | string  | Description of the product/service                                                                                                                 |
| x\_bdate        | string  | User’s birth date using the format: YYYYMMDD                                                                                                       |
| x\_address      | string  | User's address                                                                                                                                     |
| x\_zip          | string  | User's zip/postal code                                                                                                                             |
| x\_city         | string  | User's city                                                                                                                                        |
| x\_state        | string  | User's state ISO code                                                                                                                              |
| x\_version      | string  | API version. If none is specified 1.0 will be assumed. Version 1.1 includes additional information in the response                                 |
| type            | string  | The format of the response: JSON, XML or STRING. If none is specified XML will be assumed.                                                         |
| iframe\_view    | boolean | Used to determine if should be returned an iframe view                                                                                             |

{% tabs %}
{% tab title="200 Success Response" %}
{% tabs %}
{% tab title="v1.0" %}

```java
{
"status": "0",
"link": "[Link to redirect the customer]"
}
```

{% endtab %}

{% tab title="v1.1" %}

```java
{
"status": "0",
"link": "[Link to redirect the user]",
"local_amount": "[local amount]",
"usd_amount": "[Amount in usd]",
"local_currency": "[Local currency]",
"x_document": "[Reference of the transaction on Easy Cashouts API's side]",
"amount_to_deposit": "[Amount to deposit]"
}
```

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

{% hint style="info" %}
All the requests must be in x-www-form-urlencoded format and contain the following header:

`Content-Type: application/x-www-form-urlencoded`
{% endhint %}

### Example Request

{% tabs %}
{% tab title="cURL" %}

```javascript
curl -X POST \
https://api-stg.directa24.com/api_curl/streamline/NewInvoice \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'x_login=API_Key&x_trans_key=API_Passphrase&x_invoice=74170514&x_amount=10&x_iduser=userId123&x_bank=CA&x_cpf=63017363201&x_email=myemail%40directa24.com&type=json&x_country=BR&x_name=Jonh%2BSmith&x_version=1.0&control=X_CONTROL'

```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api-stg.directa24.com/api_curl/streamline/NewInvoice",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "x_login=API_Key&x_trans_key=API_Passphrase&x_invoice=74170514&x_amount=10&x_iduser=userId123&x_bank=CA&x_cpf=63017363201&x_email=myemail%40directa24.com&type=json&x_country=BR&x_name=Jonh%2BSmith&x_version=1.0&control=X_CONTROL",
CURLOPT_HTTPHEADER => array(
"Content-Type: application/x-www-form-urlencoded"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);

```

{% endtab %}

{% tab title="JAVA" %}

```java
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(mediaType, "x_login=API_Key&x_trans_key=API_Passphrase&x_invoice=74170514&x_amount=10&x_iduser=userId123&x_bank=CA&x_cpf=63017363201&x_email=myemail%40directa24.com&type=json&x_country=BR&x_name=Jonh%2BSmith&x_version=1.0&control=X_CONTROL");
Request request = new Request.Builder()
.url("https://api-stg.directa24.com/api_curl/streamline/NewInvoice")
.post(body)
.addHeader("Content-Type", "application/x-www-form-urlencoded")
.build();
Response response = client.newCall(request).execute();

```

{% endtab %}

{% tab title="C#" %}

```csharp
var client = new RestClient("https://api-stg.directa24.com/api_curl/streamline/NewInvoice");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
request.AddParameter("application/x-www-form-urlencoded", "x_login=API_Key&x_trans_key=API_Passphrase&x_invoice=74170514&x_amount=10&x_iduser=userId123&x_bank=CA&x_cpf=63017363201&x_email=myemail%40directa24.com&type=json&x_country=BR&x_name=Jonh%2BSmith&x_version=1.0&control=X_CONTROL", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

```

{% endtab %}
{% endtabs %}

### **Example Response**

{% tabs %}
{% tab title="Success Response v1.0" %}

```javascript
{
"status": "0",
"link": "[Link to redirect the customer]"
}
```

{% endtab %}

{% tab title="Error Response v1.0" %}

```javascript
{
"status": "1",
"desc": "[Error description]"
}

{
"status": "1",
"desc": "Payment method not found",
"error_code": "506"
}
```

{% endtab %}

{% tab title="Success Response v1.1" %}

```javascript
{
"status": "0",
"link": "[Link to redirect the user]",
"local_amount": "[local amount]",
"usd_amount": "[Amount in usd]",
"local_currency": "[Local currency]",
"x_document": "[Reference of the transaction on Easy Cashouts API's side]",
"amount_to_deposit": "[Amount to deposit]"
}
```

{% endtab %}

{% tab title="Error Response v1.1" %}

```javascript
{
"status": "1",
"desc": "[Error description]",
"error_code": "[Error code]"
}

{
"status": "1",
"desc": "x_cpf: must not be blank",
"error_code": "300"
}
```

{% endtab %}
{% endtabs %}

### **Mandatory fields description**

| Field         | Format                           | Description                                                                                                                                                                                                                  |
| ------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x_login`     | string (max length: 32)          | Your Easy Cashouts API **DEPOSITS** API Key, found on the Merchant Panel by going to Settings -> API Access -> Deposit Credentials -> API Key                                                                                |
| `x_trans_key` | string (max length: 32)          | Your Easy Cashouts API **DEPOSITS** API Passphrase, found on the Merchant Panel by going to Settings -> API Access -> Deposit Credentials -> API Passphrase                                                                  |
| `x_invoice`   | string (max length: 125)         | Unique identification for the transaction in your end                                                                                                                                                                        |
| `x_amount`    | decimal (max decimal numbers: 2) | Transaction's amount in the currency specified in the “x\_currency” field (if none is sent **USD** will be assumed)                                                                                                          |
| `x_country`   | string (max length: 2)           | User’s country. [Click here](https://docs.directa24.com/knowledge-base/countries-specifications) to see country codes.                                                                                                       |
| `x_bank`      | string (max length: 3)           | Payment method code. To check the available Payment Methods for your account, you can use the [Payment Methods Endpoint](https://docs.directa24.com/v1/deposits-api/streamline-api/payment-methods-endpoint)                 |
| `x_iduser`    | number (max digits: 11)          | Unique user's ID in your side                                                                                                                                                                                                |
| `x_cpf`       | String (max digits: 30)          | User’s personal identification number. [Click here](https://docs.directa24.com/knowledge-base/countries-specifications) to see the type of documents and its validations                                                     |
| `x_name`      | string (max length: 100)         | User’s full name (name and lastname)                                                                                                                                                                                         |
| `x_email`     | string (max length: 100)         | User’s valid email address                                                                                                                                                                                                   |
| `x_return`    | string (max length: 200)         | URL specified to redirect the customers once they finish the deposits. It has to be a valid URL over HTTPS. See [Return URL](https://docs.directa24.com/v1/deposits-api/streamline-api/deposit-creation-endpoint#return-url) |
| `control`     | string (max length: 32)          | Control string encoded using HMAC-SHA-256 (RFC 2104) to ensure integrity. [Instructions below](https://docs.directa24.com/v1/deposits-api/streamline-api/deposit-creation-endpoint#control-string-for-deposits)              |

### **Optional fields description**

| Field                       | Format                   | Description                                                                                                                                                                                                                                                 |
| --------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x_mobile`                  | string (max length: 20)  | User’s mobile number. **Mandatory for Colombia and the African countries**                                                                                                                                                                                  |
| `x_currency`                | string (max length: 3)   | Transaction currency in ISO 4217. If not sent, **USD** will be assumed. [Click here](https://docs.directa24.com/knowledge-base/countries-specifications) to see available currencies per country.                                                           |
| `x_version`                 | number                   | API version. If none is specified **1.0** will be assumed. Version **1.1** includes additional information in the response (see [examples responses](https://docs.directa24.com/v1/deposits-api/streamline-api/deposit-creation-endpoint#example-response)) |
| `x_description`             | string (max length: 200) | Transaction's description of the product/service                                                                                                                                                                                                            |
| `x_bdate`                   | string (max length: 8)   | User’s birth date using the format: **YYYYMMDD**                                                                                                                                                                                                            |
| `x_payer_registration_date` | string (max length: 8)   | User’s registration date on your website in UTC using the format: **YYYYMMDD**                                                                                                                                                                              |
| `x_address`                 | string (max length: 255) | User’s address. Mandatory for **BR** (Brazil) and **CO** (Colombia)                                                                                                                                                                                         |
| `x_zip`                     | string (max length: 10)  | User’s zip/postal code. Mandatory for **BR** (Brazil). [Click here](https://docs.directa24.com/knowledge-base/countries-specifications) to see zip code validations.                                                                                        |
| `x_city`                    | string (max length: 100) | User’s city                                                                                                                                                                                                                                                 |
| `x_state`                   | string (max length: 20)  | User’s state ISO 3166-2 code. Mandatory for **BR** (Brazil). [Click here](https://en.wikipedia.org/wiki/ISO_3166-2:BR) to see codes                                                                                                                         |
| `x_confirmation`            | string (max length: 200) | Should be provided if the confirmation URL needs to be different from the one registered in your panel settings. See [Confirmation URL](https://docs.directa24.com/v1/deposits-api/streamline-api/deposit-creation-endpoint#confirmation-url)               |
| `type`                      | string (max length: 20)  | The format of the response: **JSON**, **XML** or **STRING**. If none is specified **XML** will be assumed.                                                                                                                                                  |
| `iframe_view`               | boolean                  | Used to determine if should be returned an iframe view.                                                                                                                                                                                                     |

### **Control String for Deposits**

#### Example: Control String for New Invoice API

{% tabs %}
{% tab title="PHP" %}

```php
<?php
$apiSignature = 'your_deposits_API_Signature';
$message = $x_invoice .'V' . $x_amount .'I' . $x_iduser .'2' . $x_bank .'1' . $x_cpf .'H' . $x_bdate .'G' . $x_email .'Y' . $x_zip .'A' . $x_address .'P' . $x_city .'S' . $x_state . 'P';
$control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*', $apiSignature)));
?>

```

{% endtab %}

{% tab title="JAVA" %}

```java
String apiSignature = "your_deposits_API_Signature";
String message = x_invoice + "V" + x_amount + "I" + x_iduser + "2" + x_bank + "1" + x_cpf + "H" + x_bdate + "G" + x_email + "Y" + x_zip + "A" + x_address + "P" + x_city + "S" + x_state + "P";
Mac hasher = Mac.getInstance("HmacSHA256");
hasher.init(new SecretKeySpec(apiSignature.getBytes(), "HmacSHA256"));

String control = Base64.encodeBase64String(hasher.doFinal(message.getBytes())).toUpperCase();

```

{% endtab %}

{% tab title="C#" %}

```csharp
string apiSignature = "your_deposits_API_Signature";
string message = x_invoice + "V" + x_amount + "I" + x_iduser + "2" + x_bank + "1" + x_cpf + "H" + x_bdate + "G" + x_email + "Y" + x_zip + "A" + x_address + "P" + x_city + "S" + x_state + "P";
byte[] keyByte = new ASCIIEncoding().GetBytes(apiSignature);
byte[] messageBytes = new ASCIIEncoding().GetBytes(message);
byte[] hashmessage = new HMACSHA256(keyByte).ComputeHash(messageBytes);

string control = BitConverter.ToString(hashmessage).Replace("-", "").ToUpper();

```

{% endtab %}
{% endtabs %}

The `x_control` field is a mandatory field used to ensure request integrity. It should be created using HMAC-SHA-256 (RFC 2104) encoding and must include **ONLY** the following fields:

* x\_invoice
* x\_amount
* x\_iduser
* x\_bank
* x\_cpf
* x\_bdate
* x\_email
* x\_zip
* x\_address
* x\_city
* x\_state
* secretKey - your DEPOSITS API Signature which can be found on the Merchant Panel by going to *Settings -> API Access -> Deposit Credentials -> API Signature*

The Control String for deposits must be in **Upper Case** and must include all the above mentioned fields even if any of those are **empty**. Each field has to be converted to UTF-8 before actually hashing it to prevent Invalid Control Hash error when sending characters with different encodings. Please check the examples above in the different languages on how to properly calculate the Control String.

### **Return URL**

Once the customer finishes his deposit, he will be redirected back to your site using the return URL (x\_return parameter) specified as part of the New Invoice request **OR** the one registered in your panel settings (*Settings -> API Access*). We only accept HTTPS URLs. The redirect is made using POST protocol with the following parameters:

| Field          | Description                                                                                |
| -------------- | ------------------------------------------------------------------------------------------ |
| result         | Transaction result. See: [Api Codes](https://docs.directa24.com/v1/deposits-api/api-codes) |
| x\_invoice     | Unique identification for the transaction in your end                                      |
| x\_iduser      | Unique user ID in your side                                                                |
| x\_description | Transaction's description                                                                  |
| x\_document    | Unique transaction's ID at Easy Cashouts API                                               |
| x\_amount      | Payment's amount                                                                           |
| x\_control     | Control signature. Used to verify the parameters weren't modified while in transit         |

{% hint style="warning" %}
Never update the status of a payment by using the `result` sent along with the Return URL. This shows where in the payment flow the user left the payment page. Always expect the notification/check the deposit status to update the status of a payment.
{% endhint %}

#### **Control String for Return URL**

**Example: Return Redirection - control signature**

{% tabs %}
{% tab title="PHP" %}

```php
<?php
$apiSignature = 'your_deposits_API_Signature';
$message = $x_login . $result . $x_amount . $x_invoice ;
$control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*', $apiSignature)));
?>

```

{% endtab %}

{% tab title="JAVA" %}

```java
String message = x_login + result + x_amount + x_invoice;
String apiSignature = "your_deposits_API_Signature";
Mac hasher = Mac.getInstance("HmacSHA256");
hasher.init(new SecretKeySpec(apiSignature.getBytes(), "HmacSHA256"));

String control = Base64.encodeBase64String(hasher.doFinal(message.getBytes())).toUpperCase();

```

{% endtab %}

{% tab title="C#" %}

```csharp
string apiSignature = "your_deposits_API_Signature";
string message = x_login + result + x_amount + x_invoice;
byte[] keyByte = new ASCIIEncoding().GetBytes(apiSignature);
byte[] messageBytes = new ASCIIEncoding().GetBytes(message);
byte[] hashmessage = new HMACSHA256(keyByte).ComputeHash(messageBytes);

string control = BitConverter.ToString(hashmessage).Replace("-", "").ToUpper();

```

{% endtab %}
{% endtabs %}

The return URL control signature includes the following fields:

* x\_login - your Easy Cashouts API **DEPOSITS** API login which can be found on the Merchant Panel by going to *Settings -> API Access -> Deposit Credentials -> API Key*
* result
* x\_amount
* x\_invoice
* secretKey - your Easy Cashouts API **DEPOSITS** API Signature which can be found on the Merchant Panel by going to *Settings -> API Access -> Deposit Credentials -> API Signature*

### **Confirmation URL**

A notification will be sent to your confirmation URL every time the deposit changes its status by using the `x_confirmation` parameter specified as part of the New Invoice request or the one registered in your Merchant Panel settings (*Settings -> API Access*). It is made using POST protocol with the following parameters:

| Field            | Description                                                                                                                 |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------- |
| result           | Transaction result. See [possible result codes](https://docs.directa24.com/v1/deposits-api/api-codes#deposits-status-codes) |
| x\_invoice       | Unique identification for the transaction in your end                                                                       |
| x\_iduser        | Unique user ID in your side                                                                                                 |
| x\_description   | Transaction's description                                                                                                   |
| x\_document      | Unique transaction's ID at Easy Cashouts API's end                                                                          |
| x\_bank          | Payment method code. See [Payment methods](https://docs.directa24.com/v1/deposits-api/payment-methods)                      |
| x\_payment\_type | Payment type. See [payment types](https://docs.directa24.com/v1/deposits-api/api-codes#payment-types)                       |
| x\_bank\_name    | Payment method name. See [Payment methods](https://docs.directa24.com/v1/deposits-api/payment-methods)                      |
| x\_amount        | Payment amount                                                                                                              |
| x\_currency      | Payment currency in ISO 4217                                                                                                |
| x\_control       | Control signature                                                                                                           |

{% hint style="info" %}
In the STG environment, you can force a notification to be sent to your `x_confirmation` URL from the STG Merchant Panel by going to the Deposits Details page and clicking on one of the options that will appear when clicking in the three dots button on the top right of the screen. Those options will change the status of the deposit therefore sending the respective notification after a few minutes.
{% endhint %}

![How to manually Approve/Cancel a deposit in STG to test notifications](https://3883333839-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff92vedEnowdVWbjM4Cmd%2Fuploads%2FL3jLshOeQnZuAHIu77vB%2Fdeposit_notifications.png?alt=media\&token=39833c20-af81-498c-9c54-8eac3c4eabe3)

####

#### **Control String for Confirmation URL**

**Example: Confirmation Url - control signature**

{% tabs %}
{% tab title="PHP" %}

```php
<?php
$apiSignature = 'your_deposits_API_Signature';
$message = $x_login . $result . $x_amount . $x_invoice ;
$control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*', $apiSignature)));
?>

```

{% endtab %}

{% tab title="JAVA" %}

```java
String message = x_login + result + x_amount + x_invoice;
String apiSignature = "your_deposits_API_Signature";
Mac hasher = Mac.getInstance("HmacSHA256");
hasher.init(new SecretKeySpec(apiSignature.getBytes(), "HmacSHA256"));

String control = Base64.encodeBase64String(hasher.doFinal(message.getBytes())).toUpperCase();

```

{% endtab %}

{% tab title="C#" %}

```csharp
string message = x_login + result + x_amount + x_invoice;
string apiSignature = "your_deposits_API_Signature";
byte[] keyByte = new ASCIIEncoding().GetBytes(apiSignature);
byte[] messageBytes = new ASCIIEncoding().GetBytes(message);
byte[] hashmessage = new HMACSHA256(keyByte).ComputeHash(messageBytes);

string control = BitConverter.ToString(hashmessage).Replace("-", "").ToUpper();

```

{% endtab %}
{% endtabs %}

The confirmation URL control signature includes the following fields:

* x\_login - your DEPOSITS API Key which can be found on the Merchant Panel by going to *Settings -> API Access -> Deposit Credentials -> API Key*
* result
* x\_amount
* x\_invoice
* secretKey - your DEPOSITS API Signature which can be found on the Merchant Panel by going to *Settings -> API Access -> Deposit Credentials -> API Signature*

{% hint style="warning" %}
In some cases may occur that you will receive a **Cancelled** notification for a transaction and following a **Completed** notification for the same transaction. This happens if we were unable to automatically detect the Deposit (because the user paid a different amount or after it got expired) and the transaction reached its expiration time. Once our team manually approves it, we change the status from Cancelled to Completed.
{% endhint %}

Both the **Return URL** and the **Confirmation URL** can be defined by default in your panel (Settings -> API Access). These parameters can be over-ridden at any time using the **x\_return** and **x\_confirmation** parameters (however, these new urls are only active for that particular invoice, following invoice will use the default URLs previously configured if not sent again).

### **Iframes**

It is possible to display an iframe on your website instead of redirecting your customer with an external window.

In order to do this, you need to insert an *`<iframe>`* tag on your website. In the `src` attribute you must set the **link: \[link to redirect the user]** parameter from success response and append the following GET parameter "iframe\_view=1" to the link as shown below:

```
<iframe src="[link to redirect the user]&iframe_view=1"> </iframe>
```

{% hint style="warning" %}
Some Payment Methods may not be available within an iframe due to processor´s security requirements. [Check here the available ones](https://docs.directa24.com/deposits/payment-methods).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.pandablue.com/v1/deposits-api/streamline-api/deposit-creation-endpoint.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
