3.7. /api/v2/get-exchange

Introduction

Get exchange rate is initiated through HTTPS POST request by using URLs and the parameters specified below. Use OAuth HMAC-SHA1 for authentication. See Statuses.

API URLs

Integration	Production
https://sandbox.billblend.com/checkout/api/v2/get-exchange/ENDPOINTID	https://pay.billblend.com/checkout/api/v2/get-exchange/ENDPOINTID

Request Parameters

Note

Request must have content-type=application/x-www-form-urlencoded and Authorization headers.

Parameter Name	Description	Value
exchange-provider	Exchange provider.	`Necessity`: Required`Type`: String`Length`: 128
exchange-currency-code-from	Currency code that need to exchange (See:Currency codes).	`Necessity`: Required`Type`: String`Length`: 128
exchange-currency-code-to	Currency code that need to get (See:Currency codes).	`Necessity`: Required`Type`: String`Length`: 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.

Parameter Name	Description
exchange-low-rate	Provider’s buy rate.
exchange-high-rate	Provider’s sell rate.

Request Example

POST /checkout/api/v2/get-exchange/39790 HTTP/1.1
Host: sandbox.billblend.com
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth realm="",oauth_version="1.0",oauth_consumer_key="test_merch",oauth_timestamp="1684995901",oauth_nonce="1kKy3hMlAe1",oauth_signature_method="HMAC-SHA1",oauth_signature="jGUaNFqLvBO1gGgWag%2FSU3wMnUc%3D"
Content-Length: 222
Content-Type: application/x-www-form-urlencoded
Connection: close

exchange-currency-code-from=USD
&exchange-currency-code-to=RUB
&exchange-provider=test
&oauth_consumer_key=test_merch
&oauth_nonce=1kKy3hMlAe1
&oauth_signature_method=HMAC-SHA1
&oauth_timestamp=1684995901
&oauth_version=1.0

Success Response Example

HTTP/1.1 200
Server: server
Date: Thu, 25 May 2023 06:27:46 GMT
Content-Length: 48
Connection: close
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Strict-Transport-Security: max-age=31536000

exchange-low-rate=10.00
&exchange-high-rate=20.00

Fail Response Example

HTTP/1.1 403
Server: server
Date: Thu, 25 May 2023 07:02:59 GMT
Content-Type: text/html
Content-Length: 735
Connection: close
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000

error-message=Book TCurrencyBook was not found by code USB

Postman Collection

Postman Collection is available at this link – https://doc.billblend.com/integration/API_commands/api_v2_get-exchange.html#postman-collection

Request Builder

Request Builder is available at this link – https://doc.billblend.com/integration/API_commands/api_v2_get-exchange.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="z7D5PWXbnz63NDsf3qsU2d5Ua0o%3D"' --data 'exchange-currency-code-from=RUB&exchange-currency-code-to=USD&exchange-provider=test&oauth_consumer_key=merchantlogin&oauth_signature_method=HMAC-SHA1&oauth_version=1.0' 'https://pay.billblend.com/checkout/api/v2/get-exchange/ENDPOINTID'

curl -H 'Authorization: OAuth realm="",oauth_version="1.0",oauth_consumer_key="merchantlogin",oauth_signature_method="HMAC-SHA1",oauth_signature="z7D5PWXbnz63NDsf3qsU2d5Ua0o%3D"' --data 'exchange-currency-code-from=RUB&exchange-currency-code-to=USD&exchange-provider=test&oauth_consumer_key=merchantlogin&oauth_signature_method=HMAC-SHA1&oauth_version=1.0' 'https://pay.billblend.com/checkout/api/v2/get-exchange/ENDPOINTID'

<?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(
    'exchange-provider' => 'test', 
    'exchange-currency-code-from' => 'RUB', 
    'exchange-currency-code-to' => 'USD', 
    '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="z7D5PWXbnz63NDsf3qsU2d5Ua0o%3D"'
);

$responseFields = sendRequest('https://pay.billblend.com/checkout/api/v2/get-exchange/ENDPOINTID', $requestFields, $customHeaders);

print_r($responseFields);

?>

<?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(
    'exchange-provider' => 'test', 
    'exchange-currency-code-from' => 'RUB', 
    'exchange-currency-code-to' => 'USD', 
    '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="z7D5PWXbnz63NDsf3qsU2d5Ua0o%3D"'
);

$responseFields = sendRequest('https://pay.billblend.com/checkout/api/v2/get-exchange/ENDPOINTID', $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 = {
    'exchange-provider' => 'test', 
    'exchange-currency-code-from' => 'RUB', 
    'exchange-currency-code-to' => 'USD', 
    '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="z7D5PWXbnz63NDsf3qsU2d5Ua0o%3D"'
}

response_fields = send_request('https://pay.billblend.com/checkout/api/v2/get-exchange/ENDPOINTID', request_fields, custom_headers);

require 'pp'
pp response_fields

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 = {
    'exchange-provider' => 'test', 
    'exchange-currency-code-from' => 'RUB', 
    'exchange-currency-code-to' => 'USD', 
    '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="z7D5PWXbnz63NDsf3qsU2d5Ua0o%3D"'
}

response_fields = send_request('https://pay.billblend.com/checkout/api/v2/get-exchange/ENDPOINTID', request_fields, custom_headers);

require 'pp'
pp response_fields