> 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/refund-creation-endpoint.md).

# Refund Creation Endpoint

Create refunds requests from a completed deposit

### Refund Creation Endpoint

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

This endpoint allows you to request a partial or complete refund over a completed transaction.

**Headers**

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

**Request Body**

| Name                 | Type   | Description                                                                                               |
| -------------------- | ------ | --------------------------------------------------------------------------------------------------------- |
| x\_login             | string | Your Deposits API Key, can be retrieved from the Merchant Panel by going to Settings -> API Access        |
| x\_trans\_key        | string | Your Deposits API Passphrase, can be retrieved from the Merchant Panel by going to Settings -> API Access |
| x\_invoice           | string | Deposit ID on your end                                                                                    |
| x\_document          | string | Deposit ID on Easy Cashouts API's end                                                                     |
| x\_amount            | string | The amount you want to refund                                                                             |
| x\_currency          | string | The currency of the amount                                                                                |
| x\_bank\_beneficiary | string | Customer's name and lastname                                                                              |
| x\_bank\_code        | string | Customer's bank name                                                                                      |
| x\_bank\_account     | string | Customer's bank account number                                                                            |
| x\_account\_type     | string | Customer's bank account type                                                                              |
| x\_bank\_branch      | string | Customer's bank branch                                                                                    |
| x\_control           | string | HMAC256 control signature                                                                                 |
| x\_comments          | string | A comment for the refund                                                                                  |
| type                 | string | The format of the response: XML, JSON or STRING.                                                          |

{% tabs %}
{% tab title="200 Refund successfully created." %}

```bash
{
"status": "OK",
"desc": "Pending",
"control": "<SIGNATURE>",
"result": "0",
"x_invoice": "74170514",
"x_document": "4554231",
"x_amount": "10",
"x_currency": "BRL",
"x_amount_refunded": "10",
"x_refund": "14311386"
}
```

{% 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 %}

### Request fields

| Field name           | Format                           | Description                                                                                                                                                    | Default                |                                                                                                             Validations                                                                                                            |
| -------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| x\_login             | string (max length: 32)          | Your Deposits API Key, can be retrieved from the Merchant Panel by going to Settings -> API Access                                                             |                        |                                                                                                          Valid credential                                                                                                          |
| x\_trans\_key        | string (max length: 32)          | Your Deposits API Passphrase, can be retrieved from the Merchant Panel by going to Settings -> API Access                                                      |                        |                                                                                                          Valid credential                                                                                                          |
| x\_invoice           | string (max length: 125)         | Deposit ID on your end                                                                                                                                         |                        |                                                                                                                                                                                                                                    |
| x\_document          | number (max length: 11)          | Deposit ID on Easy Cashouts API's end                                                                                                                          |                        |                                                                                                                                                                                                                                    |
| x\_amount            | decimal (max decimal numbers: 2) | The amount you want to refund. If none is sent, full deposit amount will be assumed                                                                            | full value             |                                                                                        Valid number equal or smaller than the deposit amount                                                                                       |
| x\_currency          | string (max length: 3)           | The currency used for the amount specified. If none is sent, the country local currency will be assumed                                                        | country local currency |                                                                  See the list of [currencies](https://docs.directa24.com/knowledge-base/countries-specifications)                                                                  |
| x\_bank\_beneficiary | string (max length: 100)         | Customer's name and lastname                                                                                                                                   |                        |                                                                                                                                                                                                                                    |
| x\_bank\_code        | string (max length: 45)          | Customer's bank code. Retrieve it by using [the Bank Codes API](https://docs.directa24.com/docs.directa24.com/api-reference/cashouts-api/banks/get-bank-codes) |                        |                                                                                                          Valid bank code.                                                                                                          |
| x\_bank              | string (max length: 45)          | Customer's bank name. This field is optional and used in the control string.                                                                                   |                        |                                                                                                                                                                                                                                    |
| x\_bank\_account     | string (max length: 45)          | Customer's bank account                                                                                                                                        |                        |                                                                                                                                                                                                                                    |
| x\_account\_type     | string (max lenght: 1)           | Customer's account type code                                                                                                                                   |                        | <p><strong>C:</strong> current accounts</p><p><strong>S:</strong> savings accounts</p><p><strong>V:</strong> salary accounts</p><p><strong>O:</strong> joint checking accounts</p><p><strong>P:</strong> joint savings account</p> |
| x\_bank\_branch      | string (max lenght: 15)          | Customer's bank branch                                                                                                                                         |                        |                                                                                                                                                                                                                                    |
| x\_control           | string (max length: 32)          | HMAC256 control signature                                                                                                                                      |                        |                                                                                                          See instructions                                                                                                          |
| x\_comments          | string (max lenght: 200)         | A comment for the refund                                                                                                                                       |                        |                                                                                                                                                                                                                                    |
| type                 | string (max length: 20)          | The format of the response. If none is specified JSON will be assumed                                                                                          | JSON                   |                                                                                                      **`[XML, JSON, STRING]`**                                                                                                     |

#### Request Control signature

The refund control signature (`x_control`) is an HMAC256 that encrypts the content of the request with your own `secretkey`. It must include the all the above fields and use empty ("") in case of an optional one is not sent:

* x\_invoice
* x\_document
* x\_amount
* x\_bank\_beneficiary
* x\_bank -> You can leave this empty if not send in the request.
* x\_bank\_account
* x\_account\_type
* x\_bank\_branch
* secretKey - your DEPOSIT API Signature which can be found in *Settings -> API Access*

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 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.

#### Code example: Request Control signature

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

```java
String message = "A" + x_invoice + x_document + x_amount + x_bank_beneficiary + x_bank + x_bank_account + x_account_type + x_bank_branch;
Mac hasher = Mac.getInstance("HmacSHA256");
hasher.init(new SecretKeySpec(secretKey.getBytes(), "HmacSHA256"));

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

```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
$message = 'A'. $x_invoice . $x_document. $x_amount . $x_bank_beneficiary . $x_bank . $x_bank_account . $x_account_type . $x_bank_branch;
$control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*', $secretKey)));
?>

```

{% endtab %}

{% tab title="C#" %}

```csharp
string message = "A" + x_invoice + x_document + x_amount + x_bank_beneficiary + x_bank + x_bank_account + x_account_type + x_bank_branch;
byte[] keyByte = new ASCIIEncoding().GetBytes(secretKey);
byte[] messageBytes = new ASCIIEncoding().GetBytes(message);
byte[] hashmessage = new HMACSHA256(keyByte).ComputeHash(messageBytes);

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

```

{% endtab %}
{% endtabs %}

### Response fields

| Field               | Description                                                                                |
| ------------------- | ------------------------------------------------------------------------------------------ |
| status              | Refund's status, can be **OK** or **ERROR**                                                |
| desc                | Response description: "Pending" / "Completed" / "Rejected" / "Cancelled" / error\_message. |
| control             | Control signature.                                                                         |
| result              | Refund's result                                                                            |
| x\_invoice          | Unique identification for the transaction in your end.                                     |
| x\_document         | Unique transaction's ID at Easy Cashouts API.                                              |
| x\_amount           | Refund's amount (same as the request).                                                     |
| x\_currency         | Refund's currency (same as the request).                                                   |
| x\_amount\_refunded | The refunded amount, in local currency.                                                    |
| x\_refund           | Unique refund's reference at Easy Cashouts API.                                            |
| error\_code         | Returned only when the status is **Error**                                                 |

####

#### Refund Status Codes

These are the **status** codes returned by the API.

| Code | Description                             |
| ---- | --------------------------------------- |
| 0    | Refund pending                          |
| 1    | Refund completed. Final status          |
| 2    | Refund canceled. Final status           |
| 3    | Refund rejected or failed. Final status |

####

#### **Response Control signature**

The refund response control signature (`x_control`) is an HMAC256 that encrypts the content of the request with your own `secretkey`. It must include the all the above fields and use empty ("") in case of an optional one is not sent:

* result
* x\_amount
* x\_currency
* x\_invoice
* x\_document
* x\_refund
* secretKey - your DEPOSIT API Signature which can be found in *Settings -> API Access*

The Control String for deposits response must be in Upper Case and must include all the above mentioned fields even if any of those are empty. 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.

**Code example: Response Control signature**

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

```java
String message = result + x_amount + x_currency + x_invoice + x_document + x_refund;
Mac hasher = Mac.getInstance("HmacSHA256");
hasher.init(new SecretKeySpec(secretKey.getBytes(), "HmacSHA256"));

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

```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
$message = $result . $x_amount. $x_currency . $x_invoice . $x_document .$x_refund;
$control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*', $secretKey)));
?>

```

{% endtab %}

{% tab title="C#" %}

```csharp
string message = result + x_amount + x_currency + x_invoice + x_document + x_refund;
byte[] keyByte = new ASCIIEncoding().GetBytes(secretKey);
byte[] messageBytes = new ASCIIEncoding().GetBytes(message);
byte[] hashmessage = new HMACSHA256(keyByte).ComputeHash(messageBytes);

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

```

{% endtab %}
{% endtabs %}


---

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