3.4. /api/v2/get-balance
Introduction
Get Balance 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/ENDPOINTID | https://pay.billblend.com/checkout/api/v2/get-balance/ENDPOINTID |
Request Parameters
Note
Request must have content-type=application/x-www-form-urlencoded and Authorization headers.
| Parameter Name | Description | Value |
|---|---|---|
| balance-provider | Input your balance provider. | Necessity: RequiredType: 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 |
|---|---|
| balance-amount | Current balance. |
Request Example
POST /checkout/api/v2/get-balance/ 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_signature_method="HMAC-SHA1",oauth_signature="hSXMSUPP%2FIGYOOWpU4LVx0mu7SA%3D" Content-Length: 108 Content-Type: application/x-www-form-urlencoded Connection: close balance-provider=Test &oauth_consumer_key=balance_test_merchant14 &oauth_nonce=2xGTFuAgetE &oauth_signature_method=HMAC-SHA1 &oauth_timestamp=1686923599 &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
[
{
"balance-amount":29.99,
}
]
Fail Response Example
HTTP/1.1 200 Server: server Date: Fri, 16 Jun 2023 13:53:43 GMT Content-Length: 42 Connection: close X-XSS-Protection: 1 X-Content-Type-Options: nosniff Strict-Transport-Security: max-age=31536000 Strict-Transport-Security: max-age=31536000 error-message=Unknown balance provider saa
Postman Collection
Postman Collection is available at this link – https://doc.billblend.com/integration/API_commands/api_v2_get_balance.html#postman-collection
Request Builder
Request Builder is available at this link – https://doc.billblend.com/integration/API_commands/api_v2_get_balance.html#request-builder
| HTTP method | |
|---|---|
| endpoint | |
| 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="eQ8eK4Zrm2rS0FaMq3pvIgdMFEk%3D"' --data 'balance-provider=provider&oauth_consumer_key=merchantLogin&oauth_signature_method=HMAC-SHA1&oauth_version=1.0' 'https://sandbox.billblend.com/checkout/api/v2/get-balance/123'<?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-provider' => 'provider',
'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="eQ8eK4Zrm2rS0FaMq3pvIgdMFEk%3D"'
);
$responseFields = sendRequest('https://sandbox.billblend.com/checkout/api/v2/get-balance/123', $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-provider' => 'provider',
'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="eQ8eK4Zrm2rS0FaMq3pvIgdMFEk%3D"'
}
response_fields = send_request('https://sandbox.billblend.com/checkout/api/v2/get-balance/123', request_fields, custom_headers);
require 'pp'
pp response_fields
