Quickstart Guide

Environment

Env	Endpoint
`Stage`	`https://enabler-stage.mspayhub.com/`
`Prod`	`https://enabler.mspayhub.com/`

Customer Namespace

The enabler service is designed to deploy per customer, so you'll get the dedicated namespace, to be consumed in the path, when your instance is deployed.

Sandbox

Want to try out the API? Take a look at the sandbox swagger here:

Sandbox Swagger UI→OpenAPI YAML→

It is a baseline module with all transactions routed to a MockGateway. i.e. No real money will be charged. All transaction will be getting approved.

Authentication

All endpoints require Bearer Token authentication. Ensure that you include a valid token in the Authorization header of your requests.

GET {customerNamespace}/api/v1/profiles
Host: enabler-stage.mspayhub.com
Authorization: Bearer {jwtToken}

Note: in later version API key will be used as the authentication method. Stay tuned for updates.

Setup acceptance profile

The first thing you would like to setup is the profile & acceptance.

In simple terms, the profile & acceptance contains the minimal information required for constructing the payment message (like ISO8583) or other format. Like the MID/ TID pair.

To create a new profile alongside with the acceptance, send a POST request like below:

Example Request - Create Profile

POST https://enabler-stage.mspayhub.com/{customerNamespace}/api/v1/profiles
Authorization: Bearer {jwt}
Content-Type: application/json
 
{
  "profileName": "Profile 1",
  "merchantName": "ACME",
  "merchantAddr": "No. 7, Park Avenue, Sunset Beach",
  "mcc": "5999",
  "countryCode": "HK",
  "currency": "HKD",
  "acceptances": [
    {
      "acptName": "Acceptnace for VM",
      "hostMessageFormat": "MOCK",
      "supportedPayments": [
        "VISA",
        "MASTERCARD",
        "AMEX"
      ],
      "primaryMid": "1122",
      "primaryTid": "3344",
      "bindedMethods": [
        "VISA",
        "MASTERCARD"
      ]
    },
    {
      "acptName": "Acceptance for AMEX UNIONPAY",
      "hostMessageFormat": "MOCK",
      "supportedPayments": [
        "AMEX",
        "UNIONPAY"
      ],
      "primaryMid": "5566",
      "primaryTid": "7788",
      "bindedMethods": [
        "AMEX",
        "UNIONPAY"
      ]
    }
  ]
}

Note for each customer we'll deploy a dedicated namespace/ instance. Check with technical support for the customer namespace required in the path.

Example Response - 201 Created

Example Response - Profile Created

HTTP/2 201 Created
x-minesec-request-id: req_01J1XQB25TY76DX878WJVJ2YKP
Location: /profiles/prof_01J1XQB25W5BFXBYQE0E57M81C
Content-Encoding: gzip
Content-Type: application/json
 
{
  "profileId": "prof_01J1XQB25W5BFXBYQE0E57M81C",
  "profileName": "Profile 1",
  "merchantName": "ACME",
  "merchantAddr": "No. 7, Park Avenue, Sunset Beach",
  "mcc": "5999",
  "countryCode": "HK",
  "currency": "HKD",
  "acceptances": [
    {
      "acptId": "acpt_01J1XQB25YMX6DVXZHF229GSQK",
      "acptName": "Acceptnace for VM",
      "hostMessageFormat": "MPGS_AP",
      "supportedPayments": [
        "VISA",
        "MASTERCARD",
        "AMEX"
      ],
      "primaryMid": "1122",
      "primaryTid": "3344",
      "extraParams": {
        "subMchDba": "Sub Merchant Name"
      },
      "entityStatus": "ACTIVE",
      "tags": [
        "SME"
      ],
      "bindedMethods": [
        "VISA",
        "MASTERCARD"
      ],
      "createdAt": "2024-07-04T09:56:58.686625+08:00",
      "updatedAt": null
    },
    {
      "acptId": "acpt_01J1XQB2633A8SSZ8QBZV9426T",
      "acptName": "Acceptance for AMEX UNIONPAY",
      "hostMessageFormat": "MOCK",
      "supportedPayments": [
        "AMEX",
        "UNIONPAY"
      ],
      "primaryMid": "5566",
      "primaryTid": "7788",
      "extraParams": {},
      "entityStatus": "ACTIVE",
      "tags": null,
      "bindedMethods": [
        "AMEX",
        "UNIONPAY"
      ],
      "createdAt": "2024-07-04T09:56:58.69204+08:00",
      "updatedAt": null
    }
  ],
  "acptSelection": {
    "acpt_01J1XQB25YMX6DVXZHF229GSQK": [
      "VISA",
      "MASTERCARD"
    ],
    "acpt_01J1XQB2633A8SSZ8QBZV9426T": [
      "AMEX",
      "UNIONPAY"
    ]
  },
  "entityStatus": "ACTIVE",
  "createdAt": "2024-07-04T09:56:58.684618+08:00",
  "updatedAt": null
}

💡

Now you can then pass the profileId to the headless SDK when requesting a card transaction. After the card tapping, the SDK would send the data to the corresponding enabler instance, and the enabler service can do a lookup based on the profile id and select the MID/ TID for the payment message.

Query transaction

To query for transaction result, there are 2 ways of doing so.

using the enabler generated transaction id (tranId)
or using your pos reference, but you'll need to pass this posReference when request the transaction via the SDK.

Example Request - Using tranId

Send a GET with the path /transaction/{tranId} when using the transaction id to query.

Example Request - Query Txn by TranId

GET https://enabler-stage.mspayhub.com/{customerNamespace}/api/v1/transaction/{tranId}
Authorization: Bearer {jwtToken}

Example Request - Using posReference

Send a GET with the path /transaction/posReference/{posReference} when using your pos reference to query.

Example Request - Query Txn by PosReference

GET https://enabler-stage.mspayhub.com/{customerNamespace}/api/v1/transaction/posReference/{posReference}
Authorization: Bearer {jwtToken}

Example Response (200)

Example Response - Get Transaction Details

HTTP/2 200 OK
x-minesec-request-id: req_01J2FTKJNR98BW918698TNZH95
Content-Encoding: gzip
Content-Type: application/json
transfer-encoding: chunked
 
{
  "tranId": "tran_01J2FTAH9T1ZRHANY8FJXWCA32",
  "tranType": "SALE",
  "tranStatus": "APPROVED",
  "amount": {
    "value": "1.00",
    "currency": "HKD"
  },
  "paymentMethod": "VISA",
  "entryMode": "NFC",
  "accountMasked": "476173******0027",
  "accountBin": "476173",
  "accountLast4": "0027",
  "issCountryCode": "0840",
  "cvmPerformed": "NO_CVM",
  "cvmSignatureUrl": null,
  "aid": "a0000000031010",
  "appName": "VISA CREDIT",
  "tc": "a7265f79058a97dc",
  "tvr": "0000000000",
  "tsi": "0000",
  "atc": "0002",
  "profileId": "prof_01J25Q1BXRG0177HACFDACHWBR",
  "acceptanceId": "acpt_01J26FXFGSFFSYSK084MTS75VX",
  "sdkId": "60f06bc8eca4f85b",
  "posReference": null,
  "trace": "012804",
  "description": null,
  "callbackUrl": null,
  "merchantName": "ACME",
  "merchantAddr": "addr",
  "mcc": "5814",
  "primaryMid": "m1111",
  "primaryTid": "t1111",
  "subMid": "m1111",
  "subTid": "t1111",
  "hostMessageFormat": "MOCK",
  "providerReference": null,
  "linkedTranId": null,
  "preferredAcceptanceTag": null,
  "extraData": null,
  "rrn": "240711103526",
  "approvalCode": "103526",
  "batchNo": "20240710",
  "actions": [
    {
      "actionId": "act_01J2FTAH9MH9QGYPHSZKV2BM4Z",
      "trace": "12804",
      "actionType": "NEW",
      "actionStatus": "SUCCESS",
      "requestId": "req_01J2FTAGEFWTR389HR1XY66PZG",
      "amount": {
        "value": "1.00",
        "currency": "HKD"
      },
      "tranId": "tran_01J2FTAH9T1ZRHANY8FJXWCA32",
      "reason": "HostSuccess",
      "hostRespCode": "00",
      "hostRespMessage": "Approved",
      "posReference": null,
      "extraData": null,
      "createdAt": "2024-07-11T10:35:26.90097+08:00",
      "updatedAt": "2024-07-11T10:35:26.957232+08:00"
    }
  ],
  "transStatusInfo": null,
  "createdAt": "2024-07-11T10:35:26.906609+08:00",
  "updatedAt": "2024-07-11T10:35:26.957232+08:00"
}

Common Format Profile & Acceptance