Ajouter/Mettre à jour le site

Utilisez ceci lorsque vous ajoutez un nouvel emplacement de commerçant sur Hyfin, ou lorsque ses détails changent.

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

Point de terminaison

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

Agence

Chaque site, groupe de sites et entreprise de sites appartient à une agence, le niveau supérieur. Indiquez le nom de l'agence sur le site, le groupe de sites ou l'entreprise de sites, et elle est créée la première fois que vous l'utilisez. Par la suite, le même externalId renvoie toujours à la même agence, et les champs d'agence que vous envoyez ne sont pas modifiés. Les agences appartiennent à une seule application; le même externalId dans une autre application correspond donc à une agence différente.

Passerelle de paiement

Pour accepter les paiements par carte ou par ACH, un site a besoin d'une passerelle de paiement pour ce type de paiement. Envoyez un objet gateway, avec la passerelle code et ses credentials, sous le type de paiement. Chaque passerelle nécessite ses propres clés d'identification. Demandez au soutien quelles clés la vôtre exige.

  • L'envoi d'une passerelle active ce type de paiement. Réglez active à false sur le type de paiement pour le désactiver.
  • Le type de paiement doit être offert au site. Sinon, la requête échoue avec payment_card is not available ou ach is not available.
  • Un code inconnu échoue avec Unable to find a payment gateway with the code.
  • Chaque merchantId ne peut être utilisé que par un seul site dans une application. Un deuxième site avec le même échoue avec Another site already exists under this agency with the merchant_id.
Demande
Champ
Type
Description
externalId
String
Votre propre identifiant pour ce site, provenant de votre logiciel. Envoyez de nouveau le même externalId pour mettre à jour ce site au lieu d'en ajouter un nouveau.
name
String
Le nom du site/entreprise.
merchantId
String
L'identifiant du commerçant attribué à l'entreprise par la banque acquéreuse/le processeur.
agency
Agency
Une référence au dossier de l'agence.
location
L'adresse commerciale de ce site/entreprise.
paymentTypes
Les modes de paiement disponibles pour accepter les paiements des clients. Au moins un mode de paiement est requis.
primaryContact
Le principal responsable de l'entreprise. Non requis si accessType = api_only.
siteEnterprise
Une référence au dossier de l'entreprise du site.
siteGroup
Une référence à l'enregistrement du groupe de sites.
branding
La marque unique de l'entreprise, y compris le logo et la couleur principale.
accessType
String
Le niveau d'accès demandé par le site. Utilisez api_only si vous ne souhaitez pas envoyer le courriel de bienvenue au contact principal. Avec api_only, le primaryContact que vous envoyez est ignoré. Toute autre valeur est rejetée avec Invalid access_type.
Default = pro | One of api_only, basic, pro
webhook
Configurer des webhooks pour recevoir des mises à jour en temps réel lorsque des données liées à ce site sont mises à jour.
deleted
Boolean
Ce drapeau représente si l'enregistrement est supprimé et n'est plus disponible pour être utilisé.
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
}


		
Réponse
Champ
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. Un moment précis en format ISO 8601, avec un fuseau horaire. 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"
}


		

Voir aussi