When testing the communication server, we added a memo to the transaction in order to identify what customer account to credit. However, other people and organizations using HC Net might not know they need to do that. How do they find out?
The HC Net mapping protocol allows you to convert a human-readable address like sam*your_org.com[1] to an account ID. It also includes information about what should be in a transaction’s memo. When sending a payment, you contact a mapping server first to determine what HC Net account ID to pay. Luckily, the communication server does this for you.
HCNet.org provides a prebuilt mapping server that can hook into an existing user database, but you can also write your own.
The HC Net mapping server is designed to connect to any existing SQL database you might have with a list of account names. It essentially translates a mapping request into a SQL query. The server supports MySQL, PostgreSQL, and SQLite3.
At a minimum, your database should have a table with a column identifying the name to use for each account record.[2] In your existing system, you might have a table named accounts that looks something like:
| id | first_name | last_name | friendly_id |
|---|---|---|---|
| 1 | Mike | Milli | mike_milli |
| 2 | Amy | Smith | amy_smith |
| 3 | Jack | Brown | jack_brown |
| 4 | Steintór | Jákupsson | steintor_jakupsson |
| 5 | Sneha | Kapoor | sneha_kapoor |
Where Mike’s HC Net address would be mike_milli*your_org.com.
Next, download the latest mapping server for your platform. Install the executable anywhere you like. In the same directory, create a file named mapping.cfg. This will store the configuration for the server. It should look something like:
mapping.cfg TOML
Make sure to update the database connection information with the proper credentials and name for your database. Also update the value of domain in the mapping query to match your actual domain instead of your_org.com.
The mapping query is a SQL query that should return the columns id, memo, and memo_typewhen supplied with the two parts of a HC Net address, e.g. tunde_adeboyo and your_org.com for the address mike_milli*your_org.com.
Since we are mapping all addresses to our base account, we always return the base account ID for id. As in the first section, we want the account’s friendly_id as a text memo.
The reverse-mapping query is required, but because all customer accounts map to a single HC Net account in our design, we need to make sure this query always returns no rows.
Now run the server! (Unlike the communication server, there’s there no custom database to migrate.)
./mapping
Finally, others have to know the URL of your mapping server. The HCNet.toml file is publicly available file where others can find information about your HC Net integration. It should always be stored at:
https://[YOUR DOMAIN]/.well-known/HCNet.toml
It can list all sorts of properties, but the one we care about now is the URL for your mapping server. Your HCNet.toml file should look something like:
HCNet.toml TOML
MAPPING_SERVER = "https://www.your_org.com:8002/mapping"
The actual URL for your mapping server can be anything you like—it can be at your www subdomain but on a different path, it can be at a different port, or it can be on a different domain entirely. However, it must be available via HTTPS with a valid SSL certificate.[3]
Request a Mapping Info
import org.apache.http.HttpEntity;
curl "https://www.your_org.com:8002/mapping?q=mike_milli*your_ org.com&type=name"
var request = require('request');
request.get({
url: 'https://www.your_org.com:8002/mapping',
qs: {
q: 'mike_milli*your_org.com',
type: 'name'
}
}, function(error, response, body) {
console.log(body);
});
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
import org.apache.http.client.utils.URIBuilder;
import java.net.URI;
class MappingRequest {
public static void main(String [] args) throws Exception {
URI mappingUri = new URIBuilder("https://www.your_org.com:8002/mapping")
.addParameter("q", "mike_milli*your_org.com")
.addParameter("type", "name")
.build();
HttpGet mappingRequest = new HttpGet(mappingUri);
HttpClient httpClient = HttpClients.createDefault();
HttpResponse response = httpClient.execute(mappingRequest);
HttpEntity entity = response.getEntity();
if (entity != null) {
String body = EntityUtils.toString(entity);
System.out.println(body);
}
}
}