Create a merchant

POST 
/partner/partner/:partnerId/merchant/:merchantId

This endpoint creates a new merchant under your partner profile. The body of the request will need data aligned with your partner configuration, i.e. ISV id used, acquirer id used, etc.

Request

Path Parameters

partnerId PartnerIDrequired

Possible values: non-empty and <= 50 characters

Your partner ID.

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.

application/json

Body

required

The merchant to be created.

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.

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.

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.

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

defaultCardReaderLanguage string

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

cardTokenProviderInfo object

cardTokenProviderId stringrequired

The ID of the card token provider.

cardTokenProviderType object

The type of the card token provider.

clientId string

The client id of the card token provider.

apiKey string

The API key of the card token provider.

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.

Responses

200

OK

application/json

Schema

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.

Example (from schema)

{
  "merchantId": "string",
  "merchantName": "string",
  "partnerFullName": "string",
  "locationName": "string",
  "addressLine1": "string",
  "addressLine2": "string",
  "zipCode": "string",
  "city": "string",
  "countryCodeAlpha2": "string",
  "phone": "string",
  "email": "string",
  "otherEmails": [
    "string"
  ],
  "merchantCategoryCode": "string",
  "currencies": [
    "string"
  ],
  "sharedSecret": "string",
  "partnerId": "string",
  "isvId": "string",
  "isvName": "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
    }
  ],
  "customConfig": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "tipList": [
    {
      "TipBlock": [
        {
          "option": "string",
          "blockNo": "string"
        }
      ]
    }
  ],
  "tipFlag": false,
  "showTipAdjustmentLine": false,
  "anyTerminalAssigned": false,
  "hasAnyAndroidDevice": false,
  "defaultCardReaderLanguage": "string",
  "partnerCloudPosEnabled": false,
  "cardTokenProviderInfo": {
    "cardTokenProviderId": "string",
    "cardTokenProviderType": {
      "typeName": "string",
      "category": "string",
      "clientIdRequired": true
    },
    "clientId": "string",
    "apiKey": "string",
    "partnerSupportsTokenization": false,
    "anyApiKeyDefinedByPartner": false,
    "anyApiKeyDefinedByIsv": false
  },
  "customReceiptTemplate": "string",
  "customHomeScreen": "string",
  "enableAccountTypeSelection": false,
  "defaultCloudMode": false,
  "eCommerceMID": [
    "string"
  ],
  "refundAllowed": false,
  "refundOriginalCardOnly": false,
  "preAuthAllowed": false,
  "theme": "string",
  "creationDate": "string"
}

400

Bad Request

application/json

Schema

Schema

code string

Error code.

reason string

Reason of the error.

messageGuid string

Message guid of the error.

Example (from schema)

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

401

Unauthorized

application/json

Schema

Schema

code string

Error code.

reason string

Reason of the error.

messageGuid string

Message guid of the error.

Example (from schema)

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

403

Forbidden

application/json

Schema

Schema

code string

Error code.

reason string

Reason of the error.

messageGuid string

Message guid of the error.

Example (from schema)

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

409

Conflict

application/json

Schema

Schema

code string

Error code.

reason string

Reason of the error.

messageGuid string

Message guid of the error.

Example (from schema)

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

500

Internal Server Error

application/json

Schema

Schema

code string

Error code.

reason string

Reason of the error.

messageGuid string

Message guid of the error.

Example (from schema)

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

Loading...