Saltar a contenido

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

  1. 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.
  2. 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:
  3. bins forward
  4. purchase notification
  5. forced annulment notification
  6. forced refund notification
  7. 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).
  8. Auth is only a static apikey header in both directions, over TLS. There is no HMAC, mTLS, signature, OAuth or IP allowlist in the spec.
  9. 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>"}]}
Not found (HTTP 404): {"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}]}
(The sample has a trailing comma inside the array: invalid JSON.)

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 with com.prisma / com.grc merchant 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 POST supersedes 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_id is 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" and AD01/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 cuit and terminal_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):

  1. Create intention: benefits_methods_data[].benefits_card{code, description}; the field table writes benefits_data.benefits_card.description / benefits_methods_data.benefits_card.code.
  2. Forward bins (Gateway→us): benefits_methods_data[].benefits_card{code, description, card_number}. card_number is required if benefits are sent and is the wallet user's benefit card number.
  3. Complete intention (us→Gateway):
  4. payment_methods_data[].benefits_cards_accepted[].code (which benefit cards each payment method accepts)
  5. plus a separate benefits_methods_data[] carrying establishment_id, benefits_card{code,description,card_number?}, and discount{percentage, maximum_discount_amount?}.
  6. Status/notification: benefits_data{benefits_card[{code,description}], original_amount, discounted_amount}, only when a benefit card took part (e.g. code CL = "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_id is 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_number is 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. BA58 insufficient funds, BA63 daily limit, LI_TRANSACTION_TIMEOUT, LI_REFUND_IN_PROGRESS, QRNOTFOUND, AMOUNT_ERR, TIMEOUT, CVU_INEXISTENTE, INVALID_MCC, ...). It is the vocabulary for status_details.response.reason on 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 type mapping 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

  1. Base URLs and environments: no sandbox/prod hosts, no onboarding of our own callback base URL/path/apikey.
  2. Purchase notification endpoint is undefined: path, auth header, expected response code, retry/backoff, ordering, duplicates, signature. Forced annulment/refund callbacks say /{integrator_path}/annulment and /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?
  3. Notification timeout is "stipulated by the integrator": is there a minimum, or any Prisma-side retry? Is a non-2xx from us retried?
  4. 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)?
  5. Intention lifecycle: TTL/expiry of a created intention, behavior of the wallet after the intention is superseded, what DELETE does after the wallet already paid or when bins were already received, intention state names beyond created, and a state-transition table.
  6. 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)?
  7. Idempotency: no idempotency key; behavior on retrying POST /intentions, POST /forcedannulments and /forcedrefunds, and PUT complete. How are duplicates detected (integrator_intention_id uniqueness?)
  8. original_amount was made optional in v0.4 but the table says "SI". Which is right? Also payment_methods_data is "NO" in creation but the example sends it with establishment_id, trace_number, ticket_number, installments that the table does not define for that request.
  9. intention_type lists payment/annulment/refund, but only payment is supported. Is any other value accepted?
  10. 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 the terminal_number in the status response is "terminal in which the QR was generated".
  11. Postal code (CIMPRA 530) is stated as required, but no field exists in the request. What is the field name and format?
  12. wallet is a required request field for bins in the table but absent in the JSON example. Also: wallet (bins) vs wallet_code (notifications); the notification annex says "wallet code associated with the wallet's apikey".
  13. Inconsistent benefit schemas (section 5). benefits_data vs benefits_methods_data vs benefits_cards_accepted naming, and whether card_number is required.
  14. Typos / contract bugs in samples: "status":"annuled" in the forced annulment response; trailing comma in the forced annulment request JSON; payment_methods_data is an array in the request but an object in the response; the intention /annulments path vs the /forcedannulments path (two names for the same domain); intention_id is a number in 201 but a string in several examples; branch/checkout sample lengths vs a table that later says ≤67; some length columns clearly shifted by extraction.
  15. Purchase notification includes transaction_type that is not documented; the annulment/refund notifications lack branch/checkout and (annulment) tid; tid rules list 8 methods but the doc added method 63 (Cabal) in v0.25. Does 63 return a TID?
  16. Status enumerations: purchase status includes annulled/refunded, but how do we correlate when the same intention_id has several operations (payment, annulment, refund)? The same intention_id is used for GET /payments/qr, /annulments and /refunds.
  17. Refund annulled status ("annulment of refund") is shown as a refund status although annulment of a refund is out of scope (p.5) and deprecated (v0.15).
  18. 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?
  19. 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 amount in notifications inclusive or exclusive of cashback? Is original_amount the sale amount only?
  20. 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.
  21. Response-code annex: the type ↔ code mapping is garbled (codes 25-96 have no type; 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).
  22. 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").
  23. 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".
  24. HTTP semantics: PUT .../complete identifies the target by query params, not by intention_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 /largeaccounts prefix, as if /intentions/{id} and /largeaccounts/intentions coexist.
  25. Homologation: no test cases, test merchants/CBUs, test wallet, or certification checklist are provided.
  26. 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.
  27. 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.