CIS Latam × Soterex — C2P integration: sign-off document
Date: 2026-10-06 · Environment: sandbox (https://api.soterex.stag.cislatam.net) · Contract: the Stipend Payment Provider Integration Specification, accepted on 2026-08-14, plus CIS's written confirmations of 2026-08-14 and 2026-09-04
This document answers, item by item, the Integration checklist (page 13) and the "What we need from the provider" list (pages 12 to 13) of Soterex's specification. It is the written confirmation Soterex asked for before building against the contract. Where the specification is silent, CIS's written confirmations of 2026-08-14 and 2026-09-04 apply. Everything else matches the specification exactly: names, nesting and literals.
Reading guide. Each item carries one of four statuses:
| Status | Meaning |
|---|---|
| Confirmed | CIS commits to it in this document. |
| Ready in sandbox | Implemented and verified by CIS in the sandbox. Soterex can test it now. |
| Needs Soterex | Cannot be closed without something from Soterex (an URL, a secret, a confirmation). |
| Pending CIS | Depends on a CIS action that has not happened yet (production provisioning). |
Honest scope of "verified by CIS". CIS has verified each behavior in this document with automated tests and by hand, against a local receiver that checks the notification body and the HMAC signature the way the specification describes. CIS has not yet exchanged a single message with a real Soterex endpoint: that needs the notification URL and the shared secret listed in section 8. Two scheduled jobs of the sandbox are not running yet: the delivery of notifications and the automatic cancellation of expired transactions. CIS switches them on together with real delivery, once it has that URL and secret. Until then notifications wait in a queue and nothing is sent to you (2.5, 2.6), and a transaction past its last collection day cannot be paid but is not cancelled automatically (1.9).
0. Status at a glance
Contract stage
| Checklist item | Status | Where |
|---|---|---|
| Deviations 1 to 4 accepted or explicitly declined | Confirmed (all four accepted) | 1.1 |
| Status and error vocabularies confirmed as complete | Confirmed | 1.2, 1.3, Appendix C |
| Idempotency behaviour confirmed in writing | Confirmed, Ready in sandbox | 1.4 |
| Signature scheme agreed | Confirmed on CIS side; Needs Soterex (shared secret, key_id) | 1.6, Appendix B |
| Type representation fixed per field | Confirmed | 1.7 |
Build stage
| Checklist item | Status | Where |
|---|---|---|
| Sandbox credentials issued and authentication verified | Ready in sandbox (issued; secret sent through a separate channel) | 2.1 |
| Create transaction verified end to end in sandbox | Ready in sandbox | 2.2 |
Repeat create with the same transaction_id returns the original | Ready in sandbox | 2.3, 1.4 |
| Cancel verified, including already-collected and already-cancelled | Ready in sandbox | 2.4, 1.5 |
| Each notification status delivered and acknowledged in sandbox | Needs Soterex (notification URL and secret; CIS then switches the sandbox delivery job on) | 2.5, 2.6 |
| Signature verification confirmed working, including rejection of a bad signature | Needs Soterex; CIS can send a deliberately bad signature on demand | 2.6 |
| Duplicate notification handled correctly | Needs Soterex; CIS treats CODE_004 as delivered | 2.7 |
| Timeout and retry behaviour exercised | Needs Soterex: verified by CIS against a local receiver; it runs in the sandbox once CIS switches delivery on, which needs your URL and secret | 2.8 |
Launch stage
| Checklist item | Status | Where |
|---|---|---|
| Production credentials issued | Pending CIS (production is not provisioned yet) | 3.1 |
| Production endpoints and IP allowlist confirmed | Pending CIS; no allowlist required | 3.2 |
| Support and escalation contacts exchanged | Needs Soterex (CIS contact is in section 7) | 7 |
| Single low-value live transaction completed end to end before volume | Confirmed (CIS commits to it) | 3.3 |
Other written commitments of the specification
| Item | Status | Where |
|---|---|---|
| Cancellation edge cases defined in writing (collected, already cancelled, settlement window, return of funds) | Confirmed | 1.5 |
| 30 days notice before any certificate or endpoint change | Confirmed | 4 |
| Response time under 30 seconds, retry of notifications | Confirmed | 4 |
| Redemption token of at most 20 characters, stable for the life of the transaction | Confirmed | 1.8 |
| Sandbox can trigger PAID, CANCELLED and FAILED on demand | Ready in sandbox (the request is accepted and queued); delivery Needs Soterex | 2.6 |
| Next-day payment report and account statement | Needs Soterex (templates) | 6 |
1. Contract
1.1 Deviations 1 to 4 (and the fee)
| Deviation | CIS position |
|---|---|
| 1. Business parameters in a JSON body | Accepted. SendRequest and Cancel read their parameters from a JSON body. The query string (the reference implementation's shape) is also accepted, so Soterex can use the body form with no migration cost. |
| 2. Credentials in the body, or OAuth 2.0 | Accepted in its preferred form: OAuth 2.0 client credentials. POST /api/oauth/token, with the secret in Authorization: Basic (client_secret_basic) or in the form body (client_secret_post). There is no /authenticate operation. Tokens last 3600 seconds and there is no refresh token. Details in 2.1. |
3. expiration_date | Accepted. The field is spelled expiration_date, formatted yyyy-MM-dd. expirate_date is no longer returned. |
4. paying_office | Accepted. The notification field is paying_office. zoom_office is never sent. |
The fee. The specification's Operation 2 request has no fee: the provider calculates it and returns it ("We store principal plus fee as the transaction total"). CIS does exactly that:
feeis not part of theSendRequestrequest. If Soterex sends one anyway, CIS ignores it and records, in its own audit trail, that the value differed from the calculated one.- CIS calculates the fee from a fee schedule per destination country (amount tiers, each with a fixed amount, a percentage, or both), freezes it on the transaction when it is created, and returns it in the response as text (
"50.00", with the provisional schedule below). Changing the schedule later never touches transactions that already exist. - If no tier covers an amount, the create is rejected with
2026. - The schedule is provisional: a single tier of a fixed 50.00 per transaction, whatever the amount (500.00 gives 50.00, and so does 20.00: for amounts below 50 the fee is higher than the principal, and CIS does not reject the create). It applies in the sandbox and in production, which opens with the same provisional tier. It is not the definitive schedule: CIS Treasury defines that one, and it replaces the provisional tier when it is ready. The example of 500.00 giving 5.00 in the specification is an example of the calculation, not of this schedule. Please do not use these figures to estimate real fees.
1.2 Status vocabulary
The complete, closed set. CIS will notify Soterex before adding to it.
Transaction status (what a notification carries in status, and what dtc_estatus reports):
| Status | Class | Meaning | Produced by CIS in |
|---|---|---|---|
ACCEPTED | Intermediate | Created and payable. The beneficiary has not collected. | Production and sandbox. Returned in the SendRequest response. Never sent as a notification. |
PAID | Terminal | The beneficiary collected. | Production and sandbox. Notified. |
CANCELLED | Terminal | Withdrawn before collection: by Cancel from Soterex, by CIS operations, or because the MTCN expired. | Production and sandbox. Notified in all three cases. |
FAILED | Terminal | "Could not be completed", reason retained in sub_status. | Sandbox on demand only. In production CIS does not produce FAILED: a collection either completes (PAID) or the transaction stays ACCEPTED until it is paid, cancelled or expired. |
Envelope status (the outcome of the call itself): ACCEPTED (the call was accepted), REJECTED (a business rejection, or an authentication failure), ERROR (CODE_429 and CODE_500).
Sequence rules.
ACCEPTEDmoves toPAIDor toCANCELLED, never anywhere else.PAIDandCANCELLEDnever change again.- A cancelled or expired transaction never becomes
PAID. CIS refuses to pay it. - A correction is cancel-and-recreate: cancel the transaction, then send a new
SendRequestwith a newRS-reference and the old one inprevious_transaction_id. CIS shows the chain (original and replacement) to its operations staff. - A
PAIDfollowed later by aCANCELLEDfor the same transaction cannot happen:Cancelon a collected transaction is rejected (1.5).
1.3 Error vocabulary
Every business rejection is HTTP 200 with status: "REJECTED", the specific code in code, a diagnostic message that names the field (for example first_name: The field is required), and entityResponse as a plain string. There is no dtc_estatus on a rejection, except CODE_010 (see 1.5). Soterex treats an HTTP 200 with a rejecting status as a rejection, as the specification says. A rejection reports the first failing field only, checking the fields one at a time in the order of the table of the OpenAPI file (all the rules of a field, then the next field). Every error of /api/c2p/* is JSON in the same envelope, with or without an Accept header.
{
"code": "2002",
"status": "REJECTED",
"message": "first_name: The field is required",
"entityResponse": "No transaction was created"
}Retry column. "No" means the same request will fail the same way: correct it and send it again. A rejected SendRequest created nothing, so resending it with the same transaction_id is safe.
SendRequest
| Code | Meaning | HTTP | Retryable |
|---|---|---|---|
COD_000 | Transaction created (status: ACCEPTED) | 200 | n/a |
COD_009 | Replay: the transaction_id was already created, the original is returned (1.4) | 200 | n/a |
2000 | transaction_id missing. If the body could not be read (not JSON, broken JSON, or a Content-Type other than application/json) the message is body: not valid JSON or unsupported Content-Type (use application/json) | 200 | No |
2018 | transaction_id is not text, or exceeds 255 characters | 200 | No |
2002 / 2019 | first_name missing / not text or over 255 characters | 200 | No |
2003 / 2020 | last_name missing / not text or over 255 characters | 200 | No |
2004 / 2005 | amount missing / invalid (not a decimal, not greater than zero, more than 2 decimals, or above 9999999999.99): amount: must be greater than zero, with at most 2 decimals and at most 9999999999.99 | 200 | No |
2006 / 2007 | destination_country missing / invalid: Invalid value if it is not two uppercase letters, Country not enabled if it is well formed but not a country CIS operates (today only GT) | 200 | No |
2008 / 2011 | sender missing / invalid: Invalid value if it is not two uppercase letters, Must be US for any other value (the specification: always US) | 200 | No |
2010 / 2009 | origin_currency missing / invalid: Invalid value if it is not three uppercase letters, Must be USD for any other value (the specification: always USD) | 200 | No |
2012 / 2013 | beneficiary_traveling_with_minors missing / not Y or N | 200 | No |
2014 / 2025 | email not text or not a valid address / over 255 characters | 200 | No |
2021 | phone not text or over 255 characters | 200 | No |
2022 | alien_number not text or over 255 characters | 200 | No |
2015 / 2023 | full_name_of_minor missing while the minors flag is Y / not text or over 255 characters | 200 | No |
2024 | previous_transaction_id not text or over 255 characters | 200 | No |
2026 | No fee schedule covers this amount for the destination country (fee: No fee schedule covers this amount for the destination country) | 200 | No: a CIS configuration matter, contact CIS |
An empty alien_number or full_name_of_minor counts as absent, as the specification says. CIS does not reject a request that carries neither a phone nor an e-mail address.
Cancel
| Code | Meaning | HTTP | Retryable |
|---|---|---|---|
COD_000 | Cancelled, or already cancelled (idempotent) | 200 | n/a |
2100 | transaction_id missing, not text, or over 255 characters. If the body could not be read, the message is body: not valid JSON or unsupported Content-Type (use application/json) | 200 | No |
2101 / 2102 / 2103 | token missing / not 10 characters / not 10 digits | 200 | No |
2104 / 2105 | time missing / not yyyy-MM-dd HH:mm:ss | 200 | No |
2106 / 2107 | status missing / not the literal CANCELLED | 200 | No |
2110 | sub_status.code or sub_status.message is not text | 200 | No |
2111 | sub_status.code or sub_status.message exceeds 255 characters | 200 | No |
CODE_001 | Transaction not found: it does not exist for this client, or the token does not match | 200 | No |
CODE_010 | Transaction already collected (carries dtc_estatus: "PAID") | 200 | No |
Sandbox on-demand notifications (POST /api/c2p/v1/sandbox/notify, sandbox only)
| Code | Meaning | HTTP | Retryable |
|---|---|---|---|
COD_000 | Notification queued | 200 | n/a |
2200 / 2201 | transaction_id missing (or the body could not be read, same message as 2000) / not text or over 255 characters | 200 | No |
2202 / 2203 | status missing / not PAID, CANCELLED or FAILED (uppercase) | 200 | No |
2204 / 2205 | sub_status is not an object or its fields are not text / a field exceeds 255 characters | 200 | No |
2206 | sub_status sent on PAID ("must not be sent on PAID") | 200 | No |
2207 | bad_signature is not true or false | 200 | No |
2208 | Too many notifications pending delivery (limit 50) | 200 | Yes, after the next delivery cycle |
CODE_001 | No such transaction for this client | 200 | No |
Authentication and platform
| Code | Where | Meaning | HTTP | Retryable |
|---|---|---|---|---|
CODE_009 | Any /api/c2p/* call | TOKEN REQUIRED: no Authorization: Bearer header | 401 | No: fix the header |
CODE_008 | Any /api/c2p/* call | INVALID TOKEN: unknown, expired or revoked token, a value that cannot be a token CIS issued, or an inactive client | 401 | Yes, after requesting a new token |
CODE_404 | Any /api/c2p/* call | Not found: the URL does not exist | 404 | No: check the URL |
CODE_405 | Any /api/c2p/* call | Method not allowed: every operation is a POST (the response carries Allow) | 405 | No: use POST |
CODE_429 | Any /api/c2p/* call | Rate limit exceeded: Too many requests, retry after N seconds, with a Retry-After header | 429 | Yes, after Retry-After |
CODE_500 | Any /api/c2p/* call | Internal error, retry with backoff | 500 | Yes, with backoff. SendRequest and Cancel are idempotent, so a retry is safe |
unsupported_grant_type | Token endpoint | grant_type is not client_credentials | 400 | No |
invalid_request | Token endpoint | client_id or client_secret missing or not text | 400 | No |
invalid_client | Token endpoint | Wrong client_id or client_secret (CIS does not say which) | 401 | No |
temporarily_unavailable | Token endpoint | Rate limit exceeded: Too many requests, retry after N seconds, with a Retry-After header | 429 | Yes, after Retry-After |
server_error | Token endpoint | Internal error, retry with backoff | 500 | Yes, with backoff |
The 401 body carries code, status (REJECTED), dtc_estatus (null) and message, and no entityResponse. The token endpoint follows the OAuth 2.0 standard (error and error_description, in English), not the C2P envelope, and answers every error as JSON too. Any other HTTP error of /api/c2p/* uses CODE_<status> with a fixed text, and never carries internal detail. The Bearer scheme is not case sensitive.
Retired codes. The codes 2001, 2016, 2017, 2108, 2109, and CODE_002 with entityResponse.errorDetails, are no longer returned. They belong to the previous shape of the sandbox. Appendix C says what replaced each one.
1.4 Idempotency (confirmed in writing)
transaction_id is the idempotency key. Every SendRequest carrying a transaction_id that Soterex already used returns the original transaction, with its original token, fee and expiration_date, and "code": "COD_009", "message": "Duplicate request: original transaction returned". status stays ACCEPTED (the call was accepted: a replay is never rejected) and dtc_estatus is the transaction's current status. This is a replay of a transaction that is still ACCEPTED:
{
"code": "COD_009",
"status": "ACCEPTED",
"dtc_estatus": "ACCEPTED",
"message": "Duplicate request: original transaction returned",
"entityResponse": {
"transaction_id": "0197f2b4-3c1d-7a52-9e0b-5d6a1c2f8e47",
"token": "4907241455",
"amount": "500.00",
"fee": "50.00",
"expiration_date": "2026-12-04"
}
}A replay never creates a second transaction and moves no money. It also never rejects: if the replayed request carries different data (a reformatted name, another amount), CIS still returns the original, and records on its side which fields differed (never the values) so its operations staff can investigate.
The replay is resolved from the
transaction_idbefore the rest of the request is validated, so a retry that fails validation today still returns the original.A replay reports the transaction's current status in
dtc_estatus, and everything else is the response of the create (sameentityResponse). The create (COD_000) always saysACCEPTED. A replay says:The original transaction is statusdtc_estatusWhat it means for you ACCEPTEDACCEPTEDACCEPTEDIt exists and can be collected PAIDACCEPTEDPAIDThe beneficiary already collected CANCELLED(by you, by CIS, or by expiry)ACCEPTEDCANCELLEDIt can no longer be collected: send a new SendRequestwith a newRS-and the old one inprevious_transaction_idSo read
dtc_estatusbefore acting on aCOD_009:status: "ACCEPTED"only says the call was accepted. A transaction past its last collection day that CIS's expiry job has not cancelled yet still reportsACCEPTED: CIS reports the status it has stored, it does not infer it. The notification remains the authoritative event for a change of status.A race between two simultaneous creates with the same
transaction_idresolves the same way: one is created, the other gets the replay response.The key is per client: two clients can use the same
transaction_idwithout colliding.Cancelis idempotent too (1.5).
1.5 Cancel: edge cases, settlement and funds (confirmed in writing)
| Case | Result |
|---|---|
| Already collected | HTTP 200, status: "REJECTED", code: "CODE_010", dtc_estatus: "PAID", message: "Transaction already collected". Distinguishable from a transport error and from "not found". |
| Already cancelled | Succeeds idempotently: the same COD_000 "Cancellation successful" response, nothing is notified again. This includes a transaction CIS cancelled because the MTCN expired. |
Does not exist, belongs to another client, or the token does not match | CODE_001, "Transaction not found". The three cases are deliberately indistinguishable, so CODE_010 cannot be used to learn anything about another client's transactions. |
| Immediate or settlement window? | Immediate and synchronous. The response is the outcome. There is no settlement window and no pending state. |
| Do funds return automatically? | There is nothing to return on CIS's side. CIS debits its prefunding only when the beneficiary collects (principal plus fee). A transaction that was never collected consumed nothing, so cancelling it moves no funds. |
Success response (also the response to a repeated Cancel):
{
"code": "COD_000",
"status": "ACCEPTED",
"dtc_estatus": "CANCELLED",
"message": "Cancellation successful",
"entityResponse": {
"transaction_id": "0197f2b4-3c1d-7a52-9e0b-5d6a1c2f8e47",
"token": "4907241455"
}
}sub_statusis optional on the request: absent,null,{}and empty strings all count as absent. If only one ofcodeandmessageis sent, CIS fills in the other with its default.- The request's
time(US Eastern, per the specification) is validated for format only. CIS does not use it as the cancellation time: theCANCELLEDnotification carries the moment CIS applied the cancellation, in America/Guatemala. - Soterex also receives a
CANCELLEDnotification for its ownCancel, as CIS confirmed on 2026-08-14, so a cancellation is always confirmed through the webhook, whoever started it. Cancelis accepted at any time while the transaction isACCEPTED, including after the last collection day and before CIS's expiry job has run.
1.6 Webhook signature scheme
Every notification is signed. CIS never sends an unsigned notification: in real mode with no active secret, delivery fails and is retried following the schedule in 2.8 (five attempts, about an hour and a half). If there is still no secret by then, the notification is recorded as failed, and CIS resends it by hand once a secret is loaded.
| Element | Value |
|---|---|
| Algorithm | HMAC-SHA256 |
| Signed material | The exact string "{timestamp}.{body}": the timestamp, one dot, then the raw request body, byte for byte as sent |
| Key | The shared secret as plain UTF-8 text, exactly as exchanged. It is not decoded from hex or from base64 |
| Output | Lowercase hex, 64 characters |
X-CIS-Timestamp | Unix epoch in seconds, UTC, as an integer in text. The same value that was signed |
X-CIS-Signature | The HMAC, lowercase hex |
X-CIS-Key-Id | The identifier of the secret that signed (below) |
| Tolerance | Soterex should reject a timestamp more than 300 seconds away from its clock |
| Content-Type | application/json, UTF-8, no \u escapes and no escaped slashes in the body |
| Retries | Every delivery attempt takes a new timestamp and computes a new signature: a retry minutes later is still inside the 300 seconds. Nothing about the signature is stored |
Verify on the raw bytes received, before any JSON parsing; re-serializing the body changes the bytes and breaks the signature. A test vector is in Appendix B.
Secret rotation and key_id.
- Soterex provides the secret through a separately agreed channel, together with its
key_id(a short identifier such ask1; CIS usesk1if none is given). It never travels in a URL, and CIS never returns it by any API or writes it to a log. It is stored encrypted. - The secret must be between 8 and 512 characters, with no control characters. The
key_idallows letters, digits and._:-, up to 64 characters. - CIS always signs with the most recent active secret.
X-CIS-Key-Idtells Soterex which one to verify with. - Rotation with a 24-hour overlap. When CIS loads a new secret, the previous one stays valid for 24 more hours, but the signature switches to the new one from the moment the new secret takes effect. So Soterex must accept both
key_idvalues before CIS switches. Procedure: Soterex installs the new secret on its side, accepting both; CIS loads it, optionally scheduled for an agreed time (up to 30 days ahead); after 24 hours the old one expires on CIS's side and Soterex can retire it. - Revocation is immediate (for a leaked secret). CIS then falls back to the previous secret if it has not expired. With none left, nothing can be signed: deliveries fail and are retried as in 2.8, and CIS resends the ones that end as failed once a new secret is loaded. Revoking a secret that has not started yet (a scheduled change that will not happen) gives the previous secret back the validity that the new one had cut short.
1.7 Type representation, fixed per field
Responses use one representation per field, in every response and every environment.
| Field | Type | Format and notes |
|---|---|---|
code, status, dtc_estatus, message | String | Envelope. dtc_estatus is absent from rejections (except CODE_010). |
entityResponse | Object, or String | An object on success; a plain string on rejection. |
entityResponse.transaction_id | String | CIS's own reference: a UUID. See 1.8. |
entityResponse.token | String | 10 digits, never longer than 20 characters. Stable for the life of the transaction. |
entityResponse.amount, entityResponse.fee | String | Two decimals, for example "500.00". Never a number. |
entityResponse.expiration_date | String | yyyy-MM-dd, the last day the funds can be collected (1.9). |
amount in the request | Number or String | Salesforce may send either: 500, 500.0, "500.00". Greater than zero, up to two decimals, at most 9999999999.99. |
| Every other request field | String | origin_currency is always USD and sender always US (as the specification says); destination_country ISO 3166-1 alpha-2, uppercase, of a country CIS operates. |
time in Cancel | String | yyyy-MM-dd HH:mm:ss. |
| Notification fields | String | All of them, including amount and fee ("500.00"). Dates and times are in America/Guatemala. |
expires_in in the token response | Integer | 3600. The OAuth 2.0 standard representation; the specification's example showed it quoted. |
1.8 Correlation key and identifiers
- The correlation key is Soterex's
RS-reference. It travels in the request astransaction_idand in every notification asnotificationData.transaction_id. CIS matches everything on it. entityResponse.transaction_idin the responses is CIS's own reference (a UUID): Operation 2's table defines that field as "the provider's own reference", and the Operation 3 example shows the same field. CIS does not echo theRS-there. The specification also says theRS-"must be echoed back on every response and every notification": CIS reads it as applying to the notifications, wherenotificationData.transaction_idis always yourRS-, and to the request you made. Please confirm this reading (section 8).- The
tokenis the redemption credential: the beneficiary presents it to collect, and Soterex presents it to cancel. CIS issues a 10-digit number from a cryptographic random generator, unique across all transactions and never reused. It satisfies the limit of 20 characters.
1.9 MTCN validity
- Guatemala: 60 days from creation (the figure on Soterex's letter to the beneficiary). CIS configures the number of days per country.
expiration_dateis the last day the beneficiary can collect: collecting on that day is allowed. A transaction is expired when today's date in America/Guatemala is later thanexpiration_date.- An expired transaction cannot be paid. CIS then cancels it and sends
CANCELLEDwithsub_status.code=CXL_EXPIREDandmessage=MTCN expired without being collected. There is noEXPIREDstatus. - The expiry job runs on a schedule, every 5 minutes (in production). A transaction can be refused for payment a moment before its cancellation notification arrives. In the sandbox the job is not running yet: CIS switches it on together with real notification delivery, once it has your URL and secret. Until then a transaction past its last collection day cannot be paid, but it stays
ACCEPTEDand noCANCELLEDnotification is queued for it. - Expiry only touches transactions created through this API, one at a time, and moves no funds.
Please confirm that 60 days is the validity you expect (section 8).
2. Build: how to test each item in the sandbox
Base URL: https://api.soterex.stag.cislatam.net. The sandbox is the staging environment of CIS: real software, fake money and test data.
2.1 Credentials and authentication
client_id:cis_stg_mxlighrgiydwibea. Theclient_secretis sent through a separate secure channel, never by e-mail with the document.POST /api/oauth/token,Content-Type: application/x-www-form-urlencoded(a JSON body is also accepted),grant_type=client_credentials. Noscopeis required (scope=c2pis accepted and ignored) and noaudience.
{ "access_token": "<opaque token>", "token_type": "Bearer", "expires_in": 3600, "scope": "c2p" }- Use it as
Authorization: Bearer <access_token>. Thetoken_typeis alwaysBearer, in both environments. - Secret rotation of the OAuth client is supported with a 24-hour overlap: tell CIS when you want it.
- Authentication from Soterex's side is for Soterex to confirm (the Build item "sandbox credentials issued and authentication verified").
2.2 Create
POST /api/c2p/v1/SendRequest with the Operation 2 fields in a JSON body and without fee:
{
"transaction_id": "RS-54689",
"first_name": "María",
"last_name": "Gómez",
"amount": "500.00",
"origin_currency": "USD",
"destination_country": "GT",
"sender": "US",
"phone": "+15551234567",
"email": "maria@example.com",
"alien_number": "",
"beneficiary_traveling_with_minors": "N",
"full_name_of_minor": "",
"previous_transaction_id": ""
}Response (HTTP 200). fee here comes from the provisional schedule (a fixed 50.00, see 1.1):
{
"code": "COD_000",
"status": "ACCEPTED",
"dtc_estatus": "ACCEPTED",
"message": "Transaction successful",
"entityResponse": {
"transaction_id": "0197f2b4-3c1d-7a52-9e0b-5d6a1c2f8e47",
"token": "4907241455",
"amount": "500.00",
"fee": "50.00",
"expiration_date": "2026-12-04"
}
}- CIS does not send an
ACCEPTEDnotification: the creation response already carries thetoken. previous_transaction_idis optional; it links a replacement to the transaction it replaces.- Accented characters in names are stored unchanged.
2.3 Repeat create
Send the same request again: the response is the one in 1.4. Change a field and send it again: the response is still the original with COD_009. Cancel the transaction (2.4) and send the request once more: still COD_009, and now dtc_estatus is CANCELLED.
2.4 Cancel
POST /api/c2p/v1/Cancel with transaction_id, token, time and status in a JSON body, and an optional sub_status. The cases to exercise are in 1.5:
- A normal cancel:
COD_000. - The same cancel again:
COD_000, idempotent. - A cancel of a collected transaction:
CODE_010. A transaction becomes collected when a CIS operator pays it from the staging screen. Ask CIS to pay one for you (the on-demand endpoint in 2.6 deliberately does not change a transaction's state). - A cancel of a
transaction_idthat does not exist, or with a wrongtoken:CODE_001.
2.5 Notifications
CIS sends POST requests with the body shapes of Operation 4. The complete shapes, with every sub_status, are in Appendix A. Delivery is asynchronous: the notification is queued when the payment or the cancellation happens, and a delivery job sends it, at most 5 minutes later (see 2.8 for the cap per run when there is a backlog). In the sandbox that job is switched on together with real delivery, once CIS has your URL and secret (section 8), and not before. Until then the notifications wait in the queue: CIS does not send them to you and does not acknowledge them on its own either. CIS will tell you when delivery is on.
What CIS needs from Soterex's endpoint: the notification URL, and the acknowledgement of the specification (page 9):
| What Soterex's endpoint answers | What CIS does |
|---|---|
HTTP 200 and messageCode COD_000 (PAID), COD_002 (CANCELLED) or COD_003 (FAILED) | Delivered. |
HTTP 200 and messageCode CODE_004 (duplicate event) | Delivered. |
HTTP 200 with no messageCode, an unknown one, or a body that is not JSON | Retried. |
| HTTP 3xx | Permanent failure. CIS does not follow redirects. |
| HTTP 400, 401, 403, 404, 415 and any other 4xx except 429 | Permanent failure, not retried. |
| HTTP 429, 5xx, a timeout (30 seconds) or a network error | Retried. |
A permanent failure is recorded and visible to CIS operations, who can resend the notification by hand once the cause is fixed. Please answer 5xx (or 429) for anything transient, and reserve 4xx for a notification that is really wrong.
2.6 On-demand triggers (sandbox only)
The specification requires that the sandbox can trigger PAID, CANCELLED and FAILED notifications on demand against a nominated transaction. POST /api/c2p/v1/sandbox/notify, with the same OAuth token as SendRequest and Cancel:
{ "transaction_id": "RS-54689", "status": "PAID", "sub_status": null, "bad_signature": false }{
"code": "COD_000",
"status": "ACCEPTED",
"message": "Notification queued",
"entityResponse": {
"transaction_id": "RS-54689",
"status": "PAID",
"notification_id": "0197f2c0-7e44-7b13-8c5d-2a9f4e6b1d03"
}
}statusisPAID,CANCELLEDorFAILED. The notification takes the data of the transaction and the current date and time.sub_statusis optional forCANCELLEDandFAILED(defaults in Appendix A); it is rejected onPAID(2206).- It does not change the transaction. An
ACCEPTEDtransaction you triggerPAIDfor staysACCEPTED, and no balance moves. The endpoint only sends the notification. "bad_signature": truesends the notification signed with an invalid secret, so you can check that your endpoint rejects a bad signature. Expect your endpoint to answer 401, and CIS to record a permanent failure.- Only transactions of your own client: anything else answers
CODE_001, identical to a transaction that does not exist. - At most 50 notifications pending delivery, so a run of test calls cannot flood your endpoint (
2208). While real delivery is not switched on in the sandbox nothing is delivered, so test calls can reach that limit: if you hit2208before CIS tells you delivery is on, contact CIS. - The request is accepted and queued (
Notification queued) even while delivery is off; the notification reaches your endpoint once delivery is on. - This endpoint does not exist in production: it answers
404(CODE_404, like any wrong URL).
2.7 Duplicates
CIS may deliver the same notification more than once: after a lost acknowledgement it retries, as the specification describes. Soterex's endpoint should answer the repeat with HTTP 200 and CODE_004, which CIS counts as delivered. The specification says duplicates are detected on transaction identifier and status: a PAID followed by a CANCELLED is not a duplicate. (It cannot happen for the same transaction in practice: see 1.2.)
2.8 Timeout and retry
- CIS's responses. Both operations are synchronous and answer within the 30 seconds the specification asks for. Sandbox exception: the sandbox database pauses itself after a period without use, so the first call after a long quiet period can take noticeably longer than usual. A call that fails or times out can be repeated: both operations are idempotent. Production does not pause.
- CIS's notification calls (once delivery is switched on: see 2.5). A 30-second timeout per call. A failed attempt is retried with minimum waits of 1, 5, 15 and 60 minutes, five attempts in total (at least 81 minutes of waiting). The delivery job runs every 5 minutes, so in practice the waits are multiples of 5 and the whole sequence takes about an hour and a half. After the last attempt the notification is a permanent failure, visible to CIS operations and resent by hand on request. Each run of the delivery job sends at most 50 notifications, the oldest first, and gives each one a single attempt; with a longer backlog the rest leave in the following runs.
- Rate limits (so you can size a batch):
SendRequest,Canceland the sandbox endpoint share 60 requests a minute per client. The limit is counted after authentication: a request with a missing or invalid token is answered401and does not count against it.- The token endpoint allows 30 requests a minute per
client_idand source address, and 60 per source address. - A batch of 20 operations that requests a fresh token for each one fits. Two batches in the same minute may not: a token lasts one hour and can be reused, and CIS can raise the limits if you need it.
3. Launch
3.1 Production credentials
Pending CIS. The production environment is not provisioned yet. Its hostname is decided: https://api.soterex.cislatam.net (token at /api/oauth/token, operations at /api/c2p/v1/SendRequest and /api/c2p/v1/Cancel). The client_id differs per environment (cis_stg_... in the sandbox, cis_prod_... in production) and a client created in one does not exist in the other. By CIS's decision of 2026-10-04 the client_secret value is the same in both. The sandbox and production are separate hosts, as the specification requires.
3.2 Endpoints and IP addresses
- CIS does not require an IP allowlist from Soterex, and does not ask for Soterex's source IP ranges.
- CIS's source IPs for webhooks. Production is designed to send notifications through NAT Gateways, one per availability zone, so from a small set of fixed addresses. CIS gives them to Soterex once production is provisioned. The sandbox has no fixed address (the delivery job runs on tasks with changing public IPs), so please do not allowlist by IP in the sandbox: the HMAC signature is the control.
- All transport is HTTPS with TLS 1.2 or higher, enforced at CIS's load balancer.
3.3 First live transaction
CIS commits to a single low-value live transaction, completed end to end (create, collect, notification acknowledged), before any volume goes through production.
Production opens with the provisional fee schedule of section 1.1: a fixed 50.00 per transaction, whatever the amount. CIS Treasury's definitive schedule replaces it when it is defined. A production SendRequest is rejected with 2026 only if a CIS administrator leaves an amount without a tier (for example by deactivating them all).
4. Non-functional requirements
| Item | CIS position |
|---|---|
| Response time under 30 seconds | Confirmed. SendRequest and Cancel are synchronous and make no external calls. Sandbox wake-up exception in 2.8. |
| Token lifetime | 3600 seconds, no refresh token. Soterex may authenticate per operation, as it does today, within the limits in 2.8. |
| Availability | Sandbox: best effort. Production: CIS will state its support hours with the escalation contact (section 7). Notification delivery survives Soterex's endpoint being briefly unavailable, through the retries in 2.8. |
| Certificate or endpoint changes | Confirmed: CIS notifies Soterex at least 30 days before any certificate or endpoint change. |
| Encoding | UTF-8 throughout. The webhook body is sent as raw UTF-8. |
| Volume | Batches of up to 20 sequential operations fit the limits in 2.8. |
| Redemption token | At most 20 characters; CIS issues 10 digits. Stable for the life of the transaction. |
5. Where the sandbox differs from production
| Behaviour | Sandbox | Production |
|---|---|---|
| Hostname | https://api.soterex.stag.cislatam.net | https://api.soterex.cislatam.net (not provisioned yet) |
| Fees | Provisional schedule: a fixed 50.00 per transaction | The same provisional schedule at first; CIS Treasury's definitive schedule replaces it when it is defined |
| Scheduled jobs (notification delivery, expiry of the MTCN) | Not running yet: CIS switches them on together with real delivery, once it has your URL and secret. Until then notifications wait in a queue and nothing expires on its own | Run every 5 minutes |
FAILED notifications | Only on demand | Never produced |
| On-demand triggers | Available | Do not exist (404) |
| Database | Pauses after a period without use (the first call after it can be slow) | Does not pause |
| Webhook source IP | Not fixed | A small set of fixed addresses, given once provisioned |
| Notification mode | Mock until Soterex sends its URL and secret: once the delivery job runs, CIS answers itself with the specification's acknowledgement and computes the signature headers without sending anything (the job is not running yet, so for now notifications only wait in the queue). Real mode is switched on by CIS once it has both. | Real only. The mock does not exist in production: it sends nothing and never marks a notification as delivered |
6. Reports
Soterex's process also uses a next-day payment report and an account statement. As Paul Brown asked on 2026-08-27, CIS keeps producing both reports during the parallel run and after go-live. CIS needs the templates for both, as part of the Notifications specification: please send them with it (section 8).
7. Contacts
| Role | Name | Channel |
|---|---|---|
| Soterex technical contact for integration testing | Sean Rahimi | Per the Technical Kick Off thread |
| CIS technical contact | [CONTACTO CIS] | [CONTACTO CIS] |
| CIS support and escalation path for production incidents | [CONTACTO CIS] | [CONTACTO CIS] |
8. What we need from Soterex
- The Notifications URL, per environment. Until CIS has it (and the secret below), the sandbox runs in mock mode and its delivery job is off (section 5): nothing is delivered to you. It must be
https://(TLS 1.2 or later), and CIS will not accept credentials in the address (user:password@), a query string or a fragment: the webhook is authenticated by the signature. - The shared secret for the webhook signature, together with its
key_id, through a separately agreed secure channel. Never in a URL and never in an e-mail in the clear. Whether it is plain text or encoded: CIS uses it as plain UTF-8 text (1.6). Please confirm that is how you will verify. - The templates of the next-day payment report and of the account statement (section 6), with the Notifications specification.
- The validity of the MTCN: confirmation that 60 days in Guatemala is what you expect (1.9).
- 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 answers with its own reference inentityResponse.transaction_id, as Operation 2's table defines that field (1.8). Your parser must not rely on theRS-insideentityResponse: it correlates on thetransaction_idof the request you sent and on the notifications. - Written confirmation of the contract points of sections 1.2 to 1.7: statuses, errors, idempotency, Cancel edge cases, signature scheme and types.
- A named support and escalation contact on your side for production incidents.
Appendix A. Notification payloads
POST to Soterex's URL, Content-Type: application/json, with the three signature headers of 1.6. Dates and times are in America/Guatemala. Each status carries the fields the specification requires for it and nothing else: bcv_authorization does not apply in Guatemala and is not sent.
PAID. date and hour are those of the collection, not of the delivery. paying_office is the name of the CIS point of sale that paid, and is never empty. There is no sub_status on PAID.
{
"notificationData": {
"transaction_id": "RS-54689",
"status": "PAID",
"amount": "500.00",
"fee": "50.00",
"date": "2026-10-06",
"hour": "14:32",
"paying_office": "Agencia Centro Histórico"
}
}CANCELLED. time is the moment CIS applied the cancellation.
{
"notificationData": {
"transaction_id": "RS-54689",
"status": "CANCELLED",
"time": "2026-10-06 14:32:00",
"sub_status": { "code": "CXL_SENDER", "message": "Cancelled at sender request" }
}
}FAILED (sandbox on demand only). The shape of the specification:
{
"notificationData": {
"transaction_id": "RS-54689",
"status": "FAILED",
"amount": "500.00",
"fee": "50.00",
"date": "2026-10-06",
"hour": "14:32",
"sub_status": { "code": "FLD_SANDBOX", "message": "Sandbox-triggered failure" }
}
}sub_status values
code | When | message |
|---|---|---|
| The one Soterex sent | A Cancel that carried a sub_status | The one Soterex sent (a missing half is filled in from CXL_SENDER) |
CXL_SENDER | A Cancel from Soterex without a sub_status | Cancelled at sender request |
CXL_CIS | A cancellation by CIS operations | By reason: Cancelled at sender request, Beneficiary data needs correction, Amount needs correction, or Cancelled by CIS operations for any other reason |
CXL_EXPIRED | The MTCN expired | MTCN expired without being collected |
CXL_SANDBOX | An on-demand CANCELLED without a sub_status | Sandbox on-demand notification |
FLD_SANDBOX | An on-demand FAILED without a sub_status | Sandbox-triggered failure |
PAID never carries a sub_status. FAILED exists only on demand in the sandbox. If CIS ever adds a status or a sub_status family, it will tell Soterex first.
Appendix B. Signature test vector
All values are fictitious and the secret is not a real one.
| Item | Value |
|---|---|
| Secret (UTF-8 text) | test-secret-not-real |
X-CIS-Timestamp | 1790000000 |
Body (177 bytes, UTF-8, the ó is 0xC3 0xB3) | {"notificationData":{"transaction_id":"RS-54689","status":"PAID","amount":"500.00","fee":"50.00","date":"2026-10-06","hour":"14:32","paying_office":"Agencia Centro Histórico"}} |
| Signed string | 1790000000. followed by the body |
Expected X-CIS-Signature | d553c5c443c71000a8c99a3fe94aa62eb7e61bc1deffe32b6dd4d3181a79ede5 |
Reproduce it:
BODY='{"notificationData":{"transaction_id":"RS-54689","status":"PAID","amount":"500.00","fee":"50.00","date":"2026-10-06","hour":"14:32","paying_office":"Agencia Centro Histórico"}}'
printf '%s.%s' 1790000000 "$BODY" | openssl dgst -sha256 -hmac 'test-secret-not-real' | awk '{print $NF}'
# d553c5c443c71000a8c99a3fe94aa62eb7e61bc1deffe32b6dd4d3181a79ede5import hmac, hashlib
body = '{"notificationData":{"transaction_id":"RS-54689","status":"PAID","amount":"500.00","fee":"50.00","date":"2026-10-06","hour":"14:32","paying_office":"Agencia Centro Histórico"}}'
print(hmac.new(b"test-secret-not-real", b"1790000000." + body.encode("utf-8"), hashlib.sha256).hexdigest())echo hash_hmac('sha256', '1790000000.'.$body, 'test-secret-not-real');CIS computed this value with four independent tools (PHP's hash_hmac, openssl dgst, Python's hmac and Node's crypto) and all four agree. To check that your verifier rejects tampering, change one byte of the body (for example 500.00 to 500.01) or the timestamp (1790000001): the signature must no longer match.
Appendix C. Retired codes and what replaced them
These belonged to the shape the sandbox had before it was aligned to the specification. They are no longer returned.
| Retired | Replaced by |
|---|---|
COD_001 ("RECORD INSERTED SUCCESSFULLY") as the create success, and COD_002 ("RECORD UPDATED SUCCESFULLY") as the cancel success | COD_000 with Transaction successful and Cancellation successful, as in the specification |
2001 (duplicate transaction_id with a different payload) | COD_009: every repeat returns the original, whatever the payload |
2016 and 2017 (fee required, fee invalid) | Nothing: fee is no longer part of the request (1.1). 2026 is the new fee rejection |
2108 (transaction not found on Cancel) | CODE_001, and CODE_010 for an already collected one |
2109 (sub_status required on Cancel) | Nothing: sub_status is optional |
CODE_002 with HTTP 400 and entityResponse.errorDetails[] | HTTP 200, status: "REJECTED", the specific code, and entityResponse as text |
expirate_date (and Y-m-d H:i:s) | expiration_date, yyyy-MM-dd |
amount and fee as JSON numbers | Text with two decimals |
The flat notification body, HTTP Basic on the webhook, and zoom_office | The nested notificationData body, the HMAC signature, and paying_office |

