Deposit methods
Deposit object
- target_paid string
The sum of transaction amounts. After the creation equals to
0. This is a total amount paid by a user for this deposit.- payment_page string
URL of the payment page provided to payers; the page contains address, tag, QR-code and registered incoming transfers.
- address_type string
Address type. Refer to Address types for supported values.
- tracking_id string or number
Client-provided identifier of the payment in the external system.
- confirmations_needed number
Client-provided number of confirmations for sending an additional callback.
- callback_url string
URL for callback notifications.
- address string
Address for the received payment.
- destination object
All possible options to specify the address of the deposit: an object if there is only one possible option, array of objects if there are several options. Each object contains three string fields:
address— actual address,address_type— type of the address,tag— destination tag (if required), used in conjunction with addresstag_type— type of the tag or memo, applicable for XLM. Possible values:1— a 64-bit unsigned integer2— a string up to 28-bytes long
- assets object
Amounts of incoming transfers in different currencies. The information is relevant for tokens, if both tokens and coins can be sent to a single address. In this case, the funds are credited not only to the wallet from the
walletfield, but also to other wallets in other currencies. The alpha code of the currency is used as a key. Aggregated amounts are values.- label string
The deposit name for convenient searching. The string value length cannot exceed 32 characters.
- currency object
The wallet currency. Contains currency
id(refer to Currency codes for supported values).- wallet object
The wallet with which the transaction is associated. Contains wallet
idand a link to the wallet.
{
"type": "deposit",
"id": "2205",
"attributes": {
"status": 2,
"address": "2NFSVSgbXK7mipDFfuVrLvVJJ9HEgyPNXqu",
"address_type": "p2sh-segwit",
"label": "My Deposit",
"tracking_id": "2244",
"confirmations_needed": null,
"time_limit": null,
"callback_url": "https://my.client.url/cb/",
"inaccuracy": "0.00000000",
"target_amount_requested": null,
"rate_requested": "1.00000000",
"rate_expired_at": "2024-02-06T16:39:06.507593Z",
"invoice_updated_at": null,
"payment_page": "https://pay-sandbox.com/en/a08c7567-956c-4922-b80b-6e515718a9a4/pay",
"target_paid": "0.00000000",
"source_amount_requested": "0.00000000",
"target_paid_pending": "0.00000000",
"assets": {},
"destination": {
"address_type": "p2sh-segwit",
"address": "2NFSVSgbXK7mipDFfuVrLvVJJ9HEgyPNXqu"
}
},
"relationships": {
"currency": {
"data": {
"type": "currency",
"id": "1000"
}
},
"wallet": {
"data": {
"type": "wallet",
"id": "448"
}
}
}
}
{
"type": "deposit",
"id": "2422",
"attributes": {
"status": 2,
"address": null,
"address_type": "",
"label": "My Deposit",
"tracking_id": "1234567",
"confirmations_needed": 2,
"time_limit": 140768,
"callback_url": "",
"inaccuracy": "5.00000000",
"target_amount_requested": "1000.000000000000000000",
"rate_requested": null,
"rate_expired_at": null,
"invoice_updated_at": "2024-02-21T06:53:50.851941Z",
"payment_page": "https://pay-sandbox.b2binpay.com/en/7f07c559-d223-48bf-8fad-cb8a47bada47/pay",
"target_paid": "0.00",
"source_amount_requested": "0",
"target_paid_pending": "0.00",
"assets": {},
"destination": null
},
"relationships": {
"currency": {
"data": null
},
"wallet": {
"data": {
"type": "wallet",
"id": "449"
}
}
}
}
Get deposit
Request
- id string
The deposit identifier.
Filtering by any object parameters can be applied according to the JSON API Specification.
GET[base]/deposit/{id}
$ curl --request GET \
--url https://[base]/deposit/ \
--header 'authorization: Bearer eyJ0eXAiOiJKV1QiLC...' \
--header 'content-type: application/vnd.api+json'
import requests
url = 'https://[base]/deposit/'
headers = {
'authorization': 'Bearer <Change to your access token>',
'content-type': 'application/vnd.api+json',
}
requests.get(url, headers=headers)
<?php
use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;
$client = new GuzzleHttp\Client();
try {
$res = $client->get('https://[base]/deposit/', [
'headers' => [
'Authorization' => 'Bearer <Change to your access token>',
'Content-Type' => 'application/vnd.api+json',
],
]);
echo $res->getBody();
} catch (RequestException $e) {}
Response
In case of a successful response, a deposit object or an array of objects (if id was not specified) is returned.
Response codes
200 Success.
400 Bad request. You have no permission to view the deposit with given id.
404 Deposit with given id not found.
Create deposit
Before creating a deposit, you can check the parameters of the fields you need to fill in by making an OPTIONS request to the server to retrieve the data.
Request
- walletobject required
The identifier of the wallet to which the payments will be deposited.
- label string
The deposit name for convenient searching. The string value length cannot exceed 32 characters.
- callback_url string
URL to send callback notifications. Specify this value to receive a callback when a new transaction occurs. Refer to Deposit callback for more details.
- confirmations_needed number
The required number of confirmations to trigger an additional callback. Specify this value to receive an additional callback before or after the transaction is confirmed. Refer to Deposit callback for more details.
- tracking_id string or number
The deposit identifier in your system. This ID is used in callbacks.
- address_type string
Address type, depends on a currency. Refer to Address types for supported values.
POST[base]/deposit/
$ curl --request POST \
--url https://[base]/deposit/ \
--header 'authorization: Bearer eyJ0eXAiOiJKV1QiLC...' \
--header 'content-type: application/vnd.api+json' \
--data '{
"data": {
"type": "deposit",
"attributes": {
"label": "My new deposit",
"tracking_id": "d-abcd",
"confirmations_needed": 2,
"callback_url": "https://my.client.com/cb/"
},
"relationships": {
"wallet": {
"data": {
"type": "wallet",
"id": "1"
}
}
}
}
}'
import requests
url = 'https://[base]/deposit/'
headers = {
'authorization': '<Change to your access token>',
'content-type': 'application/vnd.api+json',
}
data = {
'data': {
'type': 'deposit',
'attributes': {
'label': 'My new deposit',
'tracking_id': 'd-abcd',
'confirmations_needed': 2,
'callback_url': 'https://my.client.com/cb/',
},
'relationships': {
'wallet': {
'data': {
'type': 'wallet',
'id': '1',
},
},
},
},
}
requests.post(url, headers=headers, json=data)
<?php
use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;
$client = new GuzzleHttp\Client();
try {
$res = $client->post('https://[base]/deposit/', [
'json' => [
'data' => [
'type' => 'deposit',
'attributes' => [
'label' => 'My new deposit',
'tracking_id' => 'd-abcd',
'confirmations_needed' => 2,
'callback_url' => 'https://my.client.com/cb/',
],
'relationships' => [
'wallet' => [
'data' => [
'type' => 'wallet',
'id' => '1',
],
],
],
],
],
'headers' => [
'Authorization' => 'Bearer <Change to your access token>',
'Content-Type' => 'application/vnd.api+json',
],
]);
echo $res->getBody();
} catch (RequestException $e) {}
Response
In case of a successful response, a newly created deposit object is returned, containing an address that your payers can use to send funds.
Response codes
HTTP code |
Application error code |
Error description |
Suggested action |
|---|---|---|---|
201 |
— |
OK |
The request succeeded. |
400 |
1007 |
An invalid value was specified for a field. |
Send valid values. |
400 |
3008 |
The wallet is inactive or is being registered in the system. |
Activate the wallet or wait until the process of wallet registration in the system is finished and try again. |
400 |
3021 |
A wallet activation transfer is required. |
Make a transfer to activate the wallet. |
400 |
4002 |
A payout cannot be made from the specified wallet. |
Make sure you have the permission to make payouts from the wallet you have specified. |
400 |
5005 |
The deposit address cannot be generated due to technical issues. |
Try again later. |
400 |
5006 |
The deposit rates cannot be obtained due to technical issues. |
Try again later. |
400 |
5007 |
The currency value is required if the address type is specified. |
Specify the currency value. |
400 |
6002 |
The selected currency is disabled. |
Select an active currency. |
400 |
6015 |
The currency is unavailable for all clients or for a specific client. |
Select an available currency. |
400 |
6017 |
An Enterprise user is trying to make a transaction with a custom token that was not paid for. |
Make a payment for a custom token and proceed with the transaction. |
400 |
— |
Invalid data (serializer errors). |
Send valid data. |
401 |
2007 |
No active account with the given credentials is found. |
Send correct credentials or update access tokens. |
429 |
— |
The request was throttled. |
Try again later. |
Deposit callback
A callback is a notification sent to the user’s callback URL when a transaction (deposit or payout) occurs in a blockchain. By default, the callback is sent after the transaction is confirmed. To get confirmed, a transaction should meet the following requirements:
receive the necessary number of confirmation blocks
pass AML verification
pass additional anti-fraud checks
The number of confirmations is determined by the confirmation_blocks field in the currency settings.
For example, for USDT-ETH, the confirmation_blocks field is set to 3. This means that after receiving three confirmations and passing AML and anti-fraud checks, a callback will be sent.
It is also possible to receive additional callbacks.
To do this, specify a required number in the confirmations_needed field when creating a deposit.
For example, for USDT-ETH, the confirmation_blocks value is 3 and the confirmations_needed value is 1. This means that two callbacks will be sent: one (additional) after a transaction receives one confirmation and another one (default) after a transaction receives three confirmations.
Upon receiving a required number of confirmations related to a new deposit transaction, a callback is sent to your server if the deposit request body includes a valid callback URL. You can use a callback to make changes in your system and notify your payers.
The callback is sent by a POST request, which contains useful JSON payload. After processing the payload, you should send back an HTTP code 200 response without a body. If your server is temporarily unavailable or the status of the response is different from 200, we will resend the callback several times with the increasing delay time. The number of resendings is limited. If the manual resending is required, you can do it on the Wallet management > Events page.
A callback consists of two parts: the deposit itself (data) and the transaction received for this deposit (included).
The deposit parameters (data) are as follows:
- address string
The identifier of the wallet to which the payment is deposited.
- created_at string
The time of the transfer update as per ISO 8601 with μs precision and timezone included:
YYYY-MM-DDThh:mm:ss[.SSSSSS]±hh:mm.- tracking_id string or number
The deposit identifier in your system.
- target_paid string
If an additional callback is required before or after the transaction is confirmed, set the number of confirmations that will trigger a callback sending.
- destination object
All possible options to specify the address of the deposit: an object if there is only one possible option, array of objects if there are several options. Each object contains three string fields:
address— actual address,address_type— type of the address,tag— destination tag (if required), used in conjunction with addresstag_type— type of the tag or memo, applicable for XLM. Possible values:1— a 64-bit unsigned integer2— a string up to 28-bytes long
- currency object
The transaction currency. Contains currency
id(refer to Currency codes for supported values).- wallet object
The identifier of the wallet to which the payments will be deposited.
- transfer object
The transaction identifier.
- meta.time string
The time of the callback sending as per ISO 8601 with μs precision and timezone included:
YYYY-MM-DDThh:mm:ss[.SSSSSS]±hh:mm.- meta.sign string
HMAC signature for a callback authentication. To verify that the callback was sent by us, generate an HMAC signature using sha256 as algorithm: sha256 hash of the concatenation of your login and password as a key, and the concatenation of the
transfer.status,transfer.amount,deposit.tracking_id,meta.timefields as message. Refer to Callback verification example below for a sign verification instance.
Transaction parameters (included) are described in Deposit object.
{
"data": {
"type": "deposit",
"id": "11203",
"attributes": {
"address": "0xcb959a408cbfbe64116a2dadc20188c290226fae",
"created_at": "2022-07-15T16:51:52.702456Z",
"tracking_id": "",
"target_paid": "0.300000000000000000",
"destination": {
"address_type": null,
"address": "0xcb959a408cbfbe64116a2dadc20188c290226fae"
}
},
"relationships": {
"currency": {
"data": {
"type": "currency",
"id": "1002"
}
},
"wallet": {
"data": {
"type": "wallet",
"id": "318"
}
},
"transfer": {
"data": {
"type": "transfer",
"id": "17618"
}
}
}
},
"included": [
{
"type": "currency",
"id": "1002",
"attributes": {
"iso": 1002,
"name": "Ethereum",
"alpha": "ETH",
"alias": null,
"exp": 18,
"confirmation_blocks": 3,
"minimal_transfer_amount": "0.000000000000000000",
"block_delay": 30
}
},
{
"type": "transfer",
"id": "17618",
"attributes": {
"op_id": 11203,
"op_type": 1,
"amount": "0.300000000000000000",
"commission": "0.001200000000000000",
"fee": "0.000000000000000000",
"txid": "0xa09cb1de38b9b21712ff18d08d6a625cc80ec41c9e64586095d4c46449a9eb51",
"status": 2,
"user_message": null,
"created_at": "2022-07-15T16:53:04.098536Z",
"updated_at": "2022-07-15T16:54:39.903843Z",
"confirmations": 8,
"risk": 0,
"risk_status": 4,
"amount_cleared": "0.298800000000000000"
},
"relationships": {
"currency": {
"data": {
"type": "currency",
"id": "1002"
}
}
}
}
],
"meta": {
"time": "2022-07-15T16:54:39.966327+00:00",
"sign": "1377e7a9eb3d62f7708285cd148711c62f50e53d8046e4d412a18ae9a575da85"
}
}
Callback verification
Refer to the example below for a sign verification instance.
<?php
# set API user login and password
$login = 'E8kOq803ktB7';
$password = 'E8kOq803ktB7';
# parse callback data
$callback_payload = json_decode(
'
{
"data": {
"type": "payout",
"id": "26",
"attributes": {
"address": "2NBr9k5xhvE2PxAAiFuczqQkeN76ShMdRZ6",
"created_at": "2021-09-30T13:01:49.930612Z",
"tracking_id": "12",
"fee_amount": "0.00000823",
"is_fee_included": false,
"amount": "0.00010000",
"destination": {
"address_type": "legacy",
"address": "2NBr9k5xhvE2PxAAiFuczqQkeN76ShMdRZ6"
}
},
"relationships": {
"wallet": {
"data": {
"type": "wallet",
"id": "19"
}
},
"currency": {
"data": {
"type": "currency",
"id": "1000"
}
},
"transfer": {
"data": {
"type": "transfer",
"id": "145"
}
}
}
},
"included": [
{
"type": "currency",
"id": "1000",
"attributes": {
"iso": 1000,
"name": "Bitcoin",
"alpha": "BTC",
"alias": null,
"exp": 8,
"confirmation_blocks": 3,
"minimal_transfer_amount": "0.00000546",
"block_delay": 3600
}
},
{
"type": "transfer",
"id": "145",
"attributes": {
"confirmations": 3,
"risk": 0,
"risk_status": 4,
"op_id": 26,
"op_type": 2,
"amount": "0.00010000",
"commission": "0.00000000",
"fee": "0.00000823",
"txid": "c3cc36f4569fdbfaacdbc14647e5046d9f239ab1af0268b531a5a213411a8fc9",
"status": 2,
"message": null,
"user_message": null,
"created_at": "2021-09-30T13:01:50.273446Z",
"updated_at": "2021-09-30T13:02:33.743770Z"
},
"relationships": {
"currency": {
"data": {
"type": "currency",
"id": "1000"
}
}
}
}
],
"meta": {
"time": "2021-09-30T13:02:34.059939+00:00",
"sign": "8ef2a0f0c6826895593d0d137cf6ce7353a4bbe999d4a6c363f92f1e9d7f8e32"
}
}
',
true
);
$callback_sign = $callback_payload['meta']['sign'];
$callback_time = $callback_payload['meta']['time'];
# retrieve transfer and deposit attributes
$included_transfer = array_filter(
$callback_payload['included'],
function ($item) {
return $item['type'] === 'transfer';
}
);
$included_transfer = array_pop($included_transfer)['attributes'];
$deposit = $callback_payload['data']['attributes'];
$status = $included_transfer['status'];
$amount = $included_transfer['amount'];
$tracking_id = $deposit['tracking_id'];
# prepare data for hash check
$message = $status . $amount . $tracking_id . $callback_time;
$hash_secret = hash('sha256', $login . $password, true);
$hash_hmac_result = hash_hmac('sha256', $message, $hash_secret);
# print result
if ($hash_hmac_result === $callback_sign) {
echo 'Verified';
} else {
echo 'Invalid sign';
}
echo PHP_EOL;
Deposit options method
Before creating a deposit, you can check the parameters of the fields you need to fill in to create the deposit. To do this, make an OPTIONS request to the server to retrieve the data.
Request
No request parameters.
OPT[base]/deposit
curl --request OPTIONS \
--url https://[host]/deposit/ \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/vnd.api+json' \
import requests
import json
url = "https://[host]/deposit/"
headers = {
'Content-Type': 'application/vnd.api+json',
'Authorization': 'Bearer <token>'
}
response = requests.request("OPTIONS", url, headers=headers)
print(response.text)
<?php
$client = new Client();
$headers = [
'Content-Type' => 'application/vnd.api+json',
'Authorization' => 'Bearer <token>'
];
$request = new Request('OPTIONS', 'https://[host]/deposit/', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
Response
In case of success, the response body contains an array of available methods as well as a list of parameters of the fields you need to fill in to create the deposit.
- allowed_methods array
Available methods for deposit:
GETPOSTHEADOPTIONS
- actions object
The object contains information about parameters of the fields that should be filled in when creating a deposit:
- wallet object
The object contains the information about the
walletfield.Show object fields- type string
The type of the field.
- required boolean
If
true, the field is required.- read_only boolean
If
true, you cannot edit the field.- label string
The name of the field.
- label object
The object contains information about the
labelfield.Show object fields- type string
The type of the field.
- required boolean
If
true, the field is required.- read_only boolean
If
true, you cannot edit the field.- label string
The name of the field.
- max_length integer
The maximum string value length.
- regexp string
A list of regular expressions that can be used.
- tracking_id object
The object contains information about the
tracking_idfield.Show object fields- type string
The type of the field.
- required boolean
If
true, the field is required.- read_only boolean
If
true, you cannot edit the field.- label string
The field name.
- max_length integer
The maximum string value length.
- confirmations_needed object
The object contains information about the
confirmations_neededfield.Show object fields- type string
The type of the field.
- required boolean
If
true, the field is required.- read_only boolean
If
true, you cannot edit the field.- label string
The field name.
- min_value integer
The minimum string value length.
- max_length integer
The maximum string value length.
- callback_url object
The object contains information about the
callback_urlfield.Show object fields- type string
The type of the field.
- required boolean
If
true, the field is required.- read_only boolean
If
true, you cannot edit the field.- label string
The field name.
- max_length integer
The maximum string value length.
- address-type object
The object contains information about the
address-typefield.Show object fields- type string
The type of the field.
- required boolean
If
true, the field is required.- read_only boolean
If
true, you cannot edit the field.- label string
The field name.
- max_length integer
The maximum string value length.
{
"data": {
"renders": [
"application/vnd.api+json"
],
"parses": [
"application/vnd.api+json",
"multipart/form-data"
],
"allowed_methods": [
"GET",
"POST",
"HEAD",
"OPTIONS"
],
"actions": {
"GET": {
"currency": {
"lookup_expr": "exact",
"regexp": "^[1-9][0-9]*$",
"max_length": 8,
"required": false
},
"wallet": {
"lookup_expr": "exact",
"required": false
},
"wallet_from": {
"lookup_expr": "exact",
"max_length": 64,
"required": false
},
"wallet_to": {
"lookup_expr": "exact",
"max_length": 64,
"required": false
},
"wallet_type": {
"lookup_expr": "exact",
"choices": [
{
"value": 1,
"display_name": "Merchant"
},
{
"value": 2,
"display_name": "Enterprise"
},
{
"value": 3,
"display_name": "Custody"
},
{
"value": 4,
"display_name": "NFT"
},
{
"value": 5,
"display_name": "Swap"
}
],
"required": false
},
"id": {
"lookup_expr": "exact",
"regexp": "^[1-9][0-9]*$",
"max_length": 8,
"required": false
},
"created_at_from": {
"lookup_expr": "exact",
"max_length": 32,
"required": false
},
"created_at_to": {
"lookup_expr": "exact",
"max_length": 32,
"required": false
},
"updated_at_from": {
"lookup_expr": "exact",
"max_length": 32,
"required": false
},
"updated_at_to": {
"lookup_expr": "exact",
"max_length": 32,
"required": false
},
"label": {
"lookup_expr": "icontains",
"max_length": 32,
"required": false
},
"tracking_id": {
"lookup_expr": "icontains",
"max_length": 128,
"required": false
},
"commission": {
"lookup_expr": "exact",
"regexp": "[-+]?[0-9]*\\.?[0-9]*",
"max_length": 32,
"required": false
},
"address": {
"lookup_expr": "exact",
"max_length": 256,
"required": false
},
"confirmations_needed": {
"lookup_expr": "exact",
"regexp": "^[1-9][0-9]*$",
"max_length": 2,
"required": false
},
"help_email": {
"lookup_expr": "exact",
"max_length": 64,
"required": false
},
"status": {
"lookup_expr": "exact",
"choices": [
{
"value": 2,
"display_name": "Created"
},
{
"value": 3,
"display_name": "Paid"
},
{
"value": 4,
"display_name": "Canceled"
},
{
"value": 5,
"display_name": "Unresolved"
}
],
"required": false
},
"time_limit": {
"lookup_expr": "exact",
"regexp": "^[1-9][0-9]*$",
"max_length": 8,
"required": false
},
"inaccuracy": {
"lookup_expr": "icontains",
"max_length": 32,
"required": false
},
"target_amount_requested": {
"lookup_expr": "exact",
"max_length": 32,
"required": false
},
"rate_requested": {
"lookup_expr": "exact",
"max_length": 32,
"required": false
},
"expired_at_from": {
"lookup_expr": "exact",
"max_length": 64,
"required": false
},
"expired_at_to": {
"lookup_expr": "exact",
"max_length": 64,
"required": false
},
"target_paid": {
"lookup_expr": "exact",
"max_length": 64,
"required": false
},
"enrolled": {
"lookup_expr": "exact",
"max_length": 64,
"required": false
},
"target_paid_pending": {
"lookup_expr": "exact",
"max_length": 64,
"required": false
},
"source_paid_pending": {
"lookup_expr": "exact",
"max_length": 64,
"required": false
},
"source_paid": {
"lookup_expr": "exact",
"max_length": 64,
"required": false
},
"source_commission": {
"lookup_expr": "exact",
"max_length": 64,
"required": false
},
"source_amount_requested": {
"lookup_expr": "exact",
"max_length": 64,
"required": false
}
},
"POST": {
"status": {
"type": "choice",
"required": false,
"read_only": false,
"label": "Status",
"choices": [
{
"value": 2,
"display_name": "Created"
},
{
"value": 3,
"display_name": "Paid"
},
{
"value": 4,
"display_name": "Canceled"
},
{
"value": 5,
"display_name": "Unresolved"
}
]
},
"currency": {
"type": "field",
"required": false,
"read_only": false,
"label": "Currency"
},
"address_type": {
"type": "string",
"required": false,
"read_only": false,
"label": "Address type",
"max_length": 16
},
"wallet": {
"type": "field",
"required": true,
"read_only": false,
"label": "Wallet"
},
"label": {
"type": "string",
"required": false,
"read_only": false,
"label": "Label",
"max_length": 32
},
"tracking_id": {
"type": "string",
"required": false,
"read_only": false,
"label": "Tracking id",
"max_length": 128
},
"confirmations_needed": {
"type": "integer",
"required": false,
"read_only": false,
"label": "Confirmations needed",
"min_value": 0,
"max_value": 100
},
"callback_url": {
"type": "url",
"required": false,
"read_only": false,
"label": "Callback url",
"max_length": 256
},
"inaccuracy": {
"type": "decimal",
"required": false,
"read_only": false,
"label": "Inaccuracy",
"min_value": 0
},
"time_limit": {
"type": "integer",
"required": false,
"read_only": false,
"label": "Time limit",
"min_value": 59,
"max_value": 2147483647
},
"target_amount_requested": {
"type": "decimal",
"required": false,
"read_only": false,
"label": "Target amount requested",
"min_value": 0
},
"payment_page": {
"type": "field",
"required": false,
"read_only": true,
"label": "Payment page"
},
"travel_rule_info": {
"type": "field",
"required": false,
"read_only": false,
"label": "Travel rule info"
}
}
}
}
}
Response codes
201 Success.
500 The request wasn’t completed due to an internal error on the server side.