Deposit Creation Endpoint

post
https://api-stg.directa24.com
/api_curl/streamline/NewInvoice
Streamline Deposit Creation
All the requests must be in x-www-form-urlencoded format and contain the following header:
Content-Type: application/x-www-form-urlencoded
​
Example Request
cURL
PHP
JAVA
C#
1
curl -X POST \
2
    https://api-stg.directa24.com/api_curl/streamline/NewInvoice \
3
    -H 'Content-Type: application/x-www-form-urlencoded' \
4
    -d 'x_login=API_Key&x_trans_key=API_Passphrase&x_invoice=74170514&x_amount=10&x_iduser=userId123&x_bank=CA&x_cpf=63017363201&x_email=myemail%directa24.com&type=json&x_country=BR&x_name=Jonh%2BSmith&x_version=1.0&control=X_CONTROL'
5
    
6
    
Copied!
1
<?php
2
$curl = curl_init();
3
curl_setopt_array($curl, array(
4
  CURLOPT_URL => "https://api-stg.directa24.com/api_curl/streamline/NewInvoice",
5
  CURLOPT_RETURNTRANSFER => true,
6
  CURLOPT_ENCODING => "",
7
  CURLOPT_MAXREDIRS => 10,
8
  CURLOPT_TIMEOUT => 30,
9
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
10
  CURLOPT_CUSTOMREQUEST => "POST",
11
  CURLOPT_POSTFIELDS => "x_login=API_Key&x_trans_key=API_Passphrase&x_invoice=74170514&x_amount=10&x_iduser=userId123&x_bank=CA&x_cpf=63017363201&x_email=myemail%40directa24.com&type=json&x_country=BR&x_name=Jonh%2BSmith&x_version=1.0&control=X_CONTROL",
12
  CURLOPT_HTTPHEADER => array(
13
    "Content-Type: application/x-www-form-urlencoded"
14
  ),
15
));
16
$response = curl_exec($curl);
17
$err = curl_error($curl);
18
curl_close($curl);
19
​
Copied!
1
OkHttpClient client = new OkHttpClient();
2
MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
3
RequestBody body = RequestBody.create(mediaType, "x_login=API_Key&x_trans_key=API_Passphrase&x_invoice=74170514&x_amount=10&x_iduser=userId123&x_bank=CA&x_cpf=63017363201&x_email=myemail%40directa24.com&type=json&x_country=BR&x_name=Jonh%2BSmith&x_version=1.0&control=X_CONTROL");
4
Request request = new Request.Builder()
5
 .url("https://api-stg.directa24.com/api_curl/streamline/NewInvoice")
6
 .post(body)
7
 .addHeader("Content-Type", "application/x-www-form-urlencoded")
8
 .build();
9
Response response = client.newCall(request).execute();
10
 
Copied!
1
var client = new RestClient("https://api-stg.directa24.com/api_curl/streamline/NewInvoice");
2
var request = new RestRequest(Method.POST);
3
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
4
request.AddParameter("application/x-www-form-urlencoded", "x_login=API_Key&x_trans_key=API_Passphrase&x_invoice=74170514&x_amount=10&x_iduser=userId123&x_bank=CA&x_cpf=63017363201&x_email=myemail%40directa24.com&type=json&x_country=BR&x_name=Jonh%2BSmith&x_version=1.0&control=X_CONTROL", ParameterType.RequestBody);
5
IRestResponse response = client.Execute(request);
6
​
7
​
Copied!
​
Example Response
Success Response v1.0
Error Response v1.0
Success Response v1.1
Error Response v1.1
1
{
2
    "status": "0",
3
    "link": "[Link to redirect the customer]"
4
}
Copied!
1
{
2
    "status": "1",
3
    "desc": "[Error description]"
4
}
5
​
6
{
7
    "status": "1",
8
    "desc": "Payment method not found",
9
    "error_code": "506"
10
}
Copied!
1
{
2
    "status": "0",
3
    "link": "[Link to redirect the user]",
4
    "local_amount": "[local amount]",
5
    "usd_amount": "[Amount in usd]",
6
    "local_currency": "[Local currency]",
7
    "x_document": "[Reference of the transaction on Directa24's side]",
8
    "amount_to_deposit": "[Amount to deposit]"
9
}
Copied!
1
{
2
    "status": "1",
3
    "desc": "[Error description]",
4
    "error_code": "[Error code]"
5
}
6
​
7
{
8
    "status": "1",
9
    "desc": "x_cpf: must not be blank",
10
    "error_code": "300"
11
}
Copied!
​
Mandatory fields description
Field
Format
Description
x_login
string (max length: 32)
Your Directa24 DEPOSITS API Key, found on the Merchant Panel by going to Settings -> API Access -> Deposit Credentials -> API Key
x_trans_key
string (max length: 32)
Your Directa24 DEPOSITS API Passphrase, found on the Merchant Panel by going to Settings -> API Access -> Deposit Credentials -> API Passphrase
x_invoice
string (max length: 125)
Unique identification for the transaction in your end
x_amount
decimal (max decimal numbers: 2)
Transaction's amount in the currency specified in the “x_currency” field (if none is sent USD will be assumed)
x_country
string (max length: 2)
User’s country. Click here to see country codes.
x_bank
string (max length: 3)
Payment method code. To check the available Payment Methods for your account, you can use the Payment Methods Endpoint​
x_iduser
number (max digits: 11)
Unique user's ID in your side
x_cpf
String (max digits: 30)
User’s personal identification number. Click here to see the type of documents and its validations
x_name
string (max length: 100)
User’s full name (name and lastname)
x_email
string (max length: 100)
User’s valid email address
x_return
string (max length: 200)
URL specified to redirect the customers once they finish the deposits. It has to be a valid URL over HTTPS. See Return URL​
control
string (max length: 32)
Control string encoded using HMAC-SHA-256 (RFC 2104) to ensure integrity. Instructions below​
​
Optional fields description
Field
Format
Description
x_mobile
string (max length: 20)
User’s mobile number. Mandatory for Colombia and the African countries
x_currency
string (max length: 3)
Transaction currency in ISO 4217. If not sent, USD will be assumed. Click here to see available currencies per country.
x_version
number
API version. If none is specified 1.0 will be assumed. Version 1.1 includes additional information in the response (see examples responses)
x_description
string (max length: 200)
Transaction's description of the product/service
x_bdate
string (max length: 8)
User’s birth date using the format: YYYYMMDD
x_payer_registration_date
string (max length: 8)
User’s registration date on your website using the format: YYYYMMDD
x_address
string (max length: 255)
User’s address. Mandatory for BR (Brazil) and CO (Colombia)
x_zip
string (max length: 10)
User’s zip/postal code. Mandatory for BR (Brazil). Click here to see zip code validations.
x_city
string (max length: 100)
User’s city
x_state
string (max length: 20)
User’s state ISO 3166-2 code. Mandatory for BR (Brazil). Click here to see codes
x_confirmation
string (max length: 200)
Should be provided if the confirmation URL needs to be different from the one registered in your panel settings. See Confirmation URL​
type
string (max length: 20)
The format of the response: JSON, XML or STRING. If none is specified XML will be assumed.
iframe_view
boolean
Used to determine if should be returned an iframe view.
​
Control String for Deposits
​
Example: Control String for New Invoice API
PHP
JAVA
C#
1
<?php
2
   $apiSignature = 'your_deposits_API_Signature';
3
   $message = $x_invoice .'V' . $x_amount .'I' . $x_iduser .'2' . $x_bank .'1' . $x_cpf .'H' . $x_bdate .'G' . $x_email .'Y' . $x_zip .'A' . $x_address .'P' . $x_city .'S' . $x_state . 'P';
4
   $control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*', $apiSignature)));
5
?>
6
​
7
​
Copied!
1
String apiSignature = "your_deposits_API_Signature";
2
String message = x_invoice + "V" + x_amount + "I" + x_iduser + "2" + x_bank + "1" + x_cpf + "H" + x_bdate + "G" + x_email + "Y" + x_zip + "A" + x_address + "P" + x_city + "S" + x_state + "P";
3
Mac hasher = Mac.getInstance("HmacSHA256");
4
hasher.init(new SecretKeySpec(apiSignature.getBytes(), "HmacSHA256"));
5
​
6
String control = Base64.encodeBase64String(hasher.doFinal(message.getBytes())).toUpperCase();
7
​
8
​
Copied!
1
string apiSignature = "your_deposits_API_Signature";
2
string message = x_invoice + "V" + x_amount + "I" + x_iduser + "2" + x_bank + "1" + x_cpf + "H" + x_bdate + "G" + x_email + "Y" + x_zip + "A" + x_address + "P" + x_city + "S" + x_state + "P";
3
byte[] keyByte = new ASCIIEncoding().GetBytes(apiSignature);
4
byte[] messageBytes = new ASCIIEncoding().GetBytes(message);
5
byte[] hashmessage = new HMACSHA256(keyByte).ComputeHash(messageBytes);
6
​
7
string control = BitConverter.ToString(hashmessage).Replace("-", "").ToUpper();
8
​
9
​
Copied!
The x_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
x_bank
x_cpf
x_bdate
x_email
x_zip
x_address
x_city
x_state
secretKey - your DEPOSITS API Signature which can be found on the Merchant Panel by going to Settings -> API Access -> Deposit Credentials -> API Signature
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 has to 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 above in the different languages on how to properly calculate the Control String.
​
Return URL
Once the customer finishes his deposit, he will be redirected back to your site using the return URL (x_return parameter) specified as part of the New Invoice request OR the one registered in your panel settings (Settings -> API Access). We only accept HTTPS URLs. The redirect is made using POST protocol with the following parameters:
Field
Description
result
Transaction result. See: Api Codes​
x_invoice
Unique identification for the transaction in your end
x_iduser
Unique user ID in your side
x_description
Transaction's description
x_document
Unique transaction's ID at Directa24
x_amount
Payment's amount
x_control
Control signature. Used to verify the parameters weren't modified while in transit
Never update the status of a payment by using the result sent along with the Return URL. This shows where in the payment flow the user left the payment page. Always expect the notification/check the deposit status to update the status of a payment.
Control String for Return URL
Example: Return Redirection - control signature
PHP
JAVA
C#
1
<?php
2
   $apiSignature = 'your_deposits_API_Signature';
3
   $message = $x_login . $result . $x_amount . $x_invoice ;
4
   $control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*', $apiSignature)));
5
?>
6
​
7
​
Copied!
1
String message = x_login + result +  x_amount + x_invoice;
2
String apiSignature = "your_deposits_API_Signature";
3
Mac hasher = Mac.getInstance("HmacSHA256");
4
hasher.init(new SecretKeySpec(apiSignature.getBytes(), "HmacSHA256"));
5
​
6
String control = Base64.encodeBase64String(hasher.doFinal(message.getBytes())).toUpperCase();
7
​
8
​
Copied!
1
string apiSignature = "your_deposits_API_Signature";
2
string message = x_login + result +  x_amount + x_invoice;
3
byte[] keyByte = new ASCIIEncoding().GetBytes(apiSignature);
4
byte[] messageBytes = new ASCIIEncoding().GetBytes(message);
5
byte[] hashmessage = new HMACSHA256(keyByte).ComputeHash(messageBytes);
6
​
7
string control = BitConverter.ToString(hashmessage).Replace("-", "").ToUpper();
8
​
9
​
Copied!
The return URL control signature includes the following fields:
x_login - your Directa24 DEPOSITS API login which can be found on the Merchant Panel by going to Settings -> API Access -> Deposit Credentials -> API Key
result
x_amount
x_invoice
secretKey - your Directa24 DEPOSITS API Signature which can be found on the Merchant Panel by going to Settings -> API Access -> Deposit Credentials -> API Signature
​
Confirmation URL
A notification will be sent to your confirmation URL every time the deposit changes its status by using the x_confirmation parameter specified as part of the New Invoice request or the one registered in your Merchant Panel settings (Settings -> API Access). It is made using POST protocol with the following parameters:
Field
Description
result
Transaction result. See possible result codes​
x_invoice
Unique identification for the transaction in your end
x_iduser
Unique user ID in your side
x_description
Transaction's description
x_document
Unique transaction's ID at Directa24
x_bank
Payment method code. See Payment methods​
x_payment_type
Payment type. See payment types​
x_bank_name
Payment method name. See Payment methods​
x_amount
Payment amount
x_currency
Payment currency in ISO 4217
x_control
Control signature
​
In the STG environment, you can force a notification to be sent to your x_confirmation URL from the STG Merchant Panel by going to the Deposits Details page and clicking on one of the options that will appear when clicking in the three dots button on the top right of the screen. Those options will change the status of the deposit therefore sending the respective notification after a few minutes.
How to manually Approve/Cancel a deposit in STG to test notifications
​
Control String for Confirmation URL
Example: Confirmation Url - control signature
PHP
JAVA
C#
1
<?php
2
   $apiSignature = 'your_deposits_API_Signature';
3
   $message = $x_login . $result . $x_amount . $x_invoice ;
4
   $control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*', $apiSignature)));
5
?>
6
​
7
​
Copied!
1
String message = x_login + result +  x_amount + x_invoice;
2
String apiSignature = "your_deposits_API_Signature";
3
Mac hasher = Mac.getInstance("HmacSHA256");
4
hasher.init(new SecretKeySpec(apiSignature.getBytes(), "HmacSHA256"));
5
​
6
String control = Base64.encodeBase64String(hasher.doFinal(message.getBytes())).toUpperCase();
7
​
8
​
Copied!
1
string message = x_login + result +  x_amount + x_invoice;
2
string apiSignature = "your_deposits_API_Signature";
3
byte[] keyByte = new ASCIIEncoding().GetBytes(apiSignature);
4
byte[] messageBytes = new ASCIIEncoding().GetBytes(message);
5
byte[] hashmessage = new HMACSHA256(keyByte).ComputeHash(messageBytes);
6
​
7
string control = BitConverter.ToString(hashmessage).Replace("-", "").ToUpper();
8
​
9
​
Copied!
The confirmation URL control signature includes the following fields:
x_login - your DEPOSITS API Key which can be found on the Merchant Panel by going to Settings -> API Access -> Deposit Credentials -> API Key
result
x_amount
x_invoice
secretKey - your  DEPOSITS API Signature which can be found on the Merchant Panel by going to Settings -> API Access -> Deposit Credentials -> API Signature
In some cases may occur that you will receive a Cancelled notification for a transaction and following a Completed notification for the same transaction. This happens if we were unable to automatically detect the Deposit (because the user paid a different amount or after it got expired) and the transaction reached its expiration time. Once our team manually approves it, we change the status from Cancelled to Completed.
​
Both the Return URL and the Confirmation URL can be defined by default in your panel (Settings -> API Access). These parameters can be over-ridden at any time using the x_return and x_confirmation parameters (however, these new urls are only active for that particular invoice, following invoice will use the default URLs previously configured if not sent again).
​
Iframes
It is possible to display an iframe on your website instead of redirecting your customer with an external window.
In order to do this, you need to insert an <iframe> tag on your website. In the src attribute you must set the link: [link to redirect the user] parameter from success response and append the following GET parameter "iframe_view=1" to the link as shown below:
1
<iframe src="[link to redirect the user]&iframe_view=1"> </iframe>
Copied!
Some Payment Methods may not be available within an iframe due to processor´s security requirements. Check here the available ones.