Merchant - MineSec Developer Docs

⚠️

Legacy API — deprecated. This page documents the legacy /api/v2 Merchant endpoints, kept for existing integrations. New integrations should use the current Merchant API. Once your PBO group has been switched over to the current Service API, every write and lookup endpoint on this page — create, update, delete, get details, and all payment-config endpoints — returns code: 13310 ("Your group has open the multi_acquirers;please use the new Service API") instead of working. See the Service API overview for details.

The one exception is Merchant List (GET /api/v2/mchInfo), which keeps working after the switch.

Merchant List

Retrieves a list of merchants under this PBO (Payment Business Owner).

Get Merchant List

GET /api/v2/mchInfo
Authorization: Bearer {jwt}

Parameters

Name	Type	Required	Description
mchName	string	false	Filter by merchant name (partial match)
mchId	string	false	Filter by merchant unique ID generated by MineSec system
pageNumber	number	false	Default `1`
pageSize	number	false	Default `10`; use `-1` to return all merchants on one page

This endpoint keeps working even after your PBO group has been switched over to the current Service API — it is the one endpoint on this page that does not return 13310. See the Service API overview for details.

Response

Status	Meaning	Description	Schema
200	OK (opens in a new tab)	OK	Wrapper: `Response List<T>` Data: Merchant

Example Response (200)

Example Response - Merchant List

{
  "msg": "SUCCESS",
  "code": 0,
  "data": {
    "total": 10,
    "current": 1,
    "hasNext": false,
    "records": [
      {
        "mchName": "Coffee Shop",
        "mchId": "M-12345678",
        "providerReference": "MID180045210008",
        "contactName": "John Smith",
        "contactEmail": "[email protected]",
        "contactAddress": "123 Main St, Springfield",
        "contactPhone": "555-1234",
        "mcc": "5811",
        "state": 1,
        "timeZone": "Asia/Singapore",
        "country": "SG",
        "extParams": {
          "acqMid": "1234567850001",
          "acqTid": "0001252001"
        }
      }
    ]
  }
}

Create Merchant

Creates a new merchant with the provided information.

Create Merchant

POST /api/v2/mchInfo
Authorization: Bearer {jwt}

Parameters

Full schema: MerchantRequest. Key fields:

Name	Type	Required	Description
mchName	`String`	YES	Merchant display name
providerReference	`String`	No	Your own unique reference ID for this merchant (must be unique per merchant)
contactName	`String`	YES	Merchant contact person's name
contactEmail	`String`	YES	Merchant contact email
contactPhone	`String`	No	Merchant contact phone
contactAddress	`String`	No	Merchant contact address (shown on e-receipt if set)
mcc	`String`	No	Merchant category code (ISO 18245), e.g. `5811` for "eating places"
region	`String`	No	Region code for this merchant, used for reporting/routing
timeZone	`String`	No	Merchant's local timezone (IANA tz name); defaults to the PBO's timezone if omitted
country	`String`	YES	Merchant's country (ISO 3166-1 alpha-2 code), e.g. `SG`
transType	`String`	No	Restricts this merchant to a specific transaction type, if set
state	`int`	No	`1` = active (can process payments), `0` = inactive
mdr	`String`	No	Merchant discount rate override for this merchant, if your PBO supports per-merchant MDR
merchantType	`String`	No	Merchant type classification used for reporting/segmentation
extParams	`Object`	No	Extra parameters (e.g. MID/TID, SubMID, subTID, secret token)
supportedPaymentMethods	`Array<Object>`	No	Explicit per-method acquirer bindings (see example below). If omitted, the merchant is auto-bound to your PBO's default acquirer profile(s)

To accept payments, a merchant needs at least one acquirer profile bound — either explicitly via supportedPaymentMethods (recommended, shown below) or by leaving it out and relying on your PBO's default acquirer profile(s).

Request Body Example

Example Request - Create Merchant

{
  "mchName": "Coffee Shop",
  "providerReference": "MID180045210008",
  "contactName": "John Smith",
  "contactEmail": "[email protected]",
  "contactPhone": "555-1234",
  "contactAddress": "123 Main St, Springfield",
  "mcc": "5811",
  "timeZone": "Asia/Singapore",
  "country": "SG",
  "extParams": {},
  "supportedPaymentMethods": [
    { "paymentMethod": "VISA", "profileId": 316 },
    { "paymentMethod": "MASTERCARD", "profileId": 316 }
  ]
}

To bind every payment method a single profile supports in one go, use "paymentMethod": "ALL" instead of listing each one:

Example Request - Create Merchant (bind all methods on one profile)

{
  "mchName": "Coffee Shop",
  "contactEmail": "[email protected]",
  "contactName": "John Smith",
  "timeZone": "Asia/Singapore",
  "providerReference": "MID180045210008",
  "mcc": "5814",
  "supportedPaymentMethods": [
    { "paymentMethod": "ALL", "profileId": 316 }
  ]
}

Response

Status	Meaning	Description	Schema
200	OK (opens in a new tab)	OK	Wrapper: `Response<T>` Data: Merchant
—	`code: 10000`, `"providerReference already exists"`	`providerReference` is already used by another merchant under this PBO	—

Example Response (200)

Example Response - Create Merchant

{
  "msg": "SUCCESS",
  "code": 0,
  "data": {
    "mchName": "Coffee Shop",
    "mchId": "M-87654321",
    "providerReference": "MID180045210008",
    "contactName": "John Smith",
    "contactEmail": "[email protected]",
    "state": 1,
    "timeZone": "Asia/Singapore",
    "country": "SG",
    "supportedPaymentMethods": [
      {
        "paymentMethod": "VISA",
        "profileId": 316
      },
      {
        "paymentMethod": "MASTERCARD",
        "profileId": 316
      }
    ]
  }
}

Example Response (Failure)

Example Response - Create Merchant (providerReference conflict)

{
  "msg": "providerReference already exists",
  "code": 10000
}

Get Merchant Details

Retrieves detailed information about a specific merchant.

Get Merchant Details

GET /api/v2/mchInfo/{mchId}
Authorization: Bearer {jwt}

Parameters

Name	In	Type	Required	Description
mchId	path	string	true	Merchant ID

Response

Status	Meaning	Description	Schema
200	OK (opens in a new tab)	OK	Wrapper: `Response<T>` Data: Merchant
—	`code: 10000`, `"not exist"`	`mchId` not found under this PBO	—

Example Response (200)

Same shape as Create Merchant's response — see the example above.

Update Merchant

Updates an existing merchant with the provided information.

Update Merchant

PUT /api/v2/mchInfo/{mchId}
Content-Type: application/json
Authorization: Bearer {jwt}

Parameters

Same body as Create Merchant — full schema: MerchantRequest. Commonly updated fields:

Name	Type	Required	Description
mchName	`String`	No	Merchant display name
contactName	`String`	No	Merchant contact person's name
contactEmail	`String`	No	Merchant contact email
contactPhone	`String`	No	Merchant contact phone
mcc	`String`	No	Merchant category code (ISO 18245)
region	`String`	No	Region code for this merchant
timeZone	`String`	No	Merchant's local timezone (IANA tz name)
country	`String`	No	Merchant's country (ISO 3166-1 alpha-2 code), e.g. `SG`
transType	`String`	No	Restricts this merchant to a specific transaction type, if set
state	`int`	No	`1` = active (can process payments), `0` = inactive
mdr	`String`	No	Merchant discount rate override for this merchant, if your PBO supports per-merchant MDR
merchantType	`String`	No	Merchant type classification used for reporting/segmentation

Response

Status	Meaning	Description	Schema
200	OK (opens in a new tab)	OK	Wrapper: `Response<T>` Data: Merchant, reflecting the fields as updated
—	`code: 10000`, `"not exist"`	`mchId` not found under this PBO	—

Example Response (200)

Same shape as Create Merchant's response — see the example above.

Delete Merchant

Delete an existing merchant with the provided information. If the merchant has activation code or payment config, it cannot be deleted.

Delete Merchant

DELETE /api/v2/mchInfo/{mchId}
Content-Type: application/json
Authorization: Bearer {jwt}

Parameters

Name	In	Type	Required	Description
mchId	path	string	true	Merchant ID

Response

Status	Meaning	Description	Schema
200	OK (opens in a new tab)	OK	Wrapper: `Response<T>` Data: the deleted `mchId` (string)

Example Response (200)

Example Response - Delete Merchant

{
  "msg": "SUCCESS",
  "code": 0,
  "data": "M-12345678"
}

List Payment Config

Retrieves the payment method configuration currently bound to a merchant.

List Payment Config

GET /api/v2/mchInfo/payment/{mchId}
Authorization: Bearer {jwt}

Parameters

Name	In	Type	Required	Description
mchId	path	string	true	Merchant ID

Response

Status	Meaning	Description	Schema
200	OK (opens in a new tab)	OK	Wrapper: `Response<T>` Data: `Array<PaymentMethodBinding>`, one entry per bound payment method

Example Response (200)

Example Response - List Payment Config

{
  "msg": "SUCCESS",
  "code": 0,
  "data": [
    {
      "mchId": "M-12345678",
      "paymentMethod": "VISA",
      "profileId": 316,
      "profileName": "Visa & Mastercard - US"
    },
    {
      "mchId": "M-12345678",
      "paymentMethod": "MASTERCARD",
      "profileId": 316,
      "profileName": "Visa & Mastercard - US"
    }
  ]
}

Set Payment Config

Binds (or rebinds) a payment method on this merchant to an acquirer profile. Since the whole merchant is bound to a single acquirer profile per payment method on this single-acquirer API, setting a payment method that's already bound overwrites the previous binding.

Set Payment Config

POST /api/v2/mchInfo/payment/{mchId}
Content-Type: application/json
Authorization: Bearer {jwt}

Parameters

Name	In	Type	Required	Description
mchId	path	string	true	Merchant ID
paymentMethod	body	string	true	Payment method name, e.g. `VISA`, `MASTERCARD`, or `ALL` to bind every method the profile supports
profileId	body	number	true	Acquirer profile ID to bind this payment method to, from Get Acquirer Profiles

Request Body Example

Example Request - Set Payment Config

{
  "paymentMethod": "VISA",
  "profileId": 316
}

Response

Status	Meaning	Description	Schema
200	OK (opens in a new tab)	OK	Wrapper: `Response<T>`
—	`code: 10000`, `"profile not exist"`	`profileId` not found under this PBO	—

Example Response (200)

Example Response - Set Payment Config

{
  "msg": "SUCCESS",
  "code": 0
}

Delete Payment Config

⚠️

Breaking change in the current API. The current /api/openapi/v1/mchInfo Delete Payment Config endpoint does not use this path-variable form. It takes acquirerProfileId and currency as query parameters instead of a paymentMethod path variable, and the semantics change too: instead of unbinding a single payment method, it drops the entire (acquirerProfileId, currency) binding — including every payment method configured under it. Update any integration accordingly when you migrate.

Delete Payment Config

DELETE /api/v2/mchInfo/payment/{mchId}/{paymentMethod}
Content-Type: application/json
Authorization: Bearer {jwt}

Parameters

Name	In	Type	Required	Description
mchId	path	string	true	Merchant ID
paymentMethod	path	string	true	Payment method identifier to unbind, e.g. `VISA`

Response

Status	Meaning	Description	Schema
200	OK (opens in a new tab)	OK

Example Response (200)

Example Response - Delete Payment Config

{
  "msg": "SUCCESS",
  "code": 0
}

Acquirer Profile Device