Retrieve a list of merchants

POST /partner/partner/:partnerId/merchant

This endpoint will list the merchants under your partner profile.

Request

Path Parameters

partnerId PartnerIDrequired

Possible values: non-empty and <= 50 characters

It is the ID of the partner who owns the terminal.

application/json

Body

required

The page to be retrieved.

initPosition integerrequired

Start the page from this element position.

limit integerrequired

Possible values: >= 1

Number of elements to retrieve in the page.

search string

Apply search term as filter for results. Will look among multiple attributes if the search term is included.

Responses

application/json

Schema
Example (from schema)

Schema

totalRecordsCount integer

Total number of records found.

initPosition integer

Position of the first element retrieved.

batchSize integer

Number of records in this page.

previousBatchAvailable boolean

True if there are elements before the retrieved page.

nextBatchAvailable boolean

True if there are elements after the retrieved page.

terminals object[]

Elements in the retrieved page.

Array [

brand string

Possible values: [DATECS, PAX, TELPO, VIRTUAL]

Brand of the terminal.

terminalType TerminalType

Possible values: [MPED400, MPED800, HILITE, HIPLUS, HIPRO, HIFIVE, BP50PLUS, PAXA920, PAXA80, PAXA77, PAXA50, PAX30, PAXA35, PAXA60, PAXA910, PAXA920PRO, PAXA930, PAXARIES6, PAXARIES8, PAXE500, PAXE700, PAXE800, PAXA800, PAXIM30, TELPOTPS900, TELPOTPS988, TELPOTPS989, TELPOTPS328, TELPOTPS300, TELPOTPS, VT]

Terminal type supported by the TMS. They may belong to different brands: Pax, Telpo, Datecs or Virtual Terminals.

serialNumber SerialNumber

Possible values: <= 20 characters

The serial number of the terminal.

architecture string

Possible values: [MIPS, ARM, ANDROID, NONE]

Architecture of the terminal.

softwareVersion string

Software version configured for the terminal.

acquirerTerminalId string

Terminal ID configured at the acquirer

terminalStatus string

Possible values: [U, I, C, A, D, Z, X]

Status of the terminal:

U - INACTIVE_UNASSIGNED
I - INACTIVE_CHANGED
C - ACTIVE_CHANGED
A - ACTIVE_UNCHANGED
D - PENDING_DELETION
Z - INACTIVE_ERROR
X - ACTIVE_ERROR

partnerId PartnerID

Possible values: non-empty and <= 50 characters

ID of your partner profile (provided by Handpoint)

partnerFullName string

The name of the partner. This will be provided by Handpoint

merchantId MerchantID

Possible values: non-empty and <= 20 characters

It is a unique Handpoint ID for the merchant, it must be unique across ALL TMS merchants. Handpoint will provide a range of IDs that can be used for this purpose.

merchantName string

Possible values: <= 100 characters

The name of the merchant.

creationDate string

Creation date time of the terminal.

lastModifiedDate string

Modification date time of the terminal.

]

merchants object[]

Elements in the retrieved page.

Array [

merchantId MerchantID

Possible values: non-empty and <= 20 characters

It is a unique Handpoint ID for the merchant, it must be unique across ALL TMS merchants. Handpoint will provide a range of IDs that can be used for this purpose.

merchantName string

Possible values: <= 100 characters

The name of the merchant.

merchantCategoryCode string

Possible values: <= 4 characters

4 digit code that identifies the merchant's business type.

partnerId PartnerID

Possible values: non-empty and <= 50 characters

ID of your partner profile (provided by Handpoint)

partnerFullName string

The name of the partner. This will be provided by Handpoint

partnerCloudPosEnabled boolean

Default value: false

True if partner has cloud api access enabled. Handpoint will enable this parameter on your partner profile.

isvId string

Possible values: <= 50 characters

TMS ISV ID associated with the merchant. Handpoint will provide the list of ISV id's associated to your partner profile.

isvName string

ISV name associated with the merchant. Handpoint will provide the list of ISV names associated to your partner profile.

email string

Possible values: <= 100 characters

The email of the merchant.

assignedTerminalsCount integer

Number of terminals assigned to the merchant.

anyTerminalAssigned boolean

True if there is a least one terminal assigned to the merchant.

hasAnyAndroidDevice boolean

True if there is a least one terminal with android architecture assigned to the merchant.

creationDate string

Creation date time of the merchant.

lastModifiedDate string

Modification date time of the merchant.

terminals object[]

List of terminals assigned to the merchant.

Array [

brand string

Possible values: [DATECS, PAX, TELPO, VIRTUAL]

Brand of the terminal.

terminalType TerminalType

Terminal type supported by the TMS. They may belong to different brands: Pax, Telpo, Datecs or Virtual Terminals.

serialNumber SerialNumber

Possible values: <= 20 characters

The serial number of the terminal.

architecture string

Possible values: [MIPS, ARM, ANDROID, NONE]

Architecture of the terminal.

softwareVersion string

Software version configured for the terminal.

acquirerTerminalId string

Terminal ID configured at the acquirer

terminalStatus string

Possible values: [U, I, C, A, D, Z, X]

Status of the terminal:

U - INACTIVE_UNASSIGNED
I - INACTIVE_CHANGED
C - ACTIVE_CHANGED
A - ACTIVE_UNCHANGED
D - PENDING_DELETION
Z - INACTIVE_ERROR
X - ACTIVE_ERROR

partnerId PartnerID

Possible values: non-empty and <= 50 characters

ID of your partner profile (provided by Handpoint)

partnerFullName string

The name of the partner. This will be provided by Handpoint

merchantId MerchantID

Possible values: non-empty and <= 20 characters

It is a unique Handpoint ID for the merchant, it must be unique across ALL TMS merchants. Handpoint will provide a range of IDs that can be used for this purpose.

merchantName string

Possible values: <= 100 characters

The name of the merchant.

creationDate string

Creation date time of the terminal.

lastModifiedDate string

Modification date time of the terminal.

]

currencies string[]

Possible values: >= 1

The list of currencies configured on the acquirer level (usually this is a single currency) Use the ISO 4217 code for the currency.

agreements object[]

Possible values: <= 1

An agreement is the acquirer specific configuration for the merchant.

Array [

acquirer stringrequired

Possible values: <= 50 characters

This is the ID of the acquirer(s) assigned to your partner profile in the handpoint systems. It will be provided by the Handpoint team.

acquirerMid string

Possible values: <= 100 characters

Merchant id provided by the acquirer for the merchant.

merchant MerchantIDrequired

Possible values: non-empty and <= 20 characters

It is a unique Handpoint ID for the merchant, it must be unique across ALL TMS merchants. Handpoint will provide a range of IDs that can be used for this purpose.

currencies string[]

Possible values: >= 1

The list of currencies configured on the acquirer level (usually this is a single currency) Use the ISO 4217 code for the currency.

protocolData object[]

Possible values: >= 1

It is the specific configuration for the acquirer(s) assigned to your partner profile. Ask Handpoint about which values are required per acquirer.

Array [

protocol Protocolrequired

Possible values: [AMEX, BORGUN, EVO, OMNIPAY, PostBridge, TNS, TSYS, VANTIV, ViscusDummy]

The acquirer to which transactions will be sent to by the payment terminals. ViscusDummy is a simulator used for testing purposes.

acquirerMid stringrequired

Possible values: <= 100 characters

It is the merchant id provided by the acquirer.

authorizedMids string[]

Possible values: <= 50 characters

Additional merchant ids provided by the acquirer.

defaultAcquirerTid string

Possible values: <= 100 characters

It is the terminal id provided by the acquirer. Some acquirers do not provide a terminal Id in which case passing a unique 8 digit value would work as well (ideally the last 8 digits of the terminal serial number).

debitCardOnly boolean

Default value: false

It is a flag to indicate if the terminal should only accept debit cards. If activated, the terminal will start declining all transactions made with credit cards. This feature is supported by all acquirers except TNS.

currencies string[]

The list of currencies configured on the acquirer level (usually this is a single currency) Use the ISO 4217 code for the currency.

gwConfigDummyFlag string

Default value: A

For Handpoint internal use only.

supportsMoto boolean

Default value: false

This flag enables support for MOTO transactions from the payment terminal (only available for some acquirers)

motoCvvMandatory boolean

Default value: false

For merchants with MOTO enabled, we can configure if entering the CVV value (3-4 digits at the back of the card) is mandatory or not.

]

debitCardOnly boolean

Default value: false

If any of the protocol data in the agreement has the debitCardOnly flag set to true, then this flag will be set to true.

]

merchantExternalId string

For some acquirers this is the configured merchant id at acquirer side.

zipCode string

Possible values: <= 100 characters

The zip code of the merchant's address.

city string

Possible values: <= 100 characters

The city of the merchant's address.

addressLine1 string

Possible values: <= 100 characters

First line of the merchant's address.

countryCodeAlpha2 string

Possible values: <= 2 characters

The country code of the merchant's address. ISO 3166 Alpha 2.

tipFlag boolean

Default value: false

Enable tip functionality in the merchant. Only relevant for setting up Datecs terminals, not relevant for PAX or Telpo.

showTipAdjustmentLine boolean

Default value: false

Show tip adjustment line in the receipt. It is only used if tipFlag is true. Only relevant for setting up Datecs terminals, not relevant for PAX or Telpo.

tipList object[]

Tip list configured for the merchant. Only relevant for setting up Datecs terminals, not relevant for PAX or Telpo.

Array [

TipBlock object[]

Array [

option string

blockNo string

]

{
  "totalRecordsCount": 0,
  "initPosition": 0,
  "batchSize": 0,
  "previousBatchAvailable": true,
  "nextBatchAvailable": true,
  "terminals": [
    {
      "brand": "DATECS",
      "terminalType": "MPED400",
      "serialNumber": "string",
      "architecture": "MIPS",
      "softwareVersion": "string",
      "acquirerTerminalId": "string",
      "terminalStatus": "U",
      "partnerId": "string",
      "partnerFullName": "string",
      "merchantId": "string",
      "merchantName": "string",
      "creationDate": "string",
      "lastModifiedDate": "string"
    }
  ],
  "merchants": [
    {
      "merchantId": "string",
      "merchantName": "string",
      "merchantCategoryCode": "string",
      "partnerId": "string",
      "partnerFullName": "string",
      "partnerCloudPosEnabled": false,
      "isvId": "string",
      "isvName": "string",
      "email": "string",
      "assignedTerminalsCount": 0,
      "anyTerminalAssigned": true,
      "hasAnyAndroidDevice": true,
      "creationDate": "string",
      "lastModifiedDate": "string",
      "terminals": [
        {
          "brand": "DATECS",
          "terminalType": "MPED400",
          "serialNumber": "string",
          "architecture": "MIPS",
          "softwareVersion": "string",
          "acquirerTerminalId": "string",
          "terminalStatus": "U",
          "partnerId": "string",
          "partnerFullName": "string",
          "merchantId": "string",
          "merchantName": "string",
          "creationDate": "string",
          "lastModifiedDate": "string"
        }
      ],
      "currencies": [
        "string"
      ],
      "agreements": [
        {
          "acquirer": "string",
          "acquirerMid": "string",
          "merchant": "string",
          "currencies": [
            "string"
          ],
          "protocolData": [
            {
              "protocol": "AMEX",
              "acquirerMid": "string",
              "authorizedMids": [
                "string"
              ],
              "defaultAcquirerTid": "string",
              "debitCardOnly": false,
              "currencies": [
                "string"
              ],
              "gwConfigDummyFlag": "A",
              "supportsMoto": false,
              "motoCvvMandatory": false
            }
          ],
          "debitCardOnly": false
        }
      ],
      "merchantExternalId": "string",
      "zipCode": "string",
      "city": "string",
      "addressLine1": "string",
      "countryCodeAlpha2": "string",
      "tipFlag": false,
      "showTipAdjustmentLine": false,
      "tipList": [
        {
          "TipBlock": [
            {
              "option": "string",
              "blockNo": "string"
            }
          ]
        }
      ]
    }
  ]
}

Bad Request

application/json

Schema
Example (from schema)

Schema

code string

Error code.

reason string

Reason of the error.

messageGuid string

Message guid of the error.

{
  "code": "string",
  "reason": "string",
  "messageGuid": "string"
}

Unauthorized

application/json

Schema
Example (from schema)

Schema

code string

Error code.

reason string

Reason of the error.

messageGuid string

Message guid of the error.

{
  "code": "string",
  "reason": "string",
  "messageGuid": "string"
}

Forbidden

application/json

Schema
Example (from schema)

Schema

code string

Error code.

reason string

Reason of the error.

messageGuid string

Message guid of the error.

{
  "code": "string",
  "reason": "string",
  "messageGuid": "string"
}

Conflict

application/json

Schema
Example (from schema)

Schema

code string

Error code.

reason string

Reason of the error.

messageGuid string

Message guid of the error.

{
  "code": "string",
  "reason": "string",
  "messageGuid": "string"
}

Internal Server Error

application/json

Schema
Example (from schema)

Schema

code string

Error code.

reason string

Reason of the error.

messageGuid string

Message guid of the error.

{
  "code": "string",
  "reason": "string",
  "messageGuid": "string"
}

Retrieve a list of merchants

/partner/partner/:partnerId/merchant

Request​

Path Parameters

Body

Responses​

Request

Responses