Referencia API

Referencia

Rutas, modelos de objetos, enums, configuración y formato de errores.

Referencia de rutas

Método	Ruta
GET	`/api/partner/v1/companies`
Auth Sesión Uso Listar empresas del usuario Devuelve los equipos disponibles para las herramientas del portal del usuario MakeCrypto autenticado.
POST	`/api/partner/v1/onboarding/company`
Auth Secreto de onboarding de partner Uso Crear enlace de onboarding de empresa Crea un borrador de onboarding prellenado por el partner y devuelve una URL de reclamo para el merchant.
GET	`/api/partner/v1/makepay/payment-links`
Auth Clave API de MakePay Uso Listar o crear enlaces de pago Lee los enlaces de pago de la empresa de la clave API o crea enlaces de checkout alojado MakePay.
POST	`/api/partner/v1/makepay/payment-links`
Auth Clave API de MakePay o público Uso Listar o crear enlaces de pago Lee los enlaces de pago de la empresa de la clave API o crea enlaces de checkout alojado MakePay.
POST	`/gateway/pay/{makepayKeyId}`
Auth Clave pública de formulario Uso Enviar formulario HTML de pago Recibe campos de formulario del navegador, crea un enlace de pago alojado y redirige al comprador al checkout.
GET	`/api/partner/v1/makepay/payment-links/{uid}`
Auth Clave API de MakePay Uso Obtener o actualizar enlace de pago Lee el detalle de un enlace de pago o cambia su estado a active, paused o archived.
PATCH	`/api/partner/v1/makepay/payment-links/{uid}`
Auth Clave API de MakePay Uso Obtener o actualizar enlace de pago Lee el detalle de un enlace de pago o cambia su estado a active, paused o archived.
POST	`/api/partner/v1/makepay/payment-links/{uid}/send-request-email`
Auth Clave API de MakePay Uso Enviar solicitud de pago Envía o reenvía el enlace alojado al email del cliente.
GET	`/api/partner/v1/makepay/subscriptions`
Auth Clave API de MakePay Uso Listar o crear suscripciones Devuelve planes de suscripción recurrente de MakePay o crea una suscripción y la primera factura.
POST	`/api/partner/v1/makepay/subscriptions`
Auth Clave API de MakePay Uso Listar o crear suscripciones Devuelve planes de suscripción recurrente de MakePay o crea una suscripción y la primera factura.
GET	`/api/partner/v1/makepay/customers`
Auth Clave API de MakePay Uso Listar o actualizar clientes Devuelve perfiles de clientes MakePay o crea/actualiza clientes por email.
POST	`/api/partner/v1/makepay/customers`
Auth Clave API de MakePay Uso Listar o actualizar clientes Devuelve perfiles de clientes MakePay o crea/actualiza clientes por email.
POST	`/api/partner/v1/makepay/customers/{customerId}/portal`
Auth Clave API de MakePay Uso Crear enlace del portal de cliente Genera bajo demanda una URL firmada del portal de cliente MakePay válida por 24 horas.
GET	`/api/partner/v1/timezones`
Auth Público Uso Listar zonas horarias Devuelve identificadores de zona horaria IANA soportados.
GET	`/api/partner/v1/makepay/settings`
Auth Clave API de MakePay Uso Leer o actualizar configuración de MakePay Lee o actualiza liquidación, redirecciones, comisiones y manejo de pagos incompletos.
PUT	`/api/partner/v1/makepay/settings`
Auth Clave API de MakePay Uso Leer o actualizar configuración de MakePay Lee o actualiza liquidación, redirecciones, comisiones y manejo de pagos incompletos.
GET	`/api/partner/v1/makepay/destination-assets`
Auth Clave API de MakePay Uso Listar activos de destino Devuelve los activos de liquidación soportados y el activo predeterminado actual.
GET	`/api/partner/v1/makepay/webhook-requests`
Auth Clave API de MakePay Uso Listar entregas de webhook Consulta intentos de entrega de webhooks de pago y suscripción, junto con su estado de reintento.

OAuth de onboarding para partners

POST /api/partner/v1/onboarding/company puede incluir un objeto opcional oauth. MakeCrypto valida la app OAuth, URI de redirección, scopes y desafío PKCE antes de crear el enlace de onboarding. Cuando el merchant completa el onboarding, MakeCrypto crea la empresa, concede a la app OAuth acceso a esa empresa y redirige al redirectUri registrado con un code de autorización.

{
  "idempotencyKey": "merchant_123",
  "company": {
    "name": "Acme Markets",
    "website": "https://acme.example"
  },
  "oauth": {
    "clientId": "mco_app_example",
    "redirectUri": "https://apps.makecrypto.io/oauth/callback",
    "scope": "company:read makepay:payment-links:write makepay:settings:read",
    "state": "merchant_123",
    "codeChallenge": "PKCE_S256_CODE_CHALLENGE",
    "codeChallengeMethod": "S256"
  }
}

La app partner debe conservar el code_verifier PKCE correspondiente e intercambiar el código devuelto mediante POST /oauth/token.

Objeto PaymentLink

Campo	Tipo	Notas
`id`	`string`	UUID interno.
`uid`	`string`	Identificador público de enlace de pago usado en rutas de checkout alojado y embebido.
`status`	`"active" \| "paused" \| "archived"`	Estado del enlace gestionado por el merchant.
`payload`	`PaymentLinkPayload`	Pedido, importe, cliente, redirección, metadata, marca y campos runtime del merchant.
`created_at`	`string`	Timestamp ISO.
`updated_at`	`string`	Timestamp ISO.
`expires_at`	`string \| null`	Timestamp de expiración resuelto, o `null` sin expiración.
`publicUrl`	`string`	URL de checkout alojado MakePay, incluida en respuestas de creación, listado, detalle y actualización de estado.

PaymentLinkPayload

Campo	Tipo	Notas
`title`	`string`	Etiqueta visible del pago.
`description`	`string`	Descripción visible al cliente.
`amount`	`string`	Importe decimal a cobrar.
`fiatCurrency`	`string`	Moneda visual opcional como `USD` o `EUR`.
`currency`	`string`	Símbolo de liquidación como `USDT`, `USDC` o `BTC`.
`asset`	`string`	Identificador exacto del activo de destino. Úsalo cuando un símbolo exista en varias cadenas.
`orderId`	`string`	Referencia de pedido o factura del merchant.
`customerEmail`	`string`	Usado para emails y payloads de webhook.
`clientId`	`string`	Identificador opcional de cliente en el lado merchant.
`returnUrl`	`string`	URL del merchant para navegación de retorno genérica.
`successUrl`	`string`	URL del merchant para pagos completados.
`failureUrl`	`string`	URL del merchant para pagos fallidos o cancelados.
`expirationTime`	`"15m" \| "1h" \| "12h" \| "24h" \| "72h" \| "never"`	Duración solicitada del enlace de pago.
`metadata`	`Record<string, unknown>`	Metadata definida por el merchant y devuelta en dashboards y webhooks.
`runtimeMode`	`"merchant_target_net_v2"`	Inyectado por la API para enlaces de pago nuevos.
`billingVersion`	`"v2"`	Inyectado por la API para enlaces de pago nuevos.
`merchantName`	`string`	Inyectado desde la marca de empresa cuando está disponible.
`merchantPictureUrl`	`string`	Inyectado desde el perfil de empresa cuando está disponible.
`merchantLogoUrl`	`string`	Inyectado desde la marca del merchant cuando está disponible.
`merchantPaymentLinkTheme`	`"light" \| "dark" \| "system"`	Inyectado desde la configuración de tema del checkout del merchant.

Objeto Customer

Campo	Tipo	Notas
`id`	`string`	UUID interno.
`uid`	`string`	Identificador público de cliente MakePay usado en enlaces del portal.
`email`	`string`	Email del cliente.
`name`	`string \| null`	Nombre visible del cliente. Editable desde el portal.
`clientId`	`string \| null`	Identificador de cliente del merchant. Solo lectura en el portal.
`metadata`	`Record<string, unknown>`	Metadata definida por el merchant.
`createdAt`	`string`	Timestamp ISO.
`updatedAt`	`string`	Timestamp ISO.
`urls`	`{ customerPortal: string }`	Presente en respuestas de generación de portal. No persistas esta URL.

Respuesta del portal de cliente

POST /api/partner/v1/makepay/customers/{customerId}/portal devuelve una URL de portal firmada para el cliente guardado.

json

{
  "ok": true,
  "companyId": "acct_123",
  "customer": {
    "id": "b834dd77-69b8-41a9-a4b6-95bc9dd14c2d",
    "uid": "cus_01hzy4k6p4w9y2x7e2z7n8a2xm",
    "email": "buyer@example.com",
    "name": "Ada Lovelace",
    "clientId": "client_1042",
    "metadata": {
      "source": "api"
    },
    "createdAt": "2026-04-20T10:00:00.000Z",
    "updatedAt": "2026-04-20T10:00:00.000Z",
    "urls": {
      "customerPortal": "https://makepay.io/billing?company=acct_123&customer=cus_01hzy4k6p4w9y2x7e2z7n8a2xm&expires=1776765600&signature=8d1f..."
    }
  },
  "expiresAt": "2026-04-21T10:00:00.000Z"
}

La URL es válida por 24 horas y usa el payment_link_domain verificado de la empresa cuando está disponible. Si no, cae al origen público de MakePay.

Parámetro de query	Notas
`company`	ID de cuenta de empresa MakeCrypto propietaria del cliente.
`customer`	UID de cliente MakePay.
`expires`	Timestamp Unix en segundos.
`signature`	Firma HMAC sobre `v1:{companyId}:{customerUid}:{expires}`.

Genera enlaces de portal bajo demanda cuando el cliente abre facturación. URLs expiradas, alteradas o de otro cliente se rechazan antes de cargar datos del portal.

Objeto Subscription

Campo	Tipo	Notas
`id`	`string`	UUID interno.
`uid`	`string`	Identificador de suscripción visible para el merchant.
`status`	`"active" \| "paused" \| "overdue" \| "cancelled"`	Estado actual de la suscripción.
`customerEmail`	`string`	Email del cliente usado para recordatorios y coincidencia en portal.
`label`	`string`	Etiqueta de suscripción visible al cliente.
`description`	`string \| null`	Descripción opcional.
`amountUsd`	`string`	Importe recurrente en USD.
`settlementAsset`	`string`	Identificador del activo de liquidación de destino.
`cadence`	`"weekly" \| "biweekly" \| "monthly" \| "custom_months" \| "yearly"`	Cadencia visual.
`billingIntervalUnit`	`"week" \| "month" \| "year"`	Unidad del intervalo de facturación.
`billingIntervalCount`	`number`	Número de unidades entre ciclos.
`startAt`	`string`	Timestamp ISO del primer ciclo de facturación.
`timezone`	`string`	Zona horaria IANA usada para recordatorios.
`metadata`	`Record<string, unknown>`	Metadata definida por el merchant y ajustes avanzados de redirección/tolerancia.
`cycles`	`SubscriptionCycle[]`	Ciclos generados devueltos por rutas de listado y llamadas de dashboard.

Las suscripciones pasan a overdue cuando un ciclo impago supera por al menos 24 horas su timestamp dueAt. MakePay envía un webhook firmado makepay.subscription.status_changed cada vez que cambia el estado de la suscripción.

MakePaySettings

Campo	Tipo	Notas
`status`	`"active" \| "paused"`	Disponibilidad del producto para el equipo.
`defaultDestinationAsset`	`string \| null`	Identificador de activo predeterminado usado cuando los enlaces solo envían `currency`.
`feePaidBy`	`"client" \| "merchant"`	Determina si el cliente o el merchant absorbe las comisiones de MakePay.
`returnRedirectUrl`	`string \| null`	Redirección fallback después del checkout.
`successRedirectUrl`	`string \| null`	Redirección después de un pago completado.
`failureRedirectUrl`	`string \| null`	Redirección después de pago cancelado o fallido.
`underpaymentPercentEnabled`	`boolean`	Habilita tolerancia porcentual.
`underpaymentPercentThreshold`	`number`	Porcentaje permitido de pago insuficiente.
`underpaymentFixedEnabled`	`boolean`	Habilita tolerancia fija.
`underpaymentFixedThreshold`	`number`	Importe fijo permitido de pago insuficiente.

DestinationAsset

Campo	Tipo	Notas
`assetIdentifier`	`string`	Identificador canónico de cadena, símbolo y contrato.
`chainCode`	`string`	Código de cadena de liquidación.
`chainName`	`string`	Nombre legible de la cadena.
`symbol`	`string`	Símbolo del activo.
`name`	`string`	Nombre del activo.
`decimals`	`number`	Decimales del token.
`isDefault`	`boolean`	Indica si este activo es el predeterminado actual de la empresa.

Valores de estado

active: el enlace puede abrirse y pagarse.
paused: el enlace sigue visible para el merchant pero no debe aceptar nuevos inicios de pago.
archived: el enlace se oculta de vistas activas y debe tratarse como cerrado.

Valores de estado de suscripción:

active: la suscripción cobra facturas programadas con normalidad.
paused: recordatorios y cambios de merchant/cliente han pausado la suscripción.
overdue: al menos un ciclo impago lleva 24 horas o más vencido.
cancelled: la suscripción terminó y los ciclos generados impagos se cancelan.

Formato de error

Los errores devuelven JSON con error y, cuando está disponible, errorCode.

{
  "errorCode": "invalid_destination_asset",
  "error": "payload.asset ETH.USDT-... is not available for supported settlement routes."
}