Skip to content

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), respuestas COD_001 / COD_002, expirate_date, amount y fee como número, fee obligatorio en el request, el error 2001 y el 2108. Lo vigente es 2026-10-06-c2p-sign-off (el contrato) y 2026-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 (fee obligatorio en el request, HTTP Basic en el webhook, expirate_date, sin notificar el CANCELLED que pide Soterex, sin vencimiento). Lo reemplaza el mail 2026-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 URLPOST https://api.soterex.stag.cislatam.net/api/oauth/token

2. Base URL and paths for Send and Cancel Base URL: https://api.soterex.stag.cislatam.net

  • POST /api/c2p/v1/SendRequest
  • POST /api/c2p/v1/Cancel

3. Sandbox client_id and client_secretclient_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, with grant_type=client_credentials in the body.
  • client_secret_post: client_id, client_secret and grant_type=client_credentials all in the body.

Content-Type: application/x-www-form-urlencoded. No scope is required — if you send scope=c2p we accept and ignore it. No audience parameter 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> on SendRequest and Cancel.

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 SendRequest and Cancel.

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 — fee is now required in SendRequest Our original spec (v1.4) only returned fee in the SendRequest response. Since it's actually Soterex who computes and sends the commission, we've made fee a required field in the request body as well (same format as amount: 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 token field in the SendRequest response (entityResponse.token, 10 digits). It's also the token you send us in Cancel. entityResponse.expirate_date is its planned expiration date, informational for now: we don't enforce expiry yet, so an unpaid transaction stays ACCEPTED (payable and cancellable) until it's paid or you call Cancel, 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 the Notifications webhook 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 PAID and for a CANCELLED that we ourselves initiated (not a CANCELLED you requested through Cancel — 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 same SendRequest, Cancel, a couple of error-case examples, and a sample of the Notifications payload (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 your client_secret into the collection variables and run the requests top to bottom; each one has tests that check the expected response. Note that time in Cancel must be exactly YYYY-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.

  1. Revisar el PR #55 — leer el diff, sobre todo C2PController, OAuthTokenController y 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).

  2. Mergear a main:

    bash
    gh pr merge 55 --squash
  3. Pasar main a staging (con tu flujo habitual de PR main → staging — ver doc/architecture/branching-strategy.md). El deploy de staging corre las migraciones nuevas de este PR automáticamente (tablas api_clients, api_client_secrets, personal_access_tokens, columnas C2P en transactions/countries, outbound_notifications).

  4. Generar el secret del cliente real, en tu máquina — nunca en CI:

    bash
    cd backend && php artisan api-client:generate-secret

    Te 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).

  5. 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_id generado (cis_stg_...) — anotalo, es lo que también le mandás a Sean.

  6. Probar contra staging con curl (ver ejemplos en la sección 3) antes de avisarle a Sean — confirmar que el token se emite y que SendRequest responde con un MTCN real.

  7. Mandar el mail de la sección 1 (el client_id real ya está completo en el texto) — adjuntar cis-latam-soterex-c2p-openapi-v2.yaml y cis-latam-soterex-c2p-sandbox.postman_collection.json.

  8. Mandar client_id y client_secret a 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 SendRequest y Cancel son del contrato anterior: hoy el request no lleva fee, la respuesta es COD_000 con amount y fee como texto y expiration_date, y el Cancel ya no devuelve amount. Las formas vigentes están en el sign-off, secciones 2.2 y 1.5.

Pedir un token (client_secret_post) ​

bash
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:

json
{
  "access_token": "1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "c2p"
}

SendRequest ​

bash
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:

json
{
  "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 ​

bash
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:

json
{
  "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 por client_id+IP que pedía el plan — un client_id inexistente no está protegido por el primero (no hay client_id real 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 trata Hash::check() como agnóstico de algoritmo.
  • C3 — soterex_transaction_id (columna ya existente en transactions) 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 mismo transaction_id sin 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 de SoterexSetting, 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 solo notify() 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_basic y client_secret_post, ambos formatos.
  • SendRequest con fee (MTCN emitido), sin fee (rechazado con el código nuevo 2016), y en duplicado con payload distinto (rechazado 2001). (Contrato anterior: hoy el fee no va en el request y un duplicado devuelve el original con COD_009; 2016 y 2001 se retiraron.)
  • Cancel de una transacción de otro cliente y con MTCN equivocado (ambos 2108, indistinguibles). (Hoy ambos dan CODE_001, también indistinguibles; 2108 se 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 OutboundNotification PAID quedó 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, vuelve 401 invalid_client y 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_PREFIX vací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): Cancel y un SendRequest nuevo, con qué transaction_id y 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.)

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