---
description: Create refunds requests from a completed deposit
---

# Refund Creation Endpoint

## 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 D24'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": "28F11DB2C7F4E3D1A1563C642AF8712EABE7E25540D36C8285887D3477107EA8",
  "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 D24'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/specifications/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/cashouts-api/cashout-api-v3/endpoints/cashout-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></p><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.&#x20;
* 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 D24.                                                            |
| 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 D24.                                                          |
| 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 %}

