Refund Creation Endpoint
Create refunds requests from a completed deposit
post
https://api-stg.directa24.com
/api_curl/apd/refund
Refund Creation Endpoint
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 Directa24'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
x_bank_beneficiary
string (max length: 100)
Customer's name and lastname
x_bank_code
string (max length: 45)
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
PHP
C#
1
String message = "A" + x_invoice + x_document + x_amount + x_bank_beneficiary + x_bank + x_bank_account + x_account_type + x_bank_branch;
2
Mac hasher = Mac.getInstance("HmacSHA256");
3
hasher.init(new SecretKeySpec(secretKey.getBytes(), "HmacSHA256"));
4
5
String control = Base64.encodeBase64String(hasher.doFinal(message.getBytes())).toUpperCase();
6
7
Copied!
1
<?php
2
$message = 'A'. $x_invoice . $x_document. $x_amount . $x_bank_beneficiary . $x_bank . $x_bank_account . $x_account_type . $x_bank_branch;
3
$control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*', $secretKey)));
4
?>
5
6
Copied!
1
string message = "A" + x_invoice + x_document + x_amount + x_bank_beneficiary + x_bank + x_bank_account + x_account_type + x_bank_branch;
2
byte[] keyByte = new ASCIIEncoding().GetBytes(secretKey);
3
byte[] messageBytes = new ASCIIEncoding().GetBytes(message);
4
byte[] hashmessage = new HMACSHA256(keyByte).ComputeHash(messageBytes);
5
6
string control = BitConverter.ToString(hashmessage).Replace("-", "").ToUpper();
7
8
Copied!
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 Directa24.
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 Directa24.
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
PHP
C#
1
String message = result + x_amount + x_currency + x_invoice + x_document + x_refund;
2
Mac hasher = Mac.getInstance("HmacSHA256");
3
hasher.init(new SecretKeySpec(secretKey.getBytes(), "HmacSHA256"));
4
5
String control = Base64.encodeBase64String(hasher.doFinal(message.getBytes())).toUpperCase();
6
7
Copied!
1
<?php
2
$message = $result . $x_amount. $x_currency . $x_invoice . $x_document .$x_refund;
3
$control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*', $secretKey)));
4
?>
5
6
Copied!
1
string message = result + x_amount + x_currency + x_invoice + x_document + x_refund;
2
byte[] keyByte = new ASCIIEncoding().GetBytes(secretKey);
3
byte[] messageBytes = new ASCIIEncoding().GetBytes(message);
4
byte[] hashmessage = new HMACSHA256(keyByte).ComputeHash(messageBytes);
5
6
string control = BitConverter.ToString(hashmessage).Replace("-", "").ToUpper();
7
8
Copied!
Last modified 8mo ago