Deposit methods
Deposit object
id
string
The unique system identifier of a deposit.
This value is generated automatically at the moment of deposit creation and can’t be changed.
status
number
The current deposit status. Possible values:
2
— Created — the deposit has just been created or hasn’t yet been paid in full (for deposits with indicated amounts). The deposits to Enterprise wallets are always assigned the Created status.3
— Paid — the deposit with the indicated amount was paid in full.4
— Canceled — the deposit was canceled by a user or expired with no payments received. A deposit in any status can be canceled by a user.5
— Unresolved — the deposit requires actions from the user. This status is possible in the following cases:If the amount of an incoming transfer is greater than the deposit amount.
If a payment is received after the specified expiration date.
If a payment is received for a deposit assigned the Paid or Canceled status.
is_actibe
boolean
Applicable for the Algorand blockchain only.
If true
code>, the address is activated.
In Algorand, any deposit address requires activation, that is sending 0.1–0.2 ALGO to the address. Until the address is activated, the field value is set to false
, funds can't be sent to the address. In B2BINPAY, the activation process is automated, the activation transfer has a type with the index 49. After the address is activated, the field value changes to true
and a callback is sent (if the callback URL was specified in the deposit settings), containing the deposit address.
Mind that:
Address activation takes some time, although it usually happens quickly.
The
address
field will remain empty until the deposit address is activated.Creating a deposit address costs from 0.1 (for coins) to 0.2 (for tokens) ALGO.
For other blockchains the value is always true
and insignificant.
address
string or null
The deposit address.
For deposits to Merchant wallets, if the payment currency wasn’t specified, the value is null
until a payer selects the payment currency. After that, this field is filled in with the address generated depending on the payment currency selected by the payer and can’t be changed.
For the Algorand blockchain, the value is null
until the deposit address is activated. Refer to is_active
for details.
address_type
string
For other payments, the value is an empty string.
label
string
The tag or name assigned to a deposit for easier locating it in the system.
This value is set when creating a deposit and can be changed anytime.
tracking_id
string
The identifier assigned to a deposit for easier locating related payments in external systems.
This value is set when creating a deposit and can be changed anytime.
confirmations_needed
number or null
The number of confirmations needed to trigger an additional callback.
If this field isn’t null
, two callbacks are sent: upon receiving the number of confirmations specified here and upon receiving the number of confirmations specified in the system settings. The corresponding transaction is assigned the Confirmed status as soon as the number of confirmations specified in this field received.
time_limit
number or null
Applicable for deposits to Merchant wallets only.
The lifetime of a deposit, in milliseconds, in the range from 59
to 2147483647
.
callback
string
The URL for callback notifications on new payments.
inaccuracy
string
Applicable for deposits to Merchant wallets with indicated amounts.
The payment delta, in the wallet currency.
The delta can be useful to address possible rate changes. For example, you create a deposit for 100 USDT with the expiration time of 10 minutes without specifying the payment currency. This means that the payer can pay in any currency within 10 minutes. But the rate of the currency pair may change within the specified time. In order to minimize your risks, you can set the delta value, for example of 5 USDT, which means that you expect payment from 95 USDT to 105 USDT (depending on the rate) within 10 minutes.
The delta can be also useful when the payment currency is the same as the wallet currency. For example, if you create a deposit with the indicated amount of 0.1 BTC, and the payer sends 0.1 BTC minus the commission, you won’t receive the full deposit amount. As a result, the deposit can’t be transferred to the Paid status. To avoid such situations, enter the delta value.
Mind that the delta must be less than the target_amount_requested
value.
target_amount_requested
string or null
Applicable for deposits to Merchant wallets only.
The requested deposit amount, in the wallet currency.
rate_requested
string or null
If the payment currency differs from the wallet currency, the value is the exchange rate of the payment currency to the wallet currency; otherwise, the value is 1
.
For Merchant wallets, if the payment currency wasn’t specified, the value is null
until a payer selects the payment currency. After that, this field is filled in with the current exchange rate.
rate_expired_at
string
The date and time of rate expiration.
invoice_updated_at
string or null
Applicable for deposits to Merchant wallets only.
For deposits with the expiration time specified: the date and time when the time limit was set or last updated. For other deposits the value is null
.
payment_page
string
The URL of a payment page.
target_paid
string
The total amount of funds that have already been received to the deposit address, in the wallet currency.
source_amount_requested
string
Applicable for deposits to Merchant wallets only.
The deposit amount, in the wallet currency. If the deposit currency is the same as the wallet currency, this value is calculated as target_amount_requested × 1
and then rounded up to the precision of the wallet currency (for example, to 8 digits after the decimal separator for BTC).
target_amount_requested
string
Applicable for deposits to Merchant wallets only, when the payment currency is selected and differs from the wallet currency.
The requested deposit amount, in the payment currency.
target_paid_pending
string
The amount of funds that have been received to the deposit address, but not yet credited, in the wallet currency.
assets
object
The amounts of incoming transfers in different currencies.
The alphabetic code of a currency is used as a key, the aggregated amounts are values.
destination
object or null
The deposit address.
For deposits to Merchant wallets, if the payment currency wasn’t specified, the value is null
until a payer selects the payment currency. After that, this field is filled in with the address generated depending on the payment currency selected by the payer and can’t be changed.
payment_page_redirect_url
string
The link that is displayed as a button on the payment page.
payment_page_button_text
string
The custom name of a button displayed on the payment page.
currency
object
The payment currency.
wallet
object
The wallet to which the deposit was made.
The object contains the string id
field matching the wallet system identifier.
Deposit object example
Get deposit
Request
GET
[base]/deposit/
{id}
id
string
No
The unique system identifier of a deposit.
Filtering by object parameters can be applied according to the JSON API Specification.
Request example
Response
In case of success, the response body contains a deposit object or an array of objects (if the id
wasn’t specified).
The wallets list is paginated and the default page size is 10. You can adjust pagination according to the JSON API Specification.
Response codes
200
—
The request succeeded.
—
400
5001: You can not view deposit
You don’t have permissions to view the deposit.
—
401
2007: No active account found with the given credentials
Incorrect credentials.
Send correct credentials.
404
404: Not found
The deposit with the given id
wasn’t found.
Send a correct id
.
500
—
Internal server error.
Try again later.
502
—
Bad gateway.
Try again later.
503
—
Service unavailable.
Try again later.
504
—
Gateway timeout.
Try again later.
5xx
—
Other server errors.
Try again later.
Create deposit
Before creating a deposit, you can retrieve parameters of the fields you need to fill in by calling the Deposit options method.
Request
POST
[base]/deposit/
label
string
No
The tag or name assigned to a deposit for easier locating it in the system.
The maximum string length is 32 characters.
tracking_id
string
No
The identifier assigned to a deposit for easier locating related payments in external systems.
The maximum string length is 128 characters.
confirmations_needed
number
No
The number of confirmations needed to trigger an additional callback, in the range from 0
to 100
.
callback_url
string
No
The URL for callback notifications on new payments.
The maximum string length is 256 characters.
payment_page_redirect_url
string
The link that is displayed as a button on the payment page.
payment_page_button_text
string
The custom name of a button displayed on the payment page.
id
string
Yes
The unique system identifier of a wallet to which deposit-related payments are made.
Request example
Response
In case of success, the response body contains a newly created deposit object.
Response codes
201
—
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
5005
The deposit address can’t be generated due to technical issues.
Try again later.
400
5006
The deposit rates can’t 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
A user is trying to make a transaction with a custom token that wasn’t 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.
500
—
Internal server error.
Try again later.
502
—
Bad gateway.
Try again later.
503
—
Service unavailable.
Try again later.
504
—
Gateway timeout.
Try again later.
5xx
—
Other server errors.
Try again later.
Deposit callback
A callback is a notification sent to a user’s callback URL when a new deposit-related transaction occurs in the blockchain. You can use the callback to make changes in your system and notify your payers.
Default callback
By default, the callback is sent after the transaction is confirmed. To get confirmed, a transaction should receive a necessary number of and pass the verification. The required number of confirmations is determined by the confirmation_blocks
field in the Currency object. For example, the confirmation_blocks
field is set to 3
. This means that the callback will be sent after receiving three confirmations and passing the AML check.
Additional callback
It’s possible to trigger an additional callback. To do this, specify a new number in the confirmations_needed
field when calling the Create deposit method. For example, the confirmation_blocks
value is set to 3
and the confirmations_needed
value is set to 1
. In this case, two callbacks will be sent: one (additional) after a transaction receives one confirmation and another one (default) after a transaction receives three confirmations.
Callback processing
Upon receiving a required number of confirmations related to a new deposit transaction, the callback is sent to your server if the deposit request body includes a valid callback URL. The callback is sent by a POST
-request, which contains useful JSON payload.
To verify that the callback was sent by B2BINPAY, 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.time
fields as message. Refer to the example below for a callback verification example.
After processing the payload, you should send back the HTTP 200
response code without a body. If your server is temporarily unavailable or the status of the response is different from 200
, the system will resend the callback several times with the increasing delay time. The number of re-sendings is limited. If the manual resending is required, you can do it on the Wallet management > Events page in the Web UI.
Callback structure
The callback consists of three parts:
data
— the deposit itself. Contains the Deposit object.included
— the transaction received for this deposit. Contains the Currency object and Transfer object (optional). There may be no Transfer object, if only the deposit status has changed. Keep in mind that transfer confirmation and deposit status changes are separate events that trigger two different callbacks.meta
— the metadata used for callback authentication. Contains the following fields:time
(string) — the date and time when the callback was sent.sign
(string) — the HMAC signature for a callback authentication. Refer to the Callback processing section for a callback verification example.
Callback body example
Deposit options
Request
OPT
[base]/deposit
No request parameters.
Request example
Response
In case of success, the response body contains an array of available methods along with a list of field parameters such as labels, min and max values, regular expressions used for validation, and so on.
Response codes
200
The request succeeded.
—
500
Internal server error.
The request wasn’t completed due to an internal error on the server side.
Response body example
Last updated