OAuth Request Authentication Method

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
Sign the Signature Base String with HMAC-SHA1. The signing key is the concatenation of consumer secret (Merchant control key) + & + token secret (empty string).HMAC-SHA1 Key Example:11111111-1111-1111-1111-111111111111&
Encode the signed string to Base64 to get signature for API.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
Sign the Signature Base String with RSA-SHA256 using the private key obtained in previous section.
Base64 encode the signed string to get signature for API.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

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'