2.2. Request Authentication Methods

SHA-1

To generate request with SHA-1 authentication:

Generate Signature,
Generate Request.

SHA1 Signature Generation

Concatenate all necessary parameters to String (also referred as a “signing string” or “signature base string”). Each API-command might have it’s own list and order of parameters to concatenate in signing string. Check it in the description of control parameter for the relevant API-command with SHA-1 authentication.

Note

Use minimal monetary units for amount (i.e. cent, penny etc. For amount of 0.94 USD value in signing string will be 94, for 10.15 USD value in signing string will be 1015)

For example, parameters:
```
endpointid=1111
client_orderid=902B4FF5
amount=10.42
email=john.smith@gmail.com
merchant_control=B17F59B4-A7DC-41B4-8FF9-37D986B43D20
```
will be concatenated to the string:
```
1111902B4FF51042john.smith@gmail.comB17F59B4-A7DC-41B4-8FF9-37D986B43D20
```

Encrypt the received string using SHA-1:

Java SHA-1 Generation Example:

package com.Billblend;

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

public class HashTextTest {

/**
* @param args
* @throws NoSuchAlgorithmException
*/

   public static void main(String[] args) throws NoSuchAlgorithmException {
      System.out.println(sha1("test string to sha1"));
   }

   static String sha1(String input) throws NoSuchAlgorithmException {
      MessageDigest mDigest = MessageDigest.getInstance("SHA1");
      byte[] result = mDigest.digest(input.getBytes(StandardCharsets.UTF_8));
      StringBuilder sb = new StringBuilder();
      for (byte b : result) {
         sb.append(Integer.toString((b & 0xff) + 0x100, 16).substring(1));
      }
      return sb.toString();
   }
}

JavaScript SHA-1 Generation Example

<script src="http://crypto-js.googlecode.com/svn/tags/3.1.2/build/rollups/sha1.js"></script>
<script type="text/javascript">
   var sha1value = CryptoJS.SHA1("test string to sha1");
</script>

Bash + openssl SHA-1 Generation Example

echo -n "test string to sha1" | openssl dgst -sha1

After that signature will look like this:

c6bdd88a78834ef4b863b088827a459f039e8257

SHA1 Request Generation

To make request use generated signature as the value of parameter control in request body.

Example of Request:

Request method: POST
Request URI: https://pay.billblend.com/checkout/api/v2/sale/1111
Body: client_orderid=902B4FF5&order_desc=Test Order Description&first_name=John&last_name=Smith&ssn=1267&birthday=19820115&address1=100 Main st&city=Seattle&state=WA&zip_code=98102&country=US&phone=+12063582043&cell_phone=+19023384543&amount=10.42&email=john.smith@gmail.com&currency=USD&ipaddress=65.153.12.232&site_url=https://doc.billblend.com/&credit_card_number=4538977399606732&card_printed_name=CARD HOLDER&expire_month=12&expire_year=2099&cvv2=123&purpose=user_account1&control=c6bdd88a78834ef4b863b088827a459f039e8257

Example of CURL Request:

curl --data "
   client_orderid=902B4FF5
   &order_desc=Test Order Description
   &first_name=John
   &last_name=Smith
   &ssn=1267
   &birthday=19820115
   &address1=100 Main st
   &city=Seattle
   &state=WA
   &zip_code=98102
   &country=US
   &phone=+12063582043
   &cell_phone=+19023384543
   &amount=10.42
   &email=john.smith@gmail.com
   &currency=USD
   &ipaddress=65.153.12.232
   &site_url=https://doc.billblend.com/
   &credit_card_number=4538977399606732
   &card_printed_name=CARD HOLDER
   &expire_month=12
   &expire_year=2099
   &cvv2=123
   &purpose=user_account1
   &control=c6bdd88a78834ef4b863b088827a459f039e8257
" https://pay.billblend.com/checkout/api/v2/sale/1111

OAuth HMAC-SHA1

To generate request with OAuth HMAC-SHA1 authentication:

Generate Signature,
Generate Headers,
Generate Request.

OAuth HMAC-SHA1 Signature Generation

To prepare the Signature Base String do the following steps:

Gather all request body parameters and OAuth parameters (oauth_consumer_key, oauth_nonce, oauth_signature_method, oauth_timestamp, oauth_version):

For oauth_consumer_key use a merchant login provided by Payment Gateway, ex. merchantlogin.

For oauth_nonce generate unique random nonce, ex. y3qlvMPky7g.

For oauth_signature_method set HMAC-SHA1.

For oauth_timestamp header get current timestamp in seconds, ex. 1669966913.

For oauth_version set 1.0.

Parameter oauth_signature is not included in request body parameters (only in OAuth header).
Percent-encode value of each gathered on step 1 parameter. See RFC 3986 for reference. The unreserved characters can be encoded, but should not be encoded. The reserved characters have to be encoded, for example: % is encoded to %25, / is encoded to %2F, = is encoded to %3D.
Sort all gathered on step 1 parameters together with their values in lexicographical order by parameter name.

Concatenate all gathered on step 1 parameters and their values using & and = in the following way:

object1=valueOfObject1&object2=valueOfObject2...

Concatenated parameters string example:

client-order-id=1234567890&oauth_consumer_key=merchantlogin&oauth_nonce=y3qlvMPky7g&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1669966913&oauth_version=1.0&sending-card-ref-id=7654321

Percent-encode each element (POST, URL, concatenated parameters) and construct Signature Base String with POST&URL&parameters structure (as documented in OAuth A.5.1.). | Signature Base String Example:

POST&https%3A%2F%2Fpay.billblend.com%2Fpaynet%2Fapi%2Fv2%2Fpan-eligibility%2Fsend%2FENDPOINTID&client-order-id%3D1234567890%26oauth_consumer_key%3Dmerchantlogin%26oauth_nonce%3Dy3qlvMPky7g%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1669966913%26oauth_version%3D1.0%26sending-card-ref-id%3D7654321

Encrypt Signature Base String with HMAC-SHA1. Encryption key is the concatenation of consumer secret (Merchant control key) + & + token secret (empty string).

HMAC-SHA1 Key Example:
```
11111111-1111-1111-1111-111111111111&
```

Encode encrypted string to Base64 to get signature.

Java HMAC-SHA1 Signature Generation Example:

package com.Billblend;

import org.apache.commons.codec.binary.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;

public class HMAC_SHA1 {
   private static final String HMAC_SHA1_ALGORITHM = "HmacSHA1";

   public static String calculateHMAC(String data, String key) throws NoSuchAlgorithmException, InvalidKeyException {
      SecretKeySpec signingKey = new SecretKeySpec(key.getBytes(), HMAC_SHA1_ALGORITHM);
      Mac mac = Mac.getInstance(HMAC_SHA1_ALGORITHM);
      mac.init(signingKey);
      return Base64.encodeBase64String(mac.doFinal(data.getBytes()));
   }
}

Signature will look like following string:

d/IPlITUmPcniwjA7Vckjr6WQeE=

OAuth HMAC-SHA1 Headers Generation

A request with OAuth HMAC-SHA1 authentication method must contain next headers:

content-type=application/x-www-form-urlencoded
Authorization: OAuth

OAuth header must contain the same OAuth parameters and values which were included in signature base string (oauth_consumer_key, oauth_nonce, oauth_signature_method, oauth_timestamp, oauth_version). Add signature as value of parameter oauth_signature to header Authorization. All values of parameters in OAuth header must be in quotes (See OAuth 5.4.1.) with the following structure: parameter=”value” and be separated by mandatory comma (,) and optional space. OAuth realm parameter is optional.

Authorization Header Example (Header is line-separated for display purposes):

Authorization: OAuth
oauth_consumer_key="merchantlogin",
oauth_nonce="y3qlvMPky7g",
oauth_signature="d/IPlITUmPcniwjA7Vckjr6WQeE=",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="1669966913",
oauth_version="1.0"

OAuth HMAC-SHA1 Request Generation

Use headers from previous section,
Add request parameters to body,
Percent-encode and send the request.

Example of Request:

Request method:      POST
Request URI: https://pay.billblend.com/checkout/api/v2/pan-eligibility/send/1111
Headers: Authorization=OAuth realm="",oauth_version="1.0",oauth_consumer_key="merchantlogin",oauth_timestamp="1669966913",oauth_nonce="y3qlvMPky7g",oauth_signature_method="HMAC-SHA1",oauth_signature="d%2FIPlITUmPcniwjA7Vckjr6WQeE%3D"
         Accept=*/*
         Content-Type=application/x-www-form-urlencoded; charset=ISO-8859-1
Body: client-order-id=1234567890&oauth_consumer_key=merchantlogin&oauth_nonce=y3qlvMPky7g&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1669966913&oauth_version=1.0&sending-card-ref-id=7654321

Example of CURL Request:

curl -H '
   Authorization: oauth_version="1.0",
   oauth_consumer_key="merchantlogin",
   oauth_timestamp="1669966913",
   oauth_nonce="y3qlvMPky7g",
   oauth_signature_method="HMAC-SHA1",
   oauth_signature="d%2FIPlITUmPcniwjA7Vckjr6WQeE%3D"
' --data '
   client-order-id=1234567890
   &oauth_consumer_key=merchantlogin
   &oauth_nonce=y3qlvMPky7g
   &oauth_signature_method=HMAC-SHA1
   &oauth_timestamp=1669966913
   &oauth_version=1.0
   &sending-card-ref-id=7654321
' 'https://pay.billblend.com/checkout/api/v2/pan-eligibility/send/ENDPOINTID'

OAuth RSA-SHA256

To generate request with OAuth RSA-SHA256 authentication:

Generate Key Pair,
Generate Signature,
Generate Headers,
Generate Request.

Generating Key Pair

To authorize future requests with RSA-SHA256, generate the key pair:

A PRIVATE key to sign the request. This private key must be kept secret from everyone.
A PUBLIC key to verify that the request was signed with the respective private key. Send it to support manager.

To generate keys download latest version of openssl and run following commands:

openssl genpkey -algorithm RSA -out private_key_pkcs_8.pem -pkeyopt rsa_keygen_bits:4096
openssl rsa -pubout -in private_key_pkcs_8.pem -out public_key.pem

Use different keys for production and for testing purposes to avoid compromise.

To use request builders in documentation, get the private key in PKCS#1 container. It should be unencrypted RSA private key in PKCS#1 PEM text format. To get it use the following command:

openssl rsa -in private_key_pkcs_8.pem -out private_key_pkcs_1.pem

For OpenSSL v3+ (tested on v3.0.5), use the following command instead:

openssl rsa -traditional -in private_key_pkcs_8.pem -out private_key_pkcs_1.pem

The resultant PKCS#1 RSA private key will start with —–BEGIN RSA PRIVATE KEY—–. For production purposes any format of the key supported by Connecting Party software can be used. Request builders in documentation support key length up to 4096. Example of the PKCS#1 RSA private key:

OAuth RSA-SHA256 Signature Generation

To prepare the Signature Base String do the following steps:

Gather all request body parameters and OAuth parameters (oauth_consumer_key, oauth_nonce, oauth_signature_method, oauth_timestamp, oauth_version):

For oauth_consumer_key use a merchant login provided by Payment Gateway, ex. paydroid.

For oauth_nonce generate unique random nonce, ex. hoFlZri9c17X1Tvb7yD2fsMEQUIWBQ3m.

For oauth_signature_method set RSA-SHA256.

For oauth_timestamp header get current timestamp in seconds, ex. 1669720957.

For oauth_version set 1.0.

Parameter oauth_signature is not included in request body parameters (only in OAuth header).
Percent-encode value of each gathered on step 1 parameter. See RFC 3986 for reference. The unreserved characters can be encoded, but should not be encoded. The reserved characters have to be encoded, for example: % is encoded to %25, / is encoded to %2F, = is encoded to %3D.
Sort all gathered on step 1 parameters together with their values in lexicographical order by parameter name.
Concatenate all gathered on step 1 parameters and their values using & and = by the following way:

object1=valueOfObject1&object2=valueOfObject2...

Percent-encode each element (POST, URL, concatenated parameters) and construct Signature Base String with POST&URL&parameters structure (as documented in OAuth A.5.1.). | Signature Base String Example:

POST&https%3A%2F%2Fpay.billblend.com%2Fpaynet%2Fapi%2Fv4%2Ftransfer%2FENDPOINTID&amount%3D10.42%26card_printed_name%3DJohn%2520Doe%26card_recurring_payment_id%3D42322%26client_orderid%3D1%26credit_card_number%3D4210708776705721%26currency%3DUSD%26cvv2%3D123%26deposit2card%3Dfalse%26destination-card-no%3D4232618181101636%26destination_card_recurring_payment_id%3D61622%26expire_month%3D12%26expire_year%3D2099%26ipaddress%3D1.1.1.1.1%26oauth_consumer_key%3Dpaydroid%26oauth_nonce%3DhoFlZri9c17X1Tvb7yD2fsMEQUIWBQ3m%26oauth_signature_method%3DRSA-SHA256%26oauth_timestamp%3D1669720957%26oauth_version%3D1.0%26order_desc%3DYour%2520order%2520description%26redirect_url%3Dhttp%253A%252F%252Fwww.example.com

Encrypt Signature Base String with RSA-SHA256 using the private key obtained in previous section.

Base64 encode the encrypted string to get signature.

Base64 Encoded Signature Example:

K0hLc7GYh65UDTNvJvJbqoD95T7ekVEwIx+AxLBe2rNndPVzCAZMTi58J5pJlXZA1qOrgzUj/uL764NofP6qrqBXHX9Fpg+PdoMBey7zY9nMOmtdpHhkwyqA0n8e8oh68x+8RtC1+gmaIsIJDVurpCm2CdaViC2ny90GWPrrSin9CFwDmIKBtOJ7dxNnuFQJkvLxwK9JE9gRfQssG4vOrXrn2f5DvENFvFW3fL7meiN3mKuBFyEHIv2cibWopoUTQrxAgCfTHvRuU5nRIct9oWgCYLYzROOPyAIjtyDFKcTnUql9+tD2+p2rMDDU7HqJUGy764rb4ShuvuiuEvzIaNwg3JAxho9fqcKJz5LXt4efX1i8oFt33ztYSgZRojsoW4HCzuhZcQQmRexpmtCGYKqH3Q2BsG2jIkQAxL9BOUOzXNoeXoVQIf3+47cJ0KujEHuDXROblq3o9Uos5K+Mu9Carjs8jHMiBHo4aS4IAgXVY3mEuohCuRhL9/Y9buuyvdKSNsao7qHwD/6bb9Sj2MFFhYP6gHf+p1NipH05224aX9hMZty8Ovb3+ps/wNWYC8NVfft5bh8ETowaHQ5TUOPFdvU+5IkHOnnfbvz1/+jDeErd0Pdq4xH6c5/gZVQY9j6DFpazsw8d3karwXoBduv7I3mh7L3CSjTweABaRMw=

OAuth RSA-SHA256 Headers Generation

A request with OAuth RSA-SHA256 authentication method must contain next headers:

content-type=application/x-www-form-urlencoded
Authorization: OAuth

OAuth header must contain the same OAuth parameters and values which were included in signature base string (oauth_consumer_key, oauth_nonce, oauth_signature_method, oauth_timestamp, oauth_version). Add signature as value of parameter oauth_signature to header Authorization. All values of parameters in OAuth header must be in quotes (See OAuth 5.4.1.) with the following structure: parameter=”value” and be separated by mandatory comma (,) and optional space. OAuth realm parameter is optional.

Authorization Header Example (Header is line-separated for display purposes):

Authorization: OAuth
oauth_consumer_key="paydroid",
oauth_nonce="hoFlZri9c17X1Tvb7yD2fsMEQUIWBQ3m",
oauth_signature="K0hLc7GYh65UDTNvJvJbqoD95T7ekVEwIx%2BAxLBe2rNndPVzCAZMTi58J5pJlXZA1qOrgzUj%2FuL764NofP6qrqBXHX9Fpg%2BPdoMBey7zY9nMOmtdpHhkwyqA0n8e8oh68x%2B8RtC1%2BgmaIsIJDVurpCm2CdaViC2ny90GWPrrSin9CFwDmIKBtOJ7dxNnuFQJkvLxwK9JE9gRfQssG4vOrXrn2f5DvENFvFW3fL7meiN3mKuBFyEHIv2cibWopoUTQrxAgCfTHvRuU5nRIct9oWgCYLYzROOPyAIjtyDFKcTnUql9%2BtD2%2Bp2rMDDU7HqJUGy764rb4ShuvuiuEvzIaNwg3JAxho9fqcKJz5LXt4efX1i8oFt33ztYSgZRojsoW4HCzuhZcQQmRexpmtCGYKqH3Q2BsG2jIkQAxL9BOUOzXNoeXoVQIf3%2B47cJ0KujEHuDXROblq3o9Uos5K%2BMu9Carjs8jHMiBHo4aS4IAgXVY3mEuohCuRhL9%2FY9buuyvdKSNsao7qHwD%2F6bb9Sj2MFFhYP6gHf%2Bp1NipH05224aX9hMZty8Ovb3%2Bps%2FwNWYC8NVfft5bh8ETowaHQ5TUOPFdvU%2B5IkHOnnfbvz1%2F%2BjDeErd0Pdq4xH6c5%2FgZVQY9j6DFpazsw8d3karwXoBduv7I3mh7L3CSjTweABaRMw%3D",
oauth_signature_method="RSA-SHA256",
oauth_timestamp="1669720957",
oauth_version="1.0"

OAuth RSA-SHA256 Request Generation

To make the request:

Use headers from previous section,
Add request parameters to body,
Percent-encode and send the request.

Example of Request:

Request method: POST
Request URI: https://pay.billblend.com/checkout/api/v4/transfer/4473
Headers: Authorization= OAuth oauth_nonce="C12mCYiI4RDeVTvyZDHS3f0vUbBNrK9G", oauth_signature="S4ahUgep8EV3RTIPdcpO%2FzEwB8V1XwFcGi5zhrYKySPVVA2PAY7AxezPcOCMhMwZQfcf8VOH8O9v5zZ%2BmYV2Qsq4kjPe1zEJIjjdjhI%2B2MX9VW8dWn9DyoTD2lkOYUwGsCteXU6mwGtNergN5KwGTJgqYPfzWFLllSAhGwuOd%2FgHYVRnA6jd4FvywRaRiSsnzgsasGJjWCGzX%2F1B8L78H%2FqD1W7dNJHjC2JbonUiHVT4aOs74qpqYE9zcb5rK8PH1l2ems3ArXhqFaSF85%2BYzJ%2BkSeDswqeIZ1y3NS8XPrmaLeymLNqKpOfAl9Ng47AmIjSYEw3s5fQ7Xi9t4j7Y6fQA4RnIzIdmH4oeMiyzn7dpA87wqnXm5AIm6Den2TJaDg90UoCMXuGHkqfL8GGUSjaWleTOHlk%2FO4dBGDRw4LP1aEaJktQRmT5xwyoaQfz%2Bh2MR7zDpRbVZDpUto1iYlQl5UlgojOHaLLjW1gqggbvrtVXUBT73KcIboWW00VUcbVUX5Yb%2FSu7hUZO2fNAh4LYrsVcXRJxCZuwhXCiqvbR3EziEFDGVEZnKUDLCodzHbVA9hbpxHGa7TvSLFEANCPDFtapMF9eo%2F1yOt5Tkxag4g5yNes93lrVabsTqckiFIfKR2R3CcwJ6MQtMfo8ticJcKxfo2v%2BTkC0bEaRkBGk%3D", oauth_consumer_key="ny_qa_merchant", oauth_signature_method="RSA-SHA256", oauth_timestamp="1669892964", oauth_version="1.0"
         Accept=*/*
         Content-Type=application/x-www-form-urlencoded; charset=ISO-8859-1
Body: cvv2=123&ipaddress=1.1.1.1&amount=15.42&credit_card_number=4210708776705721&client_orderid=1&deposit2card=false&destination-card-no=4232618181101636&expire_month=12&order_desc=Your%20order%20description&card_printed_name=Vasia%20Pupkin&currency=RUB&expire_year=2099&redirect_url=http%3A%2F%2Fwww.example.com

Example of CURL Request:

curl -H '
   Authorization: OAuth oauth_consumer_key="paydroid",
   oauth_nonce="JOARJWjXJgfRUVqig8HIs0ouFWKfK4N5",
   oauth_signature="k5Z0XCVdDvb5h873XG6TDMO854PsuueSnSby4h0%2F3j4TKraY6ebjoFfDmndI09%2FQp6uEbCgKregNY5N0ccIVIay49l6v7jMdIFEfqU7E5eu%2BIJcoqG7kMFcdCu29hweYx7p4ZSk%2FUtdGlN3wyUUybCAx73XYoO0tkZteAleyzQlzdpzQ99vPS8FN2WMbNdzU3H2PLf0XOZy4DbAPleZGfu3GWxXe9erGsvzBJozs3WFxiPFeULfzWWsNc1h1P7cnzNbZqXkI%2BV3qiG3jc7tDqGRZP%2BLZFw3nihNlW%2F2Nlp%2FId6QG8kPNOEx2GxAuQa8kufv%2BbpohU8UftZG1SnNfoa4nDVgNbWoSbTXbgXxwHE0ZlccwT6q%2BHbTmgggvIdGN9JuuLUL8fDSCxqu3R7YMvcwArzrkd1XEFUFvYWxHc3QpfbBu0GyLkL7pnmz%2BFPTH48COZ7yXbK6nQDFSIy8lmaEJsnnjMYyMMVgjNkDNzqwNxOQuwprTZ7KzHqWrTj0zHTOHl44q1pJhIqMwxWDPMsziExYbAzxuOkdQFZi%2BK%2Bu3M7tvG5Foy7Vwj%2BDSPMPAhj7j2AmUG4HzaJcpiBWMq0CkGWRjvneOk3NiwkEwOxq5tJOFjsroditUqJQSX1PTqf%2FtuiqaE2Gt5EYl19ZzyXbxtMjGZwL%2BzF1cT6ftTi4%3D",
   oauth_signature_method="RSA-SHA256",
   oauth_timestamp="1669892687",
   oauth_version="1.0"
' --data '
   amount=10.42
   &card_printed_name=John%20Doe
   &card_recurring_payment_id=42322
   &client_orderid=1
   &credit_card_number=4210708776705721
   &currency=USD
   &cvv2=123
   &deposit2card=false
   &destination-card-no=4232618181101636
   &destination_card_recurring_payment_id=61622
   &expire_month=12
   &expire_year=2099
   &ipaddress=1.1.1.1.1
   &order_desc=Your%20order%20description
   &redirect_url=http%3A%2F%2Fwww.example.com
' 'https://pay.billblend.com/checkout/api/v4/transfer/ENDPOINTID'