Enviar una tarjeta a alguien

Este inicio rápido recorre el ciclo de vida completo de Enviar Tarjetas. Crearás una aplicación de staging, acuñarás un token Bearer con alcance, elegirás un programa de tarjeta, recuperarás una cuenta de gasto con fondos, generarás enlaces alojados de tarjetas virtuales, experimentarás el flujo de activación del destinatario, verificarás la emisión y luego desactivarás un enlace no usado. Al final habrás completado con éxito todas las operaciones públicas de Enviar Tarjetas:

generateVCShareLinks
getVCShareLinks
deactivateVCShareLinks

—todo en el sandbox, donde no se mueven fondos reales de clientes.

Requisitos previos

Una cuenta de Fluz: crearás credenciales de API de staging y acuñarás un token de acceso con alcance en los Pasos 1–2 a continuación.
Las solicitudes van al endpoint GraphQL del sandbox. Los enlaces alojados para destinatarios usan la experiencia estándar de activación de Fluz, pero todas las operaciones de la API usan tu entorno de staging.
Tu cuenta debe tener Enviar Tarjetas habilitado (send_virtual_cards_enabled) o cada operación de Enviar Tarjetas devolverá un error de permisos.
Este inicio rápido usa una cuenta de gasto con fondos como la fuente de fondos. Las tarjetas se financian cuando se reclaman, no cuando se generan los enlaces.

Antes de comenzar

Cada solicitud en esta guía se envía a la API GraphQL de Fluz. Acuñar tu token (Paso 2) se autentica con tu API Key; todas las demás solicitudes usan tu token de acceso Bearer.

POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql

Authorization: Bearer <YOUR_USER_ACCESS_TOKEN>
Content-Type: application/json

curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Authorization: Bearer <YOUR_USER_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "query":"query { getVirtualCardOffers { offerId programName rewardValue } }"
  }'

Cada operación GraphQL a continuación usa este endpoint y tu token Bearer. La única excepción es el Paso 2, que usa el mismo endpoint pero se autentica con tu API Key (Authorization: Basic) para acuñar el token.

El flujo completo

Crea una aplicación de staging

Crea una cuenta de Fluz, luego abre la Consola de Desarrollador y crea una aplicación Staging.Cuando se crea tu aplicación, recibirás:

API Key
User ID
Account ID

Copia los tres valores en un lugar seguro.Si aún no has creado una aplicación de staging, consulta Prepara tus cuentas.

Intercambia tus credenciales por un token Bearer con alcance

Llama a generateUserAccessToken con tu API Key para generar un token de acceso de usuario de corta duración.Este token autoriza cada operación de Enviar Tarjetas a continuación.

curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Authorization: Basic <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "query":"mutation ($userId:UUID!,$accountId:UUID!,$scopes:[ScopeType!]!){generateUserAccessToken(userId:$userId,accountId:$accountId,scopes:$scopes){token scopes}}",
    "variables":{
      "userId":"<YOUR_USER_ID>",
      "accountId":"<YOUR_ACCOUNT_ID>",
      "scopes":[
        "CREATE_VIRTUALCARD",
        "LIST_PAYMENT"
      ]
    }
}'

{
  "data": {
    "generateUserAccessToken": {
      "token": "eyJhbGciOi...",
      "scopes": [
        "CREATE_VIRTUALCARD",
        "LIST_PAYMENT"
      ]
    }
  }
}

Guarda el token devuelto.Lo usarás como:

Authorization: Bearer <YOUR_USER_ACCESS_TOKEN>

para cada solicitud restante.

CREATE_VIRTUALCARD autoriza cada operación de Enviar Tarjetas.Este inicio rápido también solicita LIST_PAYMENT para que puedas recuperar la cuenta de gasto que financia tus tarjetas alojadas.

Nunca expongas tu API Key dentro de una aplicación web o móvil.Genera tokens Bearer del lado del servidor y envía solo el token de acceso a tu cliente.

Recupera una cuenta de gasto con fondos

Las tarjetas virtuales alojadas se financian desde una de tus cuentas de gasto.A diferencia de las tarjetas virtuales regulares, no se reservan fondos cuando se genera el enlace.En su lugar, la cuenta de gasto seleccionada se carga solo cuando el destinatario reclama la tarjeta con éxito.Recupera tus cuentas de gasto disponibles.

query GetSpendAccounts {
  getSpendAccounts {
    userCashBalanceId
    nickname
    availableBalance
    currency
  }
}

{
  "data": {
    "getSpendAccounts": [
      {
        "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "nickname": "Primary Spend Account",
        "availableBalance": 5000,
        "currency": "USD"
      }
    ]
  }
}

Guarda el userCashBalanceId.Proporcionarás este valor al generar tus enlaces de tarjeta alojada.

La cuenta de gasto seleccionada debe pertenecer a tu cuenta y debe contener fondos suficientes cuando el destinatario reclame la tarjeta. Si no hay saldo disponible suficiente al momento de la reclamación, la emisión de la tarjeta falla.

Elige el programa de la tarjeta

Cada tarjeta alojada se emite contra una oferta de tarjeta virtual.La oferta determina el programa emisor, las recompensas disponibles y los límites que aplican a cada tarjeta generada.Recupera las ofertas disponibles para tu cuenta.

query GetVirtualCardOffers {
  getVirtualCardOffers {
    offerId
    programName
    rewardValue
    programLimits {
      dailyLimit
      weeklyLimit
      monthlyLimit
    }
  }
}

{
  "data": {
    "getVirtualCardOffers": [
      {
        "offerId": "11111111-2222-3333-4444-555555555555",
        "programName": "Virtual Card",
        "rewardValue": "1.5%",
        "programLimits": {
          "dailyLimit": 500,
          "weeklyLimit": 2000,
          "monthlyLimit": 5000
        }
      }
    ]
  }
}

Guarda el offerId del programa contra el que deseas emitir.

La oferta seleccionada debe estar:

activa
habilitada para compartir

Si la generación falla porque la oferta no es apta para Enviar Tarjetas, confirma con tu representante de Fluz qué ofertas están habilitadas para el uso alojado.

Genera dos enlaces de tarjeta alojados

Ya estás listo para crear enlaces alojados de Enviar Tarjeta.Cada enlace generado representa una futura tarjeta virtual.En esta etapa:

No se ha emitido ninguna tarjeta.
No se han retirado fondos.
Cada enlace comienza en el estado PENDING.

La cuenta de gasto seleccionada se carga solo cuando un destinatario reclama un enlace.Para este inicio rápido generaremos dos enlaces:

Enlace A: lo reclamarás como el destinatario.
Enlace B: lo dejarás sin reclamar para luego revocarlo.

mutation GenerateVCShareLinks($input: GenerateVCShareLinksInput!) {
  generateVCShareLinks(input: $input) {
    shareLinks
  }
}

{
  "input": {
    "cardLimit": 25,
    "offerId": "<OFFER_ID>",
    "quantity": 2,
    "daysUntilExpiration": 14,
    "shareMethod": "GENERATE_URL",
    "userCashBalanceId": "<USER_CASH_BALANCE_ID>"
  }
}

{
  "data": {
    "generateVCShareLinks": {
      "shareLinks": [
        "https://fluz.app/virtual-prepaid-card/3f8ac...c1",
        "https://fluz.app/virtual-prepaid-card/9b2dd...77"
      ]
    }
  }
}

La respuesta devuelve una URL de activación alojada por cada tarjeta generada.Guarda ambas URLs.Nos referiremos a ellas como:

Enlace A
Enlace B

a lo largo del resto de este inicio rápido.

Entendiendo la configuración de generación

Int

requerido

El monto cargado en cada tarjeta alojada cuando se reclama.Cada tarjeta generada recibe su propio límite independiente.

UUID

requerido

El programa de tarjeta virtual alojada contra el que emitir.La oferta debe estar activa y habilitada para Enviar Tarjetas.

Int

requerido

La cantidad de enlaces alojados a generar.Se crea una solicitud de compartido y una URL alojada por cada cantidad solicitada.

Controla cómo reciben sus enlaces los destinatarios.

GENERATE_URL devuelve URLs alojadas para que tú las distribuyas.
EMAIL envía correos electrónicos a los destinatarios automáticamente.
PHONE_NUMBER envía un SMS a los destinatarios.

UUID

requerido

La cuenta de gasto que financia cada tarjeta generada.Aunque este campo parece opcional en el esquema GraphQL, en la práctica es obligatorio.

Int

Cuánto tiempo tienen los destinatarios para reclamar el enlace alojado.Si se omite, se usa el valor predeterminado del programa.La fecha de vencimiento resultante también se convierte en la fecha de bloqueo de la tarjeta emitida.

Entrega tarjetas por correo electrónico o SMS en su lugar

En lugar de distribuir tú mismo las URLs alojadas, Fluz puede enviar a cada destinatario su propio enlace de activación.

Email

{
  "input": {
    "cardLimit": 25,
    "offerId": "<OFFER_ID>",
    "quantity": 2,
    "shareMethod": "EMAIL",
    "recipientListEmail": [
      "alice@example.com",
      "bob@example.com"
    ],
    "userCashBalanceId": "<USER_CASH_BALANCE_ID>"
  }
}

SMS

{
  "input": {
    "cardLimit": 25,
    "offerId": "<OFFER_ID>",
    "quantity": 2,
    "shareMethod": "PHONE_NUMBER",
    "recipientListPhone": [
      "+18883606660",
      "+18885551234"
    ],
    "userCashBalanceId": "<USER_CASH_BALANCE_ID>"
  }
}

La longitud de la lista de destinatarios debe ser exactamente igual a quantity.Si no coinciden, la validación falla y no se crean enlaces.Los números de teléfono deben:

incluir el código de país
no contener espacios
proporcionarse como strings

Ejemplo:

+18883606660

Generar enlaces alojados no reserva fondos.Si la cuenta de gasto seleccionada no contiene saldo disponible suficiente cuando el destinatario reclama la tarjeta, la emisión falla.

La respuesta de generación devuelve intencionalmente solo las URLs alojadas.No devuelve:

shareRequestBatchId
shareRequestDisplayId

Los recuperarás en el siguiente paso.

Recupera las solicitudes de compartido generadas

Aunque ya tienes las URLs alojadas, normalmente también querrás los registros subyacentes de solicitudes de compartido.Estos contienen:

estado de ciclo de vida
identificadores de lote
IDs de visualización
IDs de tarjetas virtuales emitidas
información de vencimiento

Inmediatamente después de la generación, recupera tus solicitudes de compartido pendientes.

query GetVCShareLinks($input: GetVCShareLinksInput!) {
  getVCShareLinks(input: $input) {
    shareRequestBatchId
    shareRequestDisplayId
    shareObjectStatus
    linkExpirationDate
    virtualCardId
    linkUrl
  }
}

{
  "input": {
    "shareObjectStatuses": [
      "PENDING"
    ]
  }
}

{
  "data": {
    "getVCShareLinks": [
      {
        "shareRequestBatchId": "BATCH123",
        "shareRequestDisplayId": "SR-000001",
        "shareObjectStatus": "PENDING",
        "virtualCardId": null,
        "linkExpirationDate": "2026-08-01T00:00:00Z",
        "linkUrl": "https://fluz.app/virtual-prepaid-card/3f8ac...c1"
      },
      {
        "shareRequestBatchId": "BATCH123",
        "shareRequestDisplayId": "SR-000002",
        "shareObjectStatus": "PENDING",
        "virtualCardId": null,
        "linkExpirationDate": "2026-08-01T00:00:00Z",
        "linkUrl": "https://fluz.app/virtual-prepaid-card/9b2dd...77"
      }
    ]
  }
}

Haz coincidir cada linkUrl devuelto con las URLs devueltas durante la generación.Guarda:

el shareRequestBatchId compartido
ambos valores de shareRequestDisplayId

Los usarás más tarde al desactivar el enlace no utilizado.En este punto, ambos enlaces deberían tener:

Status: PENDING
Virtual Card ID: null

lo que confirma que:

los enlaces se crearon correctamente
ningún destinatario los ha reclamado aún
no se han emitido tarjetas virtuales

Reclama un enlace como el destinatario

Abre el Enlace A en tu navegador.Esta es exactamente la experiencia que ve tu destinatario.El flujo alojado guía a los destinatarios a través de la activación de la tarjeta sin requerir ninguna integración de API.Durante la activación el destinatario:

Abre la página de activación alojada.
Inicia sesión o crea una cuenta de Fluz.
Completa la verificación de identidad.
Completa la autenticación de dos factores.
Agrega una dirección de facturación si aún no hay una registrada.
Crea un PIN de la tarjeta.
Recibe su tarjeta virtual alojada.

Solo después del paso final, Fluz:

emite la tarjeta virtual
la financia desde tu cuenta de gasto
la asigna al destinatario

El destinatario se convierte en el titular autorizado de solo esa tarjeta.Ellos no obtienen acceso a:

tu cuenta de Fluz
tus cuentas de gasto
tus saldos
cualquier otra tarjeta generada

Una vez emitida, el destinatario puede:

ver la tarjeta
gastar en línea
agregarla a Apple Pay o Google Wallet (donde sea compatible)
ver futuras transacciones

Deja el Enlace B sin tocar.Lo usaremos para demostrar la revocación del enlace en la siguiente sección.

Verifica que la tarjeta fue emitida

Después de que el destinatario reclame el Enlace A, recupera nuevamente las solicitudes de compartido.Esta vez verás que el enlace reclamado transiciona de PENDING a ISSUED.

query GetVCShareLinks($input: GetVCShareLinksInput!) {
  getVCShareLinks(input: $input) {
    shareRequestDisplayId
    shareObjectStatus
    virtualCardId
    linkUrl
  }
}

{
  "input": {
    "shareRequestBatchIds": [
      "BATCH123"
    ]
  }
}

{
  "data": {
    "getVCShareLinks": [
      {
        "shareRequestDisplayId": "SR-000001",
        "shareObjectStatus": "ISSUED",
        "virtualCardId": "c8dbe6d8-2f2f-4c90-8d7e-15ef5b06e387",
        "linkUrl": "https://fluz.app/virtual-prepaid-card/3f8ac...c1"
      },
      {
        "shareRequestDisplayId": "SR-000002",
        "shareObjectStatus": "PENDING",
        "virtualCardId": null,
        "linkUrl": "https://fluz.app/virtual-prepaid-card/9b2dd...77"
      }
    ]
  }
}

Tus dos enlaces ahora deberían estar en diferentes estados de ciclo de vida.

Enlace	Estado esperado	Significado
Enlace A	`ISSUED`	El destinatario reclamó la tarjeta con éxito y se creó una tarjeta virtual.
Enlace B	`PENDING`	El enlace aún no ha sido reclamado.

La aparición de un virtualCardId confirma que la emisión de la tarjeta se completó con éxito.

Entendiendo los estados de Enviar Tarjeta

Cada Enviar Tarjeta alojada avanza por uno de cuatro estados de ciclo de vida.

Estado	Significado
`PENDING`	El enlace alojado ha sido generado pero aún no ha sido reclamado.
`ISSUED`	El destinatario reclamó el enlace con éxito y recibió una tarjeta virtual.
`USED`	La tarjeta emitida ha completado al menos una transacción.
`EXPIRED`	El enlace alojado expiró de forma natural o fue desactivado antes de ser reclamado.

Solo los enlaces en estado PENDING pueden desactivarse.Una vez que una tarjeta llega a ISSUED, desactivar el enlace original no revoca la tarjeta.

Desactiva el enlace no utilizado

Supón que el segundo destinatario nunca necesitó su tarjeta, o que se generó un lote por accidente.Puedes revocar cualquier enlace alojado no reclamado usando cualquiera de:

shareRequestBatchIds
shareRequestDisplayIds

Para este inicio rápido desactivaremos solo el Enlace B usando su ID de visualización.

mutation DeactivateVCShareLinks($input: DeactivateVCShareLinksInput!) {
  deactivateVCShareLinks(input: $input)
}

{
  "input": {
    "shareRequestDisplayIds": [
      "SR-000002"
    ]
  }
}

{
  "data": {
    "deactivateVCShareLinks": "1 share requests successfully deactivated!"
  }
}

La desactivación impide de inmediato que el enlace alojado pueda ser reclamado alguna vez.Si un destinatario abre el enlace más tarde, recibirá una experiencia de vencido o revocado en lugar del flujo de activación.

La desactivación solo afecta a enlaces no reclamados.Si un destinatario ya reclamó una tarjeta (ISSUED o USED), el enlace alojado ya no puede usarse para revocarla.Para detener el gasto en una tarjeta emitida, usa los controles apropiados del ciclo de vida de la tarjeta virtual como Bloquear tarjeta virtual.

Confirma el ciclo de vida final

Recupera las solicitudes de compartido una última vez.

query GetVCShareLinks($input: GetVCShareLinksInput!) {
  getVCShareLinks(input: $input) {
    shareRequestDisplayId
    shareObjectStatus
    virtualCardId
  }
}

{
  "input": {
    "shareRequestBatchIds": [
      "BATCH123"
    ]
  }
}

{
  "data": {
    "getVCShareLinks": [
      {
        "shareRequestDisplayId": "SR-000001",
        "shareObjectStatus": "ISSUED",
        "virtualCardId": "c8dbe6d8-2f2f-4c90-8d7e-15ef5b06e387"
      },
      {
        "shareRequestDisplayId": "SR-000002",
        "shareObjectStatus": "EXPIRED",
        "virtualCardId": null
      }
    ]
  }
}

Ya has ejercitado el ciclo de vida completo de Enviar Tarjetas.

Enlace	Estado final	Resultado
Enlace A	`ISSUED`	Reclamado con éxito y emitido a un destinatario.
Enlace B	`EXPIRED`	Revocado con éxito antes de que pudiera ser reclamado.

En este punto has utilizado con éxito las tres operaciones públicas de Enviar Tarjetas:

✅ generateVCShareLinks
✅ getVCShareLinks
✅ deactivateVCShareLinks

Terminaste 🎉

Has completado el ciclo de vida completo de Enviar Tarjetas alojadas: desde la generación hasta la activación por parte del destinatario, el seguimiento del ciclo de vida y la revocación del enlace. En el camino:

Generaste enlaces alojados de tarjetas virtuales.
Seleccionaste la cuenta de gasto que financia las tarjetas de los destinatarios.
Recuperaste y seguiste registros de solicitudes de compartido.
Reclamaste una tarjeta alojada como destinatario.
Verificaste la transición de PENDING a ISSUED.
Revocaste un enlace alojado no utilizado.
Confirmaste el estado final EXPIRED.

Desde aquí puedes explorar flujos de trabajo más avanzados de Enviar Tarjetas.

Descripción general de Enviar Tarjetas

Experiencia del destinatario, reglas del programa, estados del ciclo de vida y referencia completa de errores.

Generar enlaces de compartido

La referencia detallada de la API para cada operación de Enviar Tarjetas.

Obtener cuentas de gasto

Recupera y gestiona las cuentas de gasto utilizadas para financiar tarjetas alojadas.

Gestionar tarjetas virtuales

Bloquea y gestiona tarjetas después de que han sido emitidas a los destinatarios.

¿Quieres saber más?Contáctanos en support@fluz.app para hablar con nuestros expertos o solicitar una demostración.

Comienza

Panel de Fluz

Guías rápidas

Enviar una tarjeta a alguien

Antes de comenzar

El flujo completo

Entendiendo la configuración de generación

Email

SMS

Terminaste 🎉

Descripción general de Enviar Tarjetas

Generar enlaces de compartido

Obtener cuentas de gasto

Gestionar tarjetas virtuales

​Antes de comenzar

​El flujo completo

​Entendiendo la configuración de generación

​Email

​SMS

​Terminaste 🎉

Descripción general de Enviar Tarjetas

Generar enlaces de compartido

Obtener cuentas de gasto

Gestionar tarjetas virtuales

Antes de comenzar

El flujo completo

Entendiendo la configuración de generación

Email

SMS

Terminaste 🎉