3.6. /api/v2/get-balance/merchant
Introduction
Get Balance by Merchant is initiated through HTTPS POST request by using URLs and the parameters specified below. Use OAuth HMAC-SHA1 for authentication. See Statuses. Also can be viewed on UI. Please contact support managers to enable this feature.
API URLs
| Integration | Production |
|---|---|
| https://sandbox.billblend.com/checkout/api/v2/get-balance/merchant/MERCHANTLOGIN | https://pay.billblend.com/checkout/api/v2/get-balance/merchant/MERCHANTLOGIN |
Request Parameters
Note
Request must have content-type=application/x-www-form-urlencoded and Authorization headers.
| Parameter Name | Description | Value |
|---|---|---|
| balance-name | Balance name. If this parameter is omitted, the result will give all available balances. | Necessity: OptionalType: StringLength: 128 |
Response Parameters
Note
Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Response Parameters | Description |
|---|---|
| name | Balance name. |
| amount | Current balance including STH and Rolling reserve. |
| online-balance-live-amount | Current balance calculated from configuration excluding STH and Rolling reserve. Live = current – STH – RR.. |
| total-short-term-hold-amount | Current amount of hold based on Date bumping function. |
| total-rolling-reserve-amount | Current amount calculated from rate plan hold. |
| currency | Currency used for selected balance. |
| amount-buffer-hold | Calculated amount for OUT operations without final status. |
Request Example
POST /checkout/api/v2/get-balance/merchant/balance_test_merchant14 HTTP/1.1 Host: sandbox.billblend.com User-Agent: curl/7.83.0 Accept: */* Authorization: OAuth realm="",oauth_version="1.0",oauth_consumer_key="balance_test_merchant14",oauth_timestamp="1686924613",oauth_nonce="qoJPcins4Aw",oauth_signature_method="HMAC-SHA1",oauth_signature="M6fTXbI0tFz4Dy7YEL3SBzCN1I0%3D" Content-Length: 161 Content-Type: application/x-www-form-urlencoded Connection: close balance-name=saa &oauth_consumer_key=balance_test_merchant14 &oauth_nonce=qoJPcins4Aw &oauth_signature_method=HMAC-SHA1 &oauth_timestamp=1686924613 &oauth_version=1.0
Success Response Example
HTTP/1.1 200
Server: server
Date: Tue, 16 May 2023 08:06:05 GMT
Content-Length: 192
Connection: close
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Strict-Transport-Security: max-age=31536000
[
{
"name":"Test1",
"amount":8854.000,
"online-balance-live-amount":8854.000,
"total-short-term-hold-amount":0.000,
"total-rolling-reserve-amount":0.000,
"currency":"AUD",
"amount-buffer-hold":0.000
}
]
Fail Response Example
HTTP/1.1 200
Server: server
Date: Tue, 16 May 2023 08:06:05 GMT
Content-Length: 192
Connection: close
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Strict-Transport-Security: max-age=31536000
...
<body>
<p>Access is denied</p>
</body>
Postman Collection
Postman Collection is available at this link – https://doc.billblend.com/integration/API_commands/api_v2_get_balance_merchant.html#postman-collection
Request Builder
Request Builder is available at this link – https://doc.billblend.com/integration/API_commands/api_v2_get_balance_merchant.html#request-builder
| HTTP method | |
|---|---|
| url | |
| parameters | |
| version | |
| consumer key | |
| consumer secret | |
| timestamp | |
| nonce | |
| signature method |
curl -H 'Authorization: OAuth realm="",oauth_version="1.0",oauth_consumer_key="merchantLogin",oauth_signature_method="HMAC-SHA1",oauth_signature="JY4HO4j0L405ZnBRmwoB64uq6wc%3D"' --data 'balance-name=TestName&oauth_consumer_key=merchantLogin&oauth_signature_method=HMAC-SHA1&oauth_version=1.0' 'https://sandbox.billblend.com/checkout/api/v2/get-balance/merchant/merchantLogin'<?php
/**
* Executes request
*
* @param string $url Url for payment method
* @param array $requestFields Request data fields
* @param array $customHeaders Custom request headers
*
* @return array Host response fields
*
* @throws RuntimeException Error while executing request
*/
function sendRequest($url, array $requestFields, array $customHeaders = array())
{
$curl = curl_init($url);
curl_setopt_array($curl, array
(
CURLOPT_HEADER => 1,
CURLOPT_USERAGENT => 'Billblend-Client/1.0',
CURLOPT_SSL_VERIFYHOST => 0,
CURLOPT_SSL_VERIFYPEER => 0,
CURLOPT_POST => 1,
CURLOPT_RETURNTRANSFER => 1
));
$headersJoiner = function($key, $value) {
return "{$key}: {$value}";
};
curl_setopt($curl, CURLOPT_HTTPHEADER, array_map($headersJoiner, array_keys($customHeaders), array_values($customHeaders)));
curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($requestFields));
$response = curl_exec($curl);
if(curl_errno($curl))
{
$error_message = 'Error occurred: ' . curl_error($curl);
$error_code = curl_errno($curl);
}
elseif(curl_getinfo($curl, CURLINFO_HTTP_CODE) != 200)
{
$error_code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$error_message = "Error occurred. HTTP code: '{$error_code}'. Response: {$response}";
}
curl_close($curl);
if (!empty($error_message))
{
throw new RuntimeException($error_message, $error_code);
}
if(empty($response))
{
throw new RuntimeException('Host response is empty');
}
$responseFields = array();
parse_str($response, $responseFields);
return $responseFields;
}
$requestFields = array(
'balance-name' => 'TestName',
'oauth_version' => '1.0',
'oauth_consumer_key' => 'merchantLogin',
'oauth_signature_method' => 'HMAC-SHA1',
);
$customHeaders = array(
'Authorization' => 'OAuth realm="",oauth_version="1.0",oauth_consumer_key="merchantLogin",oauth_signature_method="HMAC-SHA1",oauth_signature="JY4HO4j0L405ZnBRmwoB64uq6wc%3D"'
);
$responseFields = sendRequest('https://sandbox.billblend.com/checkout/api/v2/get-balance/merchant/merchantLogin', $requestFields, $customHeaders);
print_r($responseFields);
?>require 'net/http'
require 'uri'
require 'cgi'
##
# Executes request
#
# @param url [String] Url for payment method
# @param request_fields [Hash] Request data fields
# @param custom_headers [Hash] Custom request headers
#
# @return [Hash] Host response fields
def send_request(url, request_fields, custom_headers = [])
begin
uri = URI url
response = Net::HTTP.start uri.hostname, uri.port, :use_ssl => uri.scheme == 'https' do |http|
post = Net::HTTP::Post.new uri.request_uri
post.set_form_data request_fields
custom_headers.each do |key, value|
post[key] = value
end
http.request post
end
rescue Exception => e
raise RuntimeError, "Error occurred. #{e.message}"
end
unless Net::HTTPOK === response
raise RuntimeError, "Error occurred. HTTP code: '#{response.code}'. Response: '#{response.body}'"
end
unless response.body
raise RuntimeError, 'Host response is empty'
end
# Change hash format from {'key' => ['value']} to {'key' => 'value'} in map block
Hash[CGI.parse(response.body).map {|key, value| [key, value.first]}]
end
request_fields = {
'balance-name' => 'TestName',
'oauth_version' => '1.0',
'oauth_consumer_key' => 'merchantLogin',
'oauth_signature_method' => 'HMAC-SHA1',
}
custom_headers = {
'Authorization' => 'OAuth realm="",oauth_version="1.0",oauth_consumer_key="merchantLogin",oauth_signature_method="HMAC-SHA1",oauth_signature="JY4HO4j0L405ZnBRmwoB64uq6wc%3D"'
}
response_fields = send_request('https://sandbox.billblend.com/checkout/api/v2/get-balance/merchant/merchantLogin', request_fields, custom_headers);
require 'pp'
pp response_fields
