Invoice methods

Invoice object

payment_page string

URL of the payment page provided to payers; the page contains address, tag, QR-code and registered incoming transfers.

address_type string

Address type. Refer to Deposit and invoice 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.

destination object

All possible options to specify the address of the invoice: an object if there is only one possible option, array of objects if there are several options. Each object contains three 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, applicable for XLM. Possible values:

  • 1 — a 64-bit unsigned integer

  • 2 — a string up to 28-bytes long

assets object

Amounts of incoming transfers in different currencies. The information is relevant for tokens, if both tokens and coins can be sent to a single address. In this case, the funds are 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 a key. Aggregated amounts are values.

label string

The invoice name for convenient search.

currency object

The invoice payment currency. Contains currency id (refer to Currency codes for supported values).

wallet object

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

INVOICE OBJECT
{
  "data": {
    "type": "deposit",
    "id": "205",
    "attributes": {
      "target_paid": "0.00",
      "payment_page": "https://pay.b2binpay.com/#/d/62e51de3-faaa-4701-b3e4-c11f207ca508",
      "address": "2NFvFBzuC7pkro5yr855JcU91KZkp4UAt6f",
      "destination": {
        "address_type": "p2sh-segwit",
        "address": "2NFvFBzuC7pkro5yr855JcU91KZkp4UAt6f"
      },
      "label": "test label",
      "tracking_id": "U-988",
      "confirmations_needed": 1,
      "callback_url": "https://my.client.url/cb/",
      "rate_requested": "9900.00000000",
      "rate_expired_at": "2021-09-17T07:35:38.352821Z",
      "invoice_updated_at": "2021-09-17T07:35:07.831725Z"
    },
    "relationships": {
      "wallet": {
        "data": {
          "type": "wallet",
          "id": "65"
        }
      },
      "currency": {
        "data": {
          "type": "currency",
          "id": "1000"
        }
      }
    }
  }
}

Get invoice

Request

id string

The invoice identifier.

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

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

headers = {
    'Authorization': 'Bearer <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/deposit/', [
        '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, an invoice 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 invoice with given id.

404 Invoice with given id not found.


Create invoice

Request

walletobject required

The identifier of the wallet to which the payments will be credited.

label string

The invoice name for convenient searching.

callback_url string

URL to send callback notifications. Specify this value to receive a callback when a new transaction occurs. Refer to Invoice callback for more details.

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. Refer to Invoice callback for more details.

tracking_id string or number

The invoice identifier in your system. This ID is used in callbacks.

address_type string

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

currency object

The invoice payment currency. Indicates the currency in which the payer will pay. The field also determines the blockchain and the rate at which the payment currency will be exchanged to the wallet currency and credited to the user wallet. If the field is blank, the invoice payment currency will be selected by a payer manually.

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": "test label",
                    "tracking_id": "U-988",
                    "confirmations_needed": 1,
                    "callback_url": "https://my.client.url/cb/"
                },
                "relationships": {
                    "currency": {
                       "data": {
                         "type": "currency",
                         "id": "1000"
                        }
                    },
                    "wallet": {
                        "data": {
                            "type": "wallet",
                            "id": "65"
                        }
                    }
                }  
            }
        }'
import requests

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

headers = {
    'Authorization': 'Bearer <Change to your access token>',
    'Idempotency-Key': '<UUID - generate version 4>',
    'Content-Type': 'application/vnd.api+json',
}

data = {
    'data': {
        'type': 'deposit',
        'attributes': {
            'label': 'test label',
            'tracking_id': 'U-988',
            'confirmations_needed': 1,
            'callback_url': 'https://my.client.url/cb/'
        },
        'relationships': {
            'currency': {
               'data': {
                 'type': 'currency',
                 'id': '1000'
                }
            },
            'wallet': {
                'data': {
                    'type': 'wallet',
                    'id': '1'
                }
            }
        }
    }
}

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/deposit/', [
        'json' => [
            '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',
                        ],
                    ],
                    'currency' => [
                       'data' => [
                         'type' => 'currency',
                         'id' => '1000',
                        ]
                    ],
                ],
            ],
        ],
        'headers' => [
            'Authorization' => 'Bearer <Change to your access token>',
            'Idempotency-Key' => '<UUID - generate version 4>',
            'Content-Type' => 'application/vnd.api+json',
        ]
    ]);
    echo $res->getBody();
} catch (RequestException $e) {}

Response

In case of a successful response, a newly created invoice object is returned, containing an address that your payers can use to send funds.

HTTP status codes

201 Success.

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


Invoice 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

  • 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 an invoice. 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 invoice transaction, a callback is sent to your server if the invoice request body includes a valid callback URL. You can use a callback to make changes in your system and notify your payers.

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.

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

The deposit parameters (data) are as follows:

address string

The identifier of the wallet to which the payment is credited.

created_at string

The time of the 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

The invoice identifier in your system.

destination object

All possible options to specify the address of the invoice: an object if there is only one possible option, array of objects if there are several options. Each object contains three 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, applicable for XLM. Possible values:

  • 1 — a 64-bit unsigned integer

  • 2 — a string up to 28-bytes long

currency object

The transaction currency. Contains currency id (refer to Currency codes for supported values).

wallet object

The identifier of the wallet to which the payments will be credited.

transfer object

The transaction identifier.

meta.time string

The time of the 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 a callback authentication. To verify that the callback was sent by us, 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 a message. Refer to Callback verification example below for a sign verification instance.

Transaction parameters (included) are described in Invoice object.

CALLBACK BODY
{
  "data": {
    "type": "deposit",
    "id": "11202",
    "attributes": {
      "address": "0xb5df932da8a243dc41e3f7c6134e6731686a55b8",
      "created_at": "2022-07-15T16:43:18.172135Z",
      "tracking_id": "",
      "target_paid": "597.83914298",
      "source_amount_requested": "0.000000000000000000",
      "target_amount_requested": null,
      "status": 2,
      "time_limit": null,
      "inaccuracy": "0.00000000",
      "destination": {
        "address_type": null,
        "address": "0xb5df932da8a243dc41e3f7c6134e6731686a55b8"
      }
    },
    "relationships": {
      "currency": {
        "data": {
          "type": "currency",
          "id": "1002"
        }
      },
      "wallet": {
        "data": {
          "type": "wallet",
          "id": "394"
        }
      },
      "transfer": {
        "data": {
          "type": "transfer",
          "id": "17616"
        }
      }
    }
  },
  "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": "17616",
      "attributes": {
        "op_id": 11202,
        "op_type": 1,
        "amount": "0.500000000000000000",
        "rate_target": "1195.67828595",
        "commission": "0.002000000000000000",
        "fee": "0.000000000000000000",
        "txid": "0x387c5c0fbd08f806e5ab1cf9bee1408a8f6a30ba66252cded72c21961aa2b266",
        "status": 2,
        "user_message": null,
        "created_at": "2022-07-15T16:46:48.017749Z",
        "updated_at": "2022-07-15T16:47:24.423418Z",
        "confirmations": 3,
        "risk": 0,
        "risk_status": 4,
        "amount_target": "595.44778640",
        "commission_target": "0",
        "amount_cleared": "595.44778640"
      },
      "relationships": {
        "currency": {
          "data": {
            "type": "currency",
            "id": "1002"
          }
        }
      }
    }
  ],
  "meta": {
    "time": "2022-07-15T16:47:24.675978+00:00",
    "sign": "5db6f651890a7889a0138b2c6dacc685cb60b2b651a1a631b0bbc7273befb3b4"
  }
}

Callback verification

Refer to the example below for a sign verification instance.

Callback verification example
<?php

# set API user login and password
$login = 'E8kOq803ktB7';
$password = 'E8kOq803ktB7';

# parse callback data
$callback_payload = json_decode(
    '
{
  "data": {
    "type": "payout",
    "id": "26",
    "attributes": {
      "address": "2NBr9k5xhvE2PxAAiFuczqQkeN76ShMdRZ6",
      "created_at": "2021-09-30T13:01:49.930612Z",
      "tracking_id": "12",
      "fee_amount": "0.00000823",
      "is_fee_included": false,
      "amount": "0.00010000",
      "destination": {
        "address_type": "legacy",
        "address": "2NBr9k5xhvE2PxAAiFuczqQkeN76ShMdRZ6"
      }
    },
    "relationships": {
      "wallet": {
        "data": {
          "type": "wallet",
          "id": "19"
        }
      },
      "currency": {
        "data": {
          "type": "currency",
          "id": "1000"
        }
      },
      "transfer": {
        "data": {
          "type": "transfer",
          "id": "145"
        }
      }
    }
  },
  "included": [
    {
      "type": "currency",
      "id": "1000",
      "attributes": {
        "iso": 1000,
        "name": "Bitcoin",
        "alpha": "BTC",
        "alias": null,
        "exp": 8,
        "confirmation_blocks": 3,
        "minimal_transfer_amount": "0.00000546",
        "block_delay": 3600
      }
    },
    {
      "type": "transfer",
      "id": "145",
      "attributes": {
        "confirmations": 3,
        "risk": 0,
        "risk_status": 4,
        "op_id": 26,
        "op_type": 2,
        "amount": "0.00010000",
        "commission": "0.00000000",
        "fee": "0.00000823",
        "txid": "c3cc36f4569fdbfaacdbc14647e5046d9f239ab1af0268b531a5a213411a8fc9",
        "status": 2,
        "message": null,
        "user_message": null,
        "created_at": "2021-09-30T13:01:50.273446Z",
        "updated_at": "2021-09-30T13:02:33.743770Z"
      },
      "relationships": {
        "currency": {
          "data": {
            "type": "currency",
            "id": "1000"
          }
        }
      }
    }
  ],
  "meta": {
    "time": "2021-09-30T13:02:34.059939+00:00",
    "sign": "8ef2a0f0c6826895593d0d137cf6ce7353a4bbe999d4a6c363f92f1e9d7f8e32"
  }
}
',
    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;