Skip to content

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:

StatusMeaning
ConfirmedCIS commits to it in this document.
Ready in sandboxImplemented and verified by CIS in the sandbox. Soterex can test it now.
Needs SoterexCannot be closed without something from Soterex (an URL, a secret, a confirmation).
Pending CISDepends 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 itemStatusWhere
Deviations 1 to 4 accepted or explicitly declinedConfirmed (all four accepted)1.1
Status and error vocabularies confirmed as completeConfirmed1.2, 1.3, Appendix C
Idempotency behaviour confirmed in writingConfirmed, Ready in sandbox1.4
Signature scheme agreedConfirmed on CIS side; Needs Soterex (shared secret, key_id)1.6, Appendix B
Type representation fixed per fieldConfirmed1.7

Build stage ​

Checklist itemStatusWhere
Sandbox credentials issued and authentication verifiedReady in sandbox (issued; secret sent through a separate channel)2.1
Create transaction verified end to end in sandboxReady in sandbox2.2
Repeat create with the same transaction_id returns the originalReady in sandbox2.3, 1.4
Cancel verified, including already-collected and already-cancelledReady in sandbox2.4, 1.5
Each notification status delivered and acknowledged in sandboxNeeds 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 signatureNeeds Soterex; CIS can send a deliberately bad signature on demand2.6
Duplicate notification handled correctlyNeeds Soterex; CIS treats CODE_004 as delivered2.7
Timeout and retry behaviour exercisedNeeds Soterex: verified by CIS against a local receiver; it runs in the sandbox once CIS switches delivery on, which needs your URL and secret2.8

Launch stage ​

Checklist itemStatusWhere
Production credentials issuedPending CIS (production is not provisioned yet)3.1
Production endpoints and IP allowlist confirmedPending CIS; no allowlist required3.2
Support and escalation contacts exchangedNeeds Soterex (CIS contact is in section 7)7
Single low-value live transaction completed end to end before volumeConfirmed (CIS commits to it)3.3

Other written commitments of the specification ​

ItemStatusWhere
Cancellation edge cases defined in writing (collected, already cancelled, settlement window, return of funds)Confirmed1.5
30 days notice before any certificate or endpoint changeConfirmed4
Response time under 30 seconds, retry of notificationsConfirmed4
Redemption token of at most 20 characters, stable for the life of the transactionConfirmed1.8
Sandbox can trigger PAID, CANCELLED and FAILED on demandReady in sandbox (the request is accepted and queued); delivery Needs Soterex2.6
Next-day payment report and account statementNeeds Soterex (templates)6

1. Contract ​

1.1 Deviations 1 to 4 (and the fee) ​

DeviationCIS position
1. Business parameters in a JSON bodyAccepted. 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.0Accepted 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_dateAccepted. The field is spelled expiration_date, formatted yyyy-MM-dd. expirate_date is no longer returned.
4. paying_officeAccepted. 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:

  • fee is not part of the SendRequest request. 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):

StatusClassMeaningProduced by CIS in
ACCEPTEDIntermediateCreated and payable. The beneficiary has not collected.Production and sandbox. Returned in the SendRequest response. Never sent as a notification.
PAIDTerminalThe beneficiary collected.Production and sandbox. Notified.
CANCELLEDTerminalWithdrawn before collection: by Cancel from Soterex, by CIS operations, or because the MTCN expired.Production and sandbox. Notified in all three cases.
FAILEDTerminal"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.

  • ACCEPTED moves to PAID or to CANCELLED, never anywhere else. PAID and CANCELLED never 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 SendRequest with a new RS- reference and the old one in previous_transaction_id. CIS shows the chain (original and replacement) to its operations staff.
  • A PAID followed later by a CANCELLED for the same transaction cannot happen: Cancel on 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.

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

CodeMeaningHTTPRetryable
COD_000Transaction created (status: ACCEPTED)200n/a
COD_009Replay: the transaction_id was already created, the original is returned (1.4)200n/a
2000transaction_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)200No
2018transaction_id is not text, or exceeds 255 characters200No
2002 / 2019first_name missing / not text or over 255 characters200No
2003 / 2020last_name missing / not text or over 255 characters200No
2004 / 2005amount 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.99200No
2006 / 2007destination_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)200No
2008 / 2011sender missing / invalid: Invalid value if it is not two uppercase letters, Must be US for any other value (the specification: always US)200No
2010 / 2009origin_currency missing / invalid: Invalid value if it is not three uppercase letters, Must be USD for any other value (the specification: always USD)200No
2012 / 2013beneficiary_traveling_with_minors missing / not Y or N200No
2014 / 2025email not text or not a valid address / over 255 characters200No
2021phone not text or over 255 characters200No
2022alien_number not text or over 255 characters200No
2015 / 2023full_name_of_minor missing while the minors flag is Y / not text or over 255 characters200No
2024previous_transaction_id not text or over 255 characters200No
2026No fee schedule covers this amount for the destination country (fee: No fee schedule covers this amount for the destination country)200No: 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 ​

CodeMeaningHTTPRetryable
COD_000Cancelled, or already cancelled (idempotent)200n/a
2100transaction_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)200No
2101 / 2102 / 2103token missing / not 10 characters / not 10 digits200No
2104 / 2105time missing / not yyyy-MM-dd HH:mm:ss200No
2106 / 2107status missing / not the literal CANCELLED200No
2110sub_status.code or sub_status.message is not text200No
2111sub_status.code or sub_status.message exceeds 255 characters200No
CODE_001Transaction not found: it does not exist for this client, or the token does not match200No
CODE_010Transaction already collected (carries dtc_estatus: "PAID")200No

Sandbox on-demand notifications (POST /api/c2p/v1/sandbox/notify, sandbox only) ​

CodeMeaningHTTPRetryable
COD_000Notification queued200n/a
2200 / 2201transaction_id missing (or the body could not be read, same message as 2000) / not text or over 255 characters200No
2202 / 2203status missing / not PAID, CANCELLED or FAILED (uppercase)200No
2204 / 2205sub_status is not an object or its fields are not text / a field exceeds 255 characters200No
2206sub_status sent on PAID ("must not be sent on PAID")200No
2207bad_signature is not true or false200No
2208Too many notifications pending delivery (limit 50)200Yes, after the next delivery cycle
CODE_001No such transaction for this client200No

Authentication and platform ​

CodeWhereMeaningHTTPRetryable
CODE_009Any /api/c2p/* callTOKEN REQUIRED: no Authorization: Bearer header401No: fix the header
CODE_008Any /api/c2p/* callINVALID TOKEN: unknown, expired or revoked token, a value that cannot be a token CIS issued, or an inactive client401Yes, after requesting a new token
CODE_404Any /api/c2p/* callNot found: the URL does not exist404No: check the URL
CODE_405Any /api/c2p/* callMethod not allowed: every operation is a POST (the response carries Allow)405No: use POST
CODE_429Any /api/c2p/* callRate limit exceeded: Too many requests, retry after N seconds, with a Retry-After header429Yes, after Retry-After
CODE_500Any /api/c2p/* callInternal error, retry with backoff500Yes, with backoff. SendRequest and Cancel are idempotent, so a retry is safe
unsupported_grant_typeToken endpointgrant_type is not client_credentials400No
invalid_requestToken endpointclient_id or client_secret missing or not text400No
invalid_clientToken endpointWrong client_id or client_secret (CIS does not say which)401No
temporarily_unavailableToken endpointRate limit exceeded: Too many requests, retry after N seconds, with a Retry-After header429Yes, after Retry-After
server_errorToken endpointInternal error, retry with backoff500Yes, 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:

json
{
  "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_id before 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 (same entityResponse). The create (COD_000) always says ACCEPTED. A replay says:

    The original transaction isstatusdtc_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 SendRequest with a new RS- and the old one in previous_transaction_id

    So read dtc_estatus before acting on a COD_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 reports ACCEPTED: 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_id resolves the same way: one is created, the other gets the replay response.

  • The key is per client: two clients can use the same transaction_id without colliding.

  • Cancel is idempotent too (1.5).

1.5 Cancel: edge cases, settlement and funds (confirmed in writing) ​

CaseResult
Already collectedHTTP 200, status: "REJECTED", code: "CODE_010", dtc_estatus: "PAID", message: "Transaction already collected". Distinguishable from a transport error and from "not found".
Already cancelledSucceeds 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 matchCODE_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):

json
{
  "code": "COD_000",
  "status": "ACCEPTED",
  "dtc_estatus": "CANCELLED",
  "message": "Cancellation successful",
  "entityResponse": {
    "transaction_id": "0197f2b4-3c1d-7a52-9e0b-5d6a1c2f8e47",
    "token": "4907241455"
  }
}
  • sub_status is optional on the request: absent, null, {} and empty strings all count as absent. If only one of code and message is 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: the CANCELLED notification carries the moment CIS applied the cancellation, in America/Guatemala.
  • Soterex also receives a CANCELLED notification for its own Cancel, as CIS confirmed on 2026-08-14, so a cancellation is always confirmed through the webhook, whoever started it.
  • Cancel is accepted at any time while the transaction is ACCEPTED, 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.

ElementValue
AlgorithmHMAC-SHA256
Signed materialThe exact string "{timestamp}.{body}": the timestamp, one dot, then the raw request body, byte for byte as sent
KeyThe shared secret as plain UTF-8 text, exactly as exchanged. It is not decoded from hex or from base64
OutputLowercase hex, 64 characters
X-CIS-TimestampUnix epoch in seconds, UTC, as an integer in text. The same value that was signed
X-CIS-SignatureThe HMAC, lowercase hex
X-CIS-Key-IdThe identifier of the secret that signed (below)
ToleranceSoterex should reject a timestamp more than 300 seconds away from its clock
Content-Typeapplication/json, UTF-8, no \u escapes and no escaped slashes in the body
RetriesEvery 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 as k1; CIS uses k1 if 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_id allows letters, digits and . _ : -, up to 64 characters.
  • CIS always signs with the most recent active secret. X-CIS-Key-Id tells 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_id values 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.

FieldTypeFormat and notes
code, status, dtc_estatus, messageStringEnvelope. dtc_estatus is absent from rejections (except CODE_010).
entityResponseObject, or StringAn object on success; a plain string on rejection.
entityResponse.transaction_idStringCIS's own reference: a UUID. See 1.8.
entityResponse.tokenString10 digits, never longer than 20 characters. Stable for the life of the transaction.
entityResponse.amount, entityResponse.feeStringTwo decimals, for example "500.00". Never a number.
entityResponse.expiration_dateStringyyyy-MM-dd, the last day the funds can be collected (1.9).
amount in the requestNumber or StringSalesforce may send either: 500, 500.0, "500.00". Greater than zero, up to two decimals, at most 9999999999.99.
Every other request fieldStringorigin_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 CancelStringyyyy-MM-dd HH:mm:ss.
Notification fieldsStringAll of them, including amount and fee ("500.00"). Dates and times are in America/Guatemala.
expires_in in the token responseInteger3600. 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 as transaction_id and in every notification as notificationData.transaction_id. CIS matches everything on it.
  • entityResponse.transaction_id in 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 the RS- there. The specification also says the RS- "must be echoed back on every response and every notification": CIS reads it as applying to the notifications, where notificationData.transaction_id is always your RS-, and to the request you made. Please confirm this reading (section 8).
  • The token is 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_date is 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 than expiration_date.
  • An expired transaction cannot be paid. CIS then cancels it and sends CANCELLED with sub_status.code = CXL_EXPIRED and message = MTCN expired without being collected. There is no EXPIRED status.
  • 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 ACCEPTED and no CANCELLED notification 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. The client_secret is 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. No scope is required (scope=c2p is accepted and ignored) and no audience.
json
{ "access_token": "<opaque token>", "token_type": "Bearer", "expires_in": 3600, "scope": "c2p" }
  • Use it as Authorization: Bearer <access_token>. The token_type is always Bearer, 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:

json
{
  "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):

json
{
  "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 ACCEPTED notification: the creation response already carries the token.
  • previous_transaction_id is 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_id that does not exist, or with a wrong token: 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 answersWhat 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 JSONRetried.
HTTP 3xxPermanent failure. CIS does not follow redirects.
HTTP 400, 401, 403, 404, 415 and any other 4xx except 429Permanent failure, not retried.
HTTP 429, 5xx, a timeout (30 seconds) or a network errorRetried.

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:

json
{ "transaction_id": "RS-54689", "status": "PAID", "sub_status": null, "bad_signature": false }
json
{
  "code": "COD_000",
  "status": "ACCEPTED",
  "message": "Notification queued",
  "entityResponse": {
    "transaction_id": "RS-54689",
    "status": "PAID",
    "notification_id": "0197f2c0-7e44-7b13-8c5d-2a9f4e6b1d03"
  }
}
  • status is PAID, CANCELLED or FAILED. The notification takes the data of the transaction and the current date and time. sub_status is optional for CANCELLED and FAILED (defaults in Appendix A); it is rejected on PAID (2206).
  • It does not change the transaction. An ACCEPTED transaction you trigger PAID for stays ACCEPTED, and no balance moves. The endpoint only sends the notification.
  • "bad_signature": true sends 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 hit 2208 before 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, Cancel and 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 answered 401 and does not count against it.
    • The token endpoint allows 30 requests a minute per client_id and 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 ​

ItemCIS position
Response time under 30 secondsConfirmed. SendRequest and Cancel are synchronous and make no external calls. Sandbox wake-up exception in 2.8.
Token lifetime3600 seconds, no refresh token. Soterex may authenticate per operation, as it does today, within the limits in 2.8.
AvailabilitySandbox: 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 changesConfirmed: CIS notifies Soterex at least 30 days before any certificate or endpoint change.
EncodingUTF-8 throughout. The webhook body is sent as raw UTF-8.
VolumeBatches of up to 20 sequential operations fit the limits in 2.8.
Redemption tokenAt most 20 characters; CIS issues 10 digits. Stable for the life of the transaction.

5. Where the sandbox differs from production ​

BehaviourSandboxProduction
Hostnamehttps://api.soterex.stag.cislatam.nethttps://api.soterex.cislatam.net (not provisioned yet)
FeesProvisional schedule: a fixed 50.00 per transactionThe 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 ownRun every 5 minutes
FAILED notificationsOnly on demandNever produced
On-demand triggersAvailableDo not exist (404)
DatabasePauses after a period without use (the first call after it can be slow)Does not pause
Webhook source IPNot fixedA small set of fixed addresses, given once provisioned
Notification modeMock 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 ​

RoleNameChannel
Soterex technical contact for integration testingSean RahimiPer 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 ​

  1. 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.
  2. 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.
  3. The templates of the next-day payment report and of the account statement (section 6), with the Notifications specification.
  4. The validity of the MTCN: confirmation that 60 days in Guatemala is what you expect (1.9).
  5. 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 in entityResponse.transaction_id, as Operation 2's table defines that field (1.8). Your parser must not rely on the RS- inside entityResponse: it correlates on the transaction_id of the request you sent and on the notifications.
  6. Written confirmation of the contract points of sections 1.2 to 1.7: statuses, errors, idempotency, Cancel edge cases, signature scheme and types.
  7. 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.

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

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

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

codeWhenmessage
The one Soterex sentA Cancel that carried a sub_statusThe one Soterex sent (a missing half is filled in from CXL_SENDER)
CXL_SENDERA Cancel from Soterex without a sub_statusCancelled at sender request
CXL_CISA cancellation by CIS operationsBy reason: Cancelled at sender request, Beneficiary data needs correction, Amount needs correction, or Cancelled by CIS operations for any other reason
CXL_EXPIREDThe MTCN expiredMTCN expired without being collected
CXL_SANDBOXAn on-demand CANCELLED without a sub_statusSandbox on-demand notification
FLD_SANDBOXAn on-demand FAILED without a sub_statusSandbox-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.

ItemValue
Secret (UTF-8 text)test-secret-not-real
X-CIS-Timestamp1790000000
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 string1790000000. followed by the body
Expected X-CIS-Signatured553c5c443c71000a8c99a3fe94aa62eb7e61bc1deffe32b6dd4d3181a79ede5

Reproduce it:

bash
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}'
# d553c5c443c71000a8c99a3fe94aa62eb7e61bc1deffe32b6dd4d3181a79ede5
python
import 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())
php
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.

RetiredReplaced by
COD_001 ("RECORD INSERTED SUCCESSFULLY") as the create success, and COD_002 ("RECORD UPDATED SUCCESFULLY") as the cancel successCOD_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 numbersText with two decimals
The flat notification body, HTTP Basic on the webhook, and zoom_officeThe nested notificationData body, the HMAC signature, and paying_office

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