Deep link de Cuenta Crezcamos (Mo$i)
Cuando el pagador elige Cuenta Crezcamos en la página de pago, la pasarela arma un enlace para la app de Mo$i. Esta página explica qué trae ese enlace, cómo se construye y cómo recibirlo en una app Flutter.
mosi://transfer es la plantilla por defecto. El esquema y los parámetros definitivos se acuerdan con Crezcamos (ver decisiones abiertas, punto 6). Lo que sigue describe el comportamiento actual del motor.
Formato
mosi://transfer?amount={amount}&reference={reference}&token={token}&merchant={merchant}
| Parámetro | Qué trae | Ejemplo |
|---|---|---|
amount | Total que paga el pagador: base + IVA + impuesto al consumo + propina + extra (no el amount base del link). Punto decimal, sin separador de miles. | 35700 |
reference | La reference del link; si el link no tiene, el token. | pedido-1042 |
token | El token del link (el mismo de /l/{token}). Es el que la app debe reenviar como payment_link_token en la confirmación. | D8bwL5EqTqOMOtO-IhIXm5NAEwTDMElp |
merchant | Nombre a mostrar del comercio: el alias; si no hay, el nombre; si no, Comercio. | Gran+Kiosko+Colombia |
Los valores se codifican como formulario: caracteres especiales en porcentaje y espacios como + (no %20). Por ejemplo, el comercio Café & Co viaja como Caf%C3%A9+%26+Co.
Ejemplo completo, para un link de 30000 con IVA al 19 %:
mosi://transfer?amount=35700&reference=pedido-1042&token=D8bwL5EqTqOMOtO-IhIXm5NAEwTDMElp&merchant=Gran+Kiosko+Colombia
Cómo se construye
- El pagador abre
https://pay.example.com/l/{token}y elige Cuenta Crezcamos. - La pasarela toma la plantilla configurada, calcula el total del link y reemplaza
{amount},{reference},{token}y{merchant}. - La página muestra el enlace (botón "Abriendo Mo$i"; en el HTML el
+aparece escapado como+, el navegador lo decodifica) y el link pasa apayment_in_progressy enseguida aredirected. Desde ese momento el link ya no se puede revocar (PATCH …/revokeresponde409); si el pagador no completa el pago, el link sigue abierto hasta que venza o se pague. - La pasarela no espera ningún retorno del navegador: el resultado llega por el webhook de confirmación.
La plantilla se configura con la variable CHECKOUT__CREZCAMOSDEEPLINKTEMPLATE. Es válida si contiene al menos uno de los cuatro marcadores y el resultado tiene un esquema de URI; si no, el checkout responde "No se pudo construir el enlace de Mo$i".
El QR de Bre-B lo genera Crezcamos al iniciar el pago; no se arma con una plantilla como este enlace.
Qué debe hacer la app al abrirlo
- Validar que sea
mosi://transfery que traigaamount(> 0) ytoken. - Mostrar al pagador el monto y el comercio y pedir confirmación antes de mover dinero.
- Hacer la transferencia (ver el flujo de transferencia). Usar un
transactionIdúnico por intento: la API de Crezcamos es idempotente por ese valor. - Confirmar el resultado a la pasarela con el
tokeny unamountigual al del enlace (si no, responde422). - Mostrar el resultado al pagador en la propia app: la pasarela no muestra nada más.
Integración en Flutter
Dependencias (pubspec.yaml): app_links para recibir el enlace y http para llamar a tu backend.
1. Registrar el esquema
Android, en android/app/src/main/AndroidManifest.xml, dentro de la <activity> principal:
<intent-filter>
<action android:name="android.intent.action.VIEW"/>
<category android:name="android.intent.category.DEFAULT"/>
<category android:name="android.intent.category.BROWSABLE"/>
<data android:scheme="mosi" android:host="transfer"/>
</intent-filter>
iOS, en ios/Runner/Info.plist:
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleURLSchemes</key>
<array><string>mosi</string></array>
</dict>
</array>
2. Interpretar el enlace
Uri.queryParameters ya decodifica + como espacio, así que Gran+Kiosko+Colombia llega como Gran Kiosko Colombia.
/// Datos que trae el deep link de Cuenta Crezcamos.
class DeepLinkPayment {
const DeepLinkPayment({
required this.amount,
required this.reference,
required this.token,
required this.merchant,
});
final num amount; // total que paga el pagador
final String reference;
final String token; // token del link: se reenvía en el webhook de confirmación
final String merchant;
/// Devuelve null si el enlace no es de Cuenta Crezcamos o está incompleto.
static DeepLinkPayment? tryParse(Uri uri) {
if (uri.scheme != 'mosi' || uri.host != 'transfer') return null;
final q = uri.queryParameters; // decodifica '+' como espacio
final amount = num.tryParse(q['amount'] ?? '');
final token = q['token'];
if (amount == null || amount <= 0 || token == null || token.isEmpty) {
return null;
}
return DeepLinkPayment(
amount: amount,
reference: q['reference'] ?? token,
token: token,
merchant: q['merchant'] ?? 'Comercio',
);
}
}
3. Recibirlo (app abierta o cerrada)
import 'package:app_links/app_links.dart';
final _links = AppLinks();
Future<void> listenDeepLinks(void Function(DeepLinkPayment) onPayment) async {
void handle(Uri? uri) {
final payment = uri == null ? null : DeepLinkPayment.tryParse(uri);
if (payment != null) onPayment(payment);
}
handle(await _links.getInitialLink()); // la app se abrió con el enlace
_links.uriLinkStream.listen(handle); // la app ya estaba abierta
}
4. Confirmar y pagar a través de tu backend
La app no debe llevar el secreto del webhook ni el client_secret del comercio. Pásale el pago a tu backend, que hace la transferencia con la API de Crezcamos y confirma a la pasarela:
import 'dart:convert';
import 'package:http/http.dart' as http;
import 'package:uuid/uuid.dart';
Future<bool> pay(DeepLinkPayment p, String fromAccount, String toAccount) async {
final res = await http.post(
Uri.parse('https://api.tu-backend.example/mosi/transfers'),
headers: {'Content-Type': 'application/json'},
body: jsonEncode({
'transactionId': const Uuid().v4(), // único por intento (idempotencia)
'accountFrom': fromAccount,
'accountTo': toAccount,
'amount': p.amount,
'paymentLinkToken': p.token, // el backend lo reenvía como payment_link_token
'reference': p.reference,
}),
);
return res.statusCode == 200;
}
Lo que hace tu backend, en orden:
POSTa la API de Crezcamos/payments-transfers/v1/transfers/accountscontransactionId,accountFrom,accountTo,amountydescription. La respuesta traedata.reference.POST {API}/webhooks/crezcamos/pse-paymentsconX-Crezcamos-Webhook-Secret, elpayment_link_token,rail: cuentas_crezcamos,status: APPROVEDoREJECTED,amountigual al del enlace yreferencecon el valor devuelto en el paso 1. Ver webhook de confirmación.
Ni el client_secret del comercio ni el X-Crezcamos-Webhook-Secret. Quien tenga el secreto del webhook puede declarar pagado cualquier link. Si la app necesita crear links, hazlo desde tu backend con POST /api/auth/token.
Probar sin mover dinero
- Crea un link con
cuentas_crezcamosen los medios aceptados. - Abre
/l/{token}, elige Cuenta Crezcamos y copia el enlacemosi://…. - En un dispositivo o emulador con la app, ábrelo (
adb shell am start -a android.intent.action.VIEW -d "mosi://transfer?amount=35700&reference=pedido-1042&token=..."en Android, oxcrun simctl openurl booted "mosi://transfer?..."en iOS). - Haz la transferencia contra el sandbox y envía la confirmación; la página de pago abierta pasa a "Pago recibido".