Deposit Creation Endpoint

Learn how to generate deposits by using the Streamline API

Streamline Deposit Creation

POST https://api-stg.directa24.com/api_curl/streamline/NewInvoice

The New Invoice API creates a new Deposit transaction and returns a URL to redirect the customer to his preferred payment method's page, where the payment can be confirmed.

Headers

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

Request Body

Name	Type	Description
x_login	string	Your D24 DEPOSITS API Key, found on the Merchant Panel by going to Settings -> API Access -> Deposit Credentials
x_trans_key	string	Your D24 DEPOSITS API Passphrase, found on the Merchant Panel by going to Settings -> API Access -> Deposit Credentials
x_invoice	string	Unique identification for the transaction in your end
x_amount	number	Transaction's amount in the currency specified in the field “x_currency” (if none is sent USD will be assumed)
x_country	string	User's country ISO Code
x_bank	string	Payment method code
x_iduser	string	Unique user ID in your side
x_cpf	string	User’s personal identification number
x_name	string	User’s full name (name and lastname)
x_email	string	User's valid email address
x_return	string	URL specified to redirect the customers once they finish the deposits. It has to be a valid URL over HTTPS
control	string	Control string encoded using HMAC-SHA-256 (RFC 2104) to ensure integrity
x_mobile	string	User’s mobile phone number
x_confirmation	string	URL used to receive notifications. Should be provided if the confirmation URL needs to be different from the one registered in your panel settings
x_currency	string	Transaction currency in ISO 4217. If not sent, USD will be assumed.
x_description	string	Description of the product/service
x_bdate	string	User’s birth date using the format: YYYYMMDD
x_address	string	User's address
x_zip	string	User's zip/postal code
x_city	string	User's city
x_state	string	User's state ISO code
x_version	string	API version. If none is specified 1.0 will be assumed. Version 1.1 includes additional information in the response
type	string	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

200 Success Response

v1.0

{
  "status": "0",
  "link": "[Link to redirect the customer]"
}

v1.1

{
  "status": "0",
  "link": "[Link to redirect the user]",
  "local_amount": "[local amount]",
  "usd_amount": "[Amount in usd]",
  "local_currency": "[Local currency]",
  "x_document": "[Reference of the transaction on Directa24's side]",
  "amount_to_deposit": "[Amount to deposit]"
}

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

curl -X POST \
    https://api-stg.directa24.com/api_curl/streamline/NewInvoice \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -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%40d24.com&type=json&x_country=BR&x_name=Jonh%2BSmith&x_version=1.0&control=X_CONTROL'
    
    

PHP

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-stg.directa24.com/api_curl/streamline/NewInvoice",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  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%40d24.com&type=json&x_country=BR&x_name=Jonh%2BSmith&x_version=1.0&control=X_CONTROL",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/x-www-form-urlencoded"
  ),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);

JAVA

OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
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%40d24.com&type=json&x_country=BR&x_name=Jonh%2BSmith&x_version=1.0&control=X_CONTROL");
Request request = new Request.Builder()
 .url("https://api-stg.directa24.com/api_curl/streamline/NewInvoice")
 .post(body)
 .addHeader("Content-Type", "application/x-www-form-urlencoded")
 .build();
Response response = client.newCall(request).execute();
 

C#

var client = new RestClient("https://api-stg.directa24.com/api_curl/streamline/NewInvoice");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
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%40d24.com&type=json&x_country=BR&x_name=Jonh%2BSmith&x_version=1.0&control=X_CONTROL", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Example Response

Success Response v1.0

{
    "status": "0",
    "link": "[Link to redirect the customer]"
}

Error Response v1.0

{
    "status": "1",
    "desc": "[Error description]"
}

{
    "status": "1",
    "desc": "Payment method not found",
    "error_code": "506"
}

Success Response v1.1

{
    "status": "0",
    "link": "[Link to redirect the user]",
    "local_amount": "[local amount]",
    "usd_amount": "[Amount in usd]",
    "local_currency": "[Local currency]",
    "x_document": "[Reference of the transaction on Directa24's side]",
    "amount_to_deposit": "[Amount to deposit]"
}

Error Response v1.1

{
    "status": "1",
    "desc": "[Error description]",
    "error_code": "[Error code]"
}

{
    "status": "1",
    "desc": "x_cpf: must not be blank",
    "error_code": "300"
}

Mandatory fields description

Field	Format	Description
x_login	string (max length: 32)	Your D24 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 D24 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 in UTC 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

<?php
   $apiSignature = 'your_deposits_API_Signature';
   $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';
   $control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*', $apiSignature)));
?>

JAVA

String apiSignature = "your_deposits_API_Signature";
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";
Mac hasher = Mac.getInstance("HmacSHA256");
hasher.init(new SecretKeySpec(apiSignature.getBytes(), "HmacSHA256"));

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

C#

string apiSignature = "your_deposits_API_Signature";
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";
byte[] keyByte = new ASCIIEncoding().GetBytes(apiSignature);
byte[] messageBytes = new ASCIIEncoding().GetBytes(message);
byte[] hashmessage = new HMACSHA256(keyByte).ComputeHash(messageBytes);

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

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

<?php
   $apiSignature = 'your_deposits_API_Signature';
   $message = $x_login . $result . $x_amount . $x_invoice ;
   $control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*', $apiSignature)));
?>

JAVA

String message = x_login + result +  x_amount + x_invoice;
String apiSignature = "your_deposits_API_Signature";
Mac hasher = Mac.getInstance("HmacSHA256");
hasher.init(new SecretKeySpec(apiSignature.getBytes(), "HmacSHA256"));

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

C#

string apiSignature = "your_deposits_API_Signature";
string message = x_login + result +  x_amount + x_invoice;
byte[] keyByte = new ASCIIEncoding().GetBytes(apiSignature);
byte[] messageBytes = new ASCIIEncoding().GetBytes(message);
byte[] hashmessage = new HMACSHA256(keyByte).ComputeHash(messageBytes);

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

The return URL control signature includes the following fields:

• x_login - your D24 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 D24 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 D24's end
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

<?php
   $apiSignature = 'your_deposits_API_Signature';
   $message = $x_login . $result . $x_amount . $x_invoice ;
   $control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*', $apiSignature)));
?>

JAVA

String message = x_login + result +  x_amount + x_invoice;
String apiSignature = "your_deposits_API_Signature";
Mac hasher = Mac.getInstance("HmacSHA256");
hasher.init(new SecretKeySpec(apiSignature.getBytes(), "HmacSHA256"));

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

C#

string message = x_login + result +  x_amount + x_invoice;
string apiSignature = "your_deposits_API_Signature";
byte[] keyByte = new ASCIIEncoding().GetBytes(apiSignature);
byte[] messageBytes = new ASCIIEncoding().GetBytes(message);
byte[] hashmessage = new HMACSHA256(keyByte).ComputeHash(messageBytes);

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

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:

<iframe src="[link to redirect the user]&iframe_view=1"> </iframe>

Some Payment Methods may not be available within an iframe due to processor´s security requirements. Check here the available ones.