Merchant - MineSec Developer Docs

API endpoints for managing merchants. Same authentication as the rest of the Service API — see the Overview for what's new in this version.

A merchant's acceptance setup is split into two parts:

Merchant profile (this section, top-level fields below) — name, contact info, MCC, etc.
Merchant payment config — the bindings that tell MineSec which acquirer profile to route each payment method through.

Merchant List

GET /api/openapi/v1/mchInfo
Authorization: Bearer {jwt}

Parameters

Name	Type	Required	Description
uuid	query	false	Filter by merchant UUID (exact match)
mchId	query	false	Filter by merchant ID (exact match)
mchName	query	false	Filter by merchant name (partial match)
activationCode	query	false	Filter by an activation code issued to this merchant
pageNumber	query	false	Default `1`
pageSize	query	false	Default `20`; use `-1` to return all on one page

Response

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

acquirers vs. Merchant payment config: acquirers on this response is a read-only summary for quick display — you cannot write to it directly. To actually create, update, or delete a merchant's acquirer/payment-method bindings, use the Merchant payment config endpoints below.

Example Response (200)

{
  "msg": "SUCCESS",
  "code": 0,
  "data": {
    "total": 1,
    "current": 1,
    "hasNext": false,
    "records": [
      {
        "uuid": "abcd-1234-efgh-5678",
        "mchId": "M-12345678",
        "id": "M-12345678",
        "groupId": "G-12345678",
        "mchName": "Coffee Shop",
        "mcc": "5811",
        "region": "US-CA",
        "timeZone": "America/Los_Angeles",
        "country": "US",
        "contactName": "John Smith",
        "contactPhone": "555-1234",
        "contactEmail": "[email protected]",
        "contactAddress": "123 Main St, Springfield",
        "state": 1,
        "currency": "USD",
        "supportedPayments": ["01", "02", "03"],
        "hasKioskTerminal": false,
        "acquirers": [
          {
            "profileId": 5201,
            "profileName": "Visa & Mastercard - US",
            "currency": "USD",
            "acqType": "card",
            "methodList": "{\"01\":[],\"02\":[]}",
            "emvList": "{\"01\":[1675],\"02\":[1676]}"
          },
          {
            "profileId": 5202,
            "profileName": "Unionpay - US",
            "currency": "USD",
            "acqType": "card",
            "methodList": "{\"03\":[]}",
            "emvList": "{\"03\":[1680]}"
          }
        ],
        "createdBy": "[email protected]",
        "createdAt": "2026-05-01T02:12:57+0000",
        "updatedAt": "2026-05-03T11:00:00+0000"
      }
    ]
  }
}

Create Merchant

Creates the merchant profile. If your PBO has a group-level default acquirer profile (asDefault: true) configured for card payments, a matching Merchant payment config entry is auto-created for it; otherwise no payment config is created and you must add one explicitly afterwards.

POST /api/openapi/v1/mchInfo
Content-Type: application/json
Authorization: Bearer {jwt}

Parameters

Name	Type	Required	Description
mchName	`String`	Yes	Merchant name
currency	`String`	Yes	Merchant's default settlement currency (ISO 4217)
contactName	`String`	Yes	Contact name
contactEmail	`String`	Yes	Contact email
mcc	`String`	No	Merchant category code (ISO 18245)
region	`String`	No	Region code
timeZone	`String`	No	Merchant timezone; defaults to the PBO's timezone if omitted
country	`String`	No	Country code (ISO 3166-1 alpha-2)
transType	`String`	No	Transaction type restriction, if any
contactPhone	`String`	No	Contact phone
contactAddress	`String`	No	Contact address (shown on e-receipt if set)
receiptLogo	`String`	No	Merchant logo URL or base64-encoded jpg/jpeg/png
receiptInfo	`String`	No	Extra text shown on the e-receipt
state	`Byte`	No	`1` = active (can process payments), `0` = inactive
providerReference	`String`	No	Your own unique reference ID for this merchant
passcode	`String`	No	Operator passcode for this merchant, if applicable
mdr	`String`	No	Merchant discount rate override, if applicable
merchantType	`String`	No	Merchant type classification
additionalData	`Object`	No	Free-form extra metadata, stored as-is

Request Body Example

{
  "mchName": "Coffee Shop",
  "currency": "USD",
  "contactName": "John Smith",
  "contactEmail": "[email protected]",
  "contactPhone": "555-1234",
  "contactAddress": "123 Main St, Springfield",
  "mcc": "5811",
  "timeZone": "America/Los_Angeles",
  "country": "US",
  "state": 1
}

Response

Status	Meaning	Description	Schema
200	OK (opens in a new tab)	Created	Wrapper: `Response<T>` Data: `Merchant` (same shape as list, see above)

Get Merchant Details

GET /api/openapi/v1/mchInfo/{mchId}
Authorization: Bearer {jwt}

Parameters

Name	In	Type	Required	Description
mchId	path	string	true	Merchant ID

Response

Same shape as Merchant List's records[] item, wrapped in Response<T>.

Update Merchant

Full replace of the merchant profile fields (not the payment config — see Merchant payment config for that).

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

Body accepts the same fields as Create Merchant.

Response

Status	Meaning	Description	Schema
200	OK (opens in a new tab)	OK	Wrapper: `Response<T>` Data: `Merchant` (same shape as list, see above)

Delete Merchant

If the merchant has an issued activation code or payment config, it cannot be deleted.

DELETE /api/openapi/v1/mchInfo/{mchId}
Authorization: Bearer {jwt}

Response

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

Merchant payment config

This is the sub-resource that connects a merchant to an acquirer profile. Each entry binds one (acquirerProfileId, currency) pair to a set of payment methods, along with the EMV configs those methods should use.

If the merchant uses a single acquirer, you need exactly one entry. Create one binding for that acquirer profile and currency, list every payment method the merchant accepts under it, and the merchant is fully configured. That is the common case.

The binding is stored per payment method rather than per merchant, so a merchant can have several entries when you need it — for example VISA and MASTERCARD routed to Acquirer A while UNIONPAY goes to Acquirer B, or a card profile alongside a qr profile. Add one entry per acquirer profile the merchant should use; nothing extra is required if you only ever add one.

List Payment Config

Returns one page-entry per (acquirerProfileId, currency) group, each with its full payment method / EMV subtree.

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

Parameters

Name	In	Type	Required	Description
mchId	path	string	true	Merchant ID
pageNumber	query	number	false	Default `1`
pageSize	query	number	false	Default `20`

Response

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

Example Response (200)

{
  "msg": "SUCCESS",
  "code": 0,
  "data": {
    "total": 2,
    "current": 1,
    "hasNext": false,
    "records": [
      {
        "merchantId": "M-12345678",
        "acquirerProfileId": "5201",
        "acquirerProfileName": "Visa & Mastercard - US",
        "acqType": "card",
        "currency": "USD",
        "mid": "1234567850001",
        "paymentMethods": [
          {
            "paymentMethodCode": "01",
            "paymentMethodName": "VISA",
            "displayName": "Visa",
            "paymentType": "card",
            "emvs": [{ "emvId": 1675, "emvName": "l3-visa" }]
          },
          {
            "paymentMethodCode": "02",
            "paymentMethodName": "MASTERCARD",
            "displayName": "Mastercard",
            "paymentType": "card",
            "emvs": [{ "emvId": 1676, "emvName": "l3-mastercard" }]
          }
        ]
      },
      {
        "merchantId": "M-12345678",
        "acquirerProfileId": "5202",
        "acquirerProfileName": "Unionpay - US",
        "acqType": "card",
        "currency": "USD",
        "mid": "1234567850002",
        "paymentMethods": [
          {
            "paymentMethodCode": "03",
            "paymentMethodName": "UNIONPAY",
            "displayName": "UnionPay",
            "paymentType": "card",
            "emvs": [{ "emvId": 1680, "emvName": "l3-unionpay" }]
          }
        ]
      }
    ]
  }
}

Save Payment Config

Adds a new (acquirerProfileId, currency) binding for this merchant. Fails if any (currency, paymentMethodCode) in the payload is already bound to a different acquirer profile on this merchant.

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

Parameters

Name	Type	Required	Description
acquirerProfileId	`String`	Yes	Acquirer profile to bind, from Acquirer Profile
currency	`String`	Yes	Currency this binding applies to
mid	`String`	No	Merchant ID at the acquirer host for this binding, if different from the PBO-level default
paymentMethods	`Array<Object>`	No	Payment methods to bind under this profile/currency
paymentMethods[].paymentMethodCode	`String`	Yes	Payment method code, see PaymentMethod enum
paymentMethods[].allows	`Array<String>`	No	Allowed transaction types and is reserved for future use.
paymentMethods[].emvs	`Array<Object>`	No	EMV configs to apply, from EMV Config
paymentMethods[].emvs[].emvId	`Number`	Yes	EMV config ID

Request Body Example

{
  "acquirerProfileId": "5201",
  "currency": "USD",
  "mid": "1234567850001",
  "paymentMethods": [
    {
      "paymentMethodCode": "01",
      "emvs": [{ "emvId": 1675 }]
    },
    {
      "paymentMethodCode": "02",
      "emvs": [{ "emvId": 1676 }]
    }
  ]
}

Response

Status	Meaning	Description	Schema
200	OK (opens in a new tab)	OK	Wrapper: `Response<T>`
—	`code: 10000`	`(currency, paymentMethodCode)` already bound to another profile	—

Example Response (Failure)

{
  "msg": "VISA/USD is already bound to acquirer profile 5202",
  "code": 10000
}

Update Payment Config

Whole-subtree replace for the given (acquirerProfileId, currency): existing payment methods for this binding are dropped and replaced with the payload.

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

Body: same as Save Payment Config.

Delete Payment Config

Changed from the legacy API. The legacy /api/v2/mchInfo Delete Payment Config endpoint takes a paymentMethod path variable and unbinds a single payment method. This endpoint instead takes acquirerProfileId and currency as query parameters and drops the entire (acquirerProfileId, currency) binding — every payment method configured under it, not just one. Account for this semantic change when migrating.

DELETE /api/openapi/v1/mchInfo/payment/{mchId}
Authorization: Bearer {jwt}

Parameters

Name	In	Type	Required	Description
mchId	path	string	true	Merchant ID
acquirerProfileId	query	string	true	Acquirer profile ID of the binding to drop
currency	query	string	true	Currency of the binding to drop

Response

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

Acquirer Profile Device