Deposit methods
Deposit object
Name | Type | Description |
---|---|---|
| string | The unique system identifier of a deposit. This value is generated automatically at the moment of deposit creation and can’t be changed. |
| number | The current deposit status. Possible values:
|
| boolean | Applicable for the Algorand blockchain only. If 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 Mind that:
For other blockchains the value is always |
| string or null | The deposit address. For deposits to Merchant wallets, if the payment currency wasn’t specified, the value is For the Algorand blockchain, the value is |
| string | For other payments, the value is an empty string. |
| 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. |
| 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. |
| number or null | The number of confirmations needed to trigger an additional callback. If this field isn’t |
| number or null | Applicable for deposits to Merchant wallets only. The lifetime of a deposit, in milliseconds, in the range from |
| string | The URL for callback notifications on new payments. |
| 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 |
| string or null | Applicable for deposits to Merchant wallets only. The requested deposit amount, in the wallet currency. |
| 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 For Merchant wallets, if the payment currency wasn’t specified, the value is |
| string | The date and time of rate expiration. |
| 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 |
| string | The URL of a payment page. |
| string | The total amount of funds that have already been received to the deposit address, in the wallet currency. |
| 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 |
| 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. |
| string | The amount of funds that have been received to the deposit address, but not yet credited, in the wallet currency. |
| 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. |
| object or null | The deposit address. For deposits to Merchant wallets, if the payment currency wasn’t specified, the value is |
| string | The link that is displayed as a button on the payment page. |
| string | The custom name of a button displayed on the payment page. |
| object | The payment currency. |
| object | The wallet to which the deposit was made. The object contains the string |
Deposit object example
Get deposit
Request
GET
[base]/deposit/
{id}
Name | Type | Required | Description |
---|---|---|---|
| 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
HTTP code | Application code | Description | Suggested action |
---|---|---|---|
| — | The request succeeded. | — |
| 5001: You can not view deposit | You don’t have permissions to view the deposit. | — |
| 2007: No active account found with the given credentials | Incorrect credentials. | Send correct credentials. |
| 404: Not found | The deposit with the given | Send a correct |
| — | Internal server error. | Try again later. |
| — | Bad gateway. | Try again later. |
| — | Service unavailable. | Try again later. |
| — | Gateway timeout. | Try again later. |
| — | 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/
Name | Type | Required | Description |
---|---|---|---|
| string | No | The tag or name assigned to a deposit for easier locating it in the system. The maximum string length is 32 characters. |
| string | No | The identifier assigned to a deposit for easier locating related payments in external systems. The maximum string length is 128 characters. |
| number | No | The number of confirmations needed to trigger an additional callback, in the range from |
| string | No | The URL for callback notifications on new payments. The maximum string length is 256 characters. |
| string | The link that is displayed as a button on the payment page. | |
| string | The custom name of a button displayed on the payment page. | |
| 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
HTTP code | Application code | Description | Suggested action |
---|---|---|---|
| — | The request succeeded. | — |
| 1007 | An invalid value was specified for a field. | Send valid values. |
| 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. |
| 3021 | A wallet activation transfer is required. | Make a transfer to activate the wallet. |
| 5005 | The deposit address can’t be generated due to technical issues. | Try again later. |
| 5006 | The deposit rates can’t be obtained due to technical issues. | Try again later. |
| 5007 | The currency value is required if the address type is specified. | Specify the currency value. |
| 6002 | The selected currency is disabled. | Select an active currency. |
| 6015 | The currency is unavailable for all clients or for a specific client. | Select an available currency. |
| 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. |
| — | Invalid data (serializer errors). | Send valid data. |
| 2007 | No active account with the given credentials is found. | Send correct credentials or update access tokens. |
| — | The request was throttled. | Try again later. |
| — | Internal server error. | Try again later. |
| — | Bad gateway. | Try again later. |
| — | Service unavailable. | Try again later. |
| — | Gateway timeout. | Try again later. |
| — | 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
HTTP code | Description | Suggested action |
---|---|---|
| The request succeeded. | — |
| Internal server error. | The request wasn’t completed due to an internal error on the server side. |
Response body example
Last updated