BlackHat Merchant is a payment processing system which can be easily integrated into any internet or real store and used for accepting payments from customers with BlackHat Coin cryptocurrency in fast, secure, convenient and (if it's required) anonymous way.

Depending on your store requirements or technical skills of the store owner the BlackHat Merchant can be either used as a standalone invoice management system through the web interface https://merchant.blackhatco.in or it could be integrated into the store via the API interface.

First of all, you need to create a new account or log in if you are already registered.

Next, go to Stores menu and create your store by filling out the required data in the form.
If your store is a website it's recommended to confirm the ownership of the website domain by passing simple and fast verification process. To do that, open the store you created by clicking on it, go to Contacts tab, click on Confirm button and follow the instructions.

Stores which have verified their websites will get a Confirmed mark right near their names on invoice payment pages.

The invoices functionality is available on Invoices page.

To issue an invoice you need to select the store on behalf of which the invoice will be issued, payment type (Transparent or Shielded), invoice amount and description.

What is the difference between Transparent and Shielded type of payment?
Like it's in the BlackHat Wallet, each account in the BlackHat Merchant System has two type of addresses to receive invoice payments: Transparent (public) and Shielded (private).

• When you use Transparent type, the destination address of the store will be publicly available in blockchain transactions which makes it possible to track the belonging of the address to a particular store
• In cases where it's necessary to avoid the exposing of store address and make the transaction private you should use Shielded type

Once the invoice is created it will appear in the table below.
Now, you need to copy the invoice link and send it to the customer who is going to pay the invoice.

The invoice statuses are the following:

• Awaiting payment: The invoice has just been created and waiting for the payment
• Processing: This is an internal status, showing that the customer started to pay this invoice. If the payment process is interrupted by the customer or due to technical issue, the payment process of this invoice could not be started again and new invoice should be issued for the customer
• Payment received: The customer paid the invoice, but the actual transaction has not been sent to the blockchain yet or the transaction is created but haven't reached 10 network confirmation
• Payment confirmed: The customer paid the invoice, the transaction has reached 10 network confirmation and the funds are credited to your BlackHat Merchant account

To speed up things, the product or service paid by the invoice can be provided to the customer even upon reaching the status Payment received.
It's up to the store operator to decide.

On the Balances page you can track your incoming transactions, manage your balances and withdraw funds to your BlackHat wallet.

Api endpoint:

https://merchant.blackhatco.in/api/<methodName>

Where <methodName> is a proper API method (see below).

The request parameters can be passed through POST or GET method (only one method should be used for all request parameters, POST is in priority)

To use the API interface you need to obtain API key and API secret key in "Settings" menu.
ATTENTION! It's only possible to see the generated API keys right after their generation. It's recommended to copy them to the safe place. You are also able to re-generate the API keys, but keep in mind that the old ones will stop working immediately.

For the security reasons, it's possible to whitelist IP addresses from which is planned to make API requests.

Making an authorized API request:

Required parameters for each request

• key: your API key
• ts: current timestamp (with milliseconds, always should be higher than in previous request)
• parameters required by the API method (see the API methods description below)
• sign: hmac sha256 signed hash of the request (API secret key is used)

Example:
Source data (example values):

• API Key: dd181df0c163c9271530eb5f165c6a63
• API secret Key: c8b67c66595af67a78ece3cb881491a2
• Method: getInvoice, invoice_id=0549991d-e3ea-476b-a8fa-5921a257c33a

The method's payload will be look like:

key=dd181df0c163c9271530eb5f165c6a63

                                ts=1651480109.1231

                                invoice_id=0549991d-e3ea-476b-a8fa-5921a257c33a

The string should be created from the request parameters and values sorted alphabetically by parameters names, like this:

invoice_id=0549991d-e3ea-476b-a8fa-5921a257c33a&key=dd181df0c163c9271530eb5f165c6a63&ts=1651480109.1231

Hashing this string with hmac sha256 using our API secret key we get this:

24ba6a52cf45b6f4dd542ed4016970a7db04e34a975dcca891fcd0010a2ad968

This is will be our sign value.

So, our final request payload will be look like:

key=dd181df0c163c9271530eb5f165c6a63

                                ts=1651480109.1231

                                invoice_id=0549991d-e3ea-476b-a8fa-5921a257c33a

                                sign=24ba6a52cf45b6f4dd542ed4016970a7db04e34a975dcca891fcd0010a2ad968

                                

1. issueInvoice - Issuing an invoice
Incoming params (*required):

• *int, store_id - an unique ID of the store
• *int, type - 0: Transparent, 1 - Shielded
• *float, amount - the amount of the invoice
• string, description - the description of the invoice

2. removeInvoice - Removing an unpaid invoice
Incoming params (*required):

• *int, invoice_id - ID of the invoice

3. getInvoice - Getting an invoice information
Incoming params (*required):

• *int, invoice_id - ID of the invoice

Invoice status value (int) description:

• Awaiting payment : 0
• Processing : 1
• Payment received : 2
• Payment confirmed : 3

The API interface could be extended upon the customer requests.

After the invoice is issued by using issueInvoice method you have two options how to carry out the payment process for the client:

Option №1. Show a payment button/link which will lead the customer to the payment page of BlackHat Merchant.
This link could be generated this way:

For example, our invoice ID is

0549991d-e3ea-476b-a8fa-5921a257c33a

So, the link will look like as follows:

https://merchant.blackhatco.in/pay?i=0549991d-e3ea-476b-a8fa-5921a257c33a

On this page the customer can choose how the invoice is going to be paid.


Option №2. The functionality of the BlackHat Merchant payment page could be reproduced inside your store by showing the payment options to the customer right inside the interface of your store.

2.1. Payment via BlackHat Mobile/Telegram wallet using QR-code. The content which should be placed into the QR code is:

invoice:0549991d-e3ea-476b-a8fa-5921a257c33a

2.2. Payment via BlackHat Telegram wallet using direct link which opens in the Telegram app. The link should be generated as follows:

https://t.me/BlackHatWalletBot?start=invoice_0549991d-e3ea-476b-a8fa-5921a257c33a

2.3. Payment via BlackHat Web wallet. The link should be generated as follows:

https://wallet.blackhatcoin.loc/pay?i=0549991d-e3ea-476b-a8fa-5921a257c33a

When it comes to tracking the invoices statuses from the server-side of the store to provide the product or service paid by the invoice, there's two ways to do that:
- Periodically pulling getInvoice method for the invoice status
- Using Webhook (push) method

To setup the Webhook, go to "Settings" and fill out the proper data into Webhook's URL and preferred request method.

When applying the settings the webhook script should exist on the web server of the store and properly answer to the test "ping" request as "pong"

Webhook will track invoices status changes and send the request containing invoice_id and status values to the specified script. Script should answer "ok" to tell the Merchant that the request is accepted.

The request will come signed the same way as it's signed for the API request and the sign needs to be checked to make sure the request is coming from Merchant System.

Here's the example of simple WebHook script on PHP:

                                    <?php

                                    $apiSecret = 'put here your API secret key';

                                    

                                    /* select which input method are you using */

                                    $input = $_POST;

                                    //$input = $_GET;

                                    

                                    if (isset($input['sign'])) {

                                     $sign = $input['sign'];

                                     unset($input['sign']);

                                     ksort($input);

                                     // checking the request sign

                                     if ($sign === hash_hmac('sha256', http_build_query($input), $apiSecret)) {

                                      if (isset($input['ping'])) {

                                       echo 'pong';

                                       exit;

                                      }

                                      if (isset($input['invoice_id'])) {

                                       // do the required backend logic

                                       echo 'ok';

                                       exit;

                                      }

                                     }

                                    }