Agregar/Actualizar Sitio

Usa esto cuando incorpores una nueva ubicación de comercio a Hyfin, o cuando cambien sus datos.

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

Punto Final

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

Agencia

Cada sitio, grupo de sitios y empresa de sitios pertenece a una agencia, el nivel superior a ellos. Indique la agencia en el sitio, grupo de sitios o empresa de sitios, y se creará la primera vez que la use. Después de eso, el mismo externalId siempre apunta a la misma agencia, y los campos de la agencia que envíe no se modifican. Las agencias pertenecen a una sola app, por lo que el mismo externalId en otra app es una agencia diferente.

Pasarela de pago

Para recibir pagos con tarjeta o ACH, un sitio necesita una pasarela de pago para ese tipo de pago. Envíe un objeto gateway, con la pasarela code y su credentials, dentro del tipo de pago. Cada pasarela necesita sus propias claves de credenciales. Pregunte a soporte qué claves necesita la suya.

  • Al enviar una pasarela se activa ese tipo de pago. Establezca active en false en el tipo de pago para desactivarlo.
  • El tipo de pago debe estar disponible para el sitio. Si no lo está, la solicitud falla con payment_card is not available o ach is not available.
  • Un código desconocido falla con Unable to find a payment gateway with the code.
  • Cada merchantId solo puede ser usado por un sitio en una app. Un segundo sitio con el mismo falla con Another site already exists under this agency with the merchant_id.
Solicitud
Campo
Tipo
Descripción
externalId
String
Tu propio id para este sitio, desde tu software. Envía de nuevo el mismo externalId para actualizar este sitio en lugar de agregar uno nuevo.
name
String
El nombre del sitio/negocio.
merchantId
String
El ID del comerciante asignado al negocio por el banco adquirente/procesador.
agency
Agency
Una referencia al registro de la agencia.
location
La dirección comercial de este sitio/negocio.
paymentTypes
Los métodos de pago disponibles para aceptar pagos de los clientes. Se requiere al menos un método de pago.
primaryContact
La persona principal responsable del negocio. No es necesario si accessType = api_only.
siteEnterprise
Una referencia al registro de la empresa del sitio.
siteGroup
Una referencia al registro del grupo del sitio.
branding
La marca única del negocio, incluyendo el logotipo y el color principal.
accessType
String
El nivel de acceso que solicita el sitio. Use api_only si no desea enviar el correo electrónico de bienvenida al contacto principal. Con api_only, el primaryContact que envíe se ignora. Cualquier otro valor se rechaza con Invalid access_type.
Default = pro | One of api_only, basic, pro
webhook
Configurar webhooks para recibir actualizaciones en tiempo real cuando se actualizan datos relacionados con este sitio.
deleted
Boolean
Esta bandera representa si el registro ha sido eliminado y ya no está disponible para ser utilizado.
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
}


		
Respuesta
Campo
Tipo
Descripción
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 momento en el tiempo en formato ISO 8601, con zona horaria. 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"
}


		

Ver también