Deposit Creation Endpoint

🆕 OpenBanking API Payment Methods Document ID Validations Cashout Bank Codes
Search…
Learn how to generate deposits by opting for the OneShot Experience or the Hosted Checkout Experience according to your needs
post
https://api-stg.directa24.com
/v3/deposits
Deposit creation
​
Experiences
When generating a deposit request there are 2 possibilities, either the deposit is created in One Shot and you can display the user directly with the payment information, or you redirect the user to our Hosted Checkout to complete the missing details.
In any of those cases, a field called checkout_type will be part of the response, containing which one of the flows it is:
Checkout_type
Description
HOSTED
The information sent is missing details required to complete the request. Redirect the customer to our Hosted Checkout to collect those details.
ONE_SHOT
The deposit request was successfully completed in One Shot and the user will be directly presented with the information to complete the payment.
Test all the API features with our Postman collection here.​
Hosted Checkout Experience
On this Experience, you only need to send some basic information about the deposit. We will take care of collecting any missing details required and displaying the customer with the payment information.
The minimum fields you need to send are:
amount
country
Other details you send will personalize the Experience on our Hosted Checkout and will help in not having to ask the customer for the information again.
Hosted Checkout Request
Request Example
JSON
cURL
Java
PHP
C#
Python
1
{
2
    "invoice_id": "100000001",
3
    "amount": "100",
4
    "country": "BR",
5
    "currency": "BRL",
6
    "payment_types": ["BANK_TRANSFER", "BANK_DEPOSIT"]
7
}
8
​
Copied!
1
curl --location --request POST 'https://api-stg.directa24.com/v3/deposits' \
2
--header 'X-Login: {{X-Login}}' \
3
--header 'X-Date: {{X-Date}}' \
4
--header 'Authorization: {{Authorization}}' \
5
--header 'X-Idempontency-Key: {{X-Idempotency-Key}}' \
6
--header 'Content-Type: application/json' \
7
--data-raw '{
8
    "invoice_id" : "100000001",
9
    "amount": "100",
10
    "country": "BR",
11
    "currency": "BRL",
12
    "payment_types": ["BANK_TRANSFER", "BANK_DEPOSIT"]
13
}
14
'
15
​
16
​
Copied!
1
import java.io.*;
2
import okhttp3.*;
3
public class main {
4
  public static void main(String []args) throws IOException{
5
    OkHttpClient client = new OkHttpClient().newBuilder()
6
      .build();
7
    MediaType mediaType = MediaType.parse("application/json");
8
    RequestBody body = RequestBody.create(mediaType, "{\n    \"invoice_id\" : \"100000001\",\n    \"amount\": \"100\",\n    \"country\": \"BR\",\n    \"currency\": \"BRL\",\n    \"payment_types\": [\"BANK_TRANSFER\", \"BANK_DEPOSIT\"]\n}\n");
9
    Request request = new Request.Builder()
10
      .url("https://api-stg.directa24.com/v3/deposits")
11
      .method("POST", body)
12
      .addHeader("X-Login", "{{X-Login}}")
13
      .addHeader("X-Date", "{{X-Date}}")
14
      .addHeader("Authorization", "{{Authorization}}")
15
      .addHeader("X-Idempontency-Key", "{{X-Idempotency-Key}}")
16
      .addHeader("Content-Type", "application/json")
17
      .build();
18
    Response response = client.newCall(request).execute();
19
    System.out.println(response.body().string());
20
  }
21
}
22
​
23
​
Copied!
1
<?php
2
​
3
$curl = curl_init();
4
​
5
curl_setopt_array($curl, array(
6
  CURLOPT_URL => "https://api-stg.directa24.com/v3/deposits",
7
  CURLOPT_RETURNTRANSFER => true,
8
  CURLOPT_ENCODING => "",
9
  CURLOPT_MAXREDIRS => 10,
10
  CURLOPT_TIMEOUT => 0,
11
  CURLOPT_FOLLOWLOCATION => true,
12
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
13
  CURLOPT_CUSTOMREQUEST => "POST",
14
  CURLOPT_POSTFIELDS =>"{\n    \"invoice_id\" : \"100000001\",\n    \"amount\": \"100\",\n    \"country\": \"BR\",\n    \"currency\": \"BRL\",\n    \"payment_types\": [\"BANK_TRANSFER\", \"BANK_DEPOSIT\"]\n}\n",
15
  CURLOPT_HTTPHEADER => array(
16
    "X-Login: {{X-Login}}",
17
    "X-Date: {{X-Date}}",
18
    "Authorization: {{Authorization}}",
19
    "X-Idempontency-Key: {{X-Idempotency-Key}}",
20
    "Content-Type: application/json"
21
  ),
22
));
23
​
24
$response = curl_exec($curl);
25
​
26
curl_close($curl);
27
echo $response;
28
​
29
​
Copied!
1
using System;
2
using RestSharp;
3
namespace HelloWorldApplication {
4
    class HelloWorld {
5
        static void Main(string[] args) {
6
            var client = new RestClient("https://api-stg.directa24.com/v3/deposits");
7
            client.Timeout = -1;
8
            var request = new RestRequest(Method.POST);
9
            request.AddHeader("X-Login", "{{X-Login}}");
10
            request.AddHeader("X-Date", "{{X-Date}}");
11
            request.AddHeader("Authorization", "{{Authorization}}");
12
            request.AddHeader("X-Idempontency-Key", "{{X-Idempotency-Key}}");
13
            request.AddHeader("Content-Type", "application/json");
14
            request.AddParameter("application/json", "{\n    \"invoice_id\" : \"100000001\",\n    \"amount\": \"100\",\n    \"country\": \"BR\",\n    \"currency\": \"BRL\",\n    \"payment_types\": [\"BANK_TRANSFER\", \"BANK_DEPOSIT\"]\n}\n",  ParameterType.RequestBody);
15
            IRestResponse response = client.Execute(request);
16
            Console.WriteLine(response.Content);
17
        }
18
    }
19
}
20
​
21
​
Copied!
1
import http.client
2
import mimetypes
3
conn = http.client.HTTPSConnection("api-stg.directa24.com")
4
payload = "{\n    \"invoice_id\" : \"100000001\",\n    \"amount\": \"100\",\n    \"country\": \"BR\",\n    \"currency\": \"BRL\",\n    \"payment_types\": [\"BANK_TRANSFER\", \"BANK_DEPOSIT\"]\n}\n"
5
headers = {
6
  'X-Login': '{{X-Login}}',
7
  'X-Date': '{{X-Date}}',
8
  'Authorization': '{{Authorization}}',
9
  'X-Idempontency-Key': '{{X-Idempotency-Key}}',
10
  'Content-Type': 'application/json'
11
}
12
conn.request("POST", "/v3/deposits", payload, headers)
13
res = conn.getresponse()
14
data = res.read()
15
print(data.decode("utf-8"))
16
​
17
​
Copied!
Hosted Checkout Response: Success
Response Fields
Field name
Format
Description
checkout_type
String
Field containing the type of the request. [ONE_SHOT, HOSTED]
redirect_url
URL
URL used to redirect the customer to our Hosted Checkout
deposit_id
Number
ID of the deposit on Directa24 end
user_id
String
ID of the user on your end. If you didn't send it, it is generated by us
merchant_invoice_id
String
ID of the deposit on your end. If you didn't send it, make sure you save it as it is generated auto-generated and may be needed in the future (See refunds)
Response Example
1
{
2
    "checkout_type": "HOSTED",
3
    "redirect_url": "https://payin-stg.directa24.com/validate/eyJhbGciOiJIUR_JErX-j3S1pVaD",
4
    "deposit_id": 300000010,
5
    "user_id": "4-2845801292757825290",
6
    "merchant_invoice_id": "100000001"
7
}
Copied!
Click here for the error response format.
OneShot Experience
On this Experience, you will send all the information required to complete the deposit request and we will respond you with the payment metadata for you to build the Checkout or with an external link for the user to see the payment information.
In case you didn't send one field that is required, we won't decline the request and instead we will prompt the customer for it 😉
 .
OneShot Request example
Each Country and Payment Method has a minimum amount of fields you need to send for the OneShot Experience. In case of looking to develop this Experience on your Cashier visit the Payment Methods page to learn more about those requirements.
JSON
cURL
Java
PHP
C#
Python
1
{
2
    "invoice_id" : "1000000001",
3
    "amount": "1000",
4
    "country": "BR",
5
    "currency": "BRL",
6
    "payer": {
7
        "id": "11",
8
        "document": "84932568207",
9
        "first_name": "Ricardo",
10
        "last_name": "Carlos",
11
        "phone": "+23385266942",
12
        "email": "[email protected]",
13
        "address": {
14
            "street": "Calle 13",
15
            "city": "bahia",
16
            "state": "SP",
17
            "zip_code": "12345-678"
18
        }
19
    },
20
    "payment_method": "BL",
21
    "description": "test description",
22
    "client_ip": "123.123.123.123",
23
    "device_id": "00000000-00000000-01234567-89ABCDEF",
24
    "back_url": "https://www.directa24.com/deposit_cancelled",
25
    "success_url": "https://www.directa24.com/deposit_completed",
26
    "error_url": "https://www.directa24.com/deposit_error",
27
    "notification_url": "https://www.directa24.com/directa24/notify",
28
    "logo": "https://www.directa24.com/directa24.png",
29
    "test": true,
30
    "mobile": false,
31
    "language": "pt"
32
}
33
​
Copied!
1
curl --location --request POST 'https://api-stg.directa24.com/v3/deposits' \
2
--header 'X-Login: xxxxxxx' \
3
--header 'X-Date: 2020-06-09T19:42:51Z' \
4
--header 'Authorization: D24 a491ad04b303b6a5b9f219a14eeb496ea8ca086d4644889faa4309bea1feae38' \
5
--header 'Content-Type: application/json' \
6
--data-raw '{
7
    "invoice_id" : "1000000001",
8
    "amount": "1000",
9
    "country": "BR",
10
    "currency": "BRL",
11
    "payer": {
12
        "id": "11",
13
        "document": "84932568207",
14
        "first_name": "Ricardo",
15
        "last_name": "Carlos",
16
        "phone": "+23385266942",
17
        "email": "[email protected]",
18
        "address": {
19
            "street": "Calle 13",
20
            "city": "bahia",
21
            "state": "SP",
22
            "zip_code": "12345-678"
23
        }
24
    },
25
    "payment_method": "BL",
26
    "description": "test description",
27
    "client_ip": "123.123.123.123",
28
    "device_id": "00000000-00000000-01234567-89ABCDEF",
29
    "back_url": "https://www.directa24.com/deposit_cancelled",
30
    "success_url": "https://www.directa24.com/deposit_completed",
31
    "error_url": "https://www.directa24.com/deposit_error",
32
    "notification_url": "https://www.directa24.com/directa24/notify",
33
    "logo": "https://www.directa24.com/directa24.png",
34
    "test": true,
35
    "mobile": false,
36
    "language": "pt"
37
}'
38
​
39
​
Copied!
1
import java.io.*;
2
import okhttp3.*;
3
public class main {
4
  public static void main(String []args) throws IOException{
5
    OkHttpClient client = new OkHttpClient().newBuilder()
6
      .build();
7
    MediaType mediaType = MediaType.parse("application/json");
8
    RequestBody body = RequestBody.create(mediaType, "{\n    \"invoice_id\" : \"1000000001\",\n    \"amount\": \"1000\",\n    \"country\": \"BR\",\n    \"currency\": \"BRL\",\n    \"payer\": {\n        \"id\": \"11\",\n        \"document\": \"84932568207\",\n       \"first_name\": \"Ricardo\",\n        \"last_name\": \"Carlos\",\n        \"phone\": \"+23385266942\",\n        \"email\": \"[email protected]\",\n        \"address\": {\n            \"street\": \"Calle 13\",\n            \"city\": \"bahia\",\n            \"state\": \"SP\",\n            \"zip_code\": \"12345-678\"\n        }\n    },\n    \"payment_method\": \"BL\",\n    \"description\": \"test description\",\n    \"client_ip\": \"123.123.123.123\",\n    \"device_id\": \"00000000-00000000-01234567-89ABCDEF\",\n    \"back_url\": \"https://www.directa24.com/deposit_cancelled\",\n    \"success_url\": \"https://www.directa24.com/deposit_completed\",\n    \"error_url\": \"https://www.directa24.com/deposit_error\",\n    \"notification_url\": \"https://www.directa24.com/directa24/notify\",\n    \"logo\": \"https://www.directa24.com/directa24.png\",\n    \"test\": true,\n    \"mobile\": false,\n    \"language\": \"pt\"\n}");
9
    Request request = new Request.Builder()
10
      .url("https://api-stg.directa24.com/v3/deposits")
11
      .method("POST", body)
12
      .addHeader("X-Login", "xxxxxxx")
13
      .addHeader("X-Date", "2020-06-09T19:42:51Z")
14
      .addHeader("Authorization", "D24 a491ad04b303b6a5b9f219a14eeb496ea8ca086d4644889faa4309bea1feae38")
15
      .addHeader("Content-Type", "application/json")
16
      .build();
17
    Response response = client.newCall(request).execute();
18
    System.out.println(response.body().string());
19
  }
20
}
21
​
22
​
Copied!
1
<?php
2
$client = new http\Client;
3
$request = new http\Client\Request;
4
$request->setRequestUrl('https://api-stg.directa24.com/v3/deposits');
5
$request->setRequestMethod('POST');
6
$body = new http\Message\Body;
7
$body->append('{
8
    "invoice_id" : "1000000001",
9
    "amount": "1000",
10
    "country": "BR",
11
    "currency": "BRL",
12
    "payer": {
13
        "id": "11",
14
        "document": "84932568207",
15
        "first_name": "Ricardo",
16
        "last_name": "Carlos",
17
        "phone": "+23385266942",
18
        "email": "[email protected]",
19
        "address": {
20
            "street": "Calle 13",
21
            "city": "bahia",
22
            "state": "SP",
23
            "zip_code": "12345-678"
24
        }
25
    },
26
    "payment_method": "BL",
27
    "description": "test description",
28
    "client_ip": "123.123.123.123",
29
    "device_id": "00000000-00000000-01234567-89ABCDEF",
30
    "back_url": "https://www.directa24.com/deposit_cancelled",
31
    "success_url": "https://www.directa24.com/deposit_completed",
32
    "error_url": "https://www.directa24.com/deposit_error",
33
    "notification_url": "https://www.directa24.com/directa24/notify",
34
    "logo": "https://www.directa24.com/directa24.png",
35
    "test": true,
36
    "mobile": false,
37
    "language": "pt"
38
}');
39
$request->setBody($body);
40
$request->setOptions(array());
41
$request->setHeaders(array(
42
  'X-Login' => 'xxxxxxxx',
43
  'X-Date' => '2020-06-09T19:42:51Z',
44
  'Authorization' => 'D24 a491ad04b303b6a5b9f219a14eeb496ea8ca086d4644889faa4309bea1feae38',
45
  'Content-Type' => 'application/json'
46
));
47
$client->enqueue($request)->send();
48
$response = $client->getResponse();
49
echo $response->getBody();
50
​
Copied!
1
using System;
2
using RestSharp;
3
namespace HelloWorldApplication {
4
    class HelloWorld {
5
        static void Main(string[] args) {
6
            var client = new RestClient("https://api-stg.directa24.com/v3/deposits");
7
            client.Timeout = -1;
8
            var request = new RestRequest(Method.POST);
9
            request.AddHeader("X-Login", "xxxxxxx");
10
            request.AddHeader("X-Date", "2020-06-09T19:42:51Z");
11
            request.AddHeader("Authorization", "D24 a491ad04b303b6a5b9f219a14eeb496ea8ca086d4644889faa4309bea1feae38");
12
            request.AddHeader("Content-Type", "application/json");
13
            request.AddParameter("application/json", "{\n    \"invoice_id\" : \"1000000001\",\n    \"amount\": \"1000\",\n    \"country\": \"BR\",\n    \"currency\": \"BRL\",\n    \"payer\": {\n        \"id\": \"11\",\n        \"document\": \"84932568207\",\n        \"first_name\": \"Ricardo\",\n        \"last_name\": \"Carlos\",\n        \"phone\": \"+23385266942\",\n        \"email\": \"[email protected]\",\n        \"address\": {\n            \"street\": \"Calle 13\",\n            \"city\": \"bahia\",\n            \"state\": \"SP\",\n            \"zip_code\": \"12345-678\"\n        }\n    },\n    \"payment_method\": \"BL\",\n    \"description\": \"test description\",\n    \"client_ip\": \"123.123.123.123\",\n    \"device_id\": \"00000000-00000000-01234567-89ABCDEF\",\n    \"back_url\": \"https://www.directa24.com/deposit_cancelled\",\n    \"success_url\": \"https://www.directa24.com/deposit_completed\",\n    \"error_url\": \"https://www.directa24.com/deposit_error\",\n    \"notification_url\": \"https://www.directa24.com/directa24/notify\",\n    \"logo\": \"https://www.directa24.com/directa24.png\",\n    \"test\": true,\n    \"mobile\": false,\n    \"language\": \"pt\"\n}",  ParameterType.RequestBody);
14
            IRestResponse response = client.Execute(request);
15
            Console.WriteLine(response.Content);
16
        }
17
    }
18
}
19
​
20
​
Copied!
1
import requests
2
​
3
url = "https://api-stg.directa24.com/v3/deposits"
4
​
5
payload = "{\n    \"invoice_id\" : \"1000000001\",\n    \"amount\": \"1000\",\n    \"country\": \"BR\",\n    \"currency\": \"BRL\",\n    \"payer\": {\n        \"id\": \"11\",\n        \"document\": \"84932568207\",\n        \"first_name\": \"Ricardo\",\n        \"last_name\": \"Carlos\",\n        \"phone\": \"+23385266942\",\n        \"email\": \"[email protected]\",\n        \"address\": {\n            \"street\": \"Calle 13\",\n            \"city\": \"bahia\",\n            \"state\": \"SP\",\n            \"zip_code\": \"12345-678\"\n        }\n    },\n    \"payment_method\": \"BL\",\n    \"description\": \"test description\",\n    \"client_ip\": \"123.123.123.123\",\n    \"device_id\": \"00000000-00000000-01234567-89ABCDEF\",\n    \"back_url\": \"https://www.directa24.com/deposit_cancelled\",\n    \"success_url\": \"https://www.directa24.com/deposit_completed\",\n    \"error_url\": \"https://www.directa24.com/deposit_error\",\n    \"notification_url\": \"https://www.directa24.com/directa24/notify\",\n    \"logo\": \"https://www.directa24.com/directa24.png\",\n    \"test\": true,\n    \"mobile\": false,\n    \"language\": \"pt\"\n}"
6
headers = {
7
  'X-Login': 'xxxxxxx',
8
  'X-Date': '2020-06-09T19:42:51Z',
9
  'Authorization': 'D24 a491ad04b303b6a5b9f219a14eeb496ea8ca086d4644889faa4309bea1feae38',
10
  'Content-Type': 'application/json'
11
}
12
​
13
response = requests.request("POST", url, headers=headers, data = payload)
14
​
15
print(response.text.encode('utf8'))
16
​
17
​
Copied!
​
OneShot Experience Response: Redirect
This integration generates a link to redirect the customer where they will see the details required to pay.
Success Response fields
Field name
Format
Description
checkout_type
String
Field containing the type of the request. [ONE_SHOT, HOSTED]
redirect_url
URL
URL used to redirect the customer where they can see the details to pay
deposit_id
Integer
ID of the deposit generated. Store this ID for future reference
user_id
String
ID of the user. If you didn't send it, it is generated by us
merchant_invoice_id
String
ID of the deposit. If you didn't send it, it is generated by us
payment_info
Object
Object containing the information about the payment
payment_info.type
String
Type of the payment method. See the list here.​
payment_info.payment_method
String
Payment method code. See the list here.​
payment_info.payment_method_name
String
Payment method name. See the list here.​
payment_info.amount
number
Exact amount the customer has to pay
payment_info.currency
string
Currency of the amount to pay
payment_info.expiration_date
string
Date in which the deposit will be marked as expired
payment_info.created_at
string
Deposit creation date
Success Response example
1
{
2
    "checkout_type": "ONE_SHOT",
3
    "redirect_url": "https://payment-stg.directa24.com/v1/checkout/eyJhbGciOiJIUzM4NCJ9.eyJqdGkiOiI1NjU3ODQ2NCIsImlhdCI6MTU5MTgyOTYzNiwiZXhwIjoxNTkzMTI1NjM2LCJsYW5ndWFnZSI6bnVsbH0.XIlYyskFpE_rh1-8sA0Bs3JzB2iMmqAXdovClPzorrZXmzol69JqkeU7TR5FMBRn",
4
    "deposit_id": 300000011,
5
    "user_id": "11",
6
    "merchant_invoice_id": "test123456789",
7
    "payment_info": {
8
        "type": "VOUCHER",
9
        "payment_method": "BC",
10
        "payment_method_name": "BCP",
11
        "amount": 6.9448,
12
        "currency": "PEN",
13
        "expiration_date": "2020-06-15 22:53:56",
14
        "created_at": "2020-06-10 22:53:55"
15
    }
16
}
Copied!
​
OneShot Experience Response: OneShot
In case you sent all the details required for a payment method and the method supports it, we will return you all the metadata required for you to build the checkout on your own website avoiding the redirection.
Success Response fields
The fields returned in this integration are the same than the REDIRECT one. The difference lies in the new metadata and secondary_metadata objects containing the information you need to build your own checkout for each payment method:
Field name
Format
Description
metadata
object
Object containing the metadata of the payment
metadata.beneficiary_name
string
Name of the account beneficiary
metadata.agency
string
Agency of the beneficiary
metadata.CNPJ
string
CNPJ of the beneficiary
metadata.account
string
Account of the beneficiary
metadata.bar_code
string
Voucher bar code token
metadata.digitable_line
string
Voucher identifier line
metadata.payer_document
string
Document number of the payer
metadata.payer_document_type
string
Type of the payer's document sent
metadata.reference
string
Reference your customer needs to pay
secondary_metadata
object
Object containing the secondary metadata of the payment
secondary_metadata.reference
string
Reference of the deposit
secondary_metadata.qr_code
string
PNG image encoded in base64 of the QR code used to display the Pix QR natively on your site
secondary_metadata.digitable_line
string
Plain text string line the user can use to manually pay for the PIX instead of scanning the QR
Please note that the metadata and the secondary_metadataobjects will respond with different values depending upon the payment method and the provider we use, the ones above are only examples. It is for that reason that you should be able to iterate through them to display the values on your cashier to your customers.
Success Response example
PIX
BOLETO
BANK_DEPOSIT
BANK_TRANSFER
VOUCHER
1
{
2
    "checkout_type": "ONE_SHOT",
3
    "redirect_url": "https://payment-stg.directa24.com/v1/checkout/eyJhbGciOiJIUzM4NCJ9.eyJqdGkiOiI1NjYwODA5NSIsImlhdCI6MTYyMTUzOTYzNCwiZXhwIjoxNjIyODM1NjM0LCJsYW5ndWFnZSI6InB0In0.dDo0kMPEhZRSSeDPiH8Km0EXD1zEd1kg0gFdyhOvQ5iBfPl9skD2NYuD2_b-spE2",
4
    "iframe": true,
5
    "deposit_id": 300642187,
6
    "user_id": "kj2n3432n4k23",
7
    "merchant_invoice_id": "postmanTest433710480",
8
    "payment_info": {
9
        "type": "VOUCHER",
10
        "payment_method": "IX",
11
        "payment_method_name": "Pix",
12
        "amount": 11.65,
13
        "currency": "BRL",
14
        "expiration_date": "2021-05-20 22:47:33",
15
        "created_at": "2021-05-20 19:40:32",
16
        "metadata": {
17
            "reference": 56608095,
18
            "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAH0AAAB9AQAAAACn+1GIAAACMUlEQVR4Xt3UMZKsIBAGYEjkCkOCV1sTuQIkioleQRK4miRyhSahH6Uzr2qRucASflXa0Pw0wd8LyJ8CIEKwUwentKFNSGi3tLlu3haf2rB4mHqjlAw7/wI2Rsc9HvIreKeoefFz/gZozWC9Rev/7+M3AOH2vT5nqQAxMyD9TtF++lEBUMOSIZ0gapRNSOeQGYZohui+AV9fMwjphLq3XgOuetmyXHaJRjcBRtEJac+Rm942IW0Jo5tGnuW77AOMGLJMIVMzXT99AIZDdUInM2fShpQp/NC4uaG0uwlZSfRYKsu4XmWfwFYdfHTzTtT10wckGF9TJ0HJ8122BhjsVgLjSlz80oaXUorazI9J3DdXQzI0hJKEg+7vKjVgSE6R3hpp4Qske+rFrtOPttfxH5BsCuvst/1Hw132ASVTYiQMLdDUBOgz3UI49Bbyffwa0kpI+UT0dqV32RowphDdi3nM9/EfUK4y4WYk8O0O3RPW+RyFtscM7wTVkBXzaZ8YmmG5yj4A95F0E7U263zvowbQPqZVsQhjx5uQ1ZCnjsJwknFuAhpmSxzwLB26y9ZQHnqnSKcYzD62YXr1B3caBLsHyhNYeX8h2kPC9I52BdCbrowtloeD+iaUMcM39Isv2brKPqCMLScm7oHbe/Q9IKEbbPJliCYY2rDYQ0jDYgB6PY8WlAbJoz+0+XzygKU0aSzZxWvrT8BdSY/p4NHd+agByEsMRskYYrqfaQ2/19+GfwmGnDkcom5PAAAAAElFTkSuQmCC",
19
            "digitable_line": "00020126850014br.gov.bcb.pix2563qrcodepix.bb.com.br/pix/v2/ab4d2855-ee85-401a-a16d-716c743aa3af5204000053039865802BR5909AP Brasil6003Pix62070503***6304428B"
20
        }
21
    }
22
}
23
​
24
// Metadata explanation
25
//
26
// reference: ID of the deposit on our end.
27
//
28
// qr_code: PNG image encoded in base64. You can use the following HTML tag 
29
//          to render the QR code on your website: 
30
// <img src='qr_code'/>
31
//
32
// digitable_line: Plain text string line the user can use to manually pay for the PIX 
33
//                 instead of scanning the QR
34
//
35
// Make sure the user can't see the QR code after the expiration_date was reached
36
​
37
        
Copied!
1
{
2
    "checkout_type": "ONE_SHOT",
3
    "redirect_url": "https://checkout.directa24.com/v1/gateway/show?id_payment=172969591&signature=514ff34c08c7c19e8f7d",
4
    "deposit_id": 30000000001,
5
    "user_id": "121",
6
    "merchant_invoice_id": "postmanTest800032729",
7
    "payment_info": {
8
        "type": "VOUCHER",
9
        "payment_method": "BL",
10
        "payment_method_name": "Boleto",
11
        "amount": 165.64,
12
        "currency": "BRL",
13
        "expiration_date": "2020-07-20 22:42:41",
14
        "created_at": "2020-07-13 22:42:41",
15
        "metadata": {
16
            "receipt_url": "https://checkout.astropay.com//v1/gateway/getFullFile?id_payment=172969591&signature=514ff34c08c7c19e8f7d",
17
            "bar_code": "iVBORw0KGgoAAAANSUhEUgAAAioAAABkAQMAAACSM4nFAAAABlBMVEX///8AAABVwtN+AAAAAXRSTlMAQObYZgAAAGpJREFUWIXtzLEJxEAMRcEFpwK1IthUoNYXfgFuRaDUYF8Pl75solnjut3tKdmcidczs1uj3vcVP45kaVkZ8dhYumcpTsvNyvfqrn0WDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ3Nf80HB11x3a9nZU8AAAAASUVORK5CYII=",
18
            "digitable_line": "00190.00009 03141.056030 01870.806179 8 83180000016564"
19
        }
20
    }
21
}
22
​
23
​
Copied!
1
{
2
    "checkout_type": "ONE_SHOT",
3
    "redirect_url": "https://checkout-stg.directa24.com/v1/gateway/show?id_payment=56578849&signature=fff0e0a6a98066c19caf",
4
    "deposit_id": 300000025,
5
    "user_id": "11",
6
    "merchant_invoice_id": "postmanTest943044826",
7
    "payment_info": {
8
        "type": "BANK_DEPOSIT",
9
        "payment_method": "BB",
10
        "payment_method_name": "Banco do Brasil",
11
        "amount": 49.99,
12
        "currency": "BRL",
13
        "expiration_date": "2020-06-17 07:04:16",
14
        "created_at": "2020-06-16 19:04:16",
15
        "metadata": {
16
            "beneficiary_name": "Directa24 LLP",
17
            "agency": "3229-X",
18
            "CNPJ": "33.444.368/0001-39",
19
            "account": "253393-4"
20
        },
21
        "secondary_metadata": {
22
            "reference": 56608095,
23
            "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAH0AAAB9AQAAAACn+1GIAAACMUlEQVR4Xt3UMZKsIBAGYEjkCkOCV1sTuQIkioleQRK4miRyhSahH6Uzr2qRucASflXa0Pw0wd8LyJ8CIEKwUwentKFNSGi3tLlu3haf2rB4mHqjlAw7/wI2Rsc9HvIreKeoefFz/gZozWC9Rev/7+M3AOH2vT5nqQAxMyD9TtF++lEBUMOSIZ0gapRNSOeQGYZohui+AV9fMwjphLq3XgOuetmyXHaJRjcBRtEJac+Rm942IW0Jo5tGnuW77AOMGLJMIVMzXT99AIZDdUInM2fShpQp/NC4uaG0uwlZSfRYKsu4XmWfwFYdfHTzTtT10wckGF9TJ0HJ8122BhjsVgLjSlz80oaXUorazI9J3DdXQzI0hJKEg+7vKjVgSE6R3hpp4Qske+rFrtOPttfxH5BsCuvst/1Hw132ASVTYiQMLdDUBOgz3UI49Bbyffwa0kpI+UT0dqV32RowphDdi3nM9/EfUK4y4WYk8O0O3RPW+RyFtscM7wTVkBXzaZ8YmmG5yj4A95F0E7U263zvowbQPqZVsQhjx5uQ1ZCnjsJwknFuAhpmSxzwLB26y9ZQHnqnSKcYzD62YXr1B3caBLsHyhNYeX8h2kPC9I52BdCbrowtloeD+iaUMcM39Isv2brKPqCMLScm7oHbe/Q9IKEbbPJliCYY2rDYQ0jDYgB6PY8WlAbJoz+0+XzygKU0aSzZxWvrT8BdSY/p4NHd+agByEsMRskYYrqfaQ2/19+GfwmGnDkcom5PAAAAAElFTkSuQmCC",
24
            "digitable_line": "00020126850014br.gov.bcb.pix2563qrcodepix.bb.com.br/pix/v2/ab4d2855-ee85-401a-a16d-716c743aa3af5204000053039865802BR5909AP Brasil6003Pix62070503***6304428B"
25
        }
26
    }
27
}
28
​
Copied!
1
{
2
    "checkout_type": "ONE_SHOT",
3
    "redirect_url": "https://checkout-stg.directa24.com/v1/gateway/show?id_payment=56579207&signature=d79896d2b815303cbed4",
4
    "deposit_id": 300000148,
5
    "user_id": "121",
6
    "merchant_invoice_id": "postmanTest349087674",
7
    "payment_info": {
8
        "type": "BANK_TRANSFER",
9
        "payment_method": "SB",
10
        "payment_method_name": "Santander",
11
        "amount": 176.02,
12
        "currency": "BRL",
13
        "expiration_date": "2020-06-21 09:48:39",
14
        "created_at": "2020-06-20 21:48:39",
15
        "metadata": {
16
            "beneficiary_name": "Directa24 LLP",
17
            "agency": "1324",
18
            "CNPJ": "47.222.214/0005-70",
19
            "account": "13023469-6"
20
        }
21
    }
22
}
Copied!
1
// OXXO - Mexico
2
{
3
    "checkout_type": "ONE_SHOT",
4
    "redirect_url": "https://checkout-stg.directa24.com/v1/gateway/show?id_payment=56578556&signature=17dc33898a1e6f3f5b8a",
5
    "deposit_id": 300000037,
6
    "user_id": "11",
7
    "merchant_invoice_id": "postmanTest88062572",
8
    "payment_info": {
9
        "type": "VOUCHER",
10
        "payment_method": "OX",
11
        "payment_method_name": "OXXO",
12
        "amount": 1343.07,
13
        "currency": "MXN",
14
        "expiration_date": "2020-06-22 19:42:45",
15
        "created_at": "2020-06-16 19:42:45",
16
        "metadata": {
17
            "bar_code": "440056578856202006210001343070",
18
            "digitable_line": "44005 65788 56202 00621 00013 43070 "
19
        }
20
    }
21
}
22
​
23
// RedPagos - Uruguay
24
{
25
    "checkout_type": "ONE_SHOT",
26
    "redirect_url": "https://checkout.directa24.com/v1/gateway/show?id_payment=174090375&signature=13fefecb67c9bec75674",
27
    "deposit_id": 303160917,
28
    "user_id": "4-5334123",
29
    "merchant_invoice_id": "postmanTest425629854",
30
    "payment_info": {
31
        "type": "VOUCHER",
32
        "payment_method": "RE",
33
        "payment_method_name": "Red Pagos",
34
        "amount": 104.97,
35
        "currency": "UYU",
36
        "expiration_date": "2020-07-30 20:18:56",
37
        "created_at": "2020-07-25 20:18:56",
38
        "metadata": {
39
            "payer_document": "39871784",
40
            "reference": "174033875",
41
            "payer_document_type": "Nº de Identidad"
42
        }
43
    }
44
}
Copied!
This integration is an extension of the REDIRECT one. It will always contain a link to redirect the customer in case you don't wan't to develop the checkout with the metadata on your website.
​
Secondary Metadata
The object secondary_metadata is used to display the customer with a second way to pay for the same deposit allowing them to choose the best option. For example, the user could create a deposit for a bank deposit method in Brasil, and show them our Bank Details (field metadata)  as well as a Pix QR code (field secondary_metadata) in case they prefer that option.
​
Error Response
Error Response fields
Field name
Format
Description
code
Number
Error code. See the list of error codes​
description
String
Description of the error
details[]
String
Details about the errors. It is not always shown
type
String
Error code name. It is not always shown. See the list of error codes​
Error Response examples
1
{
2
    "code": 201,
3
    "description": "Field validation error. Check details",
4
    "details": [
5
        "payer.document: Invalid document type and/or document",
6
        "payer.address.state: Invalid State for Country"
7
    ]
8
}
9
​
10
{
11
    "code": 201,
12
    "description": "Field validation error. Check details",
13
    "details": [
14
        "amount: invalid numeric format",
15
        "country: Invalid value. Accepted values: AR|BR|CL|CM|CN|CO|EC|GH|IN|ID|KE|MY|MX|NG|PA|PE|PH|PY|TH|TZ|UG|UY|VN|ZA"
16
    ]
17
}
18
​
19
{
20
    "code": 502,
21
    "description": "Invalid request body",
22
    "type": "INVALID_REQUEST_BODY"
23
}
24
​
25
{
26
    "code": 304,
27
    "description": "The user limit has been exceeded: TRANSACTION",
28
    "type": "USER_LIMIT_EXCEEDED"
29
}
30
​
31
{
32
    "code": 201,
33
    "description": "Field validation error. Check details",
34
    "details": [
35
        "invoiceId: must match \"^[A-Za-z0-9-_]*$\""
36
    ],
37
    "type": "BEAN_VALIDATION_ERROR"
38
}
39
​
Copied!
Crypto payments
Please get in touch with your Account Manager in order to start processing payments with Cryptocurrencies.
When processing payments to a Cryptocurrency e-wallet, you must send in the request an object called crypto with the currency and the wallet address. Please click here for more details about the crypto object.
To retrieve the actual exchange of any currency against a cryptocurrency, please use the Crypto Exchange Endpoint.​
When a customer pays a crypto transaction, the money is credited directly into the customer's wallet address and not into your merchant balance. After the transaction was paid by the customer, the status of the transaction will be APPROVED while we are transferring the funds to the user's wallet. As soon as the money gets into the user's wallet, the deposit will change to COMPLETED status. Please click here for more information about deposit statuses.
​
Request Fields Description
​
Field name
Format
Description
Default
Validations
country
string (length: 2)
Country code of the deposit in ISO 3166-1 alpha-2 code format
​
​Country codes​
amount
decimal (max decimals: 2)
Deposit amount in the currency specified
​
Number of up to 18 integers and 2 decimals places
currency
string (length: 3)
Currency code of the amount in ISO 4217 format
USD
​Currencies​
invoice_id
string (max length: 128)
Unique deposit ID on the merchant end
random
^[A-Za-z0-9-_]*$
request_payer_data_on
_validation_failure
boolean
Boolean used to specify if you want to receive declines by invalid data even if it is not required by the payment method. here for more info
false
[true, false]
payer
object[]
Object containing details about the customer
​
​Payer object​
payment_method
string (max length: 3)
Payment method code
​
​Payment method codes​
payment_type
string
Type of payment methods to show the customer. If null is sent and payment_method is null, "ALL" will be assumed
All
​Payment types available​
payment_types
array
Same as payment_type but multiple payment methods' types can be specified with an array. I.e.: payment_types: ["BANK_DEPOSIT", "BANK_TRANSFER"]
All
​Payment types available​
reported_info
object[]
Object containing details about the bank account from which the deposit will be made. Used in ONE_SHOT mode to auto-detect user's payment
​
​reported_info object​
bank_account
object[]
Object containing details about the bank account from which the deposit will be made
​
​bank_account object​
fee_on_payer
boolean
Choose if the deposit's fee will be paid by the customer or debited from your balance
false
[true, false]
surcharge_on_payer
boolean
Choose if the surcharge will be paid by the customer or debited from your balance
true
[true, false]
bonus_amount
decimal (max decimals: 2)
Used to show the customer a bonus amount. I.e.: amount:100, bonus_amount:50
User will see: Pay 100, receive 150
​
Number of up to 18 integers and 2 decimals
bonus_relative
boolean
Used to define if the bonus_amount was specified as a percentage of the amount or as an absolute value
false
[true, false]
strikethrough_price
decimal (max decimals: 2)
Used to show the customer a strikethrough amount. I.e.: 
Before: 150
Now: 100
​
Number of up to 18 integers and 2 decimals
description
string (max length: 100)
Deposit description. It will be shown to the customer on our Hosted Checkout as the description of the product to be acquired
​
String of up to 100 characters
client_ip
string
Valid IPv4 or IPv6 Address
​
IPv4/v6 Address
device_id
string (max length: 100)
Unique customer's device ID created using our JS library. Used to identify and prevent fraud
​
String of up to 100 characters
language
string (length: 2)
Language to show the customer on the deposit page in ISO 639-1 code format. *Not all the languages are available
​
String of 2 characters [es, en, pt]
back_url
string (max length: 2048)
Valid URL over HTTPS used to redirect the customer in case of cancelling the deposit
​
HTTPS URL
success_url
string (max length: 2048)
Valid URL over HTTPS used to redirect the customer in case the deposit flow was completed. The deposit status will be Pending
​
HTTPS URL
error_url
string (max length: 2048)
Valid URL over HTTPS used to redirect the customer in case of error while generating the deposit
​
HTTPS URL
notification_url
string (max length: 2048)
Valid URL over HTTPS used to receive the notifications about the deposit's changes of status. If none is sent, we will use the one configured on the Merchant Panel
​
HTTPS URL
logo
string (max length: 2048)
Valid URL over HTTPS used to show your logo on our Hosted Checkout Experience. If none is sent, we will use the one configured on the Merchant Panel
​
HTTPS URL
test
boolean
Used to flag a deposit as test. If true, the deposit will not affect the merchant's balance
false
[true, false]
mobile
boolean
Used to specify if the redirection will be made on a mobile device
false
[true, false]
early_release
boolean
Used to specify if the deposit should be early released. Useful when you want to release payments to your VIP users before it were completed
false
[true, false]
The fields bonus_amount, bonus_relative, strikethrough_price,  and description only affect our Hosted Checkout GUI and doesn't affect any balance or calculations. 
Using the same back_url, success_url and error_url is ok if you want to show your customers with a generic message when being redirected. Even better is to generate one unique link for each deposit for better user experience when being redirected. I.e.: https://www.example.com/deposit/{deposit_id_hashed}/pending
​
Required flags
We recommend sending the following flags to prevent declines and improve conversion rates.
mobile
The flag mobile is a boolean and has to be sent equal to true if the customer generating the deposit is using a mobile device/application. If not sent it defaults to false.
There are some payment methods that have a different flow on mobile devices compared to the flow on web devices because the payment method doesn't work the same way in those devices. When a deposit gets created as ONE_SHOT, it means the flow is assigned before the user navigates into our website, and therefore, we can't identify if the customer comes from a mobile device or not. 
Considering that, if the flag mobile is not sent we could route a mobile user through the web flow, therefore, affecting the ability of the customer to complete the deposit.
​
request_payer_data_on_validation_failure
The flag request_payer_data_on_validation_failure can be used to prevent the request to be declined in case you send an invalid payer.phone, payer.address.state and/or payer.address.zip_code.
If it is required by the payment method, we will return you with a HOSTED CHECKOUT link where the customer will fill in the incorrect details on our checkout and if the details is not needed by the payment method, it will be ignored and the link for ONE SHOT will be returned.
Example responses:
Error
Success: HOSTED CHECKOUT
Success: ONE SHOT
1
// With the flag request_payer_data_on_validation_failure = false
2
// or not sent (it defaults to false)
3
​
4
{
5
    "code": 201,
6
    "description": "Field validation error. Check details",
7
    "details": [
8
        "payer.address.zipCode: Invalid zip code format for Country",
9
        "payer.address.state: Invalid State for Country",
10
        "payer.phone: Invalid phone for Country"
11
    ],
12
    "type": "BEAN_VALIDATION_ERROR"
13
}
14
​
Copied!
1
// With the flag request_payer_data_on_validation_failure = true
2
// The payment method requires any of the fields so a Hosted Checkout link 
3
// is returned to collect those
4
​
5
// Typical HOSTED response
6
​
7
{
8
    "checkout_type": "HOSTED",
9
    "redirect_url": "https://payin.astro2pay.com/validate/eyJhbGciOiJIUzM4NCJ9.eyJqdGkiOiIzMzg4Mjc3OTIiLCJpYXQiOjE2MTY2MDcyMDIsImV4cCI6MTYxOTE5OTIwMn0.0-_gFW0F0Yk73J8SoAddPUaOrgsKILMVbYa1cZehrF_PEk6cj17dIXDDs6FRjkkd",
10
    "deposit_id": 338827792,
11
    "user_id": "4-1874596909371448397",
12
    "merchant_invoice_id": "postmanTest640841435"
13
}
14
​
Copied!
1
// With the flag request_payer_data_on_validation_failure = true
2
// The fields payer.phone, payer.address.state and payer.address.zip_code are not
3
// required for the payment method
4
​
5
// Typical ONE_SHOT response
6
​
7
{
8
    "checkout_type": "ONE_SHOT",
9
    "redirect_url": "https://payment.directa24.com/v1/checkout/eyJhbGciOiJIUzM4NCJ9.eyJqdGkiOiIyMDQxNzcxMjMiLCJpYXQiOjE2MTY2MDY5NzcsImV4cCI6MTYxNzkwMjk3NywibGFuZ3VhZ2UiOiJwdCJ9.sVh4-WAW2Q5lehuDMWXhUuOVQUzqmN_XRrNBDhyOZUb36dWd9a6QX9i-JB_ocjWJ",
10
    "iframe": true,
11
    "deposit_id": 338827003,
12
    "user_id": "4-1874596909371448397",
13
    "merchant_invoice_id": "postmanTest806586134",
14
    "payment_info": {
15
        "type": "BANK_DEPOSIT",
16
        "payment_method": "B",
17
        "payment_method_name": "Bradesco",
18
        "amount":