Source: IntegradoresGrandesCuentasQRv27.pdf (Prisma, v0.27, 2025-10-07). Digest generated 2026-10-01. Page numbers are PDF pages.
Prisma "QR - Sistemas Propios / Grandes Cuentas" v0.27 (Oct 2025) — Technical Digest¶
Source: IntegradoresGrandesCuentasQRv27.pdf (98 pages). I read the full text and rendered the 9 diagram pages (6, 7, 19, 22, 34, 50, 56, 61, 67) to read the sequence diagrams. Page numbers below are PDF pages (a few are approximate where a table spans pages). The doc is titled "Homologacion para Integradores - Flujo de GC".
0. Key takeaways¶
- Nomenclature. Prisma's/Payway's QR switch is called "Gateway QR (Decidir)" (p.5, 7). The integrator is called "Sistema Propio" / "Integrador Gran Cuenta". WE are the Sistema Propio.
- Direction matters. The document mixes integrator→Gateway QR calls (we are the client) with Gateway QR→integrator calls. We must expose HTTP endpoints for Prisma to call:
- bins forward
- purchase notification
- forced annulment notification
- forced refund notification
- Allowed operations (p.5): Compra (purchase), Anulación forzada, Devolución total forzada. Out of scope (p.5): partial refund, and annulment of a refund (non-forced).
- Auth is only a static
apikeyheader in both directions, over TLS. There is no HMAC, mTLS, signature, OAuth or IP allowlist in the spec. - The doc gives no base URLs, no sandbox/prod environments, no retry policy, no notification timeout, and no merchant/branch/checkout onboarding API. These are major gaps (section 10).
1. Actors and responsibilities¶
| Actor | Role in this spec |
|---|---|
| Prisma / Payway / Decidir "Gateway QR" | Hosts QR/intention registry, talks to wallets, authorizes with card brands (ISO8583, batch-close mentions) and Transferencia 3.0 (Coelsa/DEBIN-like). Provides the API we call and calls our callbacks. |
| Sistema Propio / Integrador Gran Cuenta (WE) | Owns the merchant POS relationship. Creates "intentions" per checkout, receives bins, calculates promos/benefits, answers with the "complete intention" (payment methods + installments + discounts) within 27 s, receives payment notification, can request forced annulment/refund. |
| Billetera (wallet) | Scans the QR, queries the intention, adds bins/cards, receives the complete intention, executes the purchase. Wallet↔Gateway steps (3, 4, 8, 9) are not our API; they are shown only for context. Wallets are identified by wallet / wallet_code (annex p.91-96). |
| Comercio | Identified by cuit + branch (sucursal) + checkout (caja), both strings chosen by the merchant. QR is tied to (cuit, branch, checkout). |
| Adquirente / marcas | Return authorization code, reference number, TID, response codes (annex). Terminal number "to send to the brand" is an 8-char id. |
| POS/caja | Not an API actor in this spec. The POS↔integrator contract is ours to define. |
What we must implement (integrator side):
- HTTP client to Gateway QR:
- POST /largeaccounts/intentions
- PUT /largeaccounts/intentions/complete
- DELETE /intentions/{id}
- GET /payments/qr, /annulments, /refunds
- POST /forcedannulments, POST /forcedrefunds
- HTTP server exposing 4 callbacks (paths are ours, {integrator_path}):
- PUT /{integrator_path}/intentions/{intention_id} (bins)
- purchase notification (path unspecified)
- POST /{integrator_path}/annulment
- POST /{integrator_path}/refund
- Business logic: promo/benefit calculation between bins arrival and complete-intention (27 s budget).
- Prisma provides: QR registration (alta), apikeys, wallet integration, authorization.
2. Authentication and transport (p.97)¶
- Header
apikey(case varies:apikey/Apikey) +Content-Type: application/json. - Two distinct keys:
- Integrator→Gateway: "apikey del sistema propio provista por Prisma".
- Gateway→Integrator: "apikey del Gateway QR provista por el integrador" (we generate it and give it to Prisma).
- Prisma describes its keys as public (read-only, non-sensitive, embeddable in mobile apps) vs private (backend only). Each key is bound to one site/merchant (Decidir2). All sensitive operations use private keys. Our integrator key is expected to be private.
- TLS only, HSTS on, certificate by DigiCert. The client must validate and abort on any warning.
- The doc says nothing on certificate pinning, mTLS, IP allowlisting, payload signing or replay protection.
Common auth errors (all HTTP 403, not 401):
- {"message":"Invalid authentication credentials"} (bad key)
- {"message":"You cannot consume this service"} (key valid but without permission; shown on the status query, p.40)
Common validation errors (HTTP 400):
{"error_type":"invalid_request_error","validation_errors":[{"code":"param_required|invalid_param","param":"<field>"}]}
{"error_type":"not_found_error","entity_name":"","id":""}
3. Endpoint catalog¶
3.1 Create intention — we → Gateway (pp.7-17)¶
POST /largeaccounts/intentions. Headers: apikey, Content-Type.
| Field | Type / length | Req | Notes |
|---|---|---|---|
integrator_intention_id |
alnum with specials, ≤50 | NO | Our own id, echoed back |
cuit |
alnum with specials, ≤15 | YES | e.g. "20-31455999-9" (dashes allowed) |
branch |
alnum, no specials, ≤25 | YES | Sucursal id from the merchant |
checkout |
alnum, no specials, ≤25 | YES | Caja id, unique per branch |
cbu (also called cbu/cvu) |
numeric ≤22 | YES only if merchant operates Transferencia 3.0 | Must equal the CBU loaded at QR alta; mandatory for homologation |
mcc |
numeric, 4 digits | YES (v0.20) | Must be a valid MCC; list is in an external attachment, not in this PDF |
intention_type |
alnum ≤10 | YES | payment / annulment / refund. Only payment is meaningful (see gaps) |
currency |
3, ARS|USD |
YES | v0.22 |
original_amount |
numeric 10.2 | YES | Made optional in v0.4, now "Si" (required). Contradictory, see gaps |
bins_max_quantity |
numeric, fixed 99 | YES | Max bins the integrator accepts |
cashback_max_amount |
numeric 10.2 | NO | Cash withdrawal ceiling; only with Visa Débito |
absolute_cashback |
boolean, default false | NO | true: withdrawn amount must equal cashback_max_amount; false: must be ≤ it |
payment_methods_data[] |
array | NO | Accepted payment methods. Method 112 (Transferencia 3.0) only if the merchant operates it |
.payment_method_id |
numeric ≤3 | NO | See payment-methods annex |
.bank_ids[] |
array of numbers | NO | Issuer bank ids, BCRA codes |
.establishment_id |
string | (example) | In example only |
.trace_number |
numeric | (example) | In example only; ≤10 per other tables |
.ticket_number |
numeric | (example) | In example only; ≤6 per other tables |
.installments[] |
array | (example) | Fields as in 3.4 |
benefits_methods_data[] |
array | NO | Accepted benefit cards |
.benefits_card.code |
alnum | YES if benefits sent | See benefit-cards table (not included in PDF) |
.benefits_card.description |
alnum | YES if code sent |
Additional notes in the doc:
- qr_raw: "not required; developed in case an integrator wants the QR string" (v0.11).
- Postal code (p.15): "required by BCRA, CIMPRA 530". No field name, type or example is defined.
- USD intentions (p.8): only payment methods 31 (Visa Débito), 105 (MasterCard Débito), 106 (Maestro Prisma Débito), 108 (Cabal Débito Prisma) apply. Any other method in payment_methods_data is silently omitted for USD.
- "Bimonetario" (p.97): the intention and the payment are in USD, "por ningún motivo se cruzarán las monedas". Debit cards only for now.
- Cashback is only allowed with Visa Débito.
Response 201 Created: echo of request plus:
- intention_id (numeric ≤12, generated by Gateway)
- payment_methods_data: []
- qr_raw (EMVCo-style string, e.g. contains com.prisma, com.grc, "PRISMA MEDIOS DE PAGO SA", MCC, CRC)
Errors:
- 400 param_required
- 400 invalid_param
- 403 auth
Semantics (p.7, repeated): Gateway always answers a wallet query with the last intention created for that checkout. Creating a new intention automatically invalidates the previous one; no explicit cleanup is needed.
3.2 Cancel intention — we → Gateway (pp.31-33; v0.8)¶
DELETE /intentions/{intention_id}. Header apikey (note: no /largeaccounts prefix, as written). No body.
- 204 No Content
- 404 not_found_error ("Intención no creada")
- 400 param_required / invalid_param
- 403 auth
No state restrictions are documented (e.g. what happens if the wallet already paid).
3.3 Forward bins — Gateway → us (CALLBACK, pp.19-22)¶
PUT /{integrator_path}/intentions/{intention_id}. Header apikey = key provided by the integrator.
(v0.6 changed the URL. {integrator_path} is agreed with Prisma.)
Body:
{"wallet":"<code>",
"payment_methods_data":[{"payment_method_id":1,"bank_id":22,"bin":454678}, ...],
"benefits_methods_data":[{"benefits_card":{"code":"..","description":"..","card_number":".."}}]}
| Field | Type | Req | Notes |
|---|---|---|---|
wallet |
alnum | YES | Wallet code (annex). The JSON example omits it, so the table and example conflict |
payment_methods_data[] |
array | YES | |
.payment_method_id |
numeric ≤3 | YES | |
.bank_id |
number | YES, except Transf 3.0 | |
.bin |
numeric, 6 or 8 digits | YES, except Transf 3.0 | |
benefits_methods_data[] |
array | NO | |
.benefits_card.code |
alnum | YES if card_number sent |
|
.benefits_card.description |
alnum | NO | |
.benefits_card.card_number |
alnum | YES if benefits sent | The full benefit card number |
Our response: 204 No Content. No error responses are documented for this callback.
After this we calculate promos and call "complete intention" (3.4).
3.4 Send complete intention — we → Gateway (pp.22-30)¶
PUT /largeaccounts/intentions/complete?cuit={}&branch={}&checkout={}.
- Must be sent within 27 seconds after receiving the bins notification (CIMPRA/BCRA alignment, v0.26, p.22).
- The query parameters identify the intention (no intention_id in the URL; "last intention for the checkout" semantics).
Query params: cuit (≤15, required), branch (≤25, required), checkout (≤25, required).
Body: payment_methods_data[], one entry per payment method/bin the wallet can use:
| Field | Type / length | Req | Notes |
|---|---|---|---|
bin |
numeric, 6 or 8 | YES (cards) | Absent for 112 |
payment_method_id |
numeric ≤3 | YES | |
bank_id |
numeric ≤5 | YES (cards) | |
establishment_id |
alnum ≤67 (also stated as numeric ≤3 in another table) | YES | Acquirer establishment for that method |
terminal_number |
alnum, exactly 8, no specials | YES | v0.27: now required in the example; in the table it appears as a top-level row, in the example inside each payment method. Placement is ambiguous |
trace_number |
numeric ≤10 | YES | Per payment method |
ticket_number |
numeric ≤6 | YES | Per payment method |
benefits_cards_accepted[] / .code |
NO | Omitted means the method does not accept benefit cards | |
installments[] |
array | YES | 1-installment scheme must always be present |
.quantity |
numeric 2 | YES | |
.total_amount |
numeric 10.2 | YES | |
.amount_per_installment |
numeric 10.2 | YES | |
.cft |
numeric | YES | Total financial cost |
.tna |
numeric (3.2 per table) | YES | Annual nominal rate |
benefits_methods_data[] |
array | NO | Applied benefits |
.establishment_id |
alnum ≤67 | YES if object sent | Establishment for the benefit |
.benefits_card.code/.description |
alnum | YES if object sent | |
.benefits_card.card_number |
alnum | NO | |
.discount.percentage |
numeric 3.2 | YES if object sent | |
.discount.maximum_discount_amount |
numeric 3.2 | NO |
IMPORTANT (p.24): payment method 112 (Transferencia 3.0) must always be included in the complete intention, even if bins were sent, because the wallet user may finally choose transfer.
The example shows a mix of Visa credit (1), 112, and MC (104) with installments 1 and 6.
"Cuotas MiPyME" (annex p.87): plan 13 = 3 installments, plan 16 = 6 installments. The annex says "hacer la tabla bien" (unfinished) and states that terminal option = installment in the intention.
Response: 204 No Content.
Errors:
- 400 param_required
- 400 invalid_param
- 404 "intention not found or in a state other than created"
- 403 auth
3.5 Query operation status — we → Gateway (pp.34-47)¶
Used when the notification does not arrive within the time "stipulated by the integrator".
- GET /payments/qr?intention_id={} (purchase)
- GET /annulments?intention_id={} (annulment; the PDF text shows /annulments)
- GET /refunds?intention_id={} (refund)
Header apikey. intention_id numeric ≤12, required.
Response 200 OK (same schema as the purchase notification, 3.6, without transaction_type):
| Field | Type | Notes |
|---|---|---|
id |
string/numeric ≤7 | Transaction id generated by Decidir |
intention_id |
numeric ≤12 | |
cuit, branch, checkout |
Echo | |
establishment_id |
||
transaction_datetime |
YYYY-MM-DDTHH:MM:SS (19), no timezone |
|
payment_method_id |
num | |
payment_method_code |
alnum ≤2 | e.g. "VI" |
payment_method_type |
credit_card / debit_card (annex also lists prepaid) |
|
cashback_amount |
num | Actual withdrawal (in annulment notification: annulled withdrawal) |
card_data.card_brand |
text | |
card_data.bin |
6 or 8 digits | |
card_data.last_four_digits |
||
card_data.bank_data.id / .description |
BCRA bank id and name | |
amount |
num 10.2 | |
currency |
ARS/USD | |
installments |
num 2 | |
status |
enum | Purchase: approved, rejected, annulled, refunded. Annulment: approved, rejected. Refund: approved, rejected, annulled |
status_details.card_authorization_code |
Only if approved | |
status_details.card_reference_number |
||
status_details.response.type |
See response-code annex | |
status_details.response.reason.id / .description / .ticket_footer |
ticket_footer is a message to print on the receipt (e.g. "COMPRA QR") |
|
wallet_code |
e.g. "bsf" | Wallet used |
tid |
Brand transaction id; only approved payments/refunds and only for payment methods 1, 31, 104, 105, 106, 111, 114, 116 (v0.23; 63 was added in v0.25 but the TID list was not updated) | |
terminal_data.trace_number / .ticket_number / .terminal_number |
||
benefits_data |
object | Only if a benefit card was involved |
benefits_data.benefits_card[] (code, description) |
||
benefits_data.original_amount, .discounted_amount |
Errors:
- 404 (operation not found, or belongs to another integrator)
- 400 invalid_param
- 400 param_required
- 403 "You cannot consume this service"
- 403 "Invalid authentication credentials"
3.6 Purchase notification — Gateway → us (CALLBACK, pp.47-49)¶
POST to "the URL that the Sistema Propio indicates" (the URL is registered with Prisma out of band; path and headers are not specified). The body is the same as 3.5 plus transaction_type: "payment" (not in the field table).
Response expected from us: not documented (assume 2xx). Version history: v0.16/0.17 added the notification to the flows, v0.18 added wallet_code.
3.7 Forced annulment request — we → Gateway (pp.50-55)¶
POST /forcedannulments. Header apikey.
Body:
{"intention_id":"123456","cuit":"..","terminal_number":"87980012",
"payment_methods_data":[{"payment_method_id":31,"establishment_id":"29880765","trace_number":1090,"ticket_number":131}]}
| Field | Req | Format |
|---|---|---|
intention_id |
YES | numeric ≤10 (≤12 elsewhere) |
cuit |
YES | ≤15 |
terminal_number |
YES | numeric, 8 |
payment_methods_data[] |
YES | array |
.payment_method_id |
YES | num ≤3 |
.establishment_id |
YES | alnum ≤67 |
.trace_number |
YES | num ≤10 |
.ticket_number |
YES | num ≤6 |
Response 201 Created: echo with "status":"annuled" (typo in the sample) / documented value annulment_in_progress. In the response payment_methods_data is an object, not an array.
Errors: 400 param_required, 400 invalid_param ("invalid format / does not exist"), 403 auth.
Forced annulment semantics (v0.14): internally annuls original_amount + cashback; the contract does not carry the cashback amount.
3.8 Forced annulment notification — Gateway → us (CALLBACK, pp.56-60)¶
POST /{integrator_path}/annulment. Header apikey = key provided by the integrator.
Body fields: id, intention_id, cuit, establishment_id, transaction_datetime, payment_method_id/_code/_type, cashback_amount (annulled withdrawal), card_data{...}, amount, currency, installments, status (approved/rejected), status_details{...}, wallet_code, terminal_data{trace_number,ticket_number,terminal_number}. It has no tid in the annulment sample; no branch/checkout.
Our response: 202 Accepted, no body.
3.9 Forced refund request — we → Gateway (pp.61-66; "NUEVO")¶
POST /forcedrefunds. The body and field table are identical to 3.7. Response 201 Created with status: "refund_in_progress". Same errors as 3.7.
Total refund only. For a payment with cashback, only original_amount is refunded, not the cashback (v0.14).
3.10 Forced refund notification — Gateway → us (CALLBACK, pp.67-72)¶
POST /{integrator_path}/refund. The body is like 3.8 but with tid (only approved refunds for methods 1, 31, 104, 105, 106, 111, 114, 116) and without cashback_amount. Our response: 202 Accepted.
3.11 Deprecated flows (v0.15, May 2024)¶
The non-forced total refund, annulment, and annulment-of-refund flows were deprecated "to make the QR interoperable per Banco Central regulation". Only forced annulment and forced refund remain.
4. Payment lifecycle¶
4.1 QR model¶
- The doc has no explicit static vs dynamic QR taxonomy. The model is: one QR per (cuit, branch, checkout), registered in advance ("alta del QR"; mass-upload doc and Excel referenced in v0.19, not included in the PDF). The QR payload (
qr_raw) is EMVCo withcom.prisma/com.grcmerchant info. - Each payment is a dynamic intention pre-loaded by the integrator for that checkout. The wallet scans the (static/fixed) QR, resolves (cuit, branch, checkout) and gets the latest intention (p.7).
- Therefore, only one live intention per checkout; a new
POSTsupersedes the previous one.
4.2 Intention/payment states (derived; the doc does not give an intention state diagram)¶
Explicit states in the doc:
- Intention: created (the only one named; complete-intention returns 404 if not created).
- Payment status: approved, rejected, annulled, refunded.
- Annulment result: approved, rejected. Refund result: approved, rejected, annulled.
- Forced request ack status: annulment_in_progress, refund_in_progress.
- Response type values include approved, no_response, request_authorization_card, insufficient_amount, invalid_number, expired_card, security_code_error, invalid_card (the other type values for the later codes are unclear).
stateDiagram-v2
[*] --> created: POST /largeaccounts/intentions (201)
created --> superseded: new intention for same checkout
created --> cancelled: DELETE /intentions/{id} (204)
created --> bins_received: Gateway PUT bins to integrator (wallet scanned + added bins)
bins_received --> complete_sent: PUT /intentions/complete (204, within 27s)
bins_received --> expired_no_complete: >27s without complete (inferred, undocumented)
complete_sent --> approved: wallet POST purchase OK, push notification
complete_sent --> rejected: wallet purchase declined, push notification
complete_sent --> timeout_unpaid: wallet never pays (timeout, no explicit state)
approved --> annulment_in_progress: POST /forcedannulments (201)
annulment_in_progress --> annulled: notification status approved
annulment_in_progress --> approved: notification status rejected (inferred)
approved --> refund_in_progress: POST /forcedrefunds (201)
refund_in_progress --> refunded: notification status approved
refund_in_progress --> approved: notification status rejected (inferred)
superseded --> [*]
cancelled --> [*]
rejected --> [*]
annulled --> [*]
refunded --> [*]
The superseded, bins_received, expired_no_complete, timeout_unpaid and "revert on rejected" nodes are inferred, not named in the spec.
4.3 Timing, polling, idempotency¶
- 27-second hard budget from the bins notification (our callback invoked) to our complete-intention (p.22, v0.26). The doc never says what Gateway does on a miss.
- Notification (push) is primary; GET status is the fallback if the push does not arrive "within the time stipulated by the integrator" (we define the timeout). No polling interval, backoff or max attempts are given.
- Idempotency: none documented.
integrator_intention_idis optional and only echoed. No idempotency key header. Duplicate forced annulment/refund behavior is only hinted at by error codes (LI_REFUND_IN_PROGRESS,LI_OPERATION_ALREADY_PROCESSED,LI_OPERATION_DUPLICATED,NRO.SEC.DUPLICAD= 94). - Refunds: total only (partial is out of scope but the error table has
LI_INVALID_OPERATION"partial refunds are not allowed" andAD01/AD02"Refund limit exceeded" / "Unexpected Currency",AD03"Deadline for refund surpassed",AD04"Not admitted Type"). No refund deadline value is stated. - Forced annulment and refund identify the transaction with the original (intention_id, payment_method_id, establishment_id, trace_number, ticket_number), plus
cuitandterminal_number. We must therefore persist those values from the approved notification (or complete-intention) for every payment. - Closing / settlement: only the "Cierre de lotes" section exists (p.97-98). ISO8583 field 59 must carry product type "083" with a sub-field "208" = "Q" (QR operation indicator), for all batch closes whether or not they contain QR transactions. The text is truncated at the end of the doc. This applies to whoever sends ISO closes. Reconciliation is not otherwise described.
5. Benefits / discounts structure¶
There are several inconsistent naming variants for the same concept (a naming problem for our DTOs):
- Create intention:
benefits_methods_data[].benefits_card{code, description}; the field table writesbenefits_data.benefits_card.description/benefits_methods_data.benefits_card.code. - Forward bins (Gateway→us):
benefits_methods_data[].benefits_card{code, description, card_number}.card_numberis required if benefits are sent and is the wallet user's benefit card number. - Complete intention (us→Gateway):
payment_methods_data[].benefits_cards_accepted[].code(which benefit cards each payment method accepts)- plus a separate
benefits_methods_data[]carryingestablishment_id,benefits_card{code,description,card_number?}, anddiscount{percentage, maximum_discount_amount?}. - Status/notification:
benefits_data{benefits_card[{code,description}], original_amount, discounted_amount}, only when a benefit card took part (e.g. codeCL= "Clarin 365").
The benefit-cards code table is referenced ("Ver tabla Tarjetas de beneficios") but is not in the PDF. Installments ("cuotas") are per payment method as above. "Cuotas MiPyME" (v0.24 replaced "Cuota Simple") is a government plan mapped via terminal plan codes 13 (3 installments) and 16 (6 installments).
6. Merchant / store / POS entities¶
- Identity triple:
cuit(merchant),branch(sucursal, unique per merchant, ≤25),checkout(caja, unique per branch, ≤25). All are merchant-provided strings. terminal_number(8 chars) is "the terminal number to send to the brand" and also "terminal where the QR was generated"; it was removed from create-intention in v0.6 and is now sent in complete-intention and forced annulment/refund.establishment_idis the brand/acquirer establishment, one per payment method.cbu/cvu: must match the QR alta; required for Transferencia 3.0 (holder validation against merchant CUIT).- There are no alta/baja APIs in this doc. QR registration is out of band: mass upload document + Excel + valid MCC list (v0.19), referenced but not included.
7. Sequence diagrams¶
7.1 Happy path (reconstructed from p.6 diagram; steps numbered as in the doc)¶
sequenceDiagram
autonumber
participant POS as POS/Caja
participant INT as Integrator (WE / Sistema Propio)
participant GW as Gateway QR (Prisma/Decidir)
participant W as Billetera (wallet)
POS->>INT: new sale (amount, branch, checkout) [our contract]
INT->>GW: (1) POST /largeaccounts/intentions
GW-->>INT: 201 {intention_id, qr_raw}
Note over POS,W: QR for (cuit, branch, checkout) is shown/printed
W->>W: (2) scans QR
W->>GW: (3) GET consultar intención (last intention of checkout)
GW-->>W: intention data
W->>GW: (4) PUT agregar bines a la intención
GW-->>W: ok
GW->>INT: (5) PUT /{integrator_path}/intentions/{intention_id} (bins, wallet)
INT-->>GW: 204
INT->>INT: calculate promos / installments (27 s budget)
INT->>GW: (7) PUT /largeaccounts/intentions/complete?cuit&branch&checkout
GW-->>INT: 204
GW->>W: (8) PUT intención completa con bines
W-->>GW: ok
W->>GW: (9) POST efectuar compra
GW-->>W: status (approved/rejected)
GW->>INT: [push] POST notification (payment, status approved)
opt notification late/missing
INT->>GW: (10) GET /payments/qr?intention_id=
GW-->>INT: 200 {status, status_details, tid, ...}
end
INT-->>POS: result + ticket_footer
Step (6) is not labelled in the diagram; the "calcula promos" self-call sits there.
7.2 Forced annulment / refund (pp.50, 56, 61, 67)¶
sequenceDiagram
participant POS as POS/Caja
participant INT as Integrator (WE)
participant GW as Gateway QR
participant W as Billetera
POS->>INT: void / return request
INT->>GW: (1) POST /forcedannulments (or /forcedrefunds)
GW-->>INT: 201 {status: annulment_in_progress | refund_in_progress}
GW->>W: (2) GET solicitar pedido de datos
W-->>GW: status
GW->>W: (3) PUSH notificación de anulación/devolución
alt push delivered
GW->>INT: (5) POST /{integrator_path}/annulment (or /refund)
INT-->>GW: 202 Accepted
else notification delayed beyond our timeout
INT->>GW: (4) GET /annulments?intention_id= (or /refunds)
GW-->>INT: 200 {status approved|rejected}
end
INT-->>POS: result
In the diagrams the order is (4) GET before (5) PUSH, but the text says (4) is the fallback if (5) is delayed.
8. Changelog highlights (p.1-5)¶
v0.27 (07-Oct-2025): the only change is that the complete-intention example was corrected because terminal_number is required.
Recent history:
- v0.26 (12-Aug-25): timing (27 s) for the complete intention.
- v0.25: payment method 63 (Cabal).
- v0.24: Transferencia in the complete intention; Cuota Simple → Cuotas MiPyME.
- v0.23: TID for approved payments/refunds (methods 1, 31, 104, 105, 106, 111, 114, 116).
- v0.22: USD intentions; 6 or 8-digit bins; PCT wallets.
- v0.21: bins_max_quantity = 99.
- v0.20: mcc field.
- v0.19: transfer error codes, Cuota Simple, mass-alta doc, valid MCC list, CBU must match the QR alta.
- v0.18: wallet_code in notifications.
- v0.16/0.17: notification added to flows.
- v0.15: refund/annulment (non-forced) deprecated.
- v0.14: cashback (Visa Débito only).
- v0.11: qr_raw.
- v0.8: cancel intention.
- v0.6: payment_methods_data rename, wallet field, terminal_number removed from create.
- v0.4: original_amount optional.
- v0.1-0.3: initial release (12-Apr-2021).
9. Non-functional requirements (what the doc actually says)¶
- SLA/timeouts: only the 27 s rule (and the integrator-defined notification timeout). No latency SLA, rate limits, availability or retries for either side.
- Environments: none stated (no sandbox/prod URLs). The doc is titled "Homologación", but no certification process, test cases or checklist is described. The only homologation hint is that the CBU is "necessary for homologation".
- Security: apikey + TLS (section 2). No PCI statement. The payloads carry BIN (6/8), last four digits, bank, auth code and brand TID, which is not PAN. Benefit
card_numberis a loyalty card number (sensitive PII). Our logs should avoid dumping apikeys and card data. - Status of document: "development of this functionality is currently in progress in Decidir; services are subject to modification" (p.5).
- Transfer error codes (annex pp.75-85): large table of rejection codes for Transferencia 3.0 / Coelsa / HolderValidation / refund, with description and the operation stage (e.g.
BA58insufficient funds,BA63daily limit,LI_TRANSACTION_TIMEOUT,LI_REFUND_IN_PROGRESS,QRNOTFOUND,AMOUNT_ERR,TIMEOUT,CVU_INEXISTENTE,INVALID_MCC, ...). It is the vocabulary forstatus_details.response.reasonon transfer payments. - Card response codes (annex pp.72-74):
- approved: 00 "APROBADA (authno)", 11, 85
- no_response: -1
- request_authorization_card: 01, 02, 07 (retenga y llame), 76 (llamar al emisor)
- insufficient_amount: 13, 51, 61, 65
- invalid_number: 14, 53, 56
- expired_card: 46, 49, 54
- security_code_error: 47, 55
- invalid_card: 03, 04, 05, 12
- the rest (25, 30, 38, 43, 45, 48, 50, 57, 58, 77, 89, 91, 94, 95, 96, XX "RECHAZADA (codnum)") appear without a clear
typemapping in the rendered table. - Reference tables: payment methods (p.86: 1 VI, 24 NA, 44 CE, 65 AM, 104 MC, 31 EL, 105 PD, 106 MA, 108 C2, 112 T 3.0, 111 AM Payway, 139 Discover, 114 Visa Prepago, 116 MC Prepago, 63 CA), banks (BCRA ids), wallets (acquiring wallets: modo, Cencosud, BSF, Cuenta DNI, Pampa, mepa; plus a large PCT wallet list by CUIT).
10. Ambiguities, contradictions and gaps to raise with Prisma¶
- Base URLs and environments: no sandbox/prod hosts, no onboarding of our own callback base URL/path/apikey.
- Purchase notification endpoint is undefined: path, auth header, expected response code, retry/backoff, ordering, duplicates, signature. Forced annulment/refund callbacks say
/{integrator_path}/annulmentand/refund, but the bins callback uses/{integrator_path}/intentions/{id}and the purchase notification has no path at all. Is the purchase notification on{integrator_path}/payment? - Notification timeout is "stipulated by the integrator": is there a minimum, or any Prisma-side retry? Is a non-2xx from us retried?
- What happens after the 27 s (intention expiry, error to wallet)? Does the 27 s apply per intention or per wallet attempt? What clock starts it? What does Gateway return to us if we are late (error code on complete)?
- Intention lifecycle: TTL/expiry of a
createdintention, behavior of the wallet after the intention is superseded, whatDELETEdoes after the wallet already paid or when bins were already received, intention state names beyondcreated, and a state-transition table. - Static vs dynamic QR: not described. Is the QR per checkout and permanent? How is the (cuit, branch, checkout) triple bound to the QR at alta and how do we update/remove it? Is there any API for alta/baja/consulta of QR/branch/checkout, or only the mass-upload Excel (not attached)?
- Idempotency: no idempotency key; behavior on retrying
POST /intentions,POST /forcedannulmentsand/forcedrefunds, andPUT complete. How are duplicates detected (integrator_intention_iduniqueness?) original_amountwas made optional in v0.4 but the table says "SI". Which is right? Alsopayment_methods_datais "NO" in creation but the example sends it withestablishment_id,trace_number,ticket_number,installmentsthat the table does not define for that request.intention_typelistspayment/annulment/refund, but only payment is supported. Is any other value accepted?terminal_number: removed from create (v0.6), required in complete (v0.27). The table shows it top-level, the example per payment method; forced annulment/refund take it top-level. Is it per method or one per request? Also theterminal_numberin the status response is "terminal in which the QR was generated".- Postal code (CIMPRA 530) is stated as required, but no field exists in the request. What is the field name and format?
walletis a required request field for bins in the table but absent in the JSON example. Also:wallet(bins) vswallet_code(notifications); the notification annex says "wallet code associated with the wallet's apikey".- Inconsistent benefit schemas (section 5).
benefits_datavsbenefits_methods_datavsbenefits_cards_acceptednaming, and whethercard_numberis required. - Typos / contract bugs in samples:
"status":"annuled"in the forced annulment response; trailing comma in the forced annulment request JSON;payment_methods_datais an array in the request but an object in the response; the intention/annulmentspath vs the/forcedannulmentspath (two names for the same domain);intention_idis a number in201but a string in several examples;branch/checkoutsample lengths vs a table that later says ≤67; some length columns clearly shifted by extraction. - Purchase notification includes
transaction_typethat is not documented; the annulment/refund notifications lackbranch/checkoutand (annulment)tid;tidrules list 8 methods but the doc added method 63 (Cabal) in v0.25. Does 63 return a TID? - Status enumerations: purchase
statusincludesannulled/refunded, but how do we correlate when the sameintention_idhas several operations (payment, annulment, refund)? The sameintention_idis used for GET /payments/qr, /annulments and /refunds. - Refund
annulledstatus ("annulment of refund") is shown as a refund status although annulment of a refund is out of scope (p.5) and deprecated (v0.15). - Partial refunds are out of scope, but the annex contains
LI_INVALID_OPERATION("partial refunds not allowed") and refund-limit codes. What is the refund window (AD03)? Is cashback ever refunded? - Cashback: Visa Débito only; how is the actual withdrawn amount communicated before the payment, and how do the forced annulment/refund requests treat it (no field in contract)? Is the
amountin notifications inclusive or exclusive of cashback? Isoriginal_amountthe sale amount only? - USD flow: only 4 debit methods; the payment-methods table for USD is garbled (brand column). Confirm method ids and that 112 is not allowed for USD.
- Response-code annex: the
type↔ code mapping is garbled (codes 25-96 have notype; the row for 38 contains pasted web-page text, "Willkommen bei Deutschlands beliebtester Bank – ING"). Ask for a clean table. Also the transfer-code table mixes English/Spanish and some codes appear twice (e.g.QRNOTFOUND,TIMEOUT,PAYER_INVALID_ACCOUNT). - Missing reference tables/attachments: benefit-cards codes, valid MCC list, QR mass-alta Excel/doc, wallets table content is partial/garbled, "Cuotas MiPyME" table unfinished ("Hacer la tabla bien").
- Auth hardening: nothing on key rotation, per-environment keys, IP allowlists, replay protection or signatures for callbacks. Our callbacks will be publicly reachable with a static key. Ask whether source IPs of Gateway can be allowlisted. Also HTTP 403 (not 401) for auth failure, including "valid key without permission".
- HTTP semantics:
PUT .../completeidentifies the target by query params, not byintention_id, so concurrency on one checkout (two sales quickly) is ambiguous. Confirm last-intention-wins also applies at complete time.DELETE /intentions/{id}is documented without the/largeaccountsprefix, as if/intentions/{id}and/largeaccounts/intentionscoexist. - Homologation: no test cases, test merchants/CBUs, test wallet, or certification checklist are provided.
- Settlement/reconciliation and batch-close (ISO 59): the ISO field table is truncated, and it is unclear who sends the close (us or Prisma). No reconciliation/reporting API is documented.
- Document-status disclaimer (p.5): services "subject to modification"; v0.27 only fixed an example, so check whether a newer revision exists.
Files: source PDF C:\Work\AI\GatewayPrismaQR\IntegradoresGrandesCuentasQRv27.pdf; helper UTF-8 text at C:\Users\Usuario\AppData\Local\Temp\claude\C--Work-AI-GatewayPrismaQR\d8aa3482-16d7-4f27-a2cf-570eff157e70\scratchpad\prisma_utf8.txt (rendered diagram PNGs p6.png, p7.png, p19.png, p22.png, p34.png, p50.png, p56.png, p61.png, p67.png, p73.png, p74.png in the same dir). Nothing in C:\Work\AI was modified.