Integración C2P — onboarding de Soterex en Staging
Date: 2026-09-30 Branch: feature/api-c2p-entrante (PR #55)
Reemplazado en parte por el plan de alineación del 2026-10-05, ver ADR-017. Este documento queda como el registro de lo que se mandó y se hizo el 2026-09-30, y el contrato que describe ya no rige: HTTP Basic en el webhook (usuario y contraseña de
SoterexSetting,SOTEREX_USERNAME/SOTEREX_PASSWORD), respuestasCOD_001/COD_002,expirate_date,amountyfeecomo número,feeobligatorio en el request, el error2001y el2108. Lo vigente es2026-10-06-c2p-sign-off(el contrato) y2026-10-06-mail-sean-sandbox-alineado(el mail que reemplaza al de la sección 1). Siguen vigentes los pasos de creación del cliente OAuth y el formato del token.
Este documento junta todo lo que hace falta para que Sean Rahimi (Soterex/Prutech) pueda configurar Salesforce contra nuestro staging, más lo que a vos te toca hacer para dejarlo andando. Contexto completo en doc/plans/2026-09-30-api-c2p-entrante-soterex.md y doc/architecture/ADR-012-direccion-integracion-c2p-entrante-oauth.md.
1. Mail de respuesta a Sean (inglés, listo para copiar)
Nota del 2026-10-05: este mail describe el contrato anterior (
feeobligatorio en el request, HTTP Basic en el webhook,expirate_date, sin notificar elCANCELLEDque pide Soterex, sin vencimiento). Lo reemplaza el mail2026-10-06-mail-sean-sandbox-alineado, ver ADR-017.
Responde sus 7 preguntas del mail "Re: Technical Kick Off CIS APIs" (2026-09-18). El client_id ya es el real de Staging (creado 2026-09-30) — el client_secret va como placeholder, se manda aparte, 1 a 1, por un canal seguro (no por este mail, que tiene gente en copia).
Subject: Re: Technical Kick Off CIS APIs — sandbox details
Hi Sean,
Thanks for your patience — here's everything you need to configure Salesforce against our sandbox (staging) environment.
1. Token URL
POST https://api.soterex.stag.cislatam.net/api/oauth/token2. Base URL and paths for Send and Cancel Base URL:
https://api.soterex.stag.cislatam.net
POST /api/c2p/v1/SendRequestPOST /api/c2p/v1/Cancel3. Sandbox client_id and client_secret
client_id:cis_stg_mxlighrgiydwibeaclient_secret: sent separately through a secure channel, not in this email.We've already verified this client end-to-end on our side (token issuance,
SendRequest,Cancel) against the sandbox, so it's ready to use as soon as you have the secret.4. Token request format Standard OAuth 2.0 Client Credentials (RFC 6749 §4.4). We support both forms Salesforce Named Credentials can use:
client_secret_basic:Authorization: Basic base64(client_id:client_secret)header, withgrant_type=client_credentialsin the body.client_secret_post:client_id,client_secretandgrant_type=client_credentialsall in the body.Content-Type:
application/x-www-form-urlencoded. Noscopeis required — if you sendscope=c2pwe accept and ignore it. Noaudienceparameter is used.5. Token response format, lifetime, and Authorization header
json{ "access_token": "<opaque token>", "token_type": "Bearer", "expires_in": 3600, "scope": "c2p" }Tokens are valid for 3600 seconds (1 hour). There is no refresh token — request a new one with the same credentials when it expires. Use it as
Authorization: Bearer <access_token>onSendRequestandCancel.6. Additional security requirements Sandbox: TLS 1.2+ only (enforced at our load balancer), no mTLS, no IP allowlisting. We do have per-client IP allowlisting available if you want it for production — let us know your Salesforce org's egress IP range if so. Rate limits: 30 req/min per client_id+IP on the token endpoint, 60 req/min per client_id+IP shared between
SendRequestandCancel.7. Secret rotation Yes, 24h overlap is supported: we can issue a new secret while the old one keeps working for 24 hours, then revoke it. Just let us know when you want to rotate and we'll coordinate.
One more thing —
feeis now required inSendRequestOur original spec (v1.4) only returnedfeein theSendRequestresponse. Since it's actually Soterex who computes and sends the commission, we've madefeea required field in the request body as well (same format asamount: a string matching^\d+(\.\d{1,2})?$). We'll store it and return it unchanged in the response.The MTCN for the beneficiary's letter is the
tokenfield in theSendRequestresponse (entityResponse.token, 10 digits). It's also thetokenyou send us inCancel.entityResponse.expirate_dateis its planned expiration date, informational for now: we don't enforce expiry yet, so an unpaid transaction staysACCEPTED(payable and cancellable) until it's paid or you callCancel, and no notification is sent at expiry.Updated API reference attached (
cis-latam-soterex-c2p-openapi-v2.yaml) — our internal Scalar docs are behind SSO, so please use this file directly. It documents the token endpoint,SendRequest,Cancel, and theNotificationswebhook body format. The OpenAPI file is 3.1, for reference and tooling such as Postman; if you plan to import it into Salesforce External Services, tell us and we'll send a 3.0 version.A few things we need from you:
- The Notifications URL you'd like us to call, and the credentials to authenticate against it. Today we support HTTP Basic auth; if you need a bearer token or an API key header instead, let us know. Notifications aren't active in the sandbox yet: we'll switch them on as soon as we have your URL. We'll only call it for
PAIDand for aCANCELLEDthat we ourselves initiated (not aCANCELLEDyou requested throughCancel— let us know if you want that one too).- Whether you'd like production locked down to a specific Salesforce egress IP range.
- A technical contact on your side for coordinating sandbox testing.
- Confirmation of how long an MTCN should stay valid before it expires (we're defaulting to 30 days per country in sandbox, configurable — let us know if that's not what you expect).
Attached: a Postman collection (
cis-latam-soterex-c2p-sandbox.postman_collection.json) with the token request (both forms),SendRequest, an idempotent retry of the sameSendRequest,Cancel, a couple of error-case examples, and a sample of theNotificationspayload (it points to Postman Echo by default; swap in your own receiver URL to test it) — to make it easier to test outside of Salesforce first. Just paste yourclient_secretinto the collection variables and run the requests top to bottom; each one has tests that check the expected response. Note thattimeinCancelmust be exactlyYYYY-MM-DD HH:mm:ss(the collection fills it in for you).Happy to jump on a call if anything here needs walking through.
Best, Carlos
2. Pasos de Carlos a la mañana
En orden — cada uno depende del anterior. Todo lo destructivo/hacia staging/production queda para vos, no lo hizo la sesión autónoma.
Revisar el PR #55 — leer el diff, sobre todo
C2PController,OAuthTokenControllery las decisiones de la sección "Decisiones que tomé sin Carlos" más abajo. Confirmar que los tests están verdes (ya corridos en CI del PR).Mergear a
main:bashgh pr merge 55 --squashPasar
mainastaging(con tu flujo habitual de PRmain→staging— verdoc/architecture/branching-strategy.md). El deploy de staging corre las migraciones nuevas de este PR automáticamente (tablasapi_clients,api_client_secrets,personal_access_tokens, columnas C2P entransactions/countries,outbound_notifications).Generar el secret del cliente real, en tu máquina — nunca en CI:
bashcd backend && php artisan api-client:generate-secretTe devuelve el secret en claro (guardalo vos, es lo que le mandás a Sean) y un hash Argon2id en base64 (es lo que va al workflow, nunca el secret real).
Correr el workflow para crear el cliente en staging (Actions → "Ejecutar comando artisan (manual)" →
environment: staging):api-client:create soterex --secret-hash-b64=<el hash del paso 4>Te devuelve el
client_idgenerado (cis_stg_...) — anotalo, es lo que también le mandás a Sean.Probar contra staging con
curl(ver ejemplos en la sección 3) antes de avisarle a Sean — confirmar que el token se emite y queSendRequestresponde con un MTCN real.Mandar el mail de la sección 1 (el
client_idreal ya está completo en el texto) — adjuntarcis-latam-soterex-c2p-openapi-v2.yamlycis-latam-soterex-c2p-sandbox.postman_collection.json.Mandar
client_idyclient_secreta Sean por un canal separado y seguro (nunca en el mismo mail, nunca en texto plano por un canal no cifrado) — uno a la vez, confirmando recepción.
Si además querés prender el scheduler en staging (para que notifications:deliver corra solo cada minuto, en vez de dispararlo a mano con el workflow de artisan) — eso toca Terraform, quedó deliberadamente fuera de esta sesión. Es un paso aparte, con tu ok explícito.
3. Ejemplos curl (staging, sin valores sensibles)
Nota del 2026-10-05: el token (primer ejemplo) sigue igual. Los ejemplos de
SendRequestyCancelson del contrato anterior: hoy el request no llevafee, la respuesta esCOD_000conamountyfeecomo texto yexpiration_date, y elCancelya no devuelveamount. Las formas vigentes están en el sign-off, secciones 2.2 y 1.5.
Pedir un token (client_secret_post)
curl -s -X POST "https://api.soterex.stag.cislatam.net/api/oauth/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=<<CLIENT_ID>>&client_secret=<<CLIENT_SECRET>>"Respuesta:
{
"access_token": "1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "c2p"
}SendRequest
curl -s -X POST "https://api.soterex.stag.cislatam.net/api/c2p/v1/SendRequest" \
-H "Authorization: Bearer <<ACCESS_TOKEN>>" \
-H "Content-Type: application/json" \
-d '{
"transaction_id": "sample-tx-001",
"first_name": "Maria",
"last_name": "Gonzalez",
"amount": "500.00",
"fee": "12.50",
"destination_country": "GT",
"sender": "US",
"origin_currency": "USD",
"beneficiary_traveling_with_minors": "N"
}'Respuesta:
{
"code": "COD_001",
"status": "ACCEPTED",
"dtc_estatus": "ACCEPTED",
"message": "RECORD INSERTED SUCCESSFULLY",
"entityResponse": {
"transaction_id": "sample-tx-001",
"token": "6531546915",
"expirate_date": "2026-10-29 21:42:22",
"amount": 500.00,
"fee": 12.50
}
}Cancel
curl -s -X POST "https://api.soterex.stag.cislatam.net/api/c2p/v1/Cancel" \
-H "Authorization: Bearer <<ACCESS_TOKEN>>" \
-H "Content-Type: application/json" \
-d '{
"transaction_id": "sample-tx-001",
"token": "6531546915",
"time": "2026-09-30 22:00:00",
"status": "CANCELLED",
"sub_status": { "code": "1000", "message": "Cancelled by sender" }
}'Respuesta:
{
"code": "COD_002",
"status": "ACCEPTED",
"dtc_estatus": "CANCELLED",
"message": "RECORD UPDATED SUCCESFULLY",
"entityResponse": {
"transaction_id": "sample-tx-001",
"token": "6531546915",
"amount": 500.00
}
}4. Decisiones que tomé sin Carlos
Consolidado de C1 a C4 (cada una ya está en el commit/PR correspondiente; se repite acá para tener todo junto). Ninguna toca main/staging/production ni credenciales reales — son elecciones de implementación dentro de lo que el plan dejaba abierto.
- C2 — Se agregó un segundo rate limit solo-por-IP (60/min) en
/api/oauth/token, además del 30/min porclient_id+IP que pedía el plan — unclient_idinexistente no está protegido por el primero (no hayclient_idreal contra el cual contar). Hallazgo de la revisión de seguridad. - C2 — Se usa
Hash::driver('argon2id')explícito en vez del driver default configurado de la app, tanto al crear como al verificar secrets — este Laravel no trataHash::check()como agnóstico de algoritmo. - C3 —
soterex_transaction_id(columna ya existente entransactions) hace de "external_transaction_id" del cliente; su unique constraint pasó de global a compuesto(api_client_id, soterex_transaction_id)— dos clientes distintos pueden usar el mismotransaction_idsin chocar entre sí (D10 no especificaba esto). - C3 — Se agregó
countries.mtcn_expiration_days, nullable con fallback a 30 días (D12 dejaba el valor "provisional, a confirmar con Soterex" — sin UI todavía para editarlo; el valor real se confirma con la respuesta de Sean a este mail). - C4 — La auth de
SoterexClient::notify()hacia el webhook de Soterex es un placeholder (Basic auth con usuario/contraseña deSoterexSetting, reusados de la config existente) hasta que Soterex confirme el método real — se pregunta en el mail (sección 1). (Reemplazado el 2026-10-05: el webhook se firma con HMAC-SHA256 y ya no usa usuario ni contraseña; ver ADR-017.) - C4 — Se borró el botón "Probar conexión" de la pantalla de Configuración (disparaba el viejo
tokenC2P, que ya no existe del lado de CIS) — no hay un equivalente razonable con solonotify()como única llamada saliente que queda.
5. Verificación manual ya hecha en esta sesión
Antes de escribir este documento, se verificó de punta a punta en un stack Docker descartable (Postgres + Firebase Emulator + backend + frontend, todos aislados de dev/staging reales):
- Token con
client_secret_basicyclient_secret_post, ambos formatos. SendRequestconfee(MTCN emitido), sinfee(rechazado con el código nuevo2016), y en duplicado con payload distinto (rechazado2001). (Contrato anterior: hoy elfeeno va en el request y un duplicado devuelve el original conCOD_009;2016y2001se retiraron.)Cancelde una transacción de otro cliente y con MTCN equivocado (ambos2108, indistinguibles). (Hoy ambos danCODE_001, también indistinguibles;2108se retiró.)- Pago completo de una transacción creada por API a través de la UI real (Backoffice: búsqueda por MTCN, datos del pago, los 3 documentos que bloquean confirmar, confirmar pago).
- Reportes → Estado de Situación muestra la transacción con su comisión (
USD 12.50) y el saldo de Holding de GT descontado exactamente en principal + fee (12000.00 → 11487.50). - Un
OutboundNotificationPAIDquedó encolado (PENDING) para esa transacción. - Rotación de secret con
--overlap=24h: ambos secrets (viejo y nuevo) emiten token durante el solapamiento; tras revocar el viejo, vuelve401 invalid_clienty el nuevo sigue funcionando.
Lo único que no se probó en esta sesión (porque necesita el cliente OAuth real y credenciales de sandbox, ambos prohibidos para esta sesión autónoma) es el flujo end-to-end contra staging mismo — eso es el paso 6 de la sección 2.
6. Consultas pendientes para Soterex que salen del plan de ajustes v3 (G9)
El mail de la sección 1 ya salió. Estas dos son las que salen de G9 y van en el mail único a Sean del plan Ajustes v3 (§6.2, D3-22), que es un borrador hasta que Carlos lo mande. Son solo consultas: ninguna cambia C2PController, el OAuth, SendRequest ni Cancel.
- S-2. ¿Su carta y su Salesforce siguen mostrando el MTCN con el prefijo «C-» más el token, y lo necesitan en nuestros listados? (El reporte de Cumplimiento ya lo imprime con «C-» y la búsqueda de Pago lo tolera; si dicen que no lo usan, se apaga con
CUMPLIMIENTO_MTCN_PREFIXvacía, sin tocar código.) - Lo que no se le pregunta a Soterex: «Send» o «Sent». El estado de la columna 23 del reporte de Cumplimiento es la planilla del cliente, no un estado de la API de Soterex (el contrato C2P no tiene ninguno que se llame así). Es la pregunta QC-19 al cliente. Si Sean, de paso, tiene a mano una fila de ejemplo de su propio reporte, ayuda; no es una consulta.
- S-4. ¿Cómo modifican en Soterex una transacción ya enviada (por ejemplo, si le cambiaron el nombre al beneficiario):
Cancely unSendRequestnuevo, con quétransaction_idy quésub_status? (Hoy el contrato C2P no tiene una operación de modificación; el estado «Update» de Cumplimiento sale del estado vigente en la app.)

