Payout methods

Payout object

amount string

Exact amount of the payout, in the wallet currency.

exp number

Currency precision (number of digits after the decimal separator).

address string

The blockchain address of the receiver wallet. If the payout for XRP is made to an x-address, entering a tag in the tag field is not necessary. If such a payout is made to a normal address, a user should enter the destination account address in combination with a destination tag.

tag_type string

Type of the tag or memo, applicable for XLM. Possible values:

  • 1 — a 64-bit unsigned integer

  • 2 — a string up to 28-bytes long

tag string

Destination tag for XRP, XLM, BNB.

destination object

All possible options to specify the receiver address; contains three 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

The identifier of the payment in the external system.

confirmations_needed number

Client-provided number of confirmations needed for sending an additional callback.

fee_amount string

The blockchain fee amount.

is_fee_included boolean

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

status number

If a payout should be approved by the wallet owner, the following values are posiible:

  • 1 — waiting for the approval

  • 2 — approved

callback_url string

URL for callback notifications.

currency object

The invoice payment currency.

wallet object

The wallet with which the transaction is associated. Contains the 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,
      "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

The payout identifier.

Filtering 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'
import requests

url = 'https://api.b2binpay.com/payout/'

headers = {
    'authorization': '<Change to your access token>',
    'content-type': 'application/vnd.api+json',
}

requests.get(url, headers=headers)
<?php

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

$client = new GuzzleHttp\Client();
try {
    $res = $client->get('https://api.b2binpay.com/payout/', [
        'headers' => [
            'Authorization' => 'Bearer <Change to your access token>',
            'Content-Type' => 'application/vnd.api+json',
        ],
    ]);
    echo $res->getBody();
} catch (RequestException $e) {}

Response

In case of a successful response, a payout object or an array of objects (if id was not specified) is returned.

HTTP status codes

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 a UUID4 string with hyphens: for example, 2dbcb513-bd35-404f-9709-e34878def180. Refer to Useful links for recommended programming packages and libraries that you can use to generate UUID4.

Request

walletobject required

The identifier of the payment wallet.

label string

The 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, set the number of confirmations that will trigger the callback. For more information, refer to Payout callback.

tracking_id string or number

The payout identifier in the external system which is used in callbacks.

address_type string

Address type, depends on a currency. Refer to Deposit and invoice address types for supported values.

address string

The wallet address to which the funds are sent.

amount string

The amount of the outgoing transfer.

currencyobject required

If the field is blank, the invoice payment currency will be selected by a payer manually.

tag string

Destination tag for XRP, XLM, BNB.

tag_type string

Type of the tag or memo, applicable for XLM. Possible values:

  • 1 — a 64-bit unsigned integer

  • 2 — a string up to 28-bytes long

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"
                     }
                 },
                 "currency": {
                     "data": {
                         "type": "currency",
                         "id": "1000"
                     }
                 }
             }
          }
      }'
import requests

from uuid import uuid4

url = 'https://api.b2binpay.com/payout/'

headers = {
    'authorization': 'Bearer <Change to your access token>',
    'content-type': 'application/vnd.api+json',
    'idempotency-key': str(uuid4()),
}

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',
                },
            },
            'currency': {
                'data': {
                    'type': 'currency',
                    'id': '1000',
                },
            },
        },
    },
}

requests.post(url, headers=headers, json=data)
<?php

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

$client = new GuzzleHttp\Client();
try {
    $res = $client->post('https://api.b2binpay.com/payout/', [
        'json' => [
            'data' => [
                'type' => 'payout',
                'attributes' => [
                    'tracking_id' => 'f12',
                    'confirmations_needed' => 2,
                    'callback_url' => 'https://my.client.com/cb/',
                    'amount' => '0.05',
                    'address' => 'bcrt1q92k5z02dyrjahm4hput42nps3t7ryxzzz0vl76',
                    'fee_amount' => '0.00000550',
                ],
                'relationships' => [
                    'wallet' => [
                        'data' => [
                            'type' => 'wallet',
                            'id' => '1',
                        ],
                    ],
                    'currency' => [
                        'data' => [
                            'type' => 'currency',
                            'id' => '1000',
                        ],
                    ],
                ],
            ],
        ],
        'headers' => [
            'Authorization' => 'Bearer <Change to your access token>',
            'Content-Type' => 'application/vnd.api+json',
            'Idempotency-key' => (string) Uuid::uuid4(),
        ],
    ]);
    echo $res->getBody();
} catch (RequestException $e) {}

Response

In case of a successful response, a newly created payout object is returned.

HTTP status codes

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 the 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 payout amount.

Request

amountstring required

The payout amount.

to_addressstring required

The payout destination address.

walletobject required

The payout wallet.

currencyobject required

The payout currency.

POST[base]/payout/calculate/

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

url = 'https://api.b2binpay.com/payout/calculate/'

headers = {
    'authorization': 'Bearer <Change to your access token>',
    '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',
         },
       },
     },
   },
 }

requests.post(url, headers=headers, json=data)
<?php

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

$client = new GuzzleHttp\Client();
try {
    $res = $client->post('https://api.b2binpay.com/payout/calculate/', [
        'json' => [
            'data' => [
                'type' => 'payout-calculation',
                'attributes' => [
                    'amount' => '0.05',
                    'to_address' => 'bcrt1q92k5z02dyrjahm4hput42nps3t7ryxzzz0vl76',
                ],
                'relationships' => [
                    'wallet' => [
                        'data' => [
                            'type' => 'wallet',
                            'id' => '1',
                        ],
                    ],
                    'currency' => [
                        'data' => [
                            'type' => 'currency',
                            'id' => '1000',
                        ],
                    ],
                ],
            ],
        ],
        'headers' => [
            'Authorization' => 'Bearer <Change to your access token>',
            'Content-Type' => 'application/vnd.api+json',
        ],
    ]);
    echo $res->getBody();
} catch (RequestException $e) {}

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, an error or zero low, medium and high values are returned.

is_internal boolean

If true, the 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 resulting in a higher fee.

fee.currency number

The fee currency.

commission.amount object

The commission amount.

commission.currency number

The 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

A callback is a notification sent to the user’s callback URL when a transaction (invoice or payout) occurs in a blockchain. By default, the callback is sent after the transaction is confirmed. To get confirmed, a transaction should meet the following requirements:

  • receive the necessary number of confirmations

  • pass AML verification (sometimes it may take longer than getting confirmations in the blockchain)

  • pass additional anti-fraud checks

The number of confirmations is determined by the confirmation_blocks field in the currency settings. For example, for USDT-ETH, the confirmation_blocks is set to 3. This means that after receiving three confirmations and passing AML and anti-fraud checks, a callback will be sent.

It is also possible to receive additional callbacks. To do this, specify a required number in the confirmations_needed field when creating a payout. For example, for USDT-ETH, the confirmation_blocks value is 3 and the confirmations_needed value is 1. This means that two callbacks will be sent: one (additional) after a transaction receives one confirmation and another one (default) after a transaction receives three confirmations.

Upon receiving a required number of confirmations related to a new payout transaction, a callback is sent to your server if the payout request body includes a valid callback URL. You can use a callback to make changes in your system and notify your users.

The callback is sent by a POST request, which contains useful JSON payload. After processing the payload, you should respond with an HTTP code 200 without a body. If your server is temporarily unavailable or the status of the response is different from 200, we will resend the callback several times with the increasing delay time. The number of resendings is limited. If the manual resending is required, you can do it via the Events.

Refer to Invoice callback for a callback example and descriptions.