Tokens de pago
Aquello a lo que paga el pagador: cada método emite su propio tipo de token.
Un token de pago es lo que pones frente al pagador: la dirección a la que se envía el dinero. Cada método de pago define su propio tipo de token. Algunos métodos no necesitan ninguno, porque el pagador se envía al flujo propio del proveedor en vez de pagar a una dirección. Por eso payment_tokens es un mapa por método: una entrada por cada método aceptado que emite token, y ninguna para los métodos que no lo hacen.
Hoy, con Bre-B como único método activo, los tokens vienen en dos formas: una llave (un alias corto como un número de celular o un código, registrado en el directorio de Bre-B) y un código QR opcional que codifica el mismo destino para que el pagador escanee en vez de digitar.
Tanto las plantillas como las intenciones de pago llevan tokens, y la diferencia entre ambas es la diferencia entre un afiche en la pared y una boleta con tu nombre: el token de una plantilla lo comparten todos los pagadores; el token de una intención de pago identifica un único pago esperado.
El token de Bre-B
payment_tokens.co_breb tiene tres partes:
| Campo | Qué es |
|---|---|
key_type | El tipo de llave: cellphone, email, alphanumeric, identification o merchant_code. Lo asigna la red al registrar la llave. No se conoce al momento de la creación. |
key_value | La llave en sí: lo que el pagador digita en la app de su banco para direccionar la transferencia. |
qr | El QR generado para la llave, cuando se pidió uno (create_qr: true). |
El objeto del QR lleva todo lo necesario para mostrarlo o incrustarlo: el payload EMV en texto plano (emvco), la imagen renderizada en base64 (image, con image_width y error_correction_level), el payment_id del proveedor, su usage_mode y, para QRs dinámicos, el amount fijo y el expires_at.
Puedes pedir un alias personalizado de llave con method_params.co_breb.custom_key_value, y sobreescribir los datos de comercio del QR (merchant_category_code, receiver_city, receiver_postal_code) con qr_code_data. Si los omites, Mono genera la llave y usa la configuración de tu programa.
Llave por plantilla o llave por intención de pago
method_params.co_breb.key_per decide a qué nivel se crea la llave Bre-B, y eso define el modelo de recaudo completo:
key_per | El token vive en | Tipo de QR | Los pagos son… |
|---|---|---|---|
template (por defecto) | La plantilla | Estático: multiuso, sin monto | Anónimos hasta que llegan: cualquier pagador, cualquier número de pagos. |
intent | Cada intención de pago | Dinámico: un solo uso, monto fijo, expira | Referenciados: cada pago se mapea a la intención de pago que lo esperaba. |
Una plantilla con key_per: "template" recibe pagos directamente. No puede alojar intenciones de pago, porque una llave compartida no puede decir a qué intención de pago pertenece un pago. Una plantilla con key_per: "intent" no tiene llave propia (payment_tokens queda null): cada llave se crea cuando se crea una intención de pago. Una intención de pago sin plantilla también recibe su propia llave dedicada.
El setup del token es asíncrono
Registrar un token en la red del método implica una ida y vuelta con callback, y por eso las plantillas y las intenciones de pago nacen en created. Ninguna es pagable hasta que el token queda confirmado:
- La plantilla pasa a
readyy llenapayment_tokenscuando todos los tokens pendientes quedan confirmados (lo anunciapayin_template_ready). - La intención de pago pasa a
ready_to_payy llenapayment_tokens(lo anunciapayin_intent_ready_to_pay).
Si el registro agota sus reintentos, la plantilla termina en failed (key_registration_failed, key_already_registered) o la intención de pago termina en failed (key_registration_failed, payment_token_registration_failed).
Los tokens se dan de baja
Un token solo vive mientras su dueño pueda ser pagado. Cuando una plantilla es podada o eliminada, o una intención de pago llega a un estado final (successful, failed o expired), Mono da de baja sus tokens ante el proveedor del método. Los campos prune_state / prune_reason del dueño rastrean ese desmonte.
Siguientes pasos
- Bre-B: el riel detrás de las llaves y los QRs.
- Plantillas: donde viven los tokens estáticos.
- Intenciones de pago: donde viven los tokens dinámicos.