Skip to content

Plan — Alinear la API C2P al contrato con Soterex ​

Date: 2026-10-05 Compromiso con Soterex: martes 2026-10-06, sandbox alineado y documento de sign-off enviado.

Fuentes:

  • La especificación de Soterex, aceptada como contrato definitivo el 2026-08-14: doc/reference/2026-08-12-especificacion-soterex/ (PDF y stipend-spec.txt).
  • La cadena de mails "Technical Kick Off CIS APIs" (2026-08-04 a 2026-09-30), en especial las confirmaciones escritas de CIS del 2026-08-14 y del 2026-09-04 y el mail de Paul Brown del 2026-08-27.
  • El código de main al 2026-10-05.

Qué es esto: la API C2P (ADR-012) se construyó sobre el spec v1.4 viejo (el de Zoom), no sobre la especificación de Soterex ni sobre lo que CIS confirmó por escrito. Este plan cierra todas las diferencias. Varias son bloqueantes: tal como está hoy, el Cancel de Soterex fallaría siempre y ninguna notificación se daría por entregada.

Revisado por tres revisores independientes (especificación, código, huecos) el 2026-10-05. Esta versión incorpora sus hallazgos.

Actualización 2026-10-05 (decisiones de Carlos, durante la ejecución). Este plan se deja como se escribió y se ejecutó; lo que cambió después está marcado en cada lugar con «Actualización» y registrado en los ADR:

  1. Comisión (D2b reemplazada): el tarifario provisional de Guatemala son 50.00 USD fijos por transacción, para cualquier monto, sembrados en todos los ambientes, producción incluida, y editables por país en Parámetros → Comisiones. Ya no es el 1 % ni «en producción no se siembra nada». Ver ADR-018 (Actualización).
  2. Replay: dtc_estatus del COD_009 es el estado actual de la transacción (ACCEPTED, PAID o CANCELLED), no siempre ACCEPTED. Ver ADR-017 §2.
  3. Riesgos que se dejan como están, y el scheduler apagado por ahora: registrados en ADR-017, «Riesgos y decisiones de Carlos (2026-10-05)». Los pasos 4 a 6 de §7 (dry-run, terraform apply del scheduler, cargar URL y secret y pasar a real) quedan en pausa hasta que Soterex mande la URL y el secret.

1. Diferencias encontradas ​

#TemaContrato (especificación + confirmaciones de CIS)HoyGravedad
1sub_status en CancelOpcional: "the current callers do not populate them; build for them to be absent"Obligatorio (2109/2110)Bloqueante: todo Cancel de Soterex se rechaza
2Body de la notificaciónAnidado en notificationData, campos distintos por estado (Operación 4)Plano, los mismos campos para todoBloqueante: Soterex lo rechaza con 400
3sub_status en PAID"Must not be sent on PAID"Se manda {code:"0", message:"PAID"}Bloqueante
4CANCELLED notificadotime + sub_status.code + sub_status.message obligatoriosSin timeBloqueante
5Acuse de la notificaciónmessageCode (COD_000, COD_002, COD_003; CODE_004 = duplicado, 200)Se lee codResponse === 'COD_000'Bloqueante: todo se reintenta y termina FAILED
6Firma del webhookHMAC-SHA256 sobre timestamp.body, X-CIS-Signature (hex minúscula), X-CIS-Timestamp (epoch s, UTC), X-CIS-Key-Id, tolerancia 300 s (CIS, 04/09)HTTP Basic, sin firmaBloqueante: "not negotiable" para Soterex
7ReplayTodo create con un transaction_id ya visto devuelve la transacción original con COD_009 (especificación y CIS, 04/09)Igual al alta (COD_001) si el payload coincide; 2001 si difiereBloqueante: un reintento con un dato reformateado se rechaza
8fee en SendRequestLa Operación 2 no lo manda: el proveedor lo calcula y lo devuelve ("fee — We store principal plus fee as the transaction total")Obligatorio en el request (2016); CIS no calcula nadaBloqueante: todo create según la especificación rebota
9CANCELLED por Cancel de SoterexSe confirma con notificación CANCELLED (CIS, 14/08)No se notificaAlta
10FAILED a demanda en sandboxDisparos PAID, CANCELLED y FAILED a demanda (CIS, 14/08; Paul, 27/08)No existeAlta: Soterex no cierra su etapa Build sin esto
11Nombre del vencimientoexpiration_date, formato yyyy-MM-dd (desviación 3)expirate_date, Y-m-d H:i:sAlta
12Nombre de la sucursalpaying_office (desviación 4)zoom_officeAlta
13Tipos de amount y feeTexto ("500.00") en toda respuesta (CIS, 04/09)Número en SendRequest y Cancel; fee número en la notificaciónAlta
14Respuesta de SendRequestcode: "COD_000", message: "Transaction successful"; entityResponse.transaction_id = la referencia del proveedorCOD_001, "RECORD INSERTED SUCCESSFULLY"; se devuelve el RS- de SoterexMedia
15Rechazos de negocioHTTP 200, status: "REJECTED", entityResponse como texto (Operaciones 2 y 3)HTTP 400, code: "CODE_002", entityResponse.errorDetails[]Alta
16Cancel de una ya cobradaHTTP 200, forma de rechazo, CODE_010 "Transaction already collected" (CIS, 04/09)HTTP 400, error 2108Alta
17Cancel de una inexistenteCODE_001 "Transaction not found" (especificación y CIS, 04/09)HTTP 400, error 2108Alta
18Respuesta de CancelCOD_000, "Cancellation successful", entityResponse: {transaction_id, token}COD_002, y además amountMedia
19Vencimiento"After this date the funds are no longer collectable"expires_at no se aplica en ningún ladoAlta
20previous_transaction_idOpcional en SendRequest; la cadena original→reemplazo visible para operaciones (CIS, 04/09)No existeMedia
21Notificaciones a demanda en sandboxDisparar PAID, CANCELLED y FAILED contra una transacción elegidaNo existeAlta
22Envelope en 429 y 500"Every response carries the same envelope"{"message": ...} de LaravelMedia
23Vocabularios cerradosEstados (terminal/intermedio) y errores (significado, HTTP, reintentable)No están entregadosAlta (checklist)
24Documento de sign-offPrometido el 04/09No existeAlta
25error_description del token—En españolBaja
26Textos largos y montos enormesRechazo de negocioError 500 (varchar 255, decimal(12,2))Media
27amount y fee en el requestDecimal (Salesforce puede mandar número o texto)Solo texto (si llega número: 2005)Media

2. Decisiones ​

#Decisión
D1El contrato es la especificación de Soterex + sus cuatro desviaciones + lo que CIS confirmó el 14/08 y el 04/09. Donde la especificación no dice nada, mandan las confirmaciones de CIS. Todo lo demás se copia exacto: nombres, anidado, literales (ACCEPTED, REJECTED).
D2La comisión la calcula CIS, como dice la especificación (Carlos, 2026-10-05). fee deja de ser parte del request: si Soterex lo manda, se ignora y se registra en la auditoría si difiere del calculado. CIS lo calcula con un tarifario por país de destino configurable (tramos de monto con monto fijo, porcentaje o ambos, como pidió CIS-EC en el requerimiento #2 del 2026-08-07), lo guarda en la transacción al crearla y lo devuelve en la respuesta. Cambiar el tarifario no toca transacciones existentes. Si ningún tramo cubre el monto, el alta se rechaza con 2026. Reemplaza en parte a ADR-005 (la comisión no la fijaba CIS) y la D13 de ADR-012 (fee obligatorio en el request): ADR-018.
D2bEl tarifario real lo define Tesorería (Teresa). Mientras tanto, solo fuera de producción, se carga un tarifario provisional para Guatemala: un tramo único del 1 % del principal (el mismo ejemplo de la especificación: 500.00 → 5.00), rotulado "PROVISIONAL — reemplazar por la tabla de Tesorería". En producción no se siembra nada: sin tarifario, el alta se rechaza. Actualización 2026-10-05: reemplazada por decisión de Carlos. El provisional son 50.00 USD fijos por transacción, para cualquier monto, sembrado en todos los ambientes (producción incluida) y editable por país; el 500.00 → 5.00 ya no sale del tarifario sembrado (da 50.00), y en producción ya no se rechaza por falta de tarifario. Ver ADR-018.
D3Todos los rechazos de negocio van con HTTP 200, status: "REJECTED", el código específico en code (por ejemplo "2002"), un message diagnóstico que nombre el campo, y entityResponse como texto. Sin dtc_estatus, salvo CODE_010 (ver §4.3). Los códigos 2000/2100 se mantienen.
D4entityResponse.transaction_id es la referencia de CIS (el id UUID de la transacción), como en las tablas de las Operaciones 2 y 3. El RS- viaja en el request y en todas las notificaciones. Se deja escrito en el sign-off y se pide confirmación.
D5El webhook se firma con HMAC-SHA256 y deja de usar HTTP Basic. El secret lo provee Soterex; el Admin lo carga en Configuración, cifrado, con un key_id de texto libre (el que indique Soterex; si no indica, k1). Se firma siempre con el secret activo más reciente; el anterior se conserva hasta su vencimiento solo para poder volver atrás. En modo real sin secret activo, la entrega falla y se reintenta: nunca se manda sin firmar.
D6Se notifica CANCELLED en toda cancelación: la de operaciones de CIS, la que pide Soterex por Cancel y la del vencimiento. Solo en la transición real ACCEPTED→CANCELLED: un re-cancel idempotente o el que pierde la carrera no encola nada.
D7El MTCN vence. expiration_date es el último día en que se puede cobrar. Vencida ⇔ hoy (America/Guatemala) > expires_at como fecha; expires_at nulo = no vence. La misma regla en pay() y en el comando. Una vencida no se puede pagar, y el comando la cancela y notifica CANCELLED con CXL_EXPIRED. La vigencia de Guatemala pasa a 60 días (lo que dice la carta de Soterex al beneficiario), por migración de datos y en CountrySeeder. Las ACCEPTED existentes conservan su expires_at.
D8En producción no hay FAILED: un cobro se completa (PAID) o la transacción sigue pendiente hasta que se paga, se cancela o vence. En el sandbox, FAILED se puede disparar a demanda para que Soterex pruebe su manejo, como se comprometió el 14/08.
D9Las notificaciones a demanda del sandbox no cambian el estado de la transacción. Solo mandan la notificación, quedan auditadas, y en producción la ruta no existe (404). Para probar CODE_010, un operador de CIS paga la transacción desde la UI de staging cuando Sean lo pide.
D10No se piden ni se aplican allowlists de IP (Carlos, 2026-10-05). En el sign-off: CIS no exige allowlist; la IP de salida de producción se informa cuando se provisione (producción tiene NAT Gateway en el Terraform).
D11El contacto técnico de Soterex es Sean Rahimi. El de CIS y su escalamiento quedan como placeholder para Carlos en el sign-off.
D12Solo se notifican transacciones que entraron por la API (api_client_id no nulo), en todos los caminos: pago, cancelación por UI, Cancel y vencimiento. El comando de vencimiento también actúa solo sobre esas: los datos de demo de staging no vencen ni notifican.
D13Liquidación y fondos (texto para el sign-off): la cancelación es inmediata y sincrónica, sin ventana de liquidación; una transacción no cobrada no consume prefondeo (se debita solo al cobrar, principal más comisión), así que cancelarla no mueve fondos.
D14Secuencia de estados (texto para el sign-off): ACCEPTED es intermedio; PAID y CANCELLED son terminales. Una cancelada o vencida nunca pasa a PAID; una corrección es cancel-and-recreate con un RS- nuevo y previous_transaction_id.
D15Los sub_status por defecto (CXL_*) se arman solo dentro de la notificación. Las columnas sub_status_code y sub_status_message de la transacción guardan solo lo que mandó Soterex, como hoy (el reporte de Cumplimiento las lee).

3. Lo que queda abierto con Soterex (no frena esta noche) ​

  1. El tarifario real de comisiones (D2b): lo define Tesorería de CIS, no Soterex. Hasta entonces el sandbox usa el 1 % provisional. (Actualización 2026-10-05: el provisional son 50.00 USD fijos, también en producción; ver ADR-018.)
  2. El secret del HMAC para el sandbox (y su key_id), y la URL de Notifications.
  3. Las plantillas del reporte de pagos del día siguiente y del estado de cuenta, como parte de la especificación de la Operación 4. CIS mantiene los dos reportes durante el paralelo y después del go-live (lo pidió Paul el 27/08).
  4. La vigencia del MTCN: 60 días salvo que digan otra cosa.
  5. Que el RS- no se repita en entityResponse (D4): pedir confirmación.

4. El contrato objetivo ​

4.1 SendRequest ​

Request: los campos de la Operación 2 de la especificación, sin fee (D2), más:

  • previous_transaction_id (texto, opcional).
  • amount acepta número o texto. Mayor que cero, hasta 2 decimales, hasta 9999999999.99 (2005 si no).
  • fee: si viene, se ignora. 2016 y 2017 quedan fuera de uso (se listan como retirados en el sign-off).
  • La comisión (D2): fee = fijo + amount × porcentaje / 100 del tramo del tarifario del país de destino que contiene a amount (min_amount ≤ amount ≤ max_amount, este último opcional), redondeado a 2 decimales (half-up). Si ningún tramo activo lo contiene: rechazo 2026 ("fee: No fee schedule covers this amount for the destination country").
  • Ningún texto puede provocar un 500. Códigos nuevos para textos de más de 255 caracteres:
CódigoCampo
2018transaction_id
2019first_name
2020last_name
2021phone
2022alien_number
2023full_name_of_minor
2024previous_transaction_id
2025email

Alta (HTTP 200):

json
{
  "code": "COD_000",
  "status": "ACCEPTED",
  "dtc_estatus": "ACCEPTED",
  "message": "Transaction successful",
  "entityResponse": {
    "transaction_id": "<id de la transacción en CIS>",
    "token": "4907241455",
    "amount": "500.00",
    "fee": "5.00",
    "expiration_date": "2026-12-04"
  }
}

(fee calculado con el tarifario provisional del 1 %. Actualización 2026-10-05: con el provisional vigente, 50.00 USD fijos, el fee de este ejemplo (y el de los payloads de §4.5, con el mismo monto) es "50.00"; el resto del JSON no cambia.)

Replay: todo SendRequest con un transaction_id que ya existe para ese cliente devuelve lo mismo que el alta original, con "code": "COD_009" y "message": "Duplicate request: original transaction returned", aunque el payload sea distinto. Las diferencias se registran en la auditoría (qué campos difieren, sin valores) y no se rechaza. Desaparece el 2001, también en el camino de la carrera por el índice único. Actualización 2026-10-05 (decisión de Carlos): «lo mismo que el alta» tiene una sola excepción. dtc_estatus del replay es el estado actual de la transacción (ACCEPTED, PAID o CANCELLED) y no siempre ACCEPTED; code (COD_009), status (ACCEPTED), message y entityResponse no cambian. Una ACCEPTED vencida que c2p:expire todavía no canceló sigue diciendo ACCEPTED: se informa el estado guardado, no se deduce. Ver ADR-017 §2.

Rechazo (HTTP 200), por ejemplo sin first_name:

json
{
  "code": "2002",
  "status": "REJECTED",
  "message": "first_name: The field is required",
  "entityResponse": "No transaction was created"
}

4.2 Cancel ​

Request: sub_status es opcional. null, {}, o con code y message vacíos cuentan como ausente. Si llega uno solo, se completa el otro con el valor por defecto. Se rechaza con 2110 solo si code o message no son texto, y con 2111 si superan 255 caracteres.

Éxito y re-cancel idempotente (HTTP 200):

json
{
  "code": "COD_000",
  "status": "ACCEPTED",
  "dtc_estatus": "CANCELLED",
  "message": "Cancellation successful",
  "entityResponse": { "transaction_id": "<id en CIS>", "token": "4907241455" }
}

4.3 Rechazos de Cancel (HTTP 200) ​

Casocodedtc_estatusmessageentityResponse
Transacción ya cobradaCODE_010PAIDTransaction already collected"The beneficiary already collected this transaction"
No existe para ese cliente, o el token no coincideCODE_001—Transaction not found"No transaction exists with the provided ID"
Validación (2100-2111)el código—diagnóstico con el campo"No cancellation was applied"

Se busca siempre por api_client_id + transaction_id + token: una transacción de otro cliente da CODE_001, así que distinguir "cobrada" de "no existe" no expone nada ajeno.

4.4 Envelope de 429 y 500 en /api/c2p/* ​

  • 429: {"code": "CODE_429", "status": "ERROR", "message": "Too many requests, retry after N seconds"} + Retry-After. Reintentable.
  • 500: {"code": "CODE_500", "status": "ERROR", "message": "Internal error, retry with backoff"}. Reintentable (SendRequest y Cancel son idempotentes).
  • El endpoint de token sigue el estándar OAuth (error, error_description, en inglés).

4.5 Notificaciones (Operación 4) ​

POST a la URL de Soterex, Content-Type: application/json. Todas las fechas y horas en America/Guatemala.

PAID:

json
{
  "notificationData": {
    "transaction_id": "RS-54689",
    "status": "PAID",
    "amount": "500.00",
    "fee": "5.00",
    "date": "2026-10-06",
    "hour": "14:32",
    "paying_office": "<PDV que pagó>"
  }
}
  • date y hour: los del pago, no los del envío.
  • paying_office, nunca vacío: el nombre del PDV de la transacción; si no tiene, el del PDV de la caja de la que salió el pago; si tampoco, el nombre del país.
  • Sin sub_status. Sin bcv_authorization (no aplica en Guatemala; se omite).

CANCELLED:

json
{
  "notificationData": {
    "transaction_id": "RS-54689",
    "status": "CANCELLED",
    "time": "2026-10-06 14:32:00",
    "sub_status": { "code": "CXL_SENDER", "message": "Cancelled at sender request" }
  }
}

time es el momento en que la cancelación se aplicó en CIS, nunca el time del request.

sub_status.codeCuándomessage
El que mandó SoterexCancel por la API con sub_statusel que mandó
CXL_SENDERCancel por la API sin sub_statusCancelled at sender request
CXL_CISCancelación desde la pantalla de CISsegún el motivo: cancelada_remitente → Cancelled at sender request; ajuste_beneficiario → Beneficiary data needs correction; ajuste_monto → Amount needs correction; motivo nuevo o vacío → Cancelled by CIS operations
CXL_EXPIREDVencimientoMTCN expired without being collected
CXL_SANDBOXDisparo a demanda (si el request no trae sub_status)Sandbox on-demand notification

FAILED (solo el disparo a demanda del sandbox): la forma de la especificación (amount, fee, date, hour, sub_status), con {"code": "FLD_SANDBOX", "message": "Sandbox-triggered failure"}.

Firma:

  • El payload se guarda al encolar. En cada intento, justo antes del POST: se serializa el payload (json_encode), se toma un timestamp nuevo, se calcula el HMAC sobre "{timestamp}.{body}" y se manda ese mismo string (Http::withBody($body, 'application/json')). El timestamp y la firma nunca se guardan: un reintento lleva un timestamp nuevo dentro de los 300 s.
  • Headers: X-CIS-Timestamp (epoch s, UTC), X-CIS-Signature (HMAC-SHA256 en hex minúscula), X-CIS-Key-Id.

Resultado de la entrega:

Respuesta de SoterexResultado
200 y messageCode COD_000, COD_002 o COD_003Entregada (warning en el log si no corresponde al estado enviado)
200 y messageCode CODE_004Entregada (duplicado)
200 sin messageCode, con uno desconocido, o cuerpo no JSONReintento
3xxFalla definitiva (no se siguen redirecciones)
400, 401, 403, 404, 415 y cualquier otro 4xx salvo 429Falla definitiva
429, 5xx, timeout (30 s) o error de redReintento

Reintentos: en los ciclos del scheduler, con esperas mínimas de 1, 5, 15 y 60 minutos (el scheduler de AWS corre cada 5 minutos, así que en la práctica son múltiplos de 5). Después, falla definitiva.

Falla definitiva: queda registrada en la auditoría (NOTIFICATION_FAILED, sin PII), el estado de la notificación se ve en el detalle de la transacción (entregada, pendiente o fallida, con el último error), y se puede reenviar con php artisan notifications:retry {id} (vuelve a pendiente; se firma de nuevo al enviarse).

Modo mock (el default de staging): devuelve el acuse de la especificación según el estado (messageCode COD_000 para PAID, COD_002 para CANCELLED, COD_003 para FAILED) y calcula igual los headers de firma, sin red.

4.6 Notificaciones a demanda (solo sandbox) ​

POST /api/c2p/v1/sandbox/notify, con el mismo OAuth que SendRequest y Cancel:

json
{ "transaction_id": "RS-54689", "status": "PAID", "sub_status": null, "bad_signature": false }
  • status: PAID, CANCELLED o FAILED. Arma la notificación con los datos de la transacción y la fecha y hora actuales, la encola y responde:
    json
    { "code": "COD_000", "status": "ACCEPTED", "message": "Notification queued",
      "entityResponse": { "transaction_id": "RS-54689", "status": "PAID", "notification_id": "<id>" } }
  • paying_office con la misma regla de §4.5; si la transacción no tiene PDV ni pago, SANDBOX.
  • sub_status opcional para CANCELLED y FAILED; si no viene, el de la tabla de §4.5.
  • bad_signature: true firma con un secret inválido, para que Soterex pruebe que su endpoint lo rechaza (ítem del checklist).
  • No cambia el estado de la transacción ni toca saldos (D9). Solo transacciones del mismo cliente: si no existe, CODE_001 como en §4.3. En producción la ruta no existe.

5. Entregas ​

Un solo branch: docs/plan-alineacion-contrato-c2p (el de este plan), un PR contra main, commits con prefijo K1…K8. Orden y prioridad: K1, K2, K3, K6, K4, K5, K8, K7. K7 se escribe al final y documenta solo lo que quedó hecho.

#EntregaQué incluyeTerminado cuando
K1SendRequest y Cancel (§4.1 a §4.4) y comisión (D2)Tarifario por país (tabla de tramos: país, min_amount, max_amount opcional, fixed_fee, percent, activo, descripción), servicio de cálculo, fee fuera del request (ignorado si viene, auditado si difiere), rechazo 2026, tarifario provisional de GT al 1 % solo fuera de producción (migración de datos condicionada al ambiente; D2b) (Actualización 2026-10-05: reemplazado por 50 USD fijos sembrados en todos los ambientes, producción incluida; ver ADR-018), ADR-018. Además: códigos y mensajes, expiration_date como fecha, amount/fee como texto en respuestas y número o texto en requests, replay COD_009 sin 2001, rechazos HTTP 200, CODE_010/CODE_001, sub_status opcional, códigos de largo, topes de monto, previous_transaction_id (migración; se ve en el detalle de la transacción nueva y de la original), entityResponse.transaction_id = id de CIS, envelope de 429/500, error_description del token en inglésUn test por forma de respuesta que compare el JSON entero. Un test por fila de §1 que toca la entrega. Comisión: tramo fijo, porcentaje, fijo + porcentaje, bordes de tramo, redondeo, sin tramo → 2026, fee enviado se ignora, cambiar el tarifario no altera una transacción ya creada, en producción no se siembra (Actualización 2026-10-05: sí se siembra, 50 USD fijos; ver ADR-018)
K2Notificaciones (§4.5)Payload por estado; date/hour/time del momento real; paying_office con su regla; CANCELLED en la transición real de UI y API (D6) con la tabla de sub_status; D12; entrega según la tabla; estado visible en el detalle; notifications:retry; auditoría de fallas; mock nuevoTests del JSON exacto de PAID y CANCELLED (PAID sin sub_status); un test por fila de la tabla de entrega; re-cancel no encola; cancelación por UI sin motivo lleva message no vacío; transacción sin api_client no notifica
K3Firma HMAC (§4.5, D5)Tabla de secrets del webhook (cifrados, key_id, valid_from, expires_at), pantalla en Configuración para cargarlos (sin mostrarlos de vuelta), firma en cada intento, rotación, no mandar sin secret en modo real, sacar HTTP Basic de SoterexClient y los campos usuario/contraseña de la pantalla y de la API (las columnas quedan, sin uso)Test que recalcula la firma sobre el body enviado; dos intentos llevan timestamps distintos y firmas válidas; rotación: firma el más nuevo; un byte cambiado invalida la firma; modo real sin secret no envía
K6Scheduler en stagingTerraform: enabled = true en el scheduler de staging. routes/console.php: agregar el comando de vencimiento con everyMinute() (notifications:deliver ya está). Anotar en staging.md el costo y la frecuencia (EventBridge cada 5 min). Sin terraform applyterraform fmt -check y terraform validate locales (init -backend=false). Carlos corre el plan y el apply
K4Vencimiento (D7)pay() rechaza una vencida (código nuevo, aviso en Pago); comando c2p:expire (con --dry-run, lock por fila, solo D12) que cancela y encola CANCELLED con CXL_EXPIRED; TransactionCancellationService::cancel() acepta actor nulo (sistema); vigencia de GT a 60 días por migración y en CountrySeederTests: el último día se puede pagar y el siguiente no (borde de medianoche en Guatemala); el comando solo toca ACCEPTED vencidas con api_client; es idempotente; --dry-run no cambia nada
K5Disparos a demanda (§4.6)Ruta solo fuera de producción, PAID/CANCELLED/FAILED, bad_signature, auditoríaTests: 404 en producción; no cambia estado; solo transacciones del mismo cliente; FAILED con su forma; bad_signature produce una firma que no verifica
K8ABM del tarifarioPestaña "Comisiones" en Parámetros (Admin, con el permiso abm_paises): alta, edición y desactivación de tramos por país, validación de que no se solapen, aviso visible si el tarifario es el provisional, auditoría de cada cambioTests de API (solapamiento rechazado, auditoría, permiso) y del componente
K7DocumentaciónVer §6npm run docs:build en doc/ pasa

Tests existentes que hay que reescribir, no borrar (afirman el comportamiento viejo):

  • TransactionC2PApiTest: COD_001, amount/fee numéricos, expirate_date, los 400 con entityResponse.errorDetails, el 2001 por payload distinto, los casos de 2109 y de sub_status incompleto.
  • test_cancel_no_encola_notification_salvo_que_soterex_lo_pida se invierte (D6).
  • Los tests de entrega que usan codResponse y el de HTTP Basic pasan a messageCode y HMAC.
  • Los tests que mandan fee en SendRequest o esperan 2016/2017: el fee sale del tarifario.

6. Documentación (K7) ​

  • doc/integracion/cis-latam-soterex-c2p-openapi-v2.yaml: el contrato nuevo completo, incluido el webhook con la firma, los acuses de Soterex, el endpoint de sandbox y todos los códigos.
  • doc/site/public/openapi.yaml (el sitio de docs de API): también documenta el contrato viejo. Actualizarlo con el nuevo o reemplazar la parte C2P por un puntero, para que no queden dos contratos publicados. Actualizar los docblocks de C2PController, NotificationOutboxService y SoterexClient.
  • doc/integracion/cis-latam-soterex-c2p-sandbox.postman_collection.json: requests y tests al contrato nuevo; ejemplos de notificación PAID y CANCELLED como en §4.5 con un pre-request script que firma con webhook_secret; un request para el disparo a demanda. En el repo, client_secret y webhook_secret van con placeholder.
  • doc/integracion/2026-10-06-c2p-sign-off.md (inglés, para mandar el martes), un punto por ítem del checklist de la página 13 de la especificación:
    • desviaciones 1 a 4 aceptadas; fee lo calcula CIS con su tarifario y lo devuelve (no va en el request; si llega, se ignora) — D2;
    • vocabulario de estados (ACCEPTED intermedio; PAID y CANCELLED terminales; FAILED solo a demanda en sandbox, D8);
    • lista de errores con significado, HTTP y si es reintentable, incluidos los de §4.1 a §4.4;
    • los sub_status de §4.5;
    • idempotencia (§4.1), Cancel en sus casos borde (§4.3), liquidación y fondos (D13), secuencia de estados (D14);
    • esquema de firma, rotación y key_id (D5);
    • tipos por campo; token estable de hasta 20 caracteres; entityResponse.transaction_id (D4);
    • vigencia del MTCN (D7); ambientes y hostnames (sandbox y api.soterex.cislatam.net);
    • IPs (D10); los reportes del día siguiente y el estado de cuenta (§3.3);
    • aviso de 30 días antes de cambiar certificados o endpoints; transacción real de bajo monto antes de volumen;
    • contactos: Sean por Soterex; CIS y escalamiento como placeholder [CONTACTO CIS] para Carlos.
  • ADR-017 "El contrato C2P es la especificación de Soterex": lo de §2 y qué reemplaza de ADR-012 (la auth Basic del webhook, el payload plano, el sub_status obligatorio, el 2001).
  • ADR-018 "La comisión C2P la calcula CIS con un tarifario por país": D2 y D2b; reemplaza la parte de ADR-005 que decía que CIS no fija la comisión y la D13 de ADR-012.
  • doc/integracion/2026-10-06-mail-sean-sandbox-alineado.md: borrador en inglés del mail a Sean para mandar una vez desplegado en staging. Dice solo lo que quedó hecho y verificado; lleva [CLIENT_SECRET] como placeholder (lo completa Carlos). Contenido: credenciales, que el sandbox ya está alineado a su especificación (lista corta de lo que cambió respecto de hoy), adjuntos (sign-off, OpenAPI, collection), y lo que necesitamos de ellos: URL y secret del HMAC con su key_id, y las plantillas de reportes junto con la especificación de Notifications. No pide IPs. Sean es el contacto técnico.
  • Análisis funcional y manual: el vencimiento visible en Pago y en el detalle, previous_transaction_id y el estado de la notificación en el detalle (doc/functional/2026-08-07-pago-con-documentos/, doc/manual/10-pago.md, doc/manual/20-transacciones.md).
  • doc/environments/staging.md: los pasos de §7 y notifications:retry.

7. Lo que hace Carlos (lunes 2026-10-05) ​

  1. Pedirle a Teresa el tarifario real de comisiones (D2b) y cargarlo en Parámetros → Comisiones antes de producción. En staging alcanza el 1 % provisional para las pruebas de Sean. (Actualización 2026-10-05: el provisional son 50 USD fijos y producción arranca con él; la tabla real se carga cuando Teresa la defina, ya no «antes de abrir».)
  2. Revisar y mergear el PR.
  3. Promover main a staging.

Actualización 2026-10-05: los pasos 4, 5 y 6 quedan en pausa. Carlos todavía no tiene la URL ni el secret de Soterex y la integración sigue en mock, así que el scheduler no se prende por ahora. Se retoman cuando Soterex mande esos datos.

  1. Correr php artisan c2p:expire --dry-run en staging (workflow de artisan) para ver qué vencería.
  2. terraform plan y apply del scheduler de staging (K6).
  3. Cuando Sean mande la URL y el secret del HMAC: cargarlos en Configuración y pasar Soterex de mock a real.
  4. Completar [CONTACTO CIS] en el sign-off y [CLIENT_SECRET] en el borrador del mail, y mandar el mail con el sign-off, la collection y el OpenAPI una vez desplegado en staging.

8. Riesgos ​

  • El tarifario provisional no es el real (D2b): las comisiones del sandbox (1 %) no son las que se van a cobrar. El sign-off lo dice; antes de producción tiene que estar la tabla de Tesorería. (Actualización 2026-10-05: son 50 USD fijos, y rigen también en producción hasta que Tesorería cargue la tabla real; con montos menores a 50 USD la comisión supera al principal, ver ADR-018.)
  • Cambia lo que Sean ya podría estar probando con las credenciales del 30/09. El mail se manda recién con todo desplegado, así no ve dos contratos.
  • Sin scheduler no se entrega ninguna notificación, ni siquiera el primer intento: el outbox solo se vacía con notifications:deliver. K6 lo prende, pero el apply es de Carlos.
  • El vencimiento cancela transacciones reales. Solo las de la API (D12), de a una, con lock, y con un --dry-run en staging antes de prender el scheduler.

Documentación viva — se actualiza junto con el código, no es un anexo aparte.