How the Enabler Service works?

Profiles & Acceptances

Profile-Acceptance Relationship

Profile: Represents a merchant's configuration, including the least merchant information (for assembling the payment message) and binded with one or more acceptances.
Acceptance: Represents the upstream gateway configuration, including host message formats, MIDs, TIDs, and supported payment methods.

For example let's consider a profile with 2 acceptances binded, the struct as below:

example profile

{
  "profileId": "prof_01",
  "profileName": "Example Profile",
  "providerReference": "your-system-reference-01",
  "merchantName": "ACME",
  ...
  "acceptances": [
    {
      "acptId": "acpt_01",
      "acptName": "Example Acceptance (MOCK 1)",
      "hostMessageFormat": "MPGS_AP",
      "supportedPayments": [
        "VISA",
        "MASTERCARD",
        "AMEX"
      ],
      "bindedMethods": [
        "VISA",
        "MASTERCARD"
      ],
      "primaryMid": "1122",
      "primaryTid": "3344",
      ...
    },
    {
      "acptId": "acpt_02",
      "acptName": "Example Acceptance (MOCK 2)",
      "hostMessageFormat": "MOCK",
      "supportedPayments": [
        "AMEX",
        "UNIONPAY"
      ],
      "bindedMethods": [
        "AMEX",
        "UNIONPAY"
      ],
      "primaryMid": "5566",
      "primaryTid": "7788",
      ...
    }
  ],
  ...
}

The profile is binded with 2 acceptances:

First acceptance (acpt_01)

is with MPGS_AP message format, with mid: 1122 and tid: 3344
can support 3 payment methods: "supportedPayments": ["VISA", "MASTERCARD", "AMEX"]
but it is just binded for 2 methods for this particular profile: "bindedMethods": ["VISA", "MASTERCARD"]

Second acceptance (acpt_02)

is with MOCK message format, with mid: 5566 and tid: 7788
support for AMEX & UNIONPAY
binded for both AMEX & UNIONPAY for this profile

Transactions & Actions

Transaction-Action Relationship

Transactions are the primary operations, like sales or refunds, while actions are the operations performed on those transactions, such as voiding or adjusting them.

Transaction: The main event, such as a SALE, AUTH or a REFUND.
Action: Operations performed for a transaction, like a NEW, VOID or ADJUST.

It's like a parent child relations - A transaction can have multiple actions.

For example, a voided sale transaction has 2 actions - an actionType: NEW responsible for the sale request and an actionType: VOID for the void request.

{
  "tranType": "SALE",
  "tranStatus": "VOIDED",
  "amount": {
    "value": "1.00",
    "currency": "HKD"
  },
  ...
  "actions": [
    {
      "actionId": "act_01J2DPZ7RC7ZNECC6SS2096HBY",
      "trace": "12803",
      "actionType": "VOID",
      "actionStatus": "SUCCESS",
      "requestId": "req_01J2DPZ7QWQEQ49QQX99KF2K4A",
      "amount": {
        "value": "1.00",
        "currency": "HKD"
      },
      "tranId": "tran_01J2DPY593R5ANPWYYC52AJTK1",
      "reason": "HostSuccess",
      "hostRespCode": "00",
      "hostRespMessage": "Approved",
      ...
    },
    {
      "actionId": "act_01J2DPY5918KMNX3DF2S26XBYQ",
      "trace": "12802",
      "actionType": "NEW",
      "actionStatus": "SUCCESS",
      "requestId": "req_01J2DPY4T9Z5XCDZZA9B1AWG6K",
      "amount": {
        "value": "1.00",
        "currency": "HKD"
      },
      "tranId": "tran_01J2DPY593R5ANPWYYC52AJTK1",
      "reason": "HostSuccess",
      "hostRespCode": "00",
      "hostRespMessage": "Approved",
      ...
    }
  ],
  ...
}

References from different systems

Throughout the lifecycle of a transaction, the request and data might be passed through a lot of systems. Hence there will be quite a few references/ id from different system.

As a rule of thumb, the enabler will try to include as much information as possible, so on the caller side can reason about it.

Name	Originated	Condition	Description
`transaction.tranId`	Enabler	Auto generated
`transaction.linkedTranId`	Enabler	tranId ref to another txn	Applicable to linked-refund
`transaction.posReference`	POS/ Caller on the SoftPOS	Passed via request	Caller side can pass a posReference to the app/ sdk, like a invoice number
`transaction.providerReference`	Profile	If set in the profile	Can be set in the profile, as a third party system reference of the merchant. Will be carried to transaction record
`transaction.rrn`	Upstream host response	If host responded	Returned from host response, the reference retrieval number. Usually it is used to track transaction via the acquirer system.
`transaction.approvalCode`	Upstream host response	If host responded	Returned from host response. Usually from issuer system.
`action.actionId`	Enabler	Auto generated
`action.tranId`	Transaction	tranID ref to txn	Linkage to transaction
`action.requestId`	SoftPOS app/ sdk	SDK/ app generated	With our app/ sdk, on client side it is generated. Some other API (like voiding via RESTful API), when the enabler receive the request it'll generate one.

Enabler Intro Common Format