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