Skip to main content

Retrieve a merchant profile

GET 
/partner/partner/:partnerId/merchant/:merchantId

Gets the profile of an existing merchant, including authentication information like shared secret. Depending on the details of the merchant (acquirer, features enabled etc.), the response back will vary in terms of fields.

Request​

Path Parameters

    partnerId PartnerIDrequired

    Possible values: non-empty and <= 50 characters

    Your partner ID.

    merchantId MerchantIDrequired

    Possible values: non-empty and <= 20 characters

    ID of the merchant to be retrieved.

Query Parameters

    detail stringrequired

    Possible values: [merchantobject, merchantlite, merchantid]

    Merchant Profile.

Responses​

OK

Schema
    merchantId 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.

    merchantName stringrequired

    Possible values: <= 100 characters

    The name of the merchant.

    partnerFullName string

    Your partner name. This will be provided by Handpoint

    locationName string

    Possible values: <= 100 characters

    The name of the merchant's location.

    addressLine1 stringrequired

    Possible values: <= 100 characters

    First line of the merchant's address.

    addressLine2 string

    Possible values: <= 100 characters

    Second line of the merchant's address.

    zipCode stringrequired

    Possible values: <= 100 characters

    The zip code of the merchant's address.

    city stringrequired

    Possible values: <= 100 characters

    The city of the merchant's address.

    countryCodeAlpha2 stringrequired

    Possible values: <= 2 characters

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

    phone stringrequired

    Possible values: <= 100 characters

    The phone number of the merchant. It must have the country code included. For example 00447539591287 for a UK number.

    email stringrequired

    Possible values: <= 100 characters

    The email of the merchant.

    otherEmails string[]

    Additional emails of the merchant.

    merchantCategoryCode stringrequired

    Possible values: <= 4 characters

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

    currencies string[]

    Currencies supported by this merchant. It depends on the acquirer in the agreement.

    sharedSecret stringrequired

    Possible values: <= 100 characters

    Shared secret used to tie the merchant with the payment terminal(s), used for authentication.

    partnerId PartnerIDrequired

    Possible values: non-empty and <= 50 characters

    ID of your partner profile (provided by Handpoint)

    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.

    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.

  • ]
    • customConfig object[]

    Custom configuration for the merchant.

  • Array [
    • key stringrequired

    The key of the custom configuration.

    value stringrequired

    The value of the custom configuration.

  • ]
    • 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
  • ]
  • ]
    • 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.

    anyTerminalAssigned boolean

    Default value: false

    True if the merchant has terminals assigned in the TMS.

    hasAnyAndroidDevice boolean

    Default value: false

    True if the merchant has android terminals assigned in the TMS (PAX or Telpo).

    defaultCardReaderLanguage string

    Initial language configured for the payment terminal. Only relevant for setting up Datecs terminals, not relevant for PAX or Telpo.

    partnerCloudPosEnabled boolean

    Default value: false

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

    cardTokenProviderInfo object
    cardTokenProviderId stringrequired

    The ID of the card token provider.

    cardTokenProviderType object

    The type of the card token provider.

    typeName string

    The name of the card token provider type.

    category string

    The category of the card token provider type.

    clientIdRequired boolean

    Indicates if the client id is required for the card token provider type.

    clientId string

    The client id of the card token provider.

    apiKey string

    The API key of the card token provider.

    partnerSupportsTokenization boolean

    Default value: false

    Indicates if the partner supports tokenization.

    anyApiKeyDefinedByPartner boolean

    Default value: false

    Indicates if the partner has any API key defined.

    anyApiKeyDefinedByIsv boolean

    Default value: false

    Indicates if the isv has any API key defined.

    customReceiptTemplate string

    Custom receipt template for the merchant, instead of the default receipt configured in the acquirer agreement. Optional

    customHomeScreen string

    Custom home screen for the merchant, instead of the default home screen configured in the acquirer agreement. Only relevant for setting up Datecs terminals, not relevant for PAX or Telpo.

    enableAccountTypeSelection boolean

    Default value: false

    Allow the merchant to select the account type in the terminal. Only relevant for setting up Datecs terminals, not relevant for PAX or Telpo.

    defaultCloudMode boolean

    Default value: false

    If true the Handpoint Payments app for PAX terminals will start in integrated mode. Not relevant for Datecs devices.

    eCommerceMID string[]

    Possible values: <= 50 characters

    List of ids for this merchant at a ecommerce provider.

    refundAllowed boolean

    Default value: false

    Allow refund operations for the payment terminal.

    refundOriginalCardOnly boolean

    Default value: false

    Only allow refund operations with the original card used for the initial sale transaction.

    preAuthAllowed boolean

    Default value: false

    Allow pre-auth operations for the payment terminal.

    theme string

    Possible values: <= 50 characters

    Theme ID configured for the merchant. A theme allows you to customize the logos and colors appearing ih the Handpoint payments app for PAX devices to match your brand. Contact the Handpoint team if you want us to build a theme for your terminals. Not relevant for Datecs devices.

    creationDate string

    Creation date time of the merchant.

Loading...