Skip to content

feat(braspag): Require 3DS on credit card purchases and show the result on the order - #855

Open
vitorrgg wants to merge 1 commit into
mainfrom
feat/braspag-3ds-obrigatorio
Open

vitorrgg wants to merge 1 commit into
mainfrom
feat/braspag-3ds-obrigatorio

Conversation

@vitorrgg

@vitorrgg vitorrgg commented Oct 5, 2026

Copy link
Copy Markdown
Member

Ports the Cielo 3DS (MPI V2) from the legacy app to the v3 Braspag/Cielo app, with a required 3DS policy for stores with high chargeback risk (Bom Ar Condicionado: "no card purchase without 3DS").

Behavior

3DS result required: false (default) required: true
Authenticated (ECI Visa/Elo/Amex 05/06, Master 02/01) ExternalAuthentication, capture same
Failed challenge, not enrolled, brand without 3DS, error, timeout, MPI script not loaded fraud analysis (as today) refused before calling Cielo, message suggests Pix or billet
3DS token unavailable card listed, no 3DS credit card not listed, Pix/billet keep working
  • braspag_3ds.timeout: 30–900 s (default 300 when required; legacy had 30 s fixed). The challenge may need the bank app or an SMS code.
  • braspag_3ds.fraud_analysis: optionally keep ClearSale on authenticated purchases (default unchanged).
  • Result (status, ECI, version, reference) on transaction custom_fields, shown on the order.
  • Only Cavv, Xid, Eci, Version, ReferenceId are forwarded from the browser hash.
  • Stores without braspag_3ds credentials: no change.

MPI V3

Cielo will retire MPI V2 (no date yet) and V3 isn't available for Silent Order Post. Rules live in lib-mjs/lib/braspag/3ds/policy.mjs; V3 keeps the same authorization data, so only the browser/token step changes.

Market schema

New fields required, timeout, fraud_analysis inside braspag_3ds (snippet in the app README).

Tests

  • Unit: node --test packages/apps/braspag/tests-unit/ (policy, ECI, timeout, transaction payload).
  • Browser: card script checked in Chromium against a stubbed MPI for authenticated, failed challenge, unsupported brand, MPI script error, timeout, missing token (required) and optional mode.
  • Not tested against Cielo sandbox yet: needs sandbox credentials (API, Silent Order Post and 3DS).

🤖 Generated with Claude Code

…lt on the order

Stores with high chargeback risk can now refuse any credit card purchase not
authenticated by the issuer (3DS), instead of falling back to fraud analysis.

- New `braspag_3ds.required`: anything other than authenticated (failed
  challenge, card not enrolled, brand without 3DS, script error or timeout)
  is refused before calling Cielo, with a message suggesting Pix or billet.
  If the 3DS token can't be generated, credit card is not listed and Pix and
  billet keep working
- Accepted ECI from Cielo table: Visa, Elo and Amex 05/06, Mastercard 02/01
- `braspag_3ds.timeout` (30 to 900 s, default 300 when required): the
  challenge may need the bank app or an SMS code; legacy app had 30 s fixed
- `braspag_3ds.fraud_analysis` keeps ClearSale on authenticated purchases
  (default unchanged: captured without it)
- 3DS result, ECI, version and reference on transaction custom fields

Ported from the legacy app (MPI V2 script, token and ExternalAuthentication).
3DS rules are isolated in `3ds/policy.mjs`: MPI V3 keeps the same
authorization data, so only the authentication step changes. Only the 3DS
fields Cielo expects are forwarded from the browser hash.

Without `braspag_3ds` credentials nothing changes for current stores.

Unit tests: `node --test tests-unit/`. Browser flow checked against a stubbed
MPI for authenticated, failed, unsupported brand, script error, timeout and
missing token.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant