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 utilizado. Al final habrás completado con éxito cada operación pública 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 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

Excepto para acuñar tu token (Paso 2), cada solicitud en esta guía se envía a la API GraphQL de Fluz utilizando 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 utiliza este endpoint y tu token Bearer. La única excepción es el Paso 2, que intercambia tus credenciales de aplicación por un token de acceso a través del servicio OAuth.

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 cree tu aplicación, recibirás:

clientId
clientSecret

Copia ambos valores en un lugar seguro. Tu clientSecret solo se muestra una vez.Si aún no has creado una aplicación de staging, consulta Prepara tus cuentas.

Intercambia tus credenciales por un token Bearer con alcance

Envía tus credenciales de aplicación al servicio OAuth para generar un token de acceso de usuario de corta duración.Este token autoriza cada operación de Enviar tarjetas que sigue.

curl -X POST https://oauth-service.fluzapp.com/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query":"mutation ($clientId:String!,$clientSecret:String!,$scopes:[Scope!]!){generateUserAccessToken(clientId:$clientId,clientSecret:$clientSecret,scopes:$scopes){accessToken expiresIn scopes}}",
    "variables":{
      "clientId":"<APPLICATION_CLIENT_ID>",
      "clientSecret":"<APPLICATION_CLIENT_SECRET>",
      "scopes":[
        "CREATE_SHARE_LINK",
        "LIST_PAYMENT"
      ]
    }
}'

{
  "data": {
    "generateUserAccessToken": {
      "accessToken": "eyJhbGciOi...",
      "expiresIn": 3600,
      "scopes": [
        "CREATE_SHARE_LINK",
        "LIST_PAYMENT"
      ]
    }
  }
}

Guarda el accessToken devuelto.Lo usarás como:

Authorization: Bearer <YOUR_USER_ACCESS_TOKEN>

para cada solicitud restante.

CREATE_SHARE_LINK 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 clientSecret dentro de un navegador o aplicación móvil.Genera tokens Bearer del lado del servidor y reenví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 suficiente saldo disponible en el 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 se 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 cual deseas emitir.

La oferta seleccionada debe estar:

activa
habilitada para compartir

Si la generación falla porque la oferta no es elegible para Enviar tarjetas, confirma con tu representante de Fluz qué ofertas están habilitadas para uso compartido 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 destinatario.
Enlace B: lo dejarás sin reclamar para poder revocarlo más tarde.

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.

Comprender la configuración de generación

cardLimit

Int

requerido

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

offerId

UUID

requerido

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

quantity

Int

requerido

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

Controla cómo los destinatarios reciben sus enlaces.

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

userCashBalanceId

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.

daysUntilExpiration

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 las 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.

Correo electrónico

{
  "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 cadenas

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 de la tarjeta falla.

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

shareRequestBatchId
shareRequestDisplayId

Los recuperarás en el siguiente paso.

Recupera las solicitudes de uso compartido generadas

Aunque ya tienes las URLs alojadas, por lo general también querrás los registros subyacentes de solicitud de uso compartido.Estos contienen:

estado del 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 uso 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 con éxito
ningún destinatario los ha reclamado aún
no se han emitido tarjetas virtuales

Reclama un enlace como 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 transacciones futuras

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 uso compartido.Esta vez verás que el enlace reclamado pasa 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 ha creado 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 ha completado con éxito.

Comprender los estados de Enviar tarjeta

Cada Enviar tarjeta alojada progresa a través de uno de cuatro estados del ciclo de vida.

Estado	Significado
`PENDING`	El enlace alojado se ha 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 se desactivó antes de ser reclamado.

Solo los enlaces en estado PENDING se pueden desactivar.Una vez que una tarjeta alcanza 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 sea reclamado alguna vez.Si un destinatario abre el enlace más tarde, recibirá una experiencia de expirado 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 se puede usar 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 uso 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 y emitido con éxito 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

Listo 🎉

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 uso 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 uso 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 se hayan emitido 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

Comprender la configuración de generación

Correo electrónico

SMS

Listo 🎉

Descripción general de Enviar tarjetas

Generar enlaces de uso compartido

Obtener Cuentas de gasto

Gestionar tarjetas virtuales

​Antes de comenzar

​El flujo completo

​Comprender la configuración de generación

​Correo electrónico

​SMS

​Listo 🎉

Descripción general de Enviar tarjetas

Generar enlaces de uso compartido

Obtener Cuentas de gasto

Gestionar tarjetas virtuales

Antes de comenzar

El flujo completo

Comprender la configuración de generación

Correo electrónico

SMS

Listo 🎉