Configuration & Go-live

Prepare your adapter

Deploy your adapter on an HTTPS endpoint reachable from the internet, and check it against Security & Conventions. Use a separate base URL and credential for UAT and production.

Submit the onboarding information

Send MineSec the following through your account manager:

Card options are enabled by MineSec for your account and confirmed with you before UAT. QR options are set in the acceptance of your profile; see below.

Exchange credentials and keys

Credentials never go through email or chat. MineSec provides a secure channel during onboarding.

Create the profile

Create a profile with a STD_JSON acceptance through the Profile Management API. MineSec gives you its base URL and a bearer token for each environment. The token is bound to your account, allows profile management and has an expiry date; when a request answers 401 with "Token is not valid or has expired", ask MineSec for a new one.

POST {baseUrl}/api/v1/pos/profiles
Authorization: Bearer {token}
Content-Type: application/json
 
{
  "profileName": "HostAPI-Example",
  "providerReference": "your-merchant-0001",
  "merchantName": "ACME",
  "merchantAddr": "No. 7, Park Avenue, Sunset Beach",
  "mcc": "5999",
  "countryCode": "HK",
  "currency": "HKD",
  "acceptances": [
    {
      "acptName": "Host API",
      "acptReference": "your-merchant-0001-card",
      "hostMessageFormat": "STD_JSON",
      "supportedPayments": ["VISA", "MASTERCARD"],
      "primaryMid": "100000000000001",
      "primaryTid": "10000001",
      "extraParams": {
        "hostUrl": "https://uat-api.your-host.com/api/v1",
        "hostAuth": "<bearer credential>",
        "hmacKey": "<HMAC key, hex>",
        "pinDestKeyAlias": "<PIN key alias from MineSec>",
        "track2DestKeyAlias": "<Track2 key alias from MineSec>"
      }
    }
  ]
}

A successful create answers 201 Created with the profile and its acceptances. Keep the profileId and each acptId; you need them to update the profile.

Profile Management API reference

All paths are under the base URL MineSec gives you, with Authorization: Bearer {token}:

The request and response bodies are the same as in the Profile & Acceptance API: ProfileRequest and AcceptanceUpsertRequest in, ProfileWithAcpt out. Use the paths above, not the {customerNamespace}/api/v1/profiles paths shown on that page.

The Host API also uses these optional fields, which that page does not list:

References and safe retries

• providerReference is your own ID for the profile, unique in your account. A POST with a providerReference that already exists updates that profile instead of creating a second one, so a create that timed out can be sent again.
• acptReference is your own ID for the acceptance. Keep it unique in your account: an acceptance sent without acptId is matched by acptReference, and a match on another profile is moved to this one.

Updating a profile

A PUT (or a POST that matches an existing providerReference) replaces the profile as a whole:

• Send all profile fields. They replace the stored values.
• Send every acceptance the profile should keep, each with its acptId. An acceptance left out of acceptances, or all of them when acceptances is left out, is detached from the profile and no longer receives transactions.
• An acceptance without acptId is matched by acptReference; if none matches, a new acceptance is created.
• Within an acceptance, all fields are replaced except extraParams, which is merged: the keys you send overwrite the stored ones, and keys you leave out keep their values. Leaving a key out does not remove it.
• When host settlement is enabled, an update is rejected while the profile has a batch with approved transactions that is not settled yet. Settle first, then update.

Errors

Set the acceptance as follows:

• All extraParams values are strings. Any key you add that is not in this table is forwarded to your host in posExtra on every request of the acceptance.
• For QR, also set merchantCity on the profile: it is sent as EMVCo tag 60. merchantPostalCode, shopId, shopName and providerMchId are optional profile fields that are forwarded on QR requests when set.
• Always set pinDestKeyAlias on a card acceptance; without it, PIN transactions are declined. See PIN and Track2.
• A profile can carry several acceptances, for example one for card and one for QR. Do not let two acceptances of the same profile support the same payment method: the transaction is then rejected unless the device sends a matching acceptance tag.

MineSec routes each transaction of the profile to the acceptance that supports its payment method, and sends that acceptance's MID, TID, sub MID and sub TID to your host.

Test in UAT

Run the test cases from MineSec with a UAT device and test cards or wallets. A typical set:

Go live

After UAT sign-off, repeat the credential exchange and profile creation in production, with production values. Start with a pilot merchant and one low-value transaction before you roll out.