Skip to main content

Merchant Configuration

The Stitch in-person platform supports different types of merchants: standard, sub-merchant and ISO. The information required to enable card present payments for each type of merchant differs slightly. Within this section, we'll focus on the standard type of merchants.

The below payload example creates a new merchant in the Stitch system with the following details:

  • Basic Information: Sets up a merchant named "Test Merchant" with contact information (phone, email, mobile)
  • Business Classification: The mcc (Merchant Category Code) "5814" identifies this as a restaurant or food service business.
  • Location Details: Provides the merchant's physical address in London with postal code and region code.
  • Merchant Configuration:
    • tenantId: Links this merchant to a specific tenant in the Stitch system.
    • merchantType: Defines this as a "standard" merchant (as opposed to sub-merchant or ISO).
    • clientMerchantReferenceId: Provides an external reference ID for integration with other systems.
POST /v/1/merchants
{
  "name": "Test Merchant",
  "mcc": "5814",
  "phone": "+44111234567",
  "email": "hello@acmecoffeeinc.com",
  "mobile": "+44831234567",
  "address": "17 Java avenue",
  "city": "London",
  "postalCode": "SW1A 0AA",
  "regionCode": "LO",
  "tenantId": "{{tenant_id}}",
  "merchantType": "standard",
  "clientMerchantReferenceId": "external-ref-3"
}

After creating the merchant with the above payload, you'll also need to configure payment methods for the merchant as described in the subsequent sections.

tip

You can leave out currency, timeZone, countryCode and languageCode. These values will be auto set by pulling the defaults from the account settings created by Stitch. These defaults can be overridden per merchant if the merchants are distributed across territories with multiple timezones, languages, or currencies.

note

The region code is territory specific and the error response when creating a merchant will give you a list of allowed values.

For South Africa, valid region codes are: "EC" (Eastern Cape), "FS" (Free State), "GP" (Gauteng), "KZN" (KwaZulu-Natal), "LP" (Limpopo), "MP" (Mpumalanga), "NW" (North West), "NC" (Northern Cape), and "WC" (Western Cape).

After a merchant is created, payment methods need to be allowed, depending on the products enabled for the merchant. For example: card present, softPOS, QR, etc. When adding the payment method to the merchant it requires the ID of the payment method so you'll need to look that up first on the tenant.

POST /v/1/merchants/{{merchant_id}}/payment-method-routes
{
  "tenantPaymentMethodRouteId" : "{{tenant_payment_method_id}}",
   "mid" : "L000003",
  "defaultRoute" : true
}
note

mid MID=Merchant Identifier, they are unique per route. If you don't provide a MID Stitch can auto generate one as long as the tenant was set up with this feature enabled.

note

defaultRoute set this to true as currently there will only be one route configured per merchant. This is only applicable in territories where routing is allowed or mandated based on card scheme.