Beneficiarios

Un beneficiario es un destino de dinero que guardas una vez para reutilizarlo tantas veces como quieras. En lugar de escribir el teléfono o la cuenta cada vez que emites un pago, lo guardas con POST /v2/beneficiaries, recibes un beneficiaryId y de ahí en adelante pagas citando ese id. El destino queda congelado el instante en que lo creas —rail, cuenta, banco y documento son inmutables— y nunca se borra a la fuerza: se archiva. Todo esto existe por una sola razón, money-safety: que el dinero salga siempre hacia donde tú verificaste, y no hacia donde un typo o un cambio silencioso lo desvíe.

Qué es un beneficiario y por qué usarlo

Piensa en tu libreta de contactos del teléfono. La primera vez guardas el número de una persona con su nombre; después la llamas por el nombre, no marcando los once dígitos de memoria. Un beneficiario es exactamente eso para mover dinero: registras el rail (el carril por el que viaja el dinero), la cuenta o teléfono destino y el documento del titular, le pones un alias legible, y a cambio recibes un identificador estable —el beneficiaryId—.

Ese id es la pieza que te ahorra trabajo y, más importante, te ahorra errores. Cuando emites un pago con POST /v2/payments tienes dos maneras de decir hacia dónde va el dinero:

1) Destino en línea (inline): pasas rail + beneficiary en el mismo cuerpo del pago. Útil para un destino de una sola vez.
2) Destino guardado: pasas solo beneficiaryId. Alibanca ya conoce el rail, la cuenta y el documento porque los verificaste al crear el beneficiario.

Estas dos maneras son excluyentes (un XOR, en jerga: una o la otra, jamás las dos). Si mandas beneficiaryId y rail+beneficiary en el mismo pago, la petición se rechaza. La razón es de seguridad: un pago no puede tener dos destinos ambiguos.

El destino se congela al crearse

Este es el concepto más importante de todo el recurso, así que léelo con calma. En el momento exacto en que creas un beneficiario, sus tres campos de destino —rail, beneficiary (la cuenta o el teléfono) y documento— quedan congelados: son inmutables. No hay ningún endpoint que los cambie. Ni PATCH, ni ningún otro.

¿Por qué tan estricto? Porque un beneficiario representa hacia dónde va el dinero. Si esos campos fueran editables, existiría un ataque clásico: alguien guarda una cuenta legítima, la deja pasar tus controles internos, y después la reemplaza en silencio por otra cuenta justo antes de que corra tu nómina. Todos tus pagos futuros a ese alias irían al lugar equivocado sin que nada se vea sospechoso. Congelar el destino cierra esa puerta de raíz: el par (alias → cuenta) que verificaste hoy es el mismo par que se paga dentro de seis meses.

La consecuencia práctica es simple y debes tenerla presente al diseñar tu integración: si una cuenta destino cambia, creas un beneficiario nuevo. No editas el viejo —no puedes—; archivas el viejo y guardas el nuevo con los datos correctos. Es un beneficiario por cada destino real.

Se archiva, no se borra

Cuando ya no quieres usar un beneficiario, lo archivas con DELETE /v2/beneficiaries/:id. Ojo con el nombre del verbo: aunque el método HTTP es DELETE, la operación es un soft-delete —un borrado suave—. El beneficiario no desaparece de la base de datos; se marca como archivado y deja de estar disponible para pagos nuevos.

Esto también es money-safety, pero de otro tipo: la trazabilidad. Un beneficiario que recibió dinero es parte de la historia de tus movimientos. Si se borrara de verdad, un pago viejo apuntaría a un destino que ya no existe y tu auditoría quedaría con un hueco. Al archivar, el registro se conserva intacto: puedes consultar el beneficiario por su id, ver a dónde fueron esos pagos y reconstruir cualquier historia. En un sistema que mueve dinero, la regla es preservar y marcar, nunca destruir.

Archivar es reversible en el sentido de la etiqueta: con PATCH puedes volver a poner el estado en activo si te equivocaste. Lo que jamás cambia, insistimos, es el destino congelado.

Los endpoints del recurso

El recurso Beneficiarios tiene cinco endpoints: uno para crear, dos para leer (listar y ver uno), uno para editar la etiqueta y uno para archivar. Todos viven bajo /v2 y todos exigen tus cabeceras de autenticación —x-api-key, x-nonce y x-signature— igual que el resto del API. Los que modifican datos (POST, PATCH, DELETE) llevan además idempotency-key.

Crear un beneficiario

Guarda un destino nuevo. Le pasas el rail, la cuenta o teléfono, el documento del titular y, opcionalmente, un alias legible. Alibanca valida los datos, los congela y te devuelve el beneficiario con su id —ese es el beneficiaryId que usarás al pagar—.

Cuerpo de la petición

curl -X POST https://alibanca-api-production.up.railway.app/v2/beneficiaries \
  -H "x-api-key: sk_test_…" \
  -H "x-signature: …"       # firma RSA-SHA256 del envelope canónico \
  -H "x-nonce: 1721683200123456" \
  -H "idempotency-key: benef-maria-pm-01" \
  -H "Content-Type: application/json" \
  -d '{
    "rail": "PM",
    "account": "04141234567",
    "bankCode": "0138",
    "docType": "V",
    "docNumber": "12345678",
    "alias": "María — Nómina"
  }'

{
  "status": "success",
  "traceId": "trc_9f2a7c1b",
  "payload": {
    "id": "312",
    "alias": "María — Nómina",
    "rail": "PM",
    "account": "04141234567",
    "docType": "V",
    "docNumber": "12345678",
    "status": "ACTIVE",
    "createdAt": "2026-08-18T14:03:11.482Z"
  }
}

El mismo beneficiario, pero por CCE. El riel interbancario pide dos campos más que el pago móvil: el bankCode del banco acreedor —que tiene que coincidir con los 4 primeros dígitos de la cuenta— y el beneficiaryName, el nombre que viaja a la cámara de compensación. El documento va igual que en "PM".

curl -X POST https://alibanca-api-production.up.railway.app/v2/beneficiaries \
  -H "x-api-key: sk_test_…" \
  -H "x-signature: …"       # firma RSA-SHA256 del envelope canónico \
  -H "x-nonce: 1721683200123457" \
  -H "idempotency-key: benef-distribuidora-cce-01" \
  -H "Content-Type: application/json" \
  -d '{
    "rail": "CCE",
    "account": "01020304050600070809",
    "bankCode": "0102",
    "docType": "J",
    "docNumber": "402556677",
    "beneficiaryName": "DISTRIBUIDORA CENTRAL C.A.",
    "alias": "Proveedor CCE"
  }'

El campo que te importa guardar de tu lado es payload.id: ese ben_… es el beneficiaryId. Nota que estado nace en active y que el destino ya viene congelado —lo verás idéntico cada vez que lo consultes—.

Usar el beneficiario en un pago

Este es el pago del ejemplo anterior visto en acción. Ya tienes el beneficiaryId; ahora emites el pago citándolo, sin repetir rail ni cuenta ni documento. Alibanca los resuelve desde el destino congelado.

curl -X POST https://alibanca-api-production.up.railway.app/v2/payments \
  -H "x-api-key: sk_test_…" \
  -H "x-signature: …" \
  -H "x-nonce: 1721683200123456" \
  -H "idempotency-key: pago-nomina-maria-2026-07" \
  -H "Content-Type: application/json" \
  -d '{
    "amountMinor": "150000",
    "currency": "VES",
    "beneficiaryId": "312"
  }'

Fíjate en lo que no está en ese cuerpo: no hay rail ni beneficiary. Con un beneficiario guardado, el destino sobra porque ya vive congelado bajo ese id. El monto va en amountMinor como string en céntimos ("150000" = 1.500,00 VES), nunca como número decimal.

Listar beneficiarios

Devuelve tus beneficiarios en páginas usando paginación keyset. Vale la pena entender qué es, porque no es la paginación por número de página a la que quizás estás acostumbrado.

La paginación clásica por offset dice "dame la página 3, saltando las primeras 40 filas". Es cómoda pero frágil: si alguien crea un beneficiario mientras paginas, las filas se corren y puedes ver un registro dos veces o saltarte otro. La paginación keyset resuelve esto usando un ancla estable: en vez de un número de página, avanzas desde el último id que viste. Como los ids se ordenan de forma descendente y no se reordenan, nunca hay corrimiento.

Cómo iterar

# primera página
curl "https://alibanca-api-production.up.railway.app/v2/beneficiaries?limit=20" \
  -H "x-api-key: sk_test_…" -H "x-signature: …" \
  -H "x-nonce: 1721683200123456"

# siguiente página: cursor = id más bajo de la página anterior
curl "https://alibanca-api-production.up.railway.app/v2/beneficiaries?limit=20&cursor=312" \
  -H "x-api-key: sk_test_…" -H "x-signature: …"

{
  "status": "success",
  "traceId": "trc_5b1e6a90c4d2",
  "payload": {
    "data": [
      {
        "id": "318",
        "alias": "Proveedor CCE",
        "rail": "CCE",
        "account": "01020304050600070809",
        "bankCode": "0102",
        "docType": "J",
        "docNumber": "402556677",
        "beneficiaryName": "DISTRIBUIDORA CENTRAL C.A.",
        "status": "ACTIVE",
        "createdAt": "2026-08-18T15:20:04.001Z"
      },
      {
        "id": "312",
        "alias": "María — Nómina",
        "rail": "PM",
        "account": "04141234567",
        "docType": "V",
        "docNumber": "12345678",
        "status": "ACTIVE",
        "createdAt": "2026-08-18T14:03:11.482Z"
      }
    ],
    "hasMore": false,
    "nextCursor": null
  }
}

Ver un beneficiario

Recupera un beneficiario puntual por su id. Te sirve para confirmar un destino antes de pagarle, para mostrarlo en tu interfaz o para verificar en qué estado quedó tras un archivado. Devuelve el objeto completo, con el destino congelado tal cual lo creaste.

curl "https://alibanca-api-production.up.railway.app/v2/beneficiaries/312" \
  -H "x-api-key: sk_test_…" -H "x-signature: …" \
  -H "x-nonce: 1721683200123456"

{
  "status": "success",
  "traceId": "trc_a12f5c7b3e91",
  "payload": {
    "id": "312",
    "alias": "María — Nómina",
    "rail": "PM",
    "account": "04141234567",
    "docType": "V",
    "docNumber": "12345678",
    "status": "ACTIVE",
    "createdAt": "2026-08-18T14:03:11.482Z"
  }
}

Si el id no existe (o no pertenece a tu llave) recibes un 404 con el cuerpo de error { "error": "…" }. Un beneficiario archivado sí responde aquí: por eso archivamos en vez de borrar —la lectura histórica sigue viva—, solo que su estado vendrá como archived.

Editar alias o estado

PATCH es la única puerta de edición, y a propósito es angosta: solo toca dos campos, alias y estado. Nada del destino congelado es alcanzable desde aquí. Pasas únicamente los campos que quieras cambiar (por eso es PATCH y no PUT: es una edición parcial).

curl -X PATCH https://alibanca-api-production.up.railway.app/v2/beneficiaries/312 \
  -H "x-api-key: sk_test_…" -H "x-signature: …" \
  -H "x-nonce: 1721683200123456" \
  -H "idempotency-key: patch-alias-maria-01" \
  -H "Content-Type: application/json" \
  -d '{ "alias": "María (nómina quincenal)" }'

Archivar un beneficiario

Saca el beneficiario de circulación. Recuerda: es un soft-delete. El registro se conserva —lo puedes seguir consultando por id— pero su estado pasa a archived y deja de estar disponible para pagos nuevos. Es la única forma de archivarlo: el PATCH solo mueve el alias, nunca el estado.

curl -X DELETE https://alibanca-api-production.up.railway.app/v2/beneficiaries/312 \
  -H "x-api-key: sk_test_…" -H "x-signature: …" \
  -H "x-nonce: 1721683200123456" \
  -H "idempotency-key: archivar-maria-01"

{
  "status": "success",
  "traceId": "trc_c88d41f0a2b7",
  "payload": {
    "id": "312",
    "status": "INACTIVE"
  }
}

Después de archivar, un pago que intente usar ese beneficiaryId será rechazado: el destino existe en la historia pero ya no está activo para mover dinero. Y no se revive: un beneficiario INACTIVE ya no admite PATCH (responde 404). Si vuelves a necesitar ese destino, regístralo de nuevo — archivar libera el duplicado, así que la misma cuenta se puede crear otra vez.

Cómo reemplazar un beneficiario

El destino es inmutable, así que reemplazarlo es archivar el viejo y crear uno nuevo. El orden importa: mientras el viejo siga ACTIVE, crear otro con el mismo rail y la misma account te devuelve 409 — es el mismo guard que impide que un reintento de red te acuñe dos destinos activos hacia el mismo lugar.

1. DELETE /v2/beneficiaries/{id}     ← archiva el viejo (queda INACTIVE)
2. POST   /v2/beneficiaries          ← crea el nuevo, con los datos completos

Al revés no funciona. Si intentas crear primero, el 409 te dice exactamente eso.

Errores comunes y cómo evitarlos

Buenas prácticas

Un beneficiario por destino real, no por persona. Si un mismo titular te da dos cuentas, son dos beneficiarios. Como el destino se congela, cada cuenta necesita su propio registro. El alias es donde pones el nombre humano para reconocerlos.

Usa idempotency-key determinística al crear. Si tu proceso reintenta la creación (por un timeout, por ejemplo), la misma idempotency-key te devuelve el mismo beneficiario en vez de crear un duplicado. Deriva la clave de algo estable de tu lado —un id interno del destino—, no de un aleatorio nuevo por intento.

Guarda el beneficiaryId de tu lado y trátalo como el ancla. Es el único campo que no puedes reconstruir tú: nace del POST. Persístelo junto a tu registro interno para que tus pagos futuros solo tengan que citarlo.

Prefiere beneficiarios guardados para destinos recurrentes. Menos campos en cada pago significa menos superficie de error humano, y el destino ya viene verificado y congelado. El destino en línea guárdalo para pagos de una sola vez.

Verifica antes de pagar en flujos críticos. Un GET /v2/beneficiaries/:id te confirma el estado y el destino congelado justo antes de emitir un pago grande. Barato, y te ahorra pagarle a un beneficiario que alguien archivó.