Transaction & Action API

The Transaction & Action API provide endpoints for managing payment transaction throughout their lifecycle.

[GET] Transaction / List

Retrieve a list of transactions, cursor paginated.

Get Transaction List

GET {customerNamespace}/api/v1/transactions
Authorization: Bearer {jwt}

Request

Name	Type	In	Required	Description
`cursor`	`String`	query param	No	The pagination cursor.
`pageSize`	`Int`	query param	No	Number of items per page.
`isForward`	`Boolean`	query param	No	Direction of pagination.

Example Request

base/api/v1/transaction?cursor=tran_01J2FTAH9T1ZRHANY8FJXWCA32&pageSize=20&isForward=true

Response

Status Code	Schema
`200 OK`	→ Wrapped by: `CursorPaginated` → Data: `TransactionExtract`

Example Response (200)

Example Response - Get Transaction List

HTTP/2 200 OK
x-minesec-request-id: req_01J2FT84FVG6J5AM00M2H0CX4F
Content-Encoding: gzip
Content-Type: application/json
transfer-encoding: chunked
 
{
  "hasNext": false,
  "pageSize": 10,
  "totalSize": 1,
  "currentCursor": "tran_01J2FTAH9T1ZRHANY8FJXWCA32",
  "nextCursor": null,
  "data": [
    {
      "tranId": "tran_01J2FTAH9T1ZRHANY8FJXWCA32",
      "tranType": "SALE",
      "tranStatus": "APPROVED",
      "amount": {
        "value": "1.00",
        "currency": "HKD"
      },
      "paymentMethod": "VISA",
      "entryMode": "NFC",
      "accountBin": "476173",
      "accountLast4": "0027",
      "sdkId": "60f06bc8eca4f85b",
      "posReference": null,
      "trace": "012804",
      "merchantName": "ACME",
      "primaryMid": "m1111",
      "primaryTid": "t1111",
      "subMid": "m1111",
      "subTid": "t1111",
      "hostMessageFormat": "MOCK",
      "providerReference": null,
      "linkedTranId": null,
      "rrn": "240711103526",
      "approvalCode": "103526",
      "batchNo": "20240710",
      "createdAt": "2024-07-11T10:35:26.906609+08:00",
      "updatedAt": "2024-07-11T10:35:26.957232+08:00"
    }
  ]
}

[GET] Transaction / Details

There are 2 APIs for getting a specific transaction, either by tranId or by posReference

Request by TranId

Query the transaction by its tranId

Get Transaction by tranId

GET {customerNamespace}/api/v1/transactions/{tranId}
Authorization: Bearer {jwt}

Request

Name	Type	In	Required	Description
`tranId`	`String`	path	Required

Example Request

base/api/v1/transactions/tran_01J2FTAH9T1ZRHANY8FJXWCA32

Request by PosReference

Query the transaction by the posReference. The pos ref is meant for a third party system to pass along in the transaction request for their reference/ query.

Get Transaction by posReference

GET {customerNamespace}/api/v1/transaction/posReference/{posReference}
Authorization: Bearer {jwt}

Request

Name	Type	In	Required	Description
`posReference`	`String`	path	Required

Example Request

base/api/v1/transactions/posReference/your-pos-reference-001

Response

Status Code	Schema
`200 OK`	→ `Transaction`

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"
}

[POST] Action / Perform Action

Perform an action on a transaction. Like voiding or tip adjust or perform an auth-completion.

Perform Action

POST {customerNamespace}/api/v1/transactions/{tranId}/actions
Authorization: Bearer {jwt}
Content-Type: application/json

Request Body

Type	Presence	Schema
`ActionRequest`	Required	→ `ActionRequest`

Example Request

Example Request - Perform Action

POST {customerNamespace}/api/v1/transactions/{tranId}/actions
Authorization: Bearer {jwt}
Content-Type: application/json
 
{
  "actionType": "VOID"
}

Response

Status Code	Schema
`200 OK`	→ `Transaction`

Example Response (200)

Example Response - Get Profile Details

HTTP/2 200 OK
x-minesec-request-id: req_01J2FV12HHXH0V7T33ZHE1DE7D
Content-Encoding: gzip
Content-Type: application/json
transfer-encoding: chunked
 
{
  "tranId": "tran_01J2FTAH9T1ZRHANY8FJXWCA32",
  "tranType": "SALE",
  "tranStatus": "VOIDED",
  "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_01J2FV12J72K4V218B02BWM0Q0",
      "trace": "12805",
      "actionType": "VOID",
      "actionStatus": "SUCCESS",
      "requestId": "req_01J2FV12HHXH0V7T33ZHE1DE7D",
      "amount": {
        "value": "1.00",
        "currency": "HKD"
      },
      "tranId": "tran_01J2FTAH9T1ZRHANY8FJXWCA32",
      "reason": "HostSuccess",
      "hostRespCode": "00",
      "hostRespMessage": "Approved",
      "posReference": null,
      "extraData": null,
      "createdAt": "2024-07-11T10:47:45.479228+08:00",
      "updatedAt": "2024-07-11T10:47:45.489858+08:00"
    },
    {
      "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:47:45.494356+08:00"
}

[GET] Transaction / Query Upstream Result

For async transaction, like a merchant present QR payment, to query the result from the corresponding upstream gateway.

Query Upstream

GET {customerNamespace}/api/v1/transactions/{tranId}/queryUpstream
Authorization: Bearer {jwt}

Request

Name	In	Type	Required	Description
`tranId`	path	`String`	Yes

Example Request

base/api/v1/transactions/tran_01J2FV7NTMDJV337R224X2RQ84/queryUpstream

Response

Status Code	Schema
`200 OK`	→ `Transaction`

Example Response (200)

Example Response - Query Upstream

HTTP/2 200 OK
x-minesec-request-id: req_01J2FVASKDF6NZH4EWSMZ6QK2Z
Content-Encoding: gzip
Content-Type: application/json
transfer-encoding: chunked
 
{
  "tranId": "tran_01J2FV7NTMDJV337R224X2RQ84",
  "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": "012806",
  "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": "240711105121",
  "approvalCode": "105121",
  "batchNo": "20240710",
  "actions": [
    {
      "actionId": "act_01J2FV7NTKXEXHCW1A0F7YYKY4",
      "trace": "12806",
      "actionType": "NEW",
      "actionStatus": "SUCCESS",
      "requestId": "req_01J2FV7NB1PPFSQGQBHC3DWFGB",
      "amount": {
        "value": "1.00",
        "currency": "HKD"
      },
      "tranId": "tran_01J2FV7NTMDJV337R224X2RQ84",
      "reason": "HostSuccess",
      "hostRespCode": "00",
      "hostRespMessage": "Approved",
      "posReference": null,
      "extraData": null,
      "createdAt": "2024-07-11T10:51:21.811304+08:00",
      "updatedAt": "2024-07-11T10:51:21.834372+08:00"
    }
  ],
  "transStatusInfo": null,
  "createdAt": "2024-07-11T10:51:21.812487+08:00",
  "updatedAt": "2024-07-11T10:51:21.834372+08:00"
}

[GET] Transaction / Get Upstream Token

Only applicable to host that provides tokenization service, example being the Mastercard Payment Gateway Services (MPGS)

Calling to upstream gateway to search for a card token.

This call WILL NOT request to create a token. Only query to gateway whether the card has been tokenized and possibly with the token itself.

Get Upstream Token

GET {customerNamespace}/api/v1/transactions/{tranId}/upstreamToken
Authorization: Bearer {jwt}

Request

Name	In	Type	Required	Description
`tranId`	path	`String`	Yes

Example Request

base/api/v1/transactions/tran_01J2FV7NTMDJV337R224X2RQ84/upstreamToken

Response

Status Code	Schema
`200 OK`	→ `CardToken`

Example Response (200)

Example Response - Upstream token exist

HTTP/2 200 OK
x-minesec-request-id: req_01J2FW25H5JGZHV1CZ1M34DB4B
Content-Length: 101
Content-Type: application/json
 
{
  "status": "SUCCESS",
  "token": "4761739556610027",
  "extra": {
    "repositoryId": "010826266",
    "status": "VALID"
  }
}

Example Response - Upstream token NOT exist

HTTP/2 200 OK
x-minesec-request-id: req_01J2FVY7T1JW5RPRMQRF9TRB59
Content-Length: 46
Content-Type: application/json
 
{
  "status": "NO_DATA",
  "token": null,
  "extra": null
}

[POST] Transaction / Create Upstream Token

Only applicable to host that provides tokenization service, example being the Mastercard Payment Gateway Services (MPGS)

Request to tokenize for a card token via the upstream gateway.

Create Upstream Token

POST {customerNamespace}/api/v1/transactions/{tranId}/upstreamToken
Authorization: Bearer {jwt}

Request

Name	In	Type	Required	Description
`tranId`	path	`String`	Yes

Example Request

base/api/v1/transactions/tran_01J2FV7NTMDJV337R224X2RQ84/upstreamToken

Response

Status Code	Schema
`200 OK`	→ `CardToken`

Example Response (200)

Example Response - Upstream host card token exist

HTTP/2 200 OK
x-minesec-request-id: req_01J2FW25H5JGZHV1CZ1M34DB4B
Content-Length: 101
Content-Type: application/json
 
{
  "status": "SUCCESS",
  "token": "4761739556610027",
  "extra": {
    "repositoryId": "010826266",
    "status": "VALID"
  }
}

Profile & Acceptance Notification