Refund Creation Endpoint

Create refunds requests from a completed deposit

Refund Creation Endpoint

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

200 Refund successfully created.

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

All the requests must be in x-www-form-urlencoded format and contain the following header:

Content-Type: application/x-www-form-urlencoded

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
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		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		C: current accounts S: savings accounts V: salary accounts O: joint checking accounts P: joint savings account
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

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();
   
   

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)));
?>

C#

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();

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

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();

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)));
?>

C#

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();