B2BinPAY Payment System Integration Guide
1. Scheme: Interaction with the payment system
2. Information about payment system
2.1. [gateway] URL
2.2. [currency node] URL
Coins that use Unique Payment Message(Destination Tag)
3. Obtaining a temporary token
OAuth 2.0 is used to access to Application Programming Interface (API) services.
To authorize and obtain the temporary token on the URL currency_domain/api/login, GET HTTP-request is sent with the following header:
Authorization: Basic base64_encode(key:secret)
In the case of successful authorization, the following HTTP-response (JSON) comes back:
Status: 200
Body: {
"token_type": "Bearer",
"access_token": TOKEN_WILL_BE_HERE,
"lifetime": TOKEN_LIFETIME,
}
In the case of error detection, the system returns the following information (JSON):
Status: 404|401
Body: {
"code": ERROR_CODE,
"error": ERROR_NAME
}
This temporary token used when accessing API services.
4. Creating a payment order
The POST method is used to create a payment order.
URL address: [currency node]/api/v1/pay/bills.
Whereas authorization is required to make the POST request, it is essential to provide temporary token in the HTTP-request header.
To create a payment order, the HTTP-request should be sent with the following header:
with the following parameters:
If lifetime is set to 0 (zero), created payment order will never expire.
In order to maintain the precision of small sums during transmission, capability to raise amount to the power is provided.
If the payment order is successfully created, the following HTTP-response comes back:
Status: 200
Body : {
"data": {
"id": ID,
"url": URL_TO_BILL_PAGE,
"address": BLOCKCHAIN_ADDRESS,
"created": TIME,
"expired": TIME|NULL,
"status": BILL_STATUS,
"tracking_id": TRACKING_ID,
"amount": AMOUNT_MULTIPLIED_BY_TEN_IN_POW,
"actual_amount":
ALREADY_PAID_AMOUNT_MULTIPLIED_BY_TEN_IN_POW,
"pow": POW,
"message": MESSAGE,
},
}
5. Data returned by callback
List of payment transactions in blockchain; Interest should be paid only to transaction field, which allows to request transaction in blockchain.
*Please note: It is very important to check the currency of every transaction received. In the event where an ERC20 token is sent to the ETH invoice, the system will send a callback for the ETH invoice and the ERC20 token alpha name(symbol) will be set in the field currency.
Array for signature check:
time – signature creation time
hash – hash of the string “key:secret:TIME“, where “key” and “secret” are data used for connection.
Method “bcrypt” based on “blowfish” algorithm was used to create hash.
"sign" =>
[
"time" => TIME
"hash" => HASH
]
When the data is successfully processed, the following response should be returned:
Status: 200 BODY : OK
6. Request for quotation
6.1. Request for quotes: deposit
The GET-method is used to request quotes.
You can also add the base currency alpha code at the end of the link (For example, https://gw.b2binpay.com/api/v1/rates/deposit/eur/).
The default base currency is the dollar (USD). Whereas authorization is required to make the request, it is essential to provide temporary token in the HTTP-request header.
To create a payment order, the HTTP-request should be sent with the following header:
If the request for quotes is successful, the following HTTP-response comes back:
Status: 200
Body : {
"data": [
{
"from": {
"alpha": BASE_CURRENCY_ALPHA,
"iso": BASE_CURRENCY_ISO
},
"to": {
"alpha": TARGET_CURRENCY_ALPHA,
"iso": TARGET_CURRENCY_ISO
},
"rate": RATE_MULTIPLIED_BY_TEN_IN_POW,
"pow": POW,
"expire": RATE_EXPIRE_TIMESTAMP
},
...
],
}
6.2. Request for quotes: withdrawal
The GET-method is used to request quotes.
You can also add the base currency alpha code at the end of the link (For example, https://gw.b2binpay.com/api/v1/rates/withdraw/eur/). The default base currency is the dollar (USD).
Whereas authorization is required to make the request, it is essential to provide temporary token in the HTTP-request header.
To create a payment order, the HTTP-request should be sent with the following header:
If the request for quotes is successful, the following HTTP-response comes back:
Status: 200
Body : {
"data": [
{
"from": {
"alpha": BASE_CURRENCY_ALPHA,
"iso": BASE_CURRENCY_ISO
},
"to": {
"alpha": TARGET_CURRENCY_ALPHA,
"iso": TARGET_CURRENCY_ISO
},
"rate": RATE_MULTIPLIED_BY_TEN_IN_POW,
"pow": POW,
"expire": RATE_EXPIRE_TIMESTAMP
},
...
],
}
7. Automatic withdrawal
The POST method is used to create a withdrawal.
Whereas authorization is required to make the POST request, it is essential to provide temporary token in the HTTP-request header.
To create a payment order, the HTTP-request should be sent with the following header:
with the following parameters:
If the withdrawal order is successfully created, the following HTTP-response comes back (in the same format data comes via POST-request on the callback_url specified in the parameters):
Status: 200
Body : {
"data": {
"id": ID,
"virtual_wallet_id": VIRTUAL_WALLET_ID,
"address": BLOCKCHAIN_ADDRESS,
"transaction": BLOCKCHAIN_TRANSACTION,
"created": TIME,
"callback_url": CALLBACK_URL|NULL,
"status": BILL_STATUS,
"tracking_id": TRACKING_ID,
"amount": AMOUNT_MULTIPLIED_BY_TEN_IN_POW,
"pow": POW,
"currency": {
"alpha": CURRENCY_ALPHA,
"iso": CURRENCY_ISO
},
},
}
Withdrawal status list
8. Payment statuses list
{
[
"id": ID,
"url":URL,
"address": ADDRESS_IN_BLOCKCHAIN,
"created": TIME,
"expired": TIME|NULL,
"status": BILL_STATUS,
"tracking_id": BILL_IDENTIFIER,
"amount": PAYMENT_AMOUNT,
"actual_amount": AMOUNT_OF_FUNDS_RECEIVED,
"pow": POW,
"transactions":
{
"id": TRANSACTION_ID,
"bill_id": BILL_ID,
"created": TIME_OF_PAYMENT_CREATION,
"amount": AMOUNT_MULTIPLIED_BY_TEN_IN_POW,
"pow": POW,
"status": TRANSACTION_STATUS,
"transaction": TRANSACTION_IN_BLOCKHAIN,
"type": TYPE (SEND|RECEIVE),
"currency": {
"iso": CURRENCY_ISO,
"alpha": CURRENCY_ALPHA
}
}
]
}
Transaction statuses list:
9. Examples of use
Test data used in the examples:
9.1. Obtaining a temporary token
cURL:
curl --request GET \ --url https://gw-test.b2binpay.com/api/login \ --header 'authorization: Basic MGZiYTgwYmY0MGZkOTMxOmYyMDNlZjdkMGY3NmE5OA=='
PHP:
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://gw-test.b2binpay.com/api/login",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => array(
"Authorization: Basic MGZiYTgwYmY0MGZkOTMxOmYyMDNlZjdkMGY3NmE5OA=="
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
9.2. Creating a payment order
cURL:
curl --request POST \ --url https://gw-test.b2binpay.com/api/v1/pay/bills \ --header 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJCMkJDcnlwdG9QYXkiLCJzdWIiOiIwZmJhODBiZjQwZmQ5MzEiLCJpYXQiOjE1MTE5MDY3MjIsImV4cCI6MTUyMDU0NjcyMn0.-AaTOAnhne-u8ioWMJrTozph_25mQhSTQGS2cx3tx6w' \ --header 'content-type: application/x-www-form-urlencoded' \ --data 'wallet=2&amount=100000&lifetime=0&pow=8'
PHP:
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://gw-test.b2binpay.com/api
/v1/pay/bills",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "wallet=2&amount=100000&lifetime=0&pow=8",
CURLOPT_HTTPHEADER => array(
"authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJCMkJDcnlwdG9QYXkiLCJzdWIiOiIwZmJhODBiZjQwZmQ5MzEiLCJpYXQiOjE1MTE5MDY3MjIsImV4cCI6MTUyMDU0NjcyMn0.-AaTOAnhne-u8ioWMJrTozph_25mQhSTQGS2cx3tx6w",
"content-type: application/x-www-form-urlencoded"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
9.3. Data returned by callback
Example Response:
{
"id": 11673,
"url": "https://gw-test.b2binpay.com/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJCMkJDcnlwdG9QYXkiLCJzdWIiOjExNjczLCJpYXQiOjE1ODAyOTI3MTgsImV4cCI6MTU4MDM3OTExOH0.3XtdxiRNfrDLLQCAX2HHEUmw1bo9CS5-wv8KtYHlGR0",
"address": "5e315a6e23e7e2a084e55c87b14bcdaad1f62fdbbac8e",
"created": "2020-01-29 10:11:58",
"expired": "2020-01-30 10:11:58",
"status": "2",
"tracking_id": "2",
"callback_url": "https://your.website.com/b2binpay/callback",
"amount": "500000000000000000",
"actual_amount": "500000000000000000",
"pow": "18",
"transactions": [
{
"id": "9742",
"bill_id": "11673",
"created": "2020-01-29 10:15:02",
"amount": "500000000000000000",
"pow": "18",
"status": "1",
"transaction": "NWUzMTVhNmUyM2U3ZTJhMDg0ZgU1Yzg3YjFlYmNkYWFkMWY2MmZkYmJhYzhlIzAuNTAwMDAwMDAwMDAwMDAwMDAw",
"type": "0",
"currency": {
"iso": "1000",
"alpha": "BTC"
},
"transfer_amount": "439617",
"transfer_pow": "2",
"transfer_currency": {
"iso": "840",
"alpha": "USD"
},
"transfer_rate": "883652509337",
"transfer_rate_pow": "8"
}
],
"currency": {
"iso": "1000",
"alpha": "BTC"
},
"sign":
{
"time": "Wed Jan 29 2020 10:15:06 GMT+0000",
"hash": "{HASH}"
}
}