Saltar al contenido principal

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.

El esquema es un ejemplo

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ámetroQué traeEjemplo
amountTotal que paga el pagador: base + IVA + impuesto al consumo + propina + extra (no el amount base del link). Punto decimal, sin separador de miles.35700
referenceLa reference del link; si el link no tiene, el token.pedido-1042
tokenEl 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
merchantNombre 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​

  1. El pagador abre https://pay.example.com/l/{token} y elige Cuenta Crezcamos.
  2. La pasarela toma la plantilla configurada, calcula el total del link y reemplaza {amount}, {reference}, {token} y {merchant}.
  3. 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 a payment_in_progress y enseguida a redirected. Desde ese momento el link ya no se puede revocar (PATCH …/revoke responde 409); si el pagador no completa el pago, el link sigue abierto hasta que venza o se pague.
  4. 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".

Bre-B no usa plantilla

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​

  1. Validar que sea mosi://transfer y que traiga amount (> 0) y token.
  2. Mostrar al pagador el monto y el comercio y pedir confirmación antes de mover dinero.
  3. Hacer la transferencia (ver el flujo de transferencia). Usar un transactionId único por intento: la API de Crezcamos es idempotente por ese valor.
  4. Confirmar el resultado a la pasarela con el token y un amount igual al del enlace (si no, responde 422).
  5. 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:

  1. POST a la API de Crezcamos /payments-transfers/v1/transfers/accounts con transactionId, accountFrom, accountTo, amount y description. La respuesta trae data.reference.
  2. POST {API}/webhooks/crezcamos/pse-payments con X-Crezcamos-Webhook-Secret, el payment_link_token, rail: cuentas_crezcamos, status: APPROVED o REJECTED, amount igual al del enlace y reference con el valor devuelto en el paso 1. Ver webhook de confirmación.
Qué no va dentro de la app

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​

  1. Crea un link con cuentas_crezcamos en los medios aceptados.
  2. Abre /l/{token}, elige Cuenta Crezcamos y copia el enlace mosi://….
  3. 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, o xcrun simctl openurl booted "mosi://transfer?..." en iOS).
  4. Haz la transferencia contra el sandbox y envía la confirmación; la página de pago abierta pasa a "Pago recibido".