Referencia API

Autenticación

Cabeceras de claves API, gestión de secretos, permisos y rotación.

Modelo de credenciales

Las claves API de MakePay se crean desde el área de desarrolladores de MakeCrypto y se limitan a un equipo. Cada clave tiene un ID público y un secreto. El secreto se guarda como hash y se muestra solo una vez después de crearlo.

Cabecera	Valor	Notas
`x-makecrypto-key-id`	ID de clave API de MakePay	Empieza con `mk_makepay_` para las APIs de pago de MakePay.
`x-makecrypto-key-secret`	Secreto API de un solo uso	Se muestra solo cuando se crea la clave. Guárdalo en tu gestor de secretos del servidor.

Creación de claves API

Los usuarios autenticados con permiso settings.manage pueden crear claves desde el portal o desde la ruta de integración del equipo.

Usa la ruta de descubrimiento de empresas del usuario autenticado cuando una herramienta del portal necesite mostrar los equipos disponibles para el usuario actual:

GET /api/partner/v1/companies

El id de empresa devuelto se usa solo para rutas de dashboard y gestión de claves. Las rutas de pago server-to-server de MakePay resuelven la empresa desde la clave API, así que no requieren un ID de empresa en la URL.

POST /api/partner/v1/companies/{companyId}/integrations
Content-Type: application/json

{
  "name": "Production backend",
  "appSlug": "makepay",
  "allowedOrigins": ["https://merchant.example"]
}

La respuesta incluye integration.key_id, integration.partner_id e integration.keySecret. Guarda keySecret de inmediato.

Autenticación de solicitudes

Envía el ID de clave y el secreto como cabeceras a las rutas de enlaces de pago de MakePay.

x-makecrypto-key-id: mk_makepay_...
x-makecrypto-key-secret: mksec_...

La API también acepta sesiones de navegador MakeCrypto autenticadas para llamadas del portal UI. Las integraciones server-to-server deben usar las cabeceras de clave para que las solicitudes no dependan de una sesión de usuario.

Permisos

Las rutas de lectura aceptan cualquier miembro autenticado del equipo o una clave API válida de MakePay. Las rutas que modifican datos requieren settings.manage para sesiones de navegador. Las claves API se tratan como credenciales de servidor confiables para el equipo propietario, así que mantenlas limitadas a sistemas backend que controlas.

Rotación y revocación

Crea una clave nueva, despliégala en tu backend y luego deshabilita o elimina la clave antigua en el área de desarrolladores de MakeCrypto. Los secretos existentes no se pueden revelar otra vez después de la creación.

Errores de autenticación

401 Unauthorized significa que la solicitud no tiene una sesión válida ni un par de claves API válido.
401 Invalid MakePay API credentials significa que el ID de clave, secreto, scope de producto o estado habilitado no coincide.
403 Forbidden significa que el usuario autenticado no puede acceder al equipo o no tiene el permiso requerido.
404 API key not found se devuelve en rutas de gestión de claves cuando el partnerId seleccionado no existe para el equipo.