Profile & Acceptance

The Profile & Acceptance API provide endpoints for managing profiles and their associated acceptances.

[GET] Profile / List

Retrieve a list of profiles, cursor paginated.

Get Profile List

GET {customerNamespace}/api/v1/profiles
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/profiles?cursor=prof_01J1XM44M39Z8XNQ1D5C9QDM0T&pageSize=20&isForward=true

Response

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

Example Response (200)

Example Response - Get Profile List

HTTP/2 200 OK
x-minesec-request-id: req_01J1XMQ9PRAGDZGG9MC0NT4Q4X
Content-Type: application/json
 
{
  "hasNext": false,
  "pageSize": 10,
  "totalSize": 1,
  "currentCursor": "prof_01J1XM44M39Z8XNQ1D5C9QDM0T",
  "nextCursor": null,
  "data": [
    {
      "profileId": "prof_01J1XM44M39Z8XNQ1D5C9QDM0T",
      "profileName": "Common Base Profile",
      "providerReference": "your-system-reference-01",
      "merchantName": "ACME",
      "merchantAddr": "No. 7, Park Avenue, Sunset Beach",
      "mcc": "5999",
      "countryCode": "HK",
      "currency": "HKD",
      "entityStatus": "ACTIVE",
      "createdAt": "2024-07-04T09:00:46.083329+08:00",
      "updatedAt": "2024-07-04T01:05:22.923504+08:00"
    }
  ]
}

[GET] Profile / Details

There are 2 APIs for getting a specific profile, either by profileId or by providerReference

Request by ProfileId

Query the profile by its profileId

Get Profile by profileId

GET {customerNamespace}/api/v1/profiles/{profileId}
Authorization: Bearer {jwt}

Request

Name	Type	In	Required	Description
`profileId`	`String`	path	Required	The ID of the profile.

Example Request

base/api/v1/profiles/prof_01HYYPGVE7VB901M40SVPHTQ0V

Request by ProviderRef

Query the profile by the providerReference, the provider ref is meant for third party reference/ id for this merchant information, mid/ tid bindings.

Get Profile by providerReference

GET {customerNamespace}/api/v1/profiles/providerReference/{providerReference}
Authorization: Bearer {jwt}

Request

Name	Type	In	Required	Description
`providerReference`	`String`	path	Required	The provider reference of the profile.

Example Request

base/api/v1/profiles/providerReference/your-system-reference-01

Response

Status Code	Schema
`200 OK`	→ `ProfileWithAcpt`

Example Response (200)

Example Response - Get Profile Details

HTTP/2 200 OK
x-minesec-request-id: req_01J1XMZ4CFA9NE1KCYH9Q2FN4M
Content-Encoding: gzip
Content-Type: application/json
 
{
  "profileId": "prof_01J1XM44M39Z8XNQ1D5C9QDM0T",
  "profileName": "Common Base Profile",
  "providerReference": "your-system-reference-01",
  "merchantName": "ACME",
  "merchantAddr": "No. 7, Park Avenue, Sunset Beach",
  "mcc": "5999",
  "countryCode": "HK",
  "currency": "HKD",
  "acceptances": [
    {
      "acptId": "acpt_01J1XM44M9DNRXP8HEXZEC56CA",
      "acptName": "Common Base Acpt (MOCK 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:00:46.089436+08:00",
      "updatedAt": null
    },
    {
      "acptId": "acpt_01J1XM44PF7EYVNZJP89V4HBF1",
      "acptName": "Common Base Acpt (MOCK AU)",
      "hostMessageFormat": "MOCK",
      "supportedPayments": [
        "AMEX",
        "UNIONPAY"
      ],
      "primaryMid": "5566",
      "primaryTid": "7788",
      "extraParams": {},
      "entityStatus": "ACTIVE",
      "tags": null,
      "bindedMethods": [
        "AMEX",
        "UNIONPAY"
      ],
      "createdAt": "2024-07-04T09:00:46.159783+08:00",
      "updatedAt": null
    }
  ],
  "acptSelection": {
    "acpt_01J1XM44M9DNRXP8HEXZEC56CA": [
      "VISA",
      "MASTERCARD"
    ],
    "acpt_01J1XM44PF7EYVNZJP89V4HBF1": [
      "AMEX",
      "UNIONPAY"
    ]
  },
  "entityStatus": "ACTIVE",
  "createdAt": "2024-07-04T09:00:46.083329+08:00",
  "updatedAt": "2024-07-04T01:05:22.923504+08:00"
}

[POST] Profile / Create

Create a new profile. You can also pass along a list of acceptances for upsert.

Note that if acptId is found, it will update to the `acceptance and bind it to the profile. Otherwise, this will create a new acceptance and do the binding.

Create Profile

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

Request Body

Type	Presence	Schema
`ProfileRequest`	Required	→ `ProfileRequest`

Example Request

Example Request - Create Profile

POST base/api/v1/profiles
Authorization: Bearer {jwt}
Content-Type: application/json
 
{
  "profileName": "Common Base Profile 2",
  "providerReference": "provider-reference",
  "merchantName": "ACME",
  "merchantAddr": "No. 7, Park Avenue, Sunset Beach",
  "mcc": "5999",
  "countryCode": "HK",
  "currency": "HKD",
  "acceptances": [
    {
      "acptName": "Common Base Acpt (MOCK VM)",
      "hostMessageFormat": "MPGS_AP",
      "supportedPayments": [
        "VISA",
        "MASTERCARD",
        "AMEX"
      ],
      "primaryMid": "1122",
      "primaryTid": "3344",
      "extraParams": {
        "subMchDba": "Sub Merchant Name"
      },
      "tags": [
        "SME"
      ],
      "bindedMethods": [
        "VISA",
        "MASTERCARD"
      ]
    },
    {
      "acptName": "Common Base Acpt (MOCK AU)",
      "hostMessageFormat": "MOCK",
      "supportedPayments": [
        "AMEX",
        "UNIONPAY"
      ],
      "primaryMid": "5566",
      "primaryTid": "7788",
      "bindedMethods": [
        "AMEX",
        "UNIONPAY"
      ]
    }
  ]
}

Responses

Status Code	Schema
`201 Created`	→ `ProfileWithAcpt`

Example Response

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": "Common Base Profile 2",
  "providerReference": "provider-reference",
  "merchantName": "ACME",
  "merchantAddr": "No. 7, Park Avenue, Sunset Beach",
  "mcc": "5999",
  "countryCode": "HK",
  "currency": "HKD",
  "acceptances": [
    {
      "acptId": "acpt_01J1XQB25YMX6DVXZHF229GSQK",
      "acptName": "Common Base Acpt (MOCK 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": "Common Base Acpt (MOCK AU)",
      "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
}

[PUT] Profile / Update

Update an existing profile by its ID.

This will update all subfields of the profile and the passed acceptance (upsert and bind).

Note: if the acceptance list is empty, this will unbind ALL acceptances of the given profile.

Update Profile

PUT {customerNamespace}/api/v1/profiles/{profileId}
Authorization: Bearer {jwt}
Content-Type: application/json

Request

Name	In	Type	Required	Description
`profileId`	path	`String`	Yes	The ID of the profile.

Request Body

Type	Presence	Schema
`ProfileRequest`	Required	→ `ProfileRequest`

Example Request

Example Request - Update Profile

PUT {customerNamespace}/api/v1/profiles/prof_01J1XQB25W5BFXBYQE0E57M81C
Authorization: Bearer {jwt}
Content-Type: application/json
 
{
  "profileName": "Common Base Profile",
  "providerReference": "provider-reference",
  "merchantName": "ACME",
  "merchantAddr": "No. 7, Park Avenue, Sunset Beach",
  "mcc": "5814",
  "countryCode": "HK",
  "currency": "HKD",
  "acceptances": [
    {
      "acptName": "Common Base Acpt (MOCK VM)",
      "hostMessageFormat": "MPGS_AP",
      "supportedPayments": [
        "VISA",
        "MASTERCARD",
        "AMEX"
      ],
      "primaryMid": "1122",
      "primaryTid": "3344",
      "extraParams": {
        "subMchDba": "Sub Merchant Name"
      },
      "tags": [
        "SME"
      ],
      "bindedMethods": [
        "VISA",
        "MASTERCARD"
      ]
    },
    {
      "acptName": "Common Base Acpt (MOCK AE CUP)",
      "hostMessageFormat": "MOCK",
      "supportedPayments": [
        "AMEX",
        "UNIONPAY"
      ],
      "primaryMid": "5566",
      "primaryTid": "7788",
      "bindedMethods": [
        "AMEX",
        "UNIONPAY"
      ]
    }
  ]
}

Responses

Status Code	Schema
`200 OK`	→ `ProfileWithAcpt`

Example Response

Example Response - Profile Updated

HTTP/2 200 OK
x-minesec-request-id: req_01J1XR2K618ETX2JQYYAACH9EM
Content-Encoding: gzip
Content-Type: application/json
 
{
  "profileId": "prof_01J1XQB25W5BFXBYQE0E57M81C",
  "profileName": "Common Base Profile",
  "providerReference": "provider-reference",
  "merchantName": "ACME",
  "merchantAddr": "No. 7, Park Avenue, Sunset Beach",
  "mcc": "5814",
  "countryCode": "HK",
  "currency": "HKD",
  "acceptances": [
    {
      "acptId": "acpt_01J1XR2K65YZ0PJT9WXH8GRPDZ",
      "acptName": "Common Base Acpt (MOCK 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-04T10:09:49.765309+08:00",
      "updatedAt": null
    },
    {
      "acptId": "acpt_01J1XR2K66FSJZHJ40D03TBDDH",
      "acptName": "Common Base Acpt (MOCK AE CUP)",
      "hostMessageFormat": "MOCK",
      "supportedPayments": [
        "AMEX",
        "UNIONPAY"
      ],
      "primaryMid": "5566",
      "primaryTid": "7788",
      "extraParams": {},
      "entityStatus": "ACTIVE",
      "tags": null,
      "bindedMethods": [
        "AMEX",
        "UNIONPAY"
      ],
      "createdAt": "2024-07-04T10:09:49.766681+08:00",
      "updatedAt": null
    }
  ],
  "acptSelection": {
    "acpt_01J1XR2K65YZ0PJT9WXH8GRPDZ": [
      "VISA",
      "MASTERCARD"
    ],
    "acpt_01J1XR2K66FSJZHJ40D03TBDDH": [
      "AMEX",
      "UNIONPAY"
    ]
  },
  "entityStatus": "ACTIVE",
  "createdAt": "2024-07-04T09:56:58.684618+08:00",
  "updatedAt": "2024-07-04T10:09:49.764481+08:00"
}

[POST] Profile / SignOn

Trigger all binded acceptances to sign on to their respective gateway of the given profile.

The gateway sign-on behavior depends on the module's implementation.

Typically a card gateway would do a working key exchange. Or for a QR gateway would fetch a list of enabled QR payment methods (if the host is supported).

Profile SignOn

POST {customerNamespace}/api/v1/profiles/{profileId}/signOn
Authorization: Bearer {jwt}

Request

Name	In	Type	Required	Description
`profileId`	path	`String`	Yes	The ID of the profile.

The POST /signOn doesn't require a body payload.

Example Request

Example Request - Profile SignOn

POST {customerNamespace}/api/v1/profiles/prof_01J1XQB25W5BFXBYQE0E57M81C/signOn
Authorization: Bearer {jwt}

Responses

Status Code	Schema
`200 OK`	→ `ProfileSignOn`

Example Response

Example Response - Profile SignOn

HTTP/2 200 OK
x-minesec-request-id: req_01J1XS4PWGF27A96ZR6VKHPDK0
Content-Type: application/json
 
{
  "profileId": "prof_01J1XQB25W5BFXBYQE0E57M81C",
  "profileName": "Common Base Profile",
  "acptSignOns": [
    {
      "acptId": "acpt_01J1XR2K65YZ0PJT9WXH8GRPDZ",
      "acptName": "Common Base Acpt (MOCK VM)",
      "hostMessageFormat": "MPGS_AP",
      "supportedPayment": [
        "VISA",
        "MASTERCARD",
        "AMEX"
      ],
      "resultReason": "HostSuccess",
      "hostRespCode": "00",
      "hostRespMessage": "Sign On Success"
    },
    {
      "acptId": "acpt_01J1XR2K66FSJZHJ40D03TBDDH",
      "acptName": "Common Base Acpt (MOCK AE CUP)",
      "hostMessageFormat": "MOCK",
      "supportedPayment": [
        "AMEX",
        "UNIONPAY"
      ],
      "resultReason": "HostSuccess",
      "hostRespCode": "00",
      "hostRespMessage": "Sign On Success"
    }
  ]
}

[PATCH] Profile / ToggleStatus

Update a profile's status.

If a profile is disabled and it is selected during a transaction process, the transaction request will get a 400 BadRequest response.

Profile Toggle Status

POST {customerNamespace}/api/v1/profiles/{profileId}/signOn
Authorization: Bearer {jwt}

Request

Name	In	Type	Required	Description
`profileId`	path	`String`	Yes	The ID of the profile.

Request Body

Name	Type	Required	Description
`status`	`EntityStatus`	Required	`ACTIVE`/ `DISABLED`, → `EntityStatus`

Example Request

Example Request - Profile Toggle Status

PATCH base/api/v1/profiles/prof_01J1XQB25W5BFXBYQE0E57M81C/status
Authorization: Bearer {jwt}
Content-Type: application/json
 
{
  "status": "DISABLED"
}

Responses

Status Code	Schema
`200 OK`	→ `Profile`

Example Response

Example Response - Profile Toggle Status

HTTP/2 200 OK
x-minesec-request-id: req_01J1XS8A2PX2M94JTKDVFM4KGA
Content-Type: application/json
 
{
  "profileId": "prof_01J1XQB25W5BFXBYQE0E57M81C",
  "profileName": "Common Base Profile",
  "providerReference": "provider-reference",
  "merchantName": "ACME",
  "merchantAddr": "No. 7, Park Avenue, Sunset Beach",
  "mcc": "5814",
  "countryCode": "HK",
  "currency": "HKD",
  "entityStatus": "DISABLED",
  "createdAt": "2024-07-04T09:56:58.684618+08:00",
  "updatedAt": "2024-07-04T10:30:25.630758+08:00"
}

Quickstart Guide Transaction & Action