Skip to content

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:

  1. 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 dice client_secret: unchanged, as sent to you through the secure channel on 2026-10-04: según doc/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 por client_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.
  2. 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).
  3. Adjuntar tres archivos: el sign-off (podés mandarlo como .md o exportarlo a PDF), cis-latam-soterex-c2p-openapi-v2.yaml y cis-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_secret y webhook_secret van con un placeholder (<PLACEHOLDER — …>), no con el valor.
  4. No pide IPs (decisión D10 del plan): confirmar que no hace falta agregarlo.
  5. 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_mxlighrgiydwibea
  • client_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, with POST /api/c2p/v1/SendRequest and POST /api/c2p/v1/Cancel

2. What changed since the September 30 credentials If you already started testing, please expect these differences:

  • Responses. Success is COD_000 with Transaction successful and Cancellation successful (it was COD_001 and COD_002). amount and fee are text with two decimals ("500.00"). The expiry field is expiration_date, formatted yyyy-MM-dd (it was expirate_date). The Cancel response no longer carries the amount. entityResponse.transaction_id is now CIS's own reference, not your RS- number.
  • Rejections. A business rejection is now HTTP 200 with status: "REJECTED", the specific code, a message that names the field, and entityResponse as plain text (before, HTTP 400 with errorDetails). Cancel of an already collected transaction answers CODE_010; one that does not exist, CODE_001.
  • Repeats. Every repeated transaction_id returns the original transaction with COD_009, even if the payload differs (there is no 2001 any more). status stays ACCEPTED and dtc_estatus is the transaction's current status (ACCEPTED, PAID or CANCELLED), so read it before acting on a COD_009.
  • Fee. fee is not part of the SendRequest request any more: CIS calculates it and returns it. If you send one, it is ignored. This withdraws what our September 30 e-mail said about fee being 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_currency must be USD and sender must be US, as your specification says: any other value is rejected with 2009 or 2011 (origin_currency: Must be USD, sender: Must be US). A country CIS does not operate is 2007 with Country not enabled.
  • Cancel. sub_status is optional.
  • Notifications. The body is nested under notificationData, with the fields each status requires and nothing else (paying_office, no sub_status on PAID). Every notification is signed with HMAC-SHA256 (X-CIS-Timestamp, X-CIS-Signature, X-CIS-Key-Id); HTTP Basic is gone. A CANCELLED is sent for every cancellation, including your own Cancel.
  • Expiry. The MTCN now expires: 60 days in Guatemala. After the last collection day it cannot be paid, and CIS cancels it and sends CANCELLED with CXL_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 stays ACCEPTED and no CANCELLED is queued for it.
  • On-demand triggers. POST /api/c2p/v1/sandbox/notify queues a PAID, CANCELLED or FAILED notification 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 Accept header: CODE_429 and CODE_500 (both safe to retry), and CODE_404 and CODE_405 for a wrong URL or method. Over-long text and huge amounts are rejections now, instead of a 500. 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 and Cancel behaviour, 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 your client_secret into 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, and entityResponse.transaction_id carries CIS's own reference, as Operation 2's table defines it. Your parser must not rely on the RS- inside entityResponse: you correlate on the transaction_id you 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

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