Aprovisionamiento push a billeteras digitales

Usa la query getCardProvisioningUrl para acuñar un URL de corta duración que — al abrirse en el teléfono del usuario final — inicia Fluz en el dispositivo y agrega una tarjeta virtual específica a Apple Pay (iOS) o Google Pay (Android). Puedes entregar el URL como prefieras: un código QR, un SMS, un email o un botón dentro de tu app. Fluz maneja el flujo de aprovisionamiento de la billetera a partir de ahí.

Cuándo usarlo

En cualquier lugar donde normalmente entregarías una tarjeta virtual y quieras que puedan tocarla en la billetera de su teléfono sin teclear el número. Flujos típicos:

Después de crear una oferta de tarjeta para el usuario, muestra un código QR en pantalla.
Envía por texto o email el URL al tarjetahabiente.
Inserta un botón “Agregar a Apple Pay / Google Pay” en tu propia app móvil.

Prerrequisitos: un token de acceso OAuth para el usuario final que incluya el scope CREATE_VIRTUALCARD, y algo para seleccionar la tarjeta. Ya sea el virtualCardId devuelto por createVirtualCard, o un offerId accesible para la cuenta. Si la oferta aún no se ha canjeado en una tarjeta, se crea una como parte del flujo de aprovisionamiento.

La autenticación básica (client_id / client_secret) no se acepta en esta query — debe ser un bearer token en contexto de usuario.

La query

Por tarjeta (recomendado):

query ProvisionCard($virtualCardId: String!) {
  getCardProvisioningUrl(input: { virtualCardId: $virtualCardId, platform: IOS }) {
    url
    expiresAt
  }
}

Por oferta, cuando la cuenta tiene como máximo una tarjeta activa en ella:

query ProvisionCard($offerId: String!) {
  getCardProvisioningUrl(input: { offerId: $offerId, platform: IOS }) {
    url
    expiresAt
  }
}

Input

Proporciona exactamente uno de virtualCardId u offerId.

Field	Type	Required	Description
`virtualCardId`	`String` (UUIDv4)	one of	La tarjeta a aprovisionar, tal como la devuelve `createVirtualCard`. Debe pertenecer a la cuenta del llamador y estar `ACTIVE`. Prefiere este: identifica la tarjeta sin ambigüedad.
`offerId`	`String` (UUIDv4)	one of	La oferta de tarjeta virtual a aprovisionar. Debe estar activa, ser apta para tokenización y ser accesible para la cuenta del usuario. Solo resuelve mientras la cuenta tenga como máximo una tarjeta activa en esa oferta.
`platform`	`ProvisioningPlatform`	no	Indicación de dónde el usuario abrirá el URL. Por defecto `IOS`. Ver abajo — esto no bloquea el URL a una sola plataforma.

Una oferta puede respaldar muchas tarjetas en la misma cuenta. Una vez que hay más de una tarjeta activa en una oferta, offerId ya no identifica una sola tarjeta y la query falla con VirtualCard.AMBIGUOUS_CARD_SELECTION en lugar de elegir una por ti. Si emites más de una tarjeta por oferta, usa virtualCardId.

`ProvisioningPlatform`

El URL devuelto es consciente de la plataforma: usuarios iOS reciben automáticamente la experiencia App Clip, usuarios Android obtienen automáticamente el deep link a la app de Fluz. El valor platform solo afecta lo que ocurre cuando el URL se abre en algún lugar distinto a un dispositivo iOS o Android (por ejemplo, un navegador de escritorio).

Value	Desktop / unknown-device fallback
`IOS` (default)	Lanzador de Apple App Clip
`ANDROID`	Deep link de Fluz para Android
`OTHER`	App web de Fluz

Elige el valor que mejor coincida con dónde esperas que se abra el URL. En caso de duda, déjalo como IOS.

Output

Field	Type	Description
`url`	`String!`	El URL corto para entregar al usuario. Apunta exactamente a una tarjeta.
`expiresAt`	`String!`	Marca de tiempo ISO-8601. El URL deja de funcionar en ese momento (≈ 5 minutos después de la creación).

Ejemplo

Request

curl -X POST https://transactional-graph.fluzapp.com/api/v1/graphql \
  -H "Authorization: Bearer <user_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query($id:String!){ getCardProvisioningUrl(input:{ virtualCardId:$id, platform:IOS }){ url expiresAt } }",
    "variables": { "id": "11111111-2222-4333-8444-555555555555" }
  }'

O selecciona por oferta en su lugar:

curl -X POST https://transactional-graph.fluzapp.com/api/v1/graphql \
  -H "Authorization: Bearer <user_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query($id:String!){ getCardProvisioningUrl(input:{ offerId:$id, platform:IOS }){ url expiresAt } }",
    "variables": { "id": "66666666-7777-4888-9999-000000000000" }
  }'

Response

{
  "data": {
    "getCardProvisioningUrl": {
      "url": "https://fluz.app.link/abc123XYZ",
      "expiresAt": "2026-05-26T17:42:11.000Z"
    }
  }
}

Cómo entregar el URL

El URL es opaco y no lleva número de tarjeta, pero es un secreto de tipo bearer: quien lo abra puede agregar esa tarjeta a su billetera. Entrégalo al tarjetahabiente por un canal en el que confíes. Patrones comunes:

Código QR en una pantalla — genera un QR a partir de url y muéstralo; el usuario lo escanea con la cámara de su teléfono.
SMS / email — envía el enlace directamente al teléfono o bandeja de entrada del usuario.
Deep link dentro de la app — conecta un botón en tu app móvil que abra url.

Cualquiera sea el canal de entrega, el usuario debe abrir el URL en un dispositivo móvil — ahí es donde ocurre el aprovisionamiento a la billetera.

Vigencia y reemisión

Cada llamada devuelve un URL nuevo que apunta a una tarjeta.
El URL es válido hasta expiresAt (≈ 5 minutos).
Abrir el URL no lo invalida inmediatamente. Permanece canjeable por una breve ventana de gracia después del primer uso, así que trátalo como un secreto bearer: entrégalo por un canal privado y no lo registres ni lo caches.
Si un usuario no actúa a tiempo, simplemente llama de nuevo a getCardProvisioningUrl para acuñar uno nuevo. No hay un endpoint de “refresh” separado.
Para aprovisionar varias tarjetas, llama la query una vez por tarjeta con el virtualCardId de cada tarjeta.

Manejo de errores

Todos los errores regresan en la forma estándar de errores GraphQL de Fluz, con el nombre del error en extensions.code.

Code	What it means	What to do
`Arguments.INVALID`	El id no es un UUID válido, o enviaste ambos selectores o ninguno.	Envía exactamente uno de `virtualCardId` u `offerId`.
`VirtualCard.CARD_NOT_FOUND`	No existe tal tarjeta en la cuenta del llamador.	Confirma el `virtualCardId` y que pertenezca a esta cuenta.
`VirtualCard.CARD_NOT_ACTIVE`	La tarjeta existe pero no está `ACTIVE`.	No reintentes; la tarjeta no puede agregarse a una billetera en este estado.
`VirtualCard.AMBIGUOUS_CARD_SELECTION`	La cuenta tiene más de una tarjeta activa en el `offerId` que enviaste.	Reintenta con `virtualCardId`.
`VirtualCard.OFFER_NOT_FOUND`	La oferta de la tarjeta no existe o está inactiva.	Confirma el id de la oferta; crea una nueva oferta si es necesario.
`VirtualCard.OFFER_NOT_ACCESSIBLE`	La cuenta del usuario no es elegible para esta oferta (acceso de campaña).	Muestra un mensaje genérico de “no disponible”.
`VirtualCard.OFFER_NOT_TOKENIZATION_ELIGIBLE`	El programa de la tarjeta de la oferta no soporta aprovisionamiento a billeteras.	No ofrezcas “Agregar a la billetera” para este programa de tarjeta.
`Auth.USER_REVOKED_DEVELOPER_ACCESS`	El usuario revocó el acceso OAuth a tu app.	Envía al usuario nuevamente por el consentimiento OAuth.
`Auth.INVALID_SCOPE`	El token no tiene `CREATE_VIRTUALCARD`.	Solicita el scope durante OAuth.
`Generic.EXTERNAL_SERVICE_ERROR`	Problema transitorio aguas abajo.	Reintenta — es seguro repetir la llamada.

Preguntas frecuentes

¿El URL contiene el número de la tarjeta?

No. El URL solo lleva un id de búsqueda opaco de corta duración. Las credenciales se intercambian de forma segura en el dispositivo una vez que el usuario abre el enlace.

¿Se puede reutilizar el mismo URL?

Trátalo como de un solo uso: genera uno nuevo cada vez que necesites mostrar el flujo. Abrir el enlace no lo invalida al instante, por lo que sigue siendo canjeable por una breve ventana de gracia. Entrégalo de forma privada y no lo registres ni lo caches.

¿Un solo URL puede agregar varias tarjetas?

No. Cada URL apunta exactamente a una tarjeta. Llama la query una vez por tarjeta, pasando el virtualCardId de esa tarjeta.

¿Qué pasa si el usuario está en desktop?

Llegará al fallback que seleccionaste con platform (lanzador de App Clip, deep link de Android o app web de Fluz). Para que el aprovisionamiento a la billetera funcione, necesita terminar abriendo el URL en un dispositivo móvil.

¿Debo hacer algo diferente para iOS vs. Android?

No. El mismo URL funciona para ambos — Fluz enruta automáticamente según el dispositivo.

Próximos pasos

Enviar tarjetas

Distribuye tarjetas virtuales a destinatarios por email, SMS o enlace para compartir.

Configurar el PIN de una tarjeta virtual

Configura un PIN en tarjetas elegibles antes de transacciones presenciales que soliciten PIN.

​Cuándo usarlo

​La query

​Input

​ProvisioningPlatform

​Output

​Ejemplo

​Request

​Response

​Cómo entregar el URL

​Vigencia y reemisión

​Manejo de errores

​Preguntas frecuentes

​Próximos pasos

Enviar tarjetas

Configurar el PIN de una tarjeta virtual

Cuándo usarlo

La query

Input

`ProvisioningPlatform`

Output

Ejemplo

Request

Response

Cómo entregar el URL

Vigencia y reemisión

Manejo de errores

Preguntas frecuentes

Próximos pasos