Mail a Sean — el sandbox ya está alineado a su especificación
Date: 2026-10-06 Para: Sean Rahimi (Soterex / Prutech), contacto técnico de Soterex. Plan: doc/plans/2026-10-05-alineacion-contrato-c2p-soterex.md.
Esto es un borrador. No está enviado ni guardado en ningún sistema de correo. El mail va en inglés porque se manda a Soterex; este encabezado es solo para vos y no forma parte del mail.
Antes de mandar
El checklist completo (PR, scheduler, curl contra Staging, [CONTACTO CIS], qué no está verificado contra Soterex) está en 2026-10-06-antes-de-mandar-el-sign-off. Lo que sigue es lo propio de este mail:
- La línea del
client_secret: el secret NO se pega en el mail. El sign-off (2.1), el OpenAPI y la collection dicen que viaja por un canal seguro aparte, y el mail anterior (30/09) también lo prometió porque había gente en copia. Además es el mismo secret para producción (decisión del 2026-10-04). Por defecto el cuerpo diceclient_secret: unchanged, as sent to you through the secure channel on 2026-10-04: segúndoc/environments/production.md, Sean ya lo tiene desde esa fecha.[CLIENT_SECRET]es solo para el caso en que hubo una rotación: en ese caso reemplazá la línea porclient_secret: [CLIENT_SECRET — the new secret is being sent separately, through the secure channel we agreed; it is NOT pasted in this e-mail]y mandá el valor por ese canal, nunca en este mail. Si dejás el placeholder sin completar, el texto igual no contiene ningún secret. - El mail dice la verdad del 2026-10-05: el scheduler del sandbox sigue apagado y no se entrega nada hasta tener la URL y el secret de Soterex (decisión de Carlos; el punto 4 y el «Expiry» de la sección 2 lo dicen, y el mail no promete notificaciones reales). Si cuando lo mandes ya prendiste el scheduler o pasaste a Real, esos dos puntos están desactualizados: reescribilos. Y si el PR #80 no está desplegado en Staging, el mail promete de más (describe el contrato nuevo).
- Adjuntar tres archivos: el sign-off (podés mandarlo como
.mdo exportarlo a PDF),cis-latam-soterex-c2p-openapi-v2.yamlycis-latam-soterex-c2p-sandbox.postman_collection.json. El OpenAPI y la collection llevan el mismo nombre que los del 30/09: el mail dice que los reemplazan. En la collection,client_secretywebhook_secretvan con un placeholder (<PLACEHOLDER — …>), no con el valor. - No pide IPs (decisión D10 del plan): confirmar que no hace falta agregarlo.
- Las cinco consultas de los ajustes v3 no van en este mail por defecto. Hay un borrador aparte,
2026-10-07-borrador-preguntas-a-soterex-ajustes-v3, que decide si salen después de este (lo que recomienda) o pegadas como una sección más. Este mail no las menciona.
El mail
Subject: Re: Technical Kick Off CIS APIs — sandbox aligned to your specification
Hi Sean,
The CIS sandbox now follows the Stipend Payment Provider Integration Specification you sent, together with the written confirmations from August 14 and September 4. The create, cancel and on-demand calls are deployed and ready for you to test; the delivery of notifications to you is not switched on yet (section 4). This replaces the contract in our September 30 e-mail, so please test against what is described here and in the attachments.
1. Credentials
client_id:cis_stg_mxlighrgiydwibeaclient_secret: unchanged, as sent to you through the secure channel on 2026-10-04- Token URL:
POST https://api.soterex.stag.cislatam.net/api/oauth/token(OAuth 2.0 client credentials, unchanged)- Base URL:
https://api.soterex.stag.cislatam.net, withPOST /api/c2p/v1/SendRequestandPOST /api/c2p/v1/Cancel2. What changed since the September 30 credentials If you already started testing, please expect these differences:
- Responses. Success is
COD_000withTransaction successfulandCancellation successful(it wasCOD_001andCOD_002).amountandfeeare text with two decimals ("500.00"). The expiry field isexpiration_date, formattedyyyy-MM-dd(it wasexpirate_date). TheCancelresponse no longer carries the amount.entityResponse.transaction_idis now CIS's own reference, not yourRS-number.- Rejections. A business rejection is now HTTP 200 with
status: "REJECTED", the specific code, a message that names the field, andentityResponseas plain text (before, HTTP 400 witherrorDetails).Cancelof an already collected transaction answersCODE_010; one that does not exist,CODE_001.- Repeats. Every repeated
transaction_idreturns the original transaction withCOD_009, even if the payload differs (there is no2001any more).statusstaysACCEPTEDanddtc_estatusis the transaction's current status (ACCEPTED,PAIDorCANCELLED), so read it before acting on aCOD_009.- Fee.
feeis not part of theSendRequestrequest any more: CIS calculates it and returns it. If you send one, it is ignored. This withdraws what our September 30 e-mail said aboutfeebeing required. The fee schedule is provisional: a fixed 50.00 per transaction, whatever the amount (500.00 gives 50.00, and so does 20.00). Production opens with the same provisional tier. It is not the definitive schedule, which CIS Treasury defines and which will replace it: please do not use these figures to estimate real fees.- Validation.
origin_currencymust beUSDandsendermust beUS, as your specification says: any other value is rejected with2009or2011(origin_currency: Must be USD,sender: Must be US). A country CIS does not operate is2007withCountry not enabled.- Cancel.
sub_statusis optional.- Notifications. The body is nested under
notificationData, with the fields each status requires and nothing else (paying_office, nosub_statusonPAID). Every notification is signed with HMAC-SHA256 (X-CIS-Timestamp,X-CIS-Signature,X-CIS-Key-Id); HTTP Basic is gone. ACANCELLEDis sent for every cancellation, including your ownCancel.- Expiry. The MTCN now expires: 60 days in Guatemala. After the last collection day it cannot be paid, and CIS cancels it and sends
CANCELLEDwithCXL_EXPIRED. (Our September 30 e-mail said expiry was not enforced.) In the sandbox the job that cancels expired transactions is switched on together with notification delivery (section 4): until then an expired transaction can no longer be paid, but it staysACCEPTEDand noCANCELLEDis queued for it.- On-demand triggers.
POST /api/c2p/v1/sandbox/notifyqueues aPAID,CANCELLEDorFAILEDnotification for a transaction you pick, and can queue one with a deliberately bad signature, as the specification asks. It does not change the transaction, and it does not exist in production. The notification reaches you once delivery is on (section 4).- Errors. Every error of the C2P endpoints is JSON in the same envelope as everything else, with or without an
Acceptheader:CODE_429andCODE_500(both safe to retry), andCODE_404andCODE_405for a wrong URL or method. Over-long text and huge amounts are rejections now, instead of a500. The token endpoint answers its errors in the OAuth 2.0 format.3. Attached
- The sign-off document (
2026-10-06-c2p-sign-off.md): one answer for each item of the integration checklist and of "what we need from the provider", with the complete status and error vocabularies, the idempotency andCancelbehaviour, the signature scheme with a test vector, the type of every field, and the contacts.- The updated API reference (
cis-latam-soterex-c2p-openapi-v2.yaml): it replaces the file with the same name we sent on September 30.- The updated Postman collection (
cis-latam-soterex-c2p-sandbox.postman_collection.json): it replaces the previous one. Paste yourclient_secretinto the collection variables and run it top to bottom.4. Notifications: nothing is delivered to you until we have your URL and secret. The sandbox is in mock mode and the job that delivers notifications (and the one that cancels expired transactions) is not switched on yet. So CIS sends nothing to you, and the notifications that come up (a payment, a cancellation, a test you trigger with
sandbox/notify) wait in a queue. As soon as we have the two items below, we will switch the sandbox to real delivery and let you know. Once it is on, delivery is asynchronous: a delivery job runs every 5 minutes, so a notification leaves within about 5 minutes of the event, and a notification that fails is retried (1, 5, 15 and 60 minutes, five attempts in total). Until then, please do not expect notifications. While nothing is delivered, the on-demand triggers can reach their limit of 50 pending notifications (2208): if that happens, tell us.5. A note on the sandbox. Its database pauses after a period without use, so the first call after a long quiet period can take noticeably longer than usual. If a call fails or times out, repeat it: both operations are idempotent. Production does not pause.
6. What we need from you
- The Notifications URL for the sandbox: it must be
https://, with no credentials, query string or fragment in the address (the webhook is authenticated by the signature).- The shared secret for the webhook signature, with its
key_id, through a secure channel you prefer (never in an e-mail in the clear and never in a URL). CIS uses the secret as plain UTF-8 text, as it is written.- The templates of the next-day payment report and of the account statement, together with the Notifications specification. CIS keeps producing both reports during the parallel run and after go-live.
- The MTCN validity: confirmation that 60 days in Guatemala is what you expect.
- Confirmation of how the
RS-is echoed. Your specification says it must be echoed back on every response and every notification: CIS returns it in every notification, andentityResponse.transaction_idcarries CIS's own reference, as Operation 2's table defines it. Your parser must not rely on theRS-insideentityResponse: you correlate on thetransaction_idyou send and on the notifications.- A named support and escalation contact on your side for production incidents.
- Written confirmation of the contract points in the sign-off document.
Section 8 of the sign-off document has this same list. We are not asking for any IP ranges. You are our technical contact for the sandbox tests, and the CIS contacts are in section 7 of the same document.
Happy to jump on a call to walk through any of this.
Best, Carlos

