Enterprise API

Overview

The B2BinPay API is organized in accordance with JSON API paradigm. For a better understanding of the paradigm principles, read the JSON API Specification.

We use conventional HTTP response codes, OAuth 2.0 protocol for authentication, and HMAC-SHA256 algorithm for encryption.

Via the API you can get access to all the main entities of the payment system:

  • Wallets — read-only

  • Currencies — read-only

  • Transfers — read-only

  • Rates — read-only

  • Deposits — read/write access

  • Payouts — read/write access

Filters by object parameters can be applied to any GET-method according to the JSON API Specification.

We also provide flexible options for callback — an asynchronous notification about changing the status of a deposit/payout. To receive a callback, specify a callback URL when sending a Create Deposit or Create Payout request. When a transaction receives the required number of confirmations, we will send a callback via HTTP POST request to this URL. If you need to receive an additional notification when a transaction receives more or less number of confirmations, indicate this number in the request.

All methods are private. All requests except for Obtain Token and Refresh Token must contain HTTP header: Authorization: Bearer <Access Token>.

According to JSON API Specification all requests must contain HTTP header: Content-Type: application/vnd.api+json.

Required fields are marked with *.

Base URL

Code

Production

Sandbox

[base]

https://api.b2binpay.com/

https://api-sandbox.b2binpay.com/

Authentication

Obtain Token

Note

API credentials were sent to your e-mail after registration. You can regenerate them anytime in Control panel > API Access.

Request

login* string

Your API login

password* string

Your API secret

POST[base]/token/

$ curl --request POST \
       --url https://api.b2binpay.com/token/ \
       --header 'content-type: application/vnd.api+json' \
       --data '{
         "data": {
           "type": "auth-token",
           "attributes": {
             "login": "<Change to your login>",
             "password": "<Change to your secret>"
           }
         }
       }'

Response

access string

Your access token which has an expiry time of about a minute and after expiration must be refreshed

refresh string

A long-living token which is used for obtaining new access tokens

access_expired_at string

Expiration time for access token as per ISO 8601 with μs precision and timezone included: YYYY-MM-DDThh:mm:ss[.SSSSSS]±hh:mm

refresh_expired_at string

Expiration time for refresh token as per ISO 8601 with μs precision and timezone included: YYYY-MM-DDThh:mm:ss[.SSSSSS]±hh:mm

is_2fa_confirmed boolean

If true, then 2FA is enabled

meta.time string

Time of request receiving as per ISO 8601 with μs precision and timezone included: YYYY-MM-DDThh:mm:ss[.SSSSSS]±hh:mm

meta.sign string

HMAC signature for response payload authentication. To verify that the refresh token was sent by us, generate HMAC signature using sha256 as algorithm: sha256 hash of the concatenation of your login and password as key and the concatenation of meta.time and refresh token fields as a message. Ref. to Auth Verification for sign verification example

RESPONSE EXAMPLE
{
  "data": {
    "type": "auth-token",
    "id": "0",
    "attributes": {
      "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
      "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
      "access_expired_at": "2020-12-29T05:42:11.925654Z",
      "refresh_expired_at": "2020-12-29T11:27:11.925654Z",
      "is_2fa_confirmed": false
    }
  },
  "meta": {
    "time": "2020-12-29T05:27:11.925654Z",
    "sign": "bcd6519ce27fed2ce9efe49cd09b387f050c0122c962c18ff474132bf1e88e9a"
  }
}

HTTP Codes and Errors

200 Success

400 Bad Request. No active account found with the given credentials

429 Too Many Requests. More than 15 requests were sent in 60 seconds, the request was throttled


Refresh Token

Important

Once you receive a new key pair using your refresh token, the previous refresh token can no longer be used. If you detect that you refresh token is not expired yet but invalid then this is a suspicious case.

Request

refresh* string

Your refresh token from Obtain Token response

POST[base]/token/refresh/

$ curl --request POST \
       --url https://api.b2binpay.com/token/refresh/ \
       --header 'content-type: application/vnd.api+json' \
       --data '{
           "data": {
             "type": "auth-token",
             "attributes": {
               "refresh": "<Change to your refresh token>"
             }
           }
         }'

Response

Response body is the same as for Obtain Token request, but without meta fields.

RESPONSE EXAMPLE
{
  "data": {
    "type": "auth-token",
    "id": "0",
    "attributes": {
      "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
      "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
      "access_expired_at": "2020-12-29T05:42:11.925654Z",
      "refresh_expired_at": "2020-12-29T11:27:11.925654Z",
      "is_2fa_confirmed": false
    }
  }
}

HTTP Codes and Errors

200 Success

401 Refresh token is invalid or expired


Wallet Methods

Wallet Object

status number

Current status of the wallet:

  • 1 — Not active. The wallet is available only in read mode

  • 2 — In progress. The wallet is now being registered in the system and currently unavailable

  • 3 — Active. The wallet has been activated and can be used to create deposits and payouts

created_at string

Time of wallet creation as per ISO 8601 with μs precision and timezone included: YYYY-MM-DDThh:mm:ss[.SSSSSS]±hh:mm

balance_confirmed string

Available balance, that can currently be used for payouts

balance_pending string

Locked balance, the sum of all incoming and outgoing transfers, that have not yet received confirmation: positive in case of deposit and negative in case of payout. This balance cannot currently be used for transfers

balance_unusable string

Amount of funds that may not be used. They are not available but a part of them may be unblocked. The reason for temporary blocking may be a suspicious operation that does not correspond to AML/KYT rules. If transfer is failed or cancelled then its amount will be added to unusable balance

minimal_transfer_amount string

The minimal amount of crediting to the wallet in wallet currency. If the amount of the incoming transfer is less, it will be canceled

destination object

Contains 2 string fields: address_type — ref. to Deposit Address Types for supported values, and address — public wallet address, that can be used to directly top up wallet balance

currency object

Wallet currency. Contains currency id — ref. to Currency Codes for supported values

parent object

Parent wallet, applicable for token wallets only, for coin wallets returns null. Contains parent wallet id

WALLET OBJECT
{
  "data": {
    "type": "wallet",
    "id": "20",
    "attributes": {
      "status": 3,
      "created_at": "2020-11-06T06:03:44.301815Z",
      "balance_confirmed": "0.00000000",
      "balance_pending": "0.00000000",
      "balance_unusable": "0.23221548",
      "minimal_transfer_amount": "0.100000000000000000",
      "destination": {
        "address_type": "p2sh-segwit",
        "address": "2N3Ac2cZzRVoqfJGu1bFaAebq3izTgr1WLv"
      }
    },
    "relationships": {
      "currency": {
        "data": {
          "type": "currency",
          "id": "2005"
        }
      },
      "parent": {
        "data": {
          "type": "wallet",
          "id": "14"
        }
      }
    }
  }
}

Get Wallet

Request

id string

Wallet identifier

Filters by any object parameters can be applied according to the JSON API Specification.

GET[base]/wallet/{id}

$ curl --request GET \
       --url https://api.b2binpay.com/wallet/ \
       --header 'authorization: Bearer eyJ0eXAiOiJKV1QiLC...' \
       --header 'content-type: application/vnd.api+json'

Response

In the event of success, returns a wallet object or an array of objects (if id was not specified).

Note that wallets list is paginated and default page size is 10.

HTTP Codes and Errors

200 Success

400 Bad request. You have no permission to view the wallet with given id

404 The wallet with given id was not found


Currency Methods

Currency Object

iso number

Currency numeric identifier. Equivalent to id

name string

Currency full name like Bitcoin

alpha string

Currency alphabetic identifier like BTC

exp number

Currency precision (number of digits after decimal separator)

confirmation_blocks number

Default number of blocks needed to send a callback

block_delay number

Estimated block mining time in seconds

alias string

Ticker or alias. Used for finding similar currencies based on different blockchains

CURRENCY OBJECT
{
  "data": {
    "type": "currency",
    "id": "1000",
    "attributes": {
      "iso": 1000,
      "name": "Bitcoin",
      "alpha": "BTC",
      "alias": "",
      "exp": 8,
      "confirmation_blocks": 3,
      "block_delay": 3600
    }
  }
}

Get Currency

Request

id string

Currency identifier

Filters by any object parameters can be applied according to the JSON API Specification.

GET[base]/currency/{id}

$ curl --request GET \
       --url https://api.b2binpay.com/currency/ \
       --header 'authorization: Bearer eyJ0eXAiOiJKV1QiLC...' \
       --header 'content-type: application/vnd.api+json'

Response

In the event of success, returns a currency object or an array of objects (if id was not specified).

HTTP Codes and Errors

200 Success

404 Currency with given id not found


Transfer Methods

Transfer Object

confirmations number

Number of blockchain confirmations received

op_id number

Identifier of the associated operation

op_type number

Type of the associated operation:

  • 1 — deposit

  • 2 — payout

  • 5 — incoming transfer due to exchange execution

  • 9 — writing off costs associated with sending tokens. The amount of such a transfer includes outgoing dust and blockchain fee for the withdrawal of tokens

  • 14 — direct deposit to wallet’s address

  • 15 — transfer of the dust that came with the tokens

  • 16 — other wallet fees charging

  • 17 — outgoing transfer due to exchange execution

  • 19 — non-withdrawable activation transfer for Ripple, Stellar, Binance Coin

risk_status number

Status of the AML check:

  • 1 - transfer is checked and marked as green

  • 2 - transfer is in the queue for checking

  • 3 - transfer is checked and marked as red

  • 4 - transfers of this type are unavailable to check

risk number

Percent of AML risk for the transfer. Possible value range is from 0 to 100. The field can have null value if AML check was not performed

status number

Transfer status:

  • -3 — cancelled due to security reasons or small amount of transaction

  • -2 — temporarily blocked due to security reasons

  • -1 — failed in blockchain

  • 0 — created (pending in queue for processing)

  • 1 — unconfirmed (not enough confirmations or AML checking)

  • 2 — confirmed

amount string

Useful part of the transfer amount. It is considered as the transfer amount minus the blockchain commission. For deposit transfers, this field reflects the amount received

commission string

Processing fee amount

txid string

Address for received payment

fee string

Blockchain fee. For deposits always 0

message string

n/a Always null

user_message string

Notes or descriptions in case of errors

created_at string

Time of transfer creation as per ISO 8601 with μs precision and timezone included: YYYY-MM-DDThh:mm:ss[.SSSSSS]±hh:mm

updated_at string

Time of transfer update as per ISO 8601 with μs precision and timezone included: YYYY-MM-DDThh:mm:ss[.SSSSSS]±hh:mm

currency object

Transaction currency. Contains currency id — ref. to Currency Codes for supported values

wallet object

Wallet which the transaction is associated with. Contains wallet id and link to the wallet

parent object

Contains link to other transfer, when the transfer depends on another. In other cases returns null. Applicable mainly for tokens

TRANSFER OBJECT
{
  "data": {
    "type": "transfer",
    "id": "82",
    "attributes": {
      "confirmations": 487,
      "op_id": 2,
      "op_type": 18,
      "risk_status": 1,
      "risk": 15,
      "amount": "0.00001500",
      "commission": "0.00000000",
      "fee": "0.00000329",
      "txid": "4642e3ed5f78b9b9f08a6ca2799e0b9a840a0f4eae3ca4bffebae",
      "status": 2,
      "message": null,
      "user_message": null,
      "created_at": "2020-11-06T06:25:37.151758Z",
      "updated_at": "2020-11-06T08:17:16.453885Z"
    },
    "relationships": {
      "currency": {
        "data": {
          "type": "currency",
          "id": "1000"
        }
      },
      "wallet": {
        "data": {
          "type": "wallet",
          "id": "14"
        }
      },
      "parent": {
        "data": null
      }
    }
  }
}

Get Transfer

Request

id string

Transfer identifier

Filters by any object parameters can be applied according to the JSON API Specification.

GET[base]/transfer/{id}

$ curl --request GET \
       --url https://api.b2binpay.com/transfer/ \
       --header 'authorization: Bearer eyJ0eXAiOiJKV1QiLC...' \
       --header 'content-type: application/vnd.api+json'

Response

In the event of success, returns a transfer object or an array of objects (if id was not specified).

HTTP Codes and Errors

200 Success

400 Bad request

404 Transfer with given id not found


Rates Methods

Rate Object

left string

Base currency

right string

Quote currency

bid string

Bid price

ask string

Ask price

exp number

Currency precision (number of digits after decimal separator) for bid and ask fields

created_at string

Time of the rate creation

expired_at string

Time when the rate will be replaced with a more relevant one

RATE OBJECT
{
  "data": {
    "type": "rate",
    "id": "0",
    "attributes": {
      "left": "XRP",
      "right": "USD",
      "bid": "0.55",
      "ask": "0.57",
      "exp": 2,
      "expired_at": "2021-02-22T14:12:54.954810Z",
      "created_at": "2021-02-22T14:07:54.954810Z"
    }
  }
}

Get Rates

Request

Rates can be filtered by the left and right parameter according to the JSON API Specification. For example, with this filter applied /rates?filter[left]=BTC, the response body will only contain rates with BTC base currency.

GET[base]/rates/

$ curl --request GET \
       --url https://api.b2binpay.com/rates/ \
       --header 'authorization: Bearer eyJ0eXAiOiJKV1QiLC...' \
       --header 'content-type: application/vnd.api+json'

Response

In the event of success, returns an array of rates objects.

HTTP Codes and Errors

200 Success

400 Bad request


Deposit Methods

Deposit Object

target_paid string

Sum of transactions amount. After the creation equals to 0. This is how much user paid in total for this deposit

payment_page string

URL to payment page for payers, contains address, tag, QR-code and registered incoming transfers

address_type string

Address type. Ref. to Deposit 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 received payment

message string

n/a Always null

destination object or array

All possible options to specify the address of the deposit: object if there is only one possible option, array of objects if there are several options. Each object contains 3 string fields: address — actual address, address_type — type of the address, tag — destination tag (if required), used in conjunction with address tag_type — type of the tag or memo

assets object

Amounts of incoming transfers in different currencies. The information is relevant in the case of tokens, where both tokens and coins can be sent to single address. In this case, the money is credited not only to the wallet from the wallet field, but also to other wallets in other currencies. The alpha code of the currency is used as the key. Aggregated amounts are values

currency object

Wallet currency. Contains currency id — ref. to Currency Codes for supported values

wallet object

Wallet which the transaction is associated with. Contains wallet id and link to the wallet

DEPOSIT OBJECT
{
  "data": {
    "type": "deposit",
    "id": "3",
    "attributes": {
      "target_paid": "450.00",
      "payment_page": "https://pay.b2binpay.com/#/d/4ba00d23-21e8-4608-b4aa-804ae5474705",
      "address_type": "p2sh-segwit",
      "tracking_id": "2244",
      "confirmations_needed": null,
      "callback_url": "https://my.client.url/cb/",
      "address": "2NBYrj5JbiswTH5JXrxZ5Z8esujcmfPgaYR",
      "message": null,
      "destination": {
        "address_type": "p2sh-segwit",
        "address": "2NBYrj5JbiswTH5JXrxZ5Z8esujcmfPgaYR"
      },
      "assets": {
        "USDT": {
          "wallet_id": 7,
          "target_paid": "450.00",
          "target_commission": "2.25",
          "enrolled": "447.75",
          "target_paid_pending": "0.00",
          "blockchain_balance": "0.00"
        },
        "BTC": {
          "wallet_id": 3,
          "target_paid": "0.10000000",
          "target_commission": "0.00050000",
          "enrolled": "0.09950000",
          "target_paid_pending": "0.00000000",
          "blockchain_balance": "0.10000000"
        }
      }
    },
    "relationships": {
      "currency": {
        "data": {
          "type": "currency",
          "id": "2005"
        }
      },
      "wallet": {
        "data": {
          "type": "wallet",
          "id": "7"
        }
      }
    }
  }
}

Get Deposit

Request

id string

Deposit identifier

Filters by any object parameters can be applied according to the JSON API Specification.

GET[base]/deposit/{id}

$ curl --request GET \
       --url https://api.b2binpay.com/deposit/ \
       --header 'authorization: Bearer eyJ0eXAiOiJKV1QiLC...' \
       --header 'content-type: application/vnd.api+json'

Response

Returns a deposit object or an array of objects (if id was not specified).

HTTP Codes and Errors

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

Request

wallet* object

Identifier of the wallet to which the payments will be deposited

label string

Deposit name for convenient searching

callback_url string

URL to send callback notifications. Specify this value to receive a callback when a new transaction occurs. Ref. to Deposit Callback for more detail.

confirmations_needed number

Required number of confirmations to trigger an additional callback. Specify this value to receive an additional callback before or after the transaction is confirmed. Ref. to Deposit Callback for more detail.

tracking_id string or number

Deposit identifier in your system which is used in callbacks

address_type string

Address type, depends on currency. Ref. to Deposit Address Types for supported values

POST[base]/deposit/

$ curl --request POST \
       --url https://api.b2binpay.com/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"
                 }
               }
             }
           }
         }'

Response

In the event of success, returns a newly created deposit object containing an address that your payers can use to send funds.

HTTP Codes and Errors

201 Success

400 Bad request: invalid request parameters or required field value was not sent


Deposit Callback

Upon receiving a required number of confirmations of a new deposit transaction, a callback will be sent to your server if the body of the deposit contains a valid callback URL. You can use it to make changes in your system and notificate your payers.

The callback is sent by a POST request, which contains useful JSON payload. After processing the payload, you must respond with HTTP code 200 without a body. In case your server is temporary 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. In case the manual resending is required, you can do it via the Events.

A callback consist of two parts: the deposit itself (data) and the transaction received for this deposit (included).

address string

Identifier of the wallet to which the payments is deposited

created_at string

Time of 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

Deposit identifier in your system

target_paid string

If an additional callback is required before or after the transaction is confirmed, then you can set the number of confirmations which will trigger callback sending

destination object

All possible options to specify the address of the deposit: object if there is only one possible option, array of objects if there are several options. Each object contains 3 string fields: address — actual address, address_type — type of the address, tag — destination tag (if required), used in conjunction with address tag_type — type of the tag or memo

currency object

Transaction currency. Contains currency id — ref. to Currency Codes for supported values

wallet object

Identifier of the wallet to which the payments will be deposited

transfer object

Identifier of the transaction

meta.time string

Time of 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 callback authentication. To verify that the callback was sent by us, generate HMAC signature using sha256 as algorithm: sha256 hash of the concatenation of your login and password as key and the concatenation of transfer.status, transfer.amount, deposit.tracking_id, meta.time fields as message. Ref. to Callback Verification for sign verification example

CALLBACK BODY
{
  "data": {
    "type": "deposit",
    "id": "2",
    "attributes": {
      "address": "0xe68195f0a89dad8e38b91a6810304eed3b3dcddc",
      "created_at": "2021-03-31T12:56:04.013022Z",
      "tracking_id": "249",
      "target_paid": "0.100000000000000000",
      "destination": {
        "address_type": null,
        "address": "0xe68195f0a89dad8e38b91a6810304eed3b3dcddc"
      }
    },
    "relationships": {
      "currency": {
        "data": {
          "type": "currency",
          "id": "1002"
        }
      },
      "wallet": {
        "data": {
          "type": "wallet",
          "id": "2"
        }
      },
      "transfer": {
        "data": {
          "type": "transfer",
          "id": "8"
        }
      }
    }
  },
  "included": [
    {
      "type": "currency",
      "id": "1002",
      "attributes": {
        "iso": 1002,
        "name": "Ethereum",
        "alpha": "ETH",
        "alias": null,
        "exp": 18,
        "confirmation_blocks": 3,
        "block_delay": 30
      }
    },
    {
      "type": "transfer",
      "id": "8",
      "attributes": {
        "confirmations": 7,
        "tx_index": 5,
        "op_id": 2,
        "op_type": 1,
        "amount": "0.100000000000000000",
        "commission": "0.000400000000000000",
        "fee": "0.000000000000000000",
        "txid": "0x8e406b67c78ad5ac082a20199012be86c064384c1c0056726c0afeac5876e48a",
        "status": 2,
        "message": null,
        "user_message": null,
        "created_at": "2021-03-31T12:56:53.743021Z",
        "updated_at": "2021-03-31T12:58:31.846857Z"
      },
      "relationships": {
        "currency": {
          "data": {
            "type": "currency",
            "id": "1002"
          }
        }
      }
    }
  ],
  "meta": {
    "time": "2021-03-31T12:58:33.268880+00:00",
    "sign": "fc39668305faf2f85f60883b7ec42a5370b574e5e7bfdd21f30e7d1360198742"
  }
}

Payout Methods

Payout Object

amount string

Exact amount of payout in wallet currency

exp number

Currency precision (number of digits after decimal separator)

address string

Blockchain address of receiver wallet

tag_type string

Type of the tag or memo, applicable for XLM

tag string

Destination tag for XRP, XLM, BNB

destination object

All possible options to specify the receiver address, contains 3 string fields: address — actual address, address_type — type of the address, tag — destination tag (if required) for XRP, XLM, BNB

tracking_id string or number

Identifier of the payment in the external system

confirmations_needed number

Client-provided number of confirmations needed for send an additional callback

fee_amount string

Blockchain fee

is_fee_included boolean

If true, fee will be included in the payment amount, the remaining part will be credited to the receiver’s account. If false, fee will be additionally debited from the wallet. Note that for XRP, BNB, XLM, ETH, and token currencies fee cannot be included in the amount

message string

n/a Always null

status number

If payout approvement from wallet owner is required:

  • 1 - waiting for approve

  • 2 - approved

callback_url string

URL for callback notifications

currency object

Wallet currency. Contains currency id — ref. to Currency Codes for supported values

wallet object

Wallet which the transaction is associated with. Contains wallet id

PAYOUT OBJECT
{
  "data": {
    "type": "payout",
    "id": "21",
    "attributes": {
      "amount": "0.00000010",
      "exp": 8,
      "address": "2N3Ac2cZzRVoqfJGu1bFaAebq3izTgr1WLv",
      "tag_type": null,
      "tag": null,
      "destination": {
        "address_type": "legacy",
        "address": "2N3Ac2cZzRVoqfJGu1bFaAebq3izTgr1WLv"
      },
      "tracking_id": null,
      "confirmations_needed": null,
      "fee_amount": "0.00000329",
      "is_fee_included": false,
      "message": null,
      "status": 2,
      "callback_url": null
    },
    "relationships": {
      "currency": {
        "data": {
          "type": "currency",
          "id": "1000"
        }
      },
      "wallet": {
        "data": {
          "type": "wallet",
          "id": "13"
        }
      }
    },
    "links": {
      "self": "https://api.b2binpay.com/payout/21"
    }
  }
}

Get Payout

Request

id string

Payout identifier

Filters by any object parameters can be applied according to the JSON API Specification.

GET[base]/payout/{id}

$ curl --request GET \
       --url https://api.b2binpay.com/payout/ \
       --header 'authorization: Bearer eyJ0eXAiOiJKV1QiLC...' \
       --header 'content-type: application/vnd.api+json'

Response

In the event of success, returns a payout object or an array of objects (if id was not specified).

HTTP Codes and Errors

200 Success

400 Bad request. You have no permission to view the payout with given id

404 Payout with given id not found


Create Payout

Note

For security reasons, an additional HTTP header with a unique idempotency key must be sent in the request. The key is UUID4 string with hyphens, for example, 2dbcb513-bd35-404f-9709-e34878def180. Ref. to UUID Tools for recommended programming packages and libraries which you can use to generate UUID4.

Request

wallet* object

Identifier of the payment wallet

label string

Payout name for convenient searching

callback_url string

URL to send callback notifications

confirmations_needed number

If an additional callback is required before or after the transaction is confirmed, then you can set the number of confirmations which will trigger callback sending

tracking_id string or number

Payout dentifier in the external system which is used in callbacks

address_type string

Address type, depends on currency. Ref. to Deposit Address Types for supported values

POST[base]/payout/

$ curl --request POST \
       --url https://api.b2binpay.com/payout/ \
       --header 'authorization: Bearer eyJ0eXAiOiJKV1QiLC...' \
       --header 'content-type: application/vnd.api+json' \
       --header 'idempotency-key: b6891f5b-d16f-4ba9-a1c4-9828be64a492' \
       --data '{
           "data": {
             "type": "payout",
             "attributes": {
               "amount": "0.05",
               "address": "bcrt1q92k5z02dyrjahm4hput42nps3t7ryxzzz0vl76",
               "fee_amount": "0.00000550",
               "tracking_id": "f12",
               "confirmations_needed": 2,
               "callback_url": "https://my.client.com/cb/"
             },
             "relationships": {
               "wallet": {
                 "data": {
                   "type": "wallet",
                   "id": "1"
                 }
               }
             }
           }
         }'

Response

In the event of success, returns a newly created payout object.

HTTP Codes and Errors

201 Success

400 Bad request: insufficient funds


Precalculate Fee

For your convenience, we can calculate the blockchain fee options and processing commission before actual payout. The options for blockchain fee are as follows: low, medium, and high. For calculations, we need to know the ID of the wallet from which the payout is made, destination address, and the amount of the payout.

Request

amount* string

Payout amount

to_address* string

Payout destination address

wallet* object

Payout wallet

currency object

Payout currency

POST[base]/payout/calculate/

$ curl --request POST \
       --url https://api-sandbox.b2binpay.com/payout/calculate/ \
       --header 'authorization: Bearer <Change to your access token>' \
       --header 'content-type: application/vnd.api+json' \
       --data '{
           "data": {
             "type": "payout-calculation",
             "attributes": {
               "amount": "0.0000001",
               "to_address": "2N3Ac2cZzRVoqfJGu1bFaAebq3izTgr1WLv"
             },
             "relationships": {
               "wallet": {
                 "data": {
                   "type": "wallet",
                   "id": "13"
                 }
               },
               "currency": {
                 "data": {
                   "type": "currency",
                   "id": "1000"
                 }
               }
             }
           }
         }'

Response

In the event of success, the method returns the low, medium, and high fee values. If there are no recommendations or request parameters are invalid, than error or zeros at low, medium, and high levels will be returned.

is_internal boolean

This flag indicates if payout is internal

fee.low string

Economy mode when speed does not matter

fee.medium string

Optimum processing speed for a reasonable fee

fee.high string

Priority transaction processing through high fees

fee.currency number

Fee currency

commission.amount object

Commission amount

commission.currency number

Commission currency

FEE VALUES
{
  "data": {
    "type": "payout-calculation",
    "id": "0",
    "attributes": {
      "is_internal": true,
      "fee": {
        "low": "0.00000329",
        "medium": "0.00000823",
        "high": "0.00001647",
        "dust_amount": "0.00000000",
        "currency": 1000
      },
      "commission": {
        "amount": "0.00000000",
        "currency": 1000
      }
    }
  }
}

Payout Callback

Upon receiving a required number of confirmations of the transaction, a callback will be sent to your server if the body of the payout contains a valid callback URL. You can use it to make changes in your system and notificate your users.

The callback is sent by a POST request, which contains useful JSON payload. After processing the payload, you must respond with HTTP code 200 without a body. In case your server is temporary 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. In case the manual resending is required, you can do it via the Events.

Ref. to Deposit Callback for a callback example and descriptions.

Reference

Currency Codes

ISO Code

Name

Alpha Code

Alias

Precision

1000

Bitcoin

BTC

8

1002

Ethereum

ETH

18

1003

Litecoin

LTC

8

1005

DASH

DASH

8

1006

Bitcoin Cash

BCH

8

1010

Ripple

XRP

6

1019

Dogecoin

DOGE

8

1020

Zcash

ZEC

8

1021

Stellar

XLM

7

1026

Tron

TRX

6

1125

Binance Coin based on BSC

BNB-BSC

BNB

18

2005

TetherUS based on OMNI

USDT-OMNI

USDT

8

2014

USD Coin based on ERC20

USDC-ETH

USDC

6

2015

TetherUS based on ERC20

USDT-ETH

USDT

6

2021

Paxos Standard

PAX-ETH

PAX

18

2022

TrueUSD

TUSD-ETH

TUSD

18

2025

Binance Coin based on DEX

BNB-DEX

BNB

8

2068

Dai

DAI-ETH

DAI

18

2077

Binance USD

BUSD-ETH

BUSD

18

2085

Chainlink

LINK-ETH

LINK

18

2106

Akropolis

AKRO-ETH

AKRO

18

2107

Alpha Finance Lab

ALPHA-ETH

ALPHA

18

2108

Band Protocol

BAND-ETH

BAND

18

2110

bZx Protocol

BZRX-ETH

BZRX

18

2111

Chromia

CHR-ETH

CHR

6

2112

Compound

COMP-ETH

COMP

18

2113

Decentraland

MANA-ETH

MANA

18

2114

FTX Token

FTT-ETH

FTT

18

2115

Loopring

LRC-ETH

LRC

18

2117

NuCypher

NU-ETH

NU

18

2121

Reserve Rights

RSR-ETH

RSR

18

2122

Serum

SRM-ETH

SRM

6

2123

SHIBA INU

SHIB-ETH

SHIB

18

2125

Swipe

SXP-ETH

SXP

18

2126

Synthetix

SNX-ETH

SNX

18

2128

The Sandbox

SAND-ETH

SAND

18

2129

Uniswap

UNI-ETH

UNI

18

2131

Alpha Finance Lab

ALPHA-BSC

ALPHA

18

2132

Band Protocol

BAND-BSC

BAND

18

2133

Basic Attention Token

BAT-BSC

BAT

18

2134

Chainlink

LINK-BSC

LINK

18

2135

Maker

MKR-BSC

MKR

18

2136

Reef

REEF-BSC

REEF

18

2137

SushiSwap

SUSHI-BSC

SUSHI

18

2138

Swipe

SXP-BSC

SXP

18

2139

Synthetix

SNX-BSC

SNX

18

2140

Uniswap

UNI-BSC

UNI

18

2141

yearn.finance

YFI-BSC

YFI

18

2142

USD Coin based on TRC20

USDC-TRX

USDC

6

2145

TetherUS based on TRC20

USDT-TRX

USDT

6

2942

yearn.finance

YFI-ETH

YFI

18

2946

Maker

MKR-ETH

MKR

18

2948

0x

ZRX-ETH

ZRX

18

2951

Reef

REEF-ETH

REEF

18

2955

Basic Attention Token

BAT-ETH

BAT

18

2956

Ren

REN-ETH

REN

18

2961

SushiSwap

SUSHI-ETH

SUSHI

18

2962

The Graph

GRT-ETH

GRT

18

2964

Aave

AAVE-ETH

AAVE

18

2982

Polygon

MATIC-ETH

MATIC

18

Deposit Address Types

Currency

Types Available

Default

Description

BTC

legacy, p2sh-segwit

p2sh-segwit

USDT-OMNI

legacy, p2sh-segwit

p2sh-segwit

LTC

legacy, p2sh-segwit, bech32

bech32

BCH

legacy, cash

cash

The data.attributes.destination object will contain an array of two types of addresses at once

XRP

address, x-address

x-address

The data.attributes.destination object will contain an array of two types of addresses at once

UUID Tools

Here is a list of UUID tools for the most popular programming languages:

HMAC Tools

Here is a list of HMAC tools for the most popular programming languages:

Callback Verification

  1<?php
  2
  3# set API user login and password
  4$login = 'E8kOq803ktB7';
  5$password = 'E8kOq803ktB7';
  6
  7# parse callback data
  8$callback_payload = json_decode(
  9    '
 10{
 11  "data": {
 12    "type": "deposit",
 13    "id": "17",
 14    "attributes": {
 15      "address": "2NEHcZCGSoe5NZRXqKtAtRXCfsyxzQcKd7W",
 16      "created_at": "2021-08-03T13:19:55.891255Z",
 17      "tracking_id": null,
 18      "target_paid": "0.80000000",
 19      "destination": {
 20        "address_type": "p2sh-segwit",
 21        "address": "2NEHcZCGSoe5NZRXqKtAtRXCfsyxzQcKd7W"
 22      }
 23    },
 24    "relationships": {
 25      "currency": {
 26        "data": {
 27          "type": "currency",
 28          "id": "1000"
 29        }
 30      },
 31      "wallet": {
 32        "data": {
 33          "type": "wallet",
 34          "id": "1"
 35        }
 36      },
 37      "transfer": {
 38        "data": {
 39          "type": "transfer",
 40          "id": "61"
 41        }
 42      }
 43    }
 44  },
 45  "included": [
 46    {
 47      "type": "currency",
 48      "id": "1000",
 49      "attributes": {
 50        "iso": 1000,
 51        "name": "Bitcoin",
 52        "alpha": "BTC",
 53        "alias": null,
 54        "exp": 8,
 55        "confirmation_blocks": 3,
 56        "block_delay": 3600
 57      }
 58    },
 59    {
 60      "type": "transfer",
 61      "id": "61",
 62      "attributes": {
 63        "risk": 0,
 64        "confirmations": 3,
 65        "risk_status": 4,
 66        "tx_index": null,
 67        "nonce": null,
 68        "op_id": 17,
 69        "op_type": 1,
 70        "amount": "0.20000000",
 71        "commission": "0.00080000",
 72        "fee": "0.00000000",
 73        "txid": "91ae41bc8f82ca4acd1884c9e7e7557810e8acd7131c93097b45949bd167f5f3",
 74        "status": 2,
 75        "message": null,
 76        "user_message": null,
 77        "created_at": "2021-08-03T13:51:01.794570Z",
 78        "updated_at": "2021-08-03T13:51:04.022293Z"
 79      },
 80      "relationships": {
 81        "currency": {
 82          "data": {
 83            "type": "currency",
 84            "id": "1000"
 85          }
 86        }
 87      }
 88    }
 89  ],
 90  "meta": {
 91    "time": "2021-08-03T13:51:04.225876+00:00",
 92    "sign": "82fb1fe4f97722f857b7fe80be0e6b6f5b006a52314fb9c7c2783321b43de2bc"
 93  }
 94}
 95',
 96    true
 97    );
 98
 99$callback_sign = $callback_payload['meta']['sign'];
100$callback_time = $callback_payload['meta']['time'];
101
102# retrieve transfer and deposit attributes
103$included_transfer = array_filter(
104    $callback_payload['included'],
105    function ($item) {
106        return $item['type'] === 'transfer';
107    }
108);
109$included_transfer = array_pop($included_transfer)['attributes'];
110$deposit = $callback_payload['data']['attributes'];
111
112$status = $included_transfer['status'];
113$amount = $included_transfer['amount'];
114$tracking_id = $deposit['tracking_id'];
115
116# prepare data for hash check
117$message = $status . $amount . $tracking_id . $callback_time;
118$hash_secret = hash('sha256', $login . $password, true);
119$hash_hmac_result = hash_hmac('sha256', $message, $hash_secret);
120
121# print result
122if ($hash_hmac_result === $callback_sign) {
123    echo 'Verified';
124} else {
125    echo 'Invalid sign';
126}
127echo PHP_EOL;

Auth Verification

 1// "crypto-js": "4.0.0" is installed as a dependency
 2const SHA256 = require("crypto-js/sha256");
 3const hmacSHA256 = require('crypto-js/hmac-sha256');
 4
 5// set API user login and password
 6const login = 'nQns0adI5CZNj';
 7const password = '3BXNFKKthfRk07tM';
 8
 9// parse /api/token/ response payload
10const authResponse = JSON.parse("{\n" +
11    "  \"data\": {\n" +
12    "    \"type\": \"auth-token\",\n" +
13    "    \"id\": \"0\",\n" +
14    "    \"attributes\": {\n" +
15    "      \"refresh\": \"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUz\",\n" +
16    "      \"access\": \"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI\",\n" +
17    "      \"access_expired_at\": \"2020-08-24T13:50:12.192479+03:00\",\n" +
18    "      \"refresh_expired_at\": \"2020-08-24T19:33:33.192479+03:00\",\n" +
19    "      \"is_2fa_confirmed\": false\n" +
20    "    }\n" +
21    "  },\n" +
22    "  \"meta\": {\n" +
23    "    \"time\": \"2020-08-24T10:33:33.192479Z\",\n" +
24    "    \"sign\": \"e70adec551e26b560049e42aa0993ae42cac4e03fbbb300320d8be\"\n" +
25    "  }\n" +
26    "}");
27    
28// prepare data for hash check
29const message = authResponse['meta']['time'] + authResponse['data']['attributes']['refresh'];
30const responseSign = authResponse['meta']['sign'];
31const secret = SHA256(login + password);
32const calculatedSign = hmacSHA256(message, secret).toString();
33
34// print result
35if (responseSign === calculatedSign) {
36    console.log('Verified');
37} else {
38    console.log('Invalid sign');
39}