> 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/hybrid-api/deposit-creation-endpoint.md).

# Deposit Creation Endpoint

### Hybrid Deposit Creation

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

The Hybrid API creates a URL to redirect the customers to our Hosted Checkout where they need to fill in the required details before proceeding with the payment

**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\_iduser      | string | Unique user ID in your side                                                                                                                                                             |
| x\_amount      | number | Deposit amount                                                                                                                                                                          |
| x\_country     | string | Deposit country code ISO 3166-1 alpha-2                                                                                                                                                 |
| control        | string | Deposit control string encoded using HMAC-SHA-256 (RFC 2104). Used to verify request integrity                                                                                          |
| x\_currency    | string | Deposit currency in ISO 4217. If not sent, USD will be assumed                                                                                                                          |
| x\_bank        | string | Payment method code. If not sent the customer will be able to select on on our Hosted Checkout                                                                                          |
| cpf            | string | Customer national document ID                                                                                                                                                           |
| x\_name        | string | Customer full name (name and last name)                                                                                                                                                 |
| x\_email       | string | Customer valid email address                                                                                                                                                            |
| type           | string | The format of the response: XML or JSON. If none is specified, XML will be assumed                                                                                                      |
| x\_logo        | string | URL pointing to your logo to show on our Hosted Checkout                                                                                                                                |
| x\_return      | string | URL where you would like to redirect the customers once they finish the deposits. It has to be a valid URL over HTTPS                                                                   |
| x\_confirm     | 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. It has to be a valid URL over HTTPS |
| x\_description | string | Description of the product/service offered                                                                                                                                              |

{% tabs %}
{% tab title="200 Success response" %}

```java
{
"status": "OK",
"link": "https://payin-stg.directa24.com/validate/exampleEDQ7EUuBGdItCvQsYcphwBYFuPIV1lLM"
}
```

{% 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/apd/create \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'x_login=DEPOSITS_API_KEY&x_trans_key=DEPOSITS_X_PASSPHRASE&x_invoice=ID12345&x_amount=100&x_iduser=123456&x_country=BR&control=<SIGNATURE>&type=json'

```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api-stg.directa24.com/api_curl/apd/create",
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=DEPOSITS_API_KEY&x_trans_key=DEPOSITS_X_PASSPHRASE&x_invoice=ID12345&x_amount=100&x_iduser=123456&x_country=BR&control=<SIGNATURE>&type=json",
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=DEPOSITS_API_KEY&x_trans_key=DEPOSITS_X_PASSPHRASE&x_invoice=ID12345&x_amount=100&x_iduser=123456&x_country=BR&control=<SIGNATURE>&type=json");
Request request = new Request.Builder()
.url("https://api-stg.directa24.com/api_curl/apd/create")
.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/apd/create");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
request.AddParameter("x_login=DEPOSITS_API_KEY&x_trans_key=DEPOSITS_X_PASSPHRASE&x_invoice=ID12345&x_amount=100&x_iduser=123456&x_country=BR&control=<SIGNATURE>&type=json", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

```

{% endtab %}
{% endtabs %}

### **Request fields description**

| Field           | Mandatory | Format                                          | Description                                                                                                                                                                                                                                                                                         |
| --------------- | :-------: | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x_login`       |    Yes    | 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`   |    Yes    | 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`     |    Yes    | string (max length: 125)                        | Unique identification for the deposit transaction in your side. It will also be used to retrieve the status of the transaction                                                                                                                                                                      |
| `x_iduser`      |    Yes    | number (max digits: 125)                        | Unique customer ID in your side                                                                                                                                                                                                                                                                     |
| `x_amount`      |    Yes    | decimal (up to 10 digits with up to 4 decimals) | Deposit amount in the currency specified with the field `x_currency` (defaults to USD)                                                                                                                                                                                                              |
| `x_country`     |    Yes    | string (max length: 2)                          | Customer’s country ISO 3166-1 alpha-2 code. [Click here](https://docs.directa24.com/knowledge-base/countries-specifications) to see country codes                                                                                                                                                   |
| `control`       |    Yes    | string (max length: 32)                         | Control string encoded using HMAC-SHA-256 (RFC 2104) to ensure request´s integrity. [Click here](https://docs.directa24.com/v1/deposits-api/hybrid-api/deposit-creation-endpoint#control-string-for-the-hybrid-api-requests) for instructions                                                       |
| `x_currency`    |     No    | string (max length: 3)                          | Currency in which the amount will be specified. [Click here](https://docs.directa24.com/knowledge-base/countries-specifications) to see the available currencies per country                                                                                                                        |
| `x_bank`        |     No    | string (max length: 3)                          | Payment method code (see [Payment Methods)](https://docs.directa24.com/v1/deposits-api/payment-methods). To check the available Payment Methods for your account, you can use the [get\_banks\_by\_country API](https://docs.directa24.com/v1/deposits-api/streamline-api/payment-methods-endpoint) |
| `cpf`           |     No    | String (max digits: 30)                         | Customer personal identification number. [Click here](https://docs.directa24.com/knowledge-base/countries-specifications) to see the validations                                                                                                                                                    |
| `x_name`        |     No    | string (max length: 50)                         | Customer full name (name and last name)                                                                                                                                                                                                                                                             |
| `x_email`       |     No    | string (max length: 100)                        | Customer valid email address. [Click here](https://docs.directa24.com/knowledge-base/countries-specifications) to see email validations                                                                                                                                                             |
| `type`          |     No    | string (max length: 20)                         | The format of the response: **XML** or **JSON**. If none is specified **XML** will be assumed.                                                                                                                                                                                                      |
| `x_logo`        |     No    | string (URL) (max length: 200)                  | Your company´s logo to show in our check-in page                                                                                                                                                                                                                                                    |
| `x_return`      |     No    | string (URL) (max length: 200)                  | URL where you would like to redirect the customers once they finish the deposits. It has to be a valid URL over HTTPS (I.e.: <https://www.directa24.com>). [See Return URL](https://docs.directa24.com/v1/deposits-api/streamline-api/deposit-creation-endpoint#return-url)                         |
| `x_confirm`     |     No    | string (URL) (max length: 200)                  | URL specified where we will send the deposit notifications. It has to be a valid URL over HTTPS (I.e.: <https://www.directa24.com/notify>). [See Notifications](https://docs.directa24.com/v1/deposits-api/hybrid-api/deposit-creation-endpoint#notifications)                                      |
| `x_description` |     No    | string (max length: 200)                        | Description of the transaction                                                                                                                                                                                                                                                                      |

####

#### **Optional fields**

When you use the Hybrid API, you can opt for sending only the mandatory fields. However, when the customers gets into our Hosted Checkout, we will ask them to input the missing information. If you send the `x_cpf`, `x_name`, and `x_email` fields, the information will be automatically populated onto the Checkout page and therefore, the customers wont have to manually insert it nor will be able to modify it. This is extremely useful when you already have that details on your database.

Your **logo** (`x_logo`) can be defined by default in the Merchant Panel by submitting one into Settings -> Company -> "Merchant Payment Page Logo". Otherwise, you can replace it on each request by sending a URL with your logo in the field `x_logo`.

Both the **Return URL** (`x_return`) and the **Confirmation URL** (`x_confirm`) are defined by default in your Merchant Panel by going to Settings -> API Access. These parameters can be over-ridden at any time using the **`x_return`** and **`x_confirm`** parameters in the deposit request.

### **Control String for the Hybrid API requests**

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

```php
<?php
$apiSignature = 'your_deposits_api_signature';
$message = $x_invoice .'D' . $x_amount .'P' . $x_iduser .'A';

$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 + "D" + x_amount + "P" + x_iduser + "A";
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 + "D" + x_amount + "P" + x_iduser + "A";
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 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
* secretKey - your Easy Cashouts API DEPOSITS API Signature, found on the Merchant Panel by going to Settings -> API Access -> Deposit Credentials -> API Signature

The Control String for the Hybrid API must be in Upper Case and must include all the above mentioned fields. Each field should 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 in the different languages on how to properly calculate the Control String.

####

### **Example Response**

{% tabs %}
{% tab title="Success Response" %}

```javascript
{
"status": "OK",
"link": "https://payin-stg.directa24.com/validate/exampleEDQ7EUuBGdItCvQsYcphwBYFuPIV1lLM"
}

```

{% endtab %}

{% tab title="Error Response" %}

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

{
"status": "ERROR",
"desc": "x_amount: wrong argument type"
}
```

{% endtab %}
{% endtabs %}

### Check Status

Once you redirect your customers to our **Hosted Checkout** page, they will complete all the details and click on **Confirm details**. If everything is OK, the transaction will remain in **Pending** status until we detect the customers payment. Once detected, the transaction will be changed to **Completed** state or if the user never pays it will expire and be updated to **Cancelled** state.

As soon as the user comes back to your Return URL, a POST request will come along with it with the details of the request as shown in the code snippet *"Example: POST to the Return URL"* below.

{% code title="Example: POST to the Return URL" %}

```javascript
{
"x_document": "94581245",
"x_invoice": "test8385",
"x_iduser": "1342133413",
"x_description": "",
"x_amount": "100.00",
"x_amount_usd": "100.00",
"result": "7",
"x_parent_invoice": "",
"x_control": "<SIGNATURE>"
}
```

{% endcode %}

#### **Control String for the POST to the Return URL**

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

```php
<?php
$api_key = 'your_deposits_api_key';
$x_result = 'notification_x_result';
$x_amount = 'notification_x_amount';
$x_invoice = 'notification_x_invoice';
$api_signature = 'your_deposits_api_signature';

$message = $x_login . $x_result . $x_amount . $x_invoice;
$control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*', $api_signature)));
?>

```

{% endtab %}

{% tab title="JAVA" %}

```java
String api_key = "your_deposits_api_key";
String x_result = "notification_x_result";
String x_amount = "notification_x_amount";
String x_invoice = "notification_x_invoice";
String api_signature = "your_deposits_api_signature";

String message = x_login + x_result + x_amount + x_invoice;
Mac hasher = Mac.getInstance("HmacSHA256");
hasher.init(new SecretKeySpec(api_signature.getBytes(), "HmacSHA256"));

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

```

{% endtab %}

{% tab title="C#" %}

```csharp
string api_key = "your_deposits_api_key";
string x_result = "notification_x_result";
string x_amount = "notification_x_amount";
string x_invoice = "notification_x_invoice";
string api_signature = "your_deposits_api_signature";

string message = x_login + x_result + x_amount + x_invoice;
byte[] keyByte = new ASCIIEncoding().GetBytes(api_signature);
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 we sent in the notification, is used to ensure request integrity. It should be created using HMAC-SHA-256 (RFC 2104) encoding and must include **ONLY** the following fields:

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

The Control String for the POST of the Return URL Hybrid API must be in Upper Case and must include all the above mentioned fields. Each field should 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 in the different languages on how to properly calculate the Control String.

#### **Webpaystatus API**

> Example: webpaystatus API´s response in Pending status

{% tabs %}
{% tab title="Pending response example" %}

```java
{
"result": "7",
"x_iduser": "123456",
"x_invoice": "test9417",
"x_amount": "100.00",
"PT": "0",
"Sign": "<SIGNATURE>",
"x_document": "192170814",
"x_bank": "MC",
"x_payment_type": "03",
"x_bank_name": "Mastercard",
"x_currency": "USD"
}
```

{% endtab %}

{% tab title="Not found response example" %}

```java
{
"result": "6",
"x_iduser": "0",
"x_invoice": "test9417z",
"x_amount": "0",
"PT": "0",
"Sign": "<SIGNATURE>",
"x_document": "-1",
"x_bank": " ",
"x_payment_type": "0",
"x_bank_name": " ",
"x_currency": " "
}
```

{% endtab %}
{% endtabs %}

If the user fails to be redirected to your `return_url`, you wont be notified about the transaction in Pending state until it changes to either "Completed" or "Cancelled". Therefore, after some minutes (recommended 5 minutes) of the requests being created, you can opt to use the [Deposit Status API](https://docs.directa24.com/v1/deposits-api/streamline-api/deposit-status-endpoint) to check whether the transaction was created and left Pending on our end. That would happen only if the customer finished the flow on the Hosted Checkout page and was redirected to the Payment Method page to deposit.

If the transaction was created, when you check its status with the [Deposit Status API](https://docs.directa24.com/v1/deposits-api/streamline-api/deposit-status-endpoint), you will receive a response with **"result": "7"** along with other details about the transaction. Result 7 means "Transaction Pending, awaiting customer's deposit". If the transaction was never created, be it because the user inserted incorrect data or they have never completed the flow, when you use the [Deposit Status API](https://docs.directa24.com/v1/deposits-api/streamline-api/deposit-status-endpoint) you will receive a response with **"result": "6"** meaning "Transaction not found on the system". Feel free to check its status again after some more time in case the user is delayed.

[Click here](https://docs.directa24.com/v1/deposits-api/api-codes) for all the results code meanings.

### **Notifications**

#### Transaction completed

{% code title="Notification example: Transaction completed" %}

```java
{
"result": "9",
"x_currency": "USD",
"x_amount": "100.00",
"x_description": "",
"x_iduser": "1342133413",
"x_bank_name": "Banco%20do%20Brasil",
"x_document": "94580928",
"x_bank": "BB",
"x_payment_type": "00",
"x_amount_usd": "100.00",
"x_control": "<SIGNATURE>",
"x_invoice": "test9349"
}
```

{% endcode %}

####

#### Transaction expired

{% code title="Notification example: Transaction expired" %}

```java
{
"result": "8",
"x_currency": "USD",
"x_amount": "100.00",
"x_description": "",
"x_iduser": "1342133413",
"x_bank_name": "Banco%20do%20Brasil",
"x_document": "94580929",
"x_bank": "BB",
"x_payment_type": "00",
"x_amount_usd": "100.00",
"x_control": "<SIGNATURE>",
"x_invoice": "test6337"
}
```

{% endcode %}

If the transaction was successfully created, you will receive a notification in the URL specified in the `x_confirm` field every time it changes its status. `result` **9** in case the payment was completed. At that moment, you can release the funds to the customer in your website as the payment has been detected and the funds are now in your account. A `result` **8** in case the payment wasn't completed before it reached its expiration time.

[Click here](https://docs.directa24.com/v1/deposits-api/api-codes#deposits-status-codes) for all the result codes meanings.


---

# 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/hybrid-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.
