Clientes (API)

Un cliente representa a la persona a la que cobrarás dentro del proyecto. La forma habitual de crear un cliente es capturando su tarjeta con un : Zelta Pay tokeniza la tarjeta y crea el cliente automáticamente, emitiendo el webhook customer.created. También puedes crear clientes directamente por API y adjuntarles una tarjeta vaulteada.

Un cliente vaulteado es aquel que tiene una tarjeta almacenada de forma segura por el procesador activo de la cuenta (NMI o Emetec). El token registra qué procesador la guardó, de modo que todos los cobros posteriores se enrutan a ese mismo procesador. Solo los clientes vaulteados pueden ser cobrados con o suscritos con .

Todos los endpoints requieren tu API key de proyecto en el header X-API-Key.

El objeto cliente

Todos los endpoints de clientes devuelven el objeto cliente completo (crear, obtener y adjuntar vault bajo data.customer; listar bajo data.customers como arreglo, junto con total). Los campos ligados a la tarjeta (paymentProvider, customerVaultId, card*) son null hasta que el cliente queda vaulteado.

{
  "success": true,
  "data": {
    "customer": {
      "id": "1234567890",
      "projectId": "prj_1234567890abcdef",
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+50760000000",
      "status": "active",
      "paymentProvider": "nmi",
      "customerVaultId": "nmi_vault_abc123",
      "cardLast4": "1111",
      "cardBrand": "visa",
      "cardBin": "411111",
      "cardExp": "1028",
      "createdAt": "2026-06-04T00:00:00.000Z",
      "updatedAt": "2026-06-04T00:00:00.000Z"
    }
  },
  "message": "Customer created"
}

Campo	Tipo	Descripción
id	string	Identificador único del cliente
projectId	string	Proyecto al que pertenece el cliente
name	string	Nombre del cliente
email	string	Correo del cliente
phone	string | null	Teléfono del cliente (null si no se envió)
status	string	active o inactive
paymentProvider	string | null	Procesador que almacenó la tarjeta (nmi o emetec); null si aún no está vaulteado
customerVaultId	string | null	Id de la bóveda del procesador; null si aún no está vaulteado
cardLast4	string | null	Últimos 4 dígitos de la tarjeta (solo para mostrar)
cardBrand	string | null	Marca de la tarjeta (solo para mostrar)
cardBin	string | null	BIN de la tarjeta (solo para mostrar)
cardExp	string | null	Vencimiento MMYY (solo para mostrar)
createdAt	string	Fecha de creación (ISO 8601)
updatedAt	string	Fecha de última actualización (ISO 8601)

Cobros vs. datos de tarjeta

Los campos card* son metadata de facturación solo para mostrar (para que tu software los almacene y los muestre al usuario). Los cobros siempre usan la referencia de la bóveda (customerVaultId), nunca los dígitos de la tarjeta.

Listar clientes

GET /v1/customers

Parámetros de consulta: paginación estándar (lim, off) más un filtro opcional status (active, inactive).

curl "https://api-pay.zelta.dev/v1/customers?lim=10" \
  -H "X-API-Key: tu-api-key-de-proyecto"

Crear un cliente

POST /v1/customers

Cuerpo de la solicitud:

Campo	Tipo	Requerido	Descripción
name	string	Sí	Nombre del cliente (1-120 caracteres)
email	string	Sí	Correo del cliente (formato de email válido)
phone	string	No	Teléfono del cliente (máx. 40 caracteres)

curl -X POST https://api-pay.zelta.dev/v1/customers \
  -H "X-API-Key: tu-api-key-de-proyecto" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "+50760000000"
  }'

Un cliente creado así aún no tiene tarjeta almacenada. Para poder cobrarle debes adjuntarle una tarjeta vaulteada (ver abajo) o capturarla con un .

Obtener un cliente

GET /v1/customers/:id

curl "https://api-pay.zelta.dev/v1/customers/1234567890" \
  -H "X-API-Key: tu-api-key-de-proyecto"

Adjuntar una tarjeta vaulteada

Asocia al cliente una tarjeta ya tokenizada por el procesador indicado, pasando el id de la bóveda (customerVaultId) que ese procesador devolvió al tokenizarla. Esto convierte al cliente en vaulteado y habilita cobros y suscripciones.

POST /v1/customers/:id/vault

Cuerpo de la solicitud:

Campo	Tipo	Requerido	Descripción
customerVaultId	string	Sí	Id de la bóveda que devolvió el procesador al tokenizar la tarjeta
paymentProvider	string	No	Procesador que almacenó la tarjeta: nmi o emetec. Por defecto nmi
cardLast4	string	No	Últimos 4 dígitos de la tarjeta (solo para mostrar)
cardBrand	string	No	Marca de la tarjeta (máx. 40 caracteres, solo para mostrar)
cardBin	string	No	BIN de la tarjeta (6-8 dígitos, solo para mostrar)
cardExp	string	No	Vencimiento en formato MMYY (solo para mostrar)

Los campos card* son metadata de facturación solo para mostrar: los cobros siempre usan la referencia de la bóveda, nunca estos valores.

curl -X POST https://api-pay.zelta.dev/v1/customers/1234567890/vault \
  -H "X-API-Key: tu-api-key-de-proyecto" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentProvider": "nmi",
    "customerVaultId": "nmi_vault_abc123",
    "cardLast4": "1111",
    "cardBrand": "visa",
    "cardBin": "411111",
    "cardExp": "1028"
  }'

Las colecciones son solo tarjeta

El vaulteo solo aplica a tarjetas (NMI o Emetec). Yappy no puede almacenar una credencial, por lo que no puede usarse para crear clientes vaulteados.

Siguientes pasos

• — captura la tarjeta y crea el cliente en un solo paso
• — cobra a un cliente vaulteado
• — suscribe a un cliente vaulteado a un plan
• — el evento customer.created