Add/Update Site

Use this when you bring a new merchant location onto Hyfin, or its details change.

A site must be created prior to making any of the standard API calls. A unique site should be created for each unique Merchant ID (MID).

Endpoint

The following endpoint can be used to add or update sites. You must replace the {base_url} variable.

POST
{base_url}/api/v4/site/addUpdate

Agency

Every site, site group and site enterprise belongs to an agency, the level above them. Name the agency on the site, site group or site enterprise, and it is created the first time you use it. After that, the same externalId always points to the same agency, and agency fields you send are not changed. Agencies belong to one app, so the same externalId in another app is a different agency.

Payment gateway

To take card or ACH payments, a site needs a payment gateway for that payment type. Send a gateway object, with the gateway code and its credentials, under the payment type. Each gateway needs its own credential keys. Ask support which keys yours needs.

  • Sending a gateway turns that payment type on. Set active to false on the payment type to turn it off.
  • The payment type must be available to the site. If it is not, the request fails with payment_card is not available or ach is not available.
  • An unknown code fails with Unable to find a payment gateway with the code.
  • Each merchantId can be used by only one site in an app. A second site with the same one fails with Another site already exists under this agency with the merchant_id.
Request
Field
Type
Description
externalId
String
Your own id for this site, from your software. Send the same externalId again to update this site instead of adding a new one.
name
String
The name of the site/business.
merchantId
String
The merchant id assigned to the business by the acquiring bank/processor.
agency
Agency
A reference to the agency record.
location
The business address of this site/business.
paymentTypes
The payment methods available to accept payments from customers. At least one payment method is required.
primaryContact
The main person responsible for the business. Not required if accessType = api_only.
siteEnterprise
A reference to the site enterprise record.
siteGroup
A reference to the site group record.
branding
The unique branding of the business including the logo and primary color.
accessType
String
The level of access the site is requesting. Use api_only if you do not wish to send the welcome email to the primary contact. With api_only the primaryContact you send is ignored. Any other value is rejected with Invalid access_type.
Default = pro | One of api_only, basic, pro
webhook
Setup webhooks to receive real-time updates when data related to this site is updated.
deleted
Boolean
This flag represents whether the record is deleted and no longer available to be used.
Sample Request
			
{
  "externalId": "12345678",
  "name": "Sample Company",
  "merchantId": "123544633452",
  "agency": {
    "externalId": "65123125",
    "name": "Sample Agency"
  },
  "location": {
    "addressLine1": "123 Main Street",
    "addressLine2": "Suite 123",
    "city": "Naples",
    "stateCode": "FL",
    "zipCode": "34102",
    "phone": "239-123-1234",
    "website": "https://samplecompany.com"
  },
  "primaryContact": {
    "firstName": "Thomas",
    "lastName": "Smith",
    "email": "tsmith@samplecompany.com",
    "mobilePhone": "239-987-6543"
  },
  "paymentTypes": {
    "paymentCard": {
      "active": true,
      "gateway": {
        "code": "gatewaycode",
        "credentials": {
          "key": "value",
          "key2": "value2"
        }
      }
    },
    "ach": {
      "active": true,
      "gateway": {
        "code": "gatewaycode",
        "credentials": {
          "key": "value",
          "key2": "value2"
        }
      }
    }
  },
  "branding": {
    "logoUrl": "https://samplecompany.com/images/logo.png",
    "color": "#336699"
  },
  "accessType": "basic",
  "webhook": {
    "active": true,
    "url": "https://mysoftware.com/webhook"
  },
  "deleted": false
}


		
Response
Field
Type
Description
success
Boolean
Whether the record was added or updated successfully.
action
String
Informs whether the record was added or updated. Will only be returned if success is true.
One of added, updated
_id
String
The id we assign to the record.
updatedAt
The date the record was last updated. A moment in time in ISO 8601, with a time zone. Format = YYYY-MM-DDTHH:mm:ss.SSSZ
errors
String [ ]
A list of errors. Will only be returned if success is false.
			
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "updatedAt": "2025-05-30T19:19:44.143Z"
}


		

Related