Deposit methods

Deposit object

NameTypeDescription

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 truecode>, 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 trueand 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 trueand 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

{
  "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"
    },
    "payment_page_redirect_url": "https://my.crm.com",
    "payment_page_button_text": "Back to CRM"
  },
  "relationships": {
    "currency": {
      "data": {
        "type": "currency",
        "id": "1000"
      }
    },
    "wallet": {
      "data": {
        "type": "wallet",
        "id": "448"
      }
    }
  }
}

Get deposit

Request

GET [base]/deposit/{id}

NameTypeRequiredDescription

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

curl --request GET \
--url [base]/deposit/ \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/vnd.api+json'

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 codeApplication codeDescriptionSuggested action

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/

NameTypeRequiredDescription

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

curl --request POST \
--url [base]/deposit/ \
--header 'Authorization: Bearer <token>.' \
--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/",
      "payment_page_redirect_url": "https://my.crm.com",
      "payment_page_button_text": "Back to CRM"
    },
    "relationships": {
      "wallet": {
        "data": {
          "type": "wallet",
          "id": "1"
        }
      }
    }
  }
}'

Response

In case of success, the response body contains a newly created deposit object.

Response codes

HTTP codeApplication codeDescriptionSuggested action

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.

Callback verification example
<?php

# set API user login and password
$login = 'Your API key';
$password = 'Your API secret';

# parse callback data
$callback_payload = json_decode (
  '{
    "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"
    }
  }',
  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;

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

{
  "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"
  }
}

Deposit options

Request

OPT [base]/deposit

No request parameters.

Request example

curl --request OPTIONS \
--url [base]/deposit/ \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/vnd.api+json' \

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 codeDescriptionSuggested action

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

{
  "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"
        }
      }
    }
  }
}

Last updated