Deposit Creation Endpoint

Hybrid Deposit Creation

POST https://api-stg.directa24.com/api_curl/apd/create

The Hybrid API creates a URL to redirect the customers to our Hosted Checkout where they need to fill in the required details before proceeding with the payment

Headers

Name Type Description

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

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_iduser	string	Unique user ID in your side
x_amount	number	Deposit amount
x_country	string	Deposit country code ISO 3166-1 alpha-2
control	string	Deposit control string encoded using HMAC-SHA-256 (RFC 2104). Used to verify request integrity
x_currency	string	Deposit currency in ISO 4217. If not sent, USD will be assumed
x_bank	string	Payment method code. If not sent the customer will be able to select on on our Hosted Checkout
cpf	string	Customer national document ID
x_name	string	Customer full name (name and last name)
x_email	string	Customer valid email address
type	string	The format of the response: XML or JSON. If none is specified, XML will be assumed
x_logo	string	URL pointing to your logo to show on our Hosted Checkout
x_return	string	URL where you would like to redirect the customers once they finish the deposits. It has to be a valid URL over HTTPS
x_confirm	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. It has to be a valid URL over HTTPS
x_description	string	Description of the product/service offered

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_iduser

string

Unique user ID in your side

x_amount

number

Deposit amount

x_country

string

Deposit country code ISO 3166-1 alpha-2

control

string

Deposit control string encoded using HMAC-SHA-256 (RFC 2104). Used to verify request integrity

x_currency

string

Deposit currency in ISO 4217. If not sent, USD will be assumed

x_bank

string

Payment method code. If not sent the customer will be able to select on on our Hosted Checkout

cpf

string

Customer national document ID

x_name

string

Customer full name (name and last name)

x_email

string

Customer valid email address

type

string

The format of the response: XML or JSON. If none is specified, XML will be assumed

x_logo

string

URL pointing to your logo to show on our Hosted Checkout

x_return

string

URL where you would like to redirect the customers once they finish the deposits. It has to be a valid URL over HTTPS

x_confirm

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. It has to be a valid URL over HTTPS

x_description

string

Description of the product/service offered

{
    "status": "OK",
    "link": "https://payin-stg.directa24.com/validate/exampleEDQ7EUuBGdItCvQsYcphwBYFuPIV1lLM"
}

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 -X POST \
    https://api-stg.directa24.com/api_curl/apd/create \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'x_login=DEPOSITS_API_KEY&x_trans_key=DEPOSITS_X_PASSPHRASE&x_invoice=ID12345&x_amount=100&x_iduser=123456&x_country=BR&control=18F7889C2D4D9E9A21ABF2EBB4038322D60028DE949FB2DA2A4BB91AFB67D5CF&type=json'

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-stg.directa24.com/api_curl/apd/create",
  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=DEPOSITS_API_KEY&x_trans_key=DEPOSITS_X_PASSPHRASE&x_invoice=ID12345&x_amount=100&x_iduser=123456&x_country=BR&control=18F7889C2D4D9E9A21ABF2EBB4038322D60028DE949FB2DA2A4BB91AFB67D5CF&type=json",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/x-www-form-urlencoded"
  ),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);

OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(mediaType, "x_login=DEPOSITS_API_KEY&x_trans_key=DEPOSITS_X_PASSPHRASE&x_invoice=ID12345&x_amount=100&x_iduser=123456&x_country=BR&control=18F7889C2D4D9E9A21ABF2EBB4038322D60028DE949FB2DA2A4BB91AFB67D5CF&type=json");
Request request = new Request.Builder()
 .url("https://api-stg.directa24.com/api_curl/apd/create")
 .post(body)
 .addHeader("Content-Type", "application/x-www-form-urlencoded")
 .build();
Response response = client.newCall(request).execute();

var client = new RestClient("https://api-stg.directa24.com/api_curl/apd/create");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
request.AddParameter("x_login=DEPOSITS_API_KEY&x_trans_key=DEPOSITS_X_PASSPHRASE&x_invoice=ID12345&x_amount=100&x_iduser=123456&x_country=BR&control=18F7889C2D4D9E9A21ABF2EBB4038322D60028DE949FB2DA2A4BB91AFB67D5CF&type=json", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Request fields description

Field Mandatory Format Description

Field	Mandatory	Format	Description
`x_login`	Yes	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`	Yes	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`	Yes	string (max length: 125)	Unique identification for the deposit transaction in your side. It will also be used to retrieve the status of the transaction
`x_iduser`	Yes	number (max digits: 125)	Unique customer ID in your side
`x_amount`	Yes	decimal (up to 10 digits with up to 4 decimals)	Deposit amount in the currency specified with the field `x_currency` (defaults to USD)
`x_country`	Yes	string (max length: 2)	Customer’s country ISO 3166-1 alpha-2 code. Click here to see country codes
`control`	Yes	string (max length: 32)	Control string encoded using HMAC-SHA-256 (RFC 2104) to ensure request´s integrity. Click here for instructions
`x_currency`	No	string (max length: 3)	Currency in which the amount will be specified. Click here to see the available currencies per country
`x_bank`	No	string (max length: 3)	Payment method code (see Payment Methods). To check the available Payment Methods for your account, you can use the get_banks_by_country API
`cpf`	No	String (max digits: 30)	Customer personal identification number. Click here to see the validations
`x_name`	No	string (max length: 50)	Customer full name (name and last name)
`x_email`	No	string (max length: 100)	Customer valid email address. Click here to see email validations
`type`	No	string (max length: 20)	The format of the response: XML or JSON. If none is specified XML will be assumed.
`x_logo`	No	string (URL) (max length: 200)	Your company´s logo to show in our check-in page
`x_return`	No	string (URL) (max length: 200)	URL where you would like to redirect the customers once they finish the deposits. It has to be a valid URL over HTTPS (I.e.: https://www.d24.com). See Return URL
`x_confirm`	No	string (URL) (max length: 200)	URL specified where we will send the deposit notifications. It has to be a valid URL over HTTPS (I.e.: https://www.d24.com/notify). See Notifications
`x_description`	No	string (max length: 200)	Description of the transaction

x_login

Yes

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

Yes

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

Yes

string (max length: 125)

Unique identification for the deposit transaction in your side. It will also be used to retrieve the status of the transaction

x_iduser

Yes

number (max digits: 125)

Unique customer ID in your side

x_amount

Yes

decimal (up to 10 digits with up to 4 decimals)

Deposit amount in the currency specified with the field x_currency (defaults to USD)

x_country

Yes

string (max length: 2)

Customer’s country ISO 3166-1 alpha-2 code. Click here to see country codes

control

Yes

string (max length: 32)

Control string encoded using HMAC-SHA-256 (RFC 2104) to ensure request´s integrity. Click here for instructions

x_currency

string (max length: 3)

Currency in which the amount will be specified. Click here to see the available currencies per country

x_bank

string (max length: 3)

Payment method code (see Payment Methods). To check the available Payment Methods for your account, you can use the get_banks_by_country API

cpf

String (max digits: 30)

Customer personal identification number. Click here to see the validations

x_name

string (max length: 50)

Customer full name (name and last name)

x_email

string (max length: 100)

Customer valid email address. Click here to see email validations

type

string (max length: 20)

The format of the response: XML or JSON. If none is specified XML will be assumed.

x_logo

string (URL) (max length: 200)

Your company´s logo to show in our check-in page

x_return

string (URL) (max length: 200)

URL where you would like to redirect the customers once they finish the deposits. It has to be a valid URL over HTTPS (I.e.: https://www.d24.com). See Return URL

x_confirm

string (URL) (max length: 200)

URL specified where we will send the deposit notifications. It has to be a valid URL over HTTPS (I.e.: https://www.d24.com/notify). See Notifications

x_description

string (max length: 200)

Description of the transaction

Optional fields

When you use the Hybrid API, you can opt for sending only the mandatory fields. However, when the customers gets into our Hosted Checkout, we will ask them to input the missing information. If you send the x_cpf, x_name, and x_email fields, the information will be automatically populated onto the Checkout page and therefore, the customers wont have to manually insert it nor will be able to modify it. This is extremely useful when you already have that details on your database.

Your logo (x_logo) can be defined by default in the Merchant Panel by submitting one into Settings -> Company -> "Merchant Payment Page Logo". Otherwise, you can replace it on each request by sending a URL with your logo in the field x_logo.

Both the Return URL (x_return) and the Confirmation URL (x_confirm) are defined by default in your Merchant Panel by going to Settings -> API Access. These parameters can be over-ridden at any time using the x_return and x_confirm parameters in the deposit request.

Control String for the Hybrid API requests

<?php
   $apiSignature = 'your_deposits_api_signature';
   $message = $x_invoice .'D' . $x_amount .'P' . $x_iduser .'A';

   $control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*', $apiSignature)));
?>

String apiSignature = "your_deposits_api_signature";
String message = x_invoice + "D" + x_amount + "P" + x_iduser + "A";
Mac hasher = Mac.getInstance("HmacSHA256");
hasher.init(new SecretKeySpec(apiSignature.getBytes(), "HmacSHA256"));

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

string apiSignature = "your_deposits_api_signature";
string message = x_invoice + "D" + x_amount + "P" + x_iduser + "A";
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 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
secretKey - your D24 DEPOSITS API Signature, found on the Merchant Panel by going to Settings -> API Access -> Deposit Credentials -> API Signature

The Control String for the Hybrid API must be in Upper Case and must include all the above mentioned fields. 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.

Example Response

{
    "status": "OK",
    "link": "https://payin-stg.directa24.com/validate/exampleEDQ7EUuBGdItCvQsYcphwBYFuPIV1lLM"
}

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

{
    "status": "ERROR",
    "desc": "x_amount: wrong argument type"
}

Check Status

Once you redirect your customers to our Hosted Checkout page, they will complete all the details and click on Confirm details. If everything is OK, the transaction will remain in Pending status until we detect the customers payment. Once detected, the transaction will be changed to Completed state or if the user never pays it will expire and be updated to Cancelled state.

As soon as the user comes back to your Return URL, a POST request will come along with it with the details of the request as shown in the code snippet "Example: POST to the Return URL" below.

Example: POST to the Return URL

{
    "x_document": "94581245",
    "x_invoice": "test8385",
    "x_iduser": "1342133413",
    "x_description": "",
    "x_amount": "100.00",
    "x_amount_usd": "100.00",
    "result": "7",
    "x_parent_invoice": "",
    "x_control": "225A6B7EC24E049E9A7D8EE622F7F08ED6B4551A1A6E99CE231759D8694FAC99"
}

Control String for the POST to the Return URL

<?php
    $api_key = 'your_deposits_api_key';
    $x_result = 'notification_x_result';
    $x_amount = 'notification_x_amount';
    $x_invoice = 'notification_x_invoice';
    $api_signature = 'your_deposits_api_signature';

    $message = $x_login . $x_result . $x_amount . $x_invoice;
    $control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*', $api_signature)));
?>

String api_key = "your_deposits_api_key";
String x_result = "notification_x_result";
String x_amount = "notification_x_amount";
String x_invoice = "notification_x_invoice";
String api_signature = "your_deposits_api_signature";

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

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

string api_key = "your_deposits_api_key";
string x_result = "notification_x_result";
string x_amount = "notification_x_amount";
string x_invoice = "notification_x_invoice";
string api_signature = "your_deposits_api_signature";

string message = x_login + x_result + x_amount + x_invoice;
byte[] keyByte = new ASCIIEncoding().GetBytes(api_signature);
byte[] messageBytes = new ASCIIEncoding().GetBytes(message);
byte[] hashmessage = new HMACSHA256(keyByte).ComputeHash(messageBytes);

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

The x_control field we sent in the notification, is used to ensure request integrity. It should be created using HMAC-SHA-256 (RFC 2104) encoding and must include ONLY the following fields:

x_login - your D24 DEPOSITS API Key, found on the Merchant Panel by going to Settings API Access -> Deposit Credentials -> API Key
x_result
x_amount
x_invoice
secretKey - your D24 DEPOSITS API Signature, found on the Merchant Panel by going to Settings -> API Access -> Deposit Credentials -> API Signature

The Control String for the POST of the Return URL Hybrid API must be in Upper Case and must include all the above mentioned fields. 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.

Webpaystatus API

Example: webpaystatus API´s response in Pending status

{
    "result": "7",
    "x_iduser": "123456",
    "x_invoice": "test9417",
    "x_amount": "100.00",
    "PT": "0",
    "Sign": "EB2619F51E2730F59E742E6DC2AE692FE98B7141A0578259A0B5C5E74159AFD3",
    "x_document": "192170814",
    "x_bank": "MC",
    "x_payment_type": "03",
    "x_bank_name": "Mastercard",
    "x_currency": "USD"
}

{
    "result": "6",
    "x_iduser": "0",
    "x_invoice": "test9417z",
    "x_amount": "0",
    "PT": "0",
    "Sign": "691332E815899FF50610C30D58E930FF6E5D8001458CD0790A5F468B29F712A8",
    "x_document": "-1",
    "x_bank": " ",
    "x_payment_type": "0",
    "x_bank_name": " ",
    "x_currency": " "
}

If the user fails to be redirected to your return_url, you wont be notified about the transaction in Pending state until it changes to either "Completed" or "Cancelled". Therefore, after some minutes (recommended 5 minutes) of the requests being created, you can opt to use the Deposit Status API to check whether the transaction was created and left Pending on our end. That would happen only if the customer finished the flow on the Hosted Checkout page and was redirected to the Payment Method page to deposit.

If the transaction was created, when you check its status with the Deposit Status API, you will receive a response with "result": "7" along with other details about the transaction. Result 7 means "Transaction Pending, awaiting customer's deposit". If the transaction was never created, be it because the user inserted incorrect data or they have never completed the flow, when you use the Deposit Status API you will receive a response with "result": "6" meaning "Transaction not found on the system". Feel free to check its status again after some more time in case the user is delayed.

Click here for all the results code meanings.

Notifications

Transaction completed

Notification example: Transaction completed

{
    "result": "9",
    "x_currency": "USD",
    "x_amount": "100.00",
    "x_description": "",
    "x_iduser": "1342133413",
    "x_bank_name": "Banco%20do%20Brasil",
    "x_document": "94580928",
    "x_bank": "BB",
    "x_payment_type": "00",
    "x_amount_usd": "100.00",
    "x_control": "85D9DF316186318C327F0C10D3926138FF6327D25B8601AEFC5156484BB417BB",
    "x_invoice": "test9349"
}

Transaction expired

Notification example: Transaction expired

{
    "result": "8",
    "x_currency": "USD",
    "x_amount": "100.00",
    "x_description": "",
    "x_iduser": "1342133413",
    "x_bank_name": "Banco%20do%20Brasil",
    "x_document": "94580929",
    "x_bank": "BB",
    "x_payment_type": "00",
    "x_amount_usd": "100.00",
    "x_control": "C267884F0B0BF30224AF2BF1321E387034D1AA08F890A3BF576922EE2A70B3A2",
    "x_invoice": "test6337"
}

If the transaction was successfully created, you will receive a notification in the URL specified in the x_confirm field every time it changes its status. result 9 in case the payment was completed. At that moment, you can release the funds to the customer in your website as the payment has been detected and the funds are now in your account. A result 8 in case the payment wasn't completed before it reached its expiration time.

Click here for all the result codes meanings.

PreviousHybrid API NextPayment Methods

Last updated 1 year ago