Provisionamiento por inserción a billeteras digitales

Usa la consulta getCardProvisioningUrl para acuñar una URL corta de un solo uso que —al abrirse en el teléfono del usuario final— inicia Fluz en el dispositivo y añade la tarjeta virtual de una oferta determinada a Apple Pay (iOS) o Google Pay (Android). Puedes entregar la URL como prefieras: un código QR, un SMS, un correo electrónico o un botón dentro de tu app. Fluz se encarga del flujo de provisionamiento en la billetera desde allí.

Cuándo usarlo

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

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

Requisitos previos: un token de acceso OAuth para el usuario final que incluya el alcance CREATE_VIRTUALCARD, y una oferta de tarjeta virtual para el usuario (creada mediante el API de ofertas existente).

La autenticación básica (client_id / client_secret) no es aceptada en esta consulta: debe ser un token bearer en contexto de usuario.

La consulta

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

Entrada

Campo	Tipo	Requerido	Descripción
`offerId`	`String!` (UUIDv4)	sí	La oferta de tarjeta virtual a provisionar. Debe estar activa, ser apta para tokenización y ser accesible para la cuenta del usuario.
`platform`	`ProvisioningPlatform`	no	Pista sobre dónde el usuario abrirá la URL. Predeterminado: `IOS`. Ver abajo: esto no bloquea la URL a una sola plataforma.

`ProvisioningPlatform`

La URL devuelta es consciente de la plataforma: los usuarios de iOS obtienen automáticamente la experiencia de App Clip, y los de Android reciben automáticamente el deep link de la app de Fluz. El valor platform solo afecta lo que sucede cuando la URL se abre en un lugar distinto a un dispositivo iOS o Android (p. ej., un navegador de escritorio).

Valor	Contingencia en escritorio / dispositivo desconocido
`IOS` (predeterminado)	Lanzador de Apple App Clip
`ANDROID`	Deep link de Fluz para Android
`OTHER`	App web de Fluz

Elige el valor que mejor coincida con el lugar donde esperas que se abra la URL. Si tienes dudas, déjalo como IOS.

Salida

Campo	Tipo	Descripción
`url`	`String!`	La URL corta para entregar al usuario. De un solo uso.
`expiresAt`	`String!`	Marca de tiempo ISO-8601. La 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:{ offerId:$id, platform:IOS }){ url expiresAt } }",
    "variables": { "id": "11111111-2222-3333-4444-555555555555" }
  }'

Response

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

Cómo entregar la URL

La URL es opaca y no contiene datos sensibles: es seguro mostrarla en códigos QR, SMS, correo electrónico o UI dentro de tu app. 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 / correo: 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.

Sea cual sea el canal de entrega, el usuario debe abrir la URL en un dispositivo móvil: ahí es donde ocurre el provisionamiento de la billetera.

Vigencia y reemisión

Cada llamada devuelve una URL nueva y de un solo uso.
La URL es válida hasta expiresAt (≈ 5 minutos).
Si un usuario no actúa a tiempo, simplemente llama de nuevo a getCardProvisioningUrl para acuñar una nueva. No hay un endpoint de “refresh” por separado.

Manejo de errores

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

Código	Qué significa	Qué hacer
`Arguments.INVALID`	`offerId` no es un UUID válido.	Valida la entrada de tu lado.
`VirtualCard.OFFER_NOT_FOUND`	La oferta no existe o está inactiva.	Confirma el id de la oferta; crea una nueva 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_AVAILABLE`	La oferta ya fue canjeada en una tarjeta que ya no está activa.	No reintentes con la misma oferta; crea una nueva.
`VirtualCard.OFFER_NOT_TOKENIZATION_ELIGIBLE`	El programa de la tarjeta de la oferta no admite provisionamiento a billetera.	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.	Vuelve a llevar al usuario por el consentimiento de OAuth.
`Auth.INVALID_SCOPE`	El token no tiene `CREATE_VIRTUALCARD`.	Solicita el alcance durante OAuth.
`Generic.EXTERNAL_SERVICE_ERROR`	Problema transitorio aguas abajo.	Reintenta: la llamada es segura de repetir.

Preguntas frecuentes

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

No. La URL solo transporta un id de búsqueda opaco y 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 la misma URL?

No. Es de un solo uso. Genera una nueva cada vez que necesites mostrar el flujo.

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

Aterrizará en la contingencia que seleccionaste con platform (lanzador de App Clip, deep link de Android o app web de Fluz). Para que el provisionamiento de la billetera funcione, debe terminar abriendo la URL en un dispositivo móvil.

¿Necesito hacer algo distinto para iOS vs. Android?

No. La misma URL funciona para ambos: Fluz enruta automáticamente según el dispositivo.

Próximos pasos

Enviar tarjetas

Distribuye tarjetas virtuales a destinatarios por correo electrónico, SMS o enlace compartido.

Configurar un PIN de tarjeta virtual

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

​Cuándo usarlo

​La consulta

​Entrada

​ProvisioningPlatform

​Salida

​Ejemplo

​Request

​Response

​Cómo entregar la URL

​Vigencia y reemisión

​Manejo de errores

​Preguntas frecuentes

​Próximos pasos

Enviar tarjetas

Configurar un PIN de tarjeta virtual

Cuándo usarlo

La consulta

Entrada

`ProvisioningPlatform`

Salida

Ejemplo

Request

Response

Cómo entregar la URL

Vigencia y reemisión

Manejo de errores

Preguntas frecuentes

Próximos pasos