guillotina-redsys 1.0.0

Redsys support for guillotina

Redsys (Sermepa) REST + 3-D Secure 2.x integration for the Guillotina framework.

This package provides:

• A Guillotina utility to orchestrate Redsys REST calls.

• Pydantic v1 models for merchant parameters, EMV3DS, final authorization, and errors.

• An async HTTP client (aiohttp + tenacity) with retries.

• Mandatory Redis usage to correlate and finish 3-DS flows (stores threeDSCompInd and CRES).

• Guillotina services (endpoints) to start transactions, run AuthenticationData, and handle ACS callbacks.

Requirements

• Python 3.9+

• Guillotina

• aiohttp, tenacity, pydantic==1.*

• Redis via guillotina.contrib.redis

• Redsys merchant credentials (FUC, Terminal, Secret Key)

Installation

pip install guillotina_redsys

Configuration

Enable the app and configure the utility in Guillotina settings. The Redis add-on must be enabled.

Example (pseudocode):

apps = ["guillotina.contrib.redis", "guillotina_redsys"]
app_settings = {
    "applications": apps,
    "load_utilities": {
        "redsys": {
            "provides": "guillotina_redsys.interfaces.IRedsysUtility",
            "factory": "guillotina_redsys.utility.RedsysUtility",
            "settings": {
                "merchant_code": os.environ["REDSYS_MERCHANT_CODE"],
                "terminal": os.environ.get("REDSYS_TERMINAL", "001"),
                "secret_key": os.environ["REDSYS_SECRET_KEY"],
                "url_redsys": os.environ.get(
                    "REDSYS_URL", "https://sis-t.redsys.es:25443/sis/rest"
                ),
                "container_url": os.environ["REDSYS_CONTAINER_URL"],
            },
        }
    },
}

Suggested environment variables:

export REDSYS_MERCHANT_CODE=999008881
export REDSYS_TERMINAL=001
export REDSYS_SECRET_KEY=...
export REDSYS_URL=https://sis-t.redsys.es:25443/sis/rest
export REDSYS_CONTAINER_URL=https://your.app/db/container

Exposed services (HTTP)

Resource-scoped:

• POST @initTransactionRedsys: calls iniciaPeticionREST; returns decoded payload and a prebuilt payload for 3DS Method.

• POST @initThreeDS: helper to initiate 3DS Method (mainly for testing; in production the browser posts the form).

• POST @initTrataPeticion: builds AuthenticationData; returns either (acsURL + creq) for challenge or a final frictionless result.

Container-scoped (callbacks and finalization):

• POST @notificationRedsys3DS/{order_id}/{three_dss_trans_id}: stores threeDSCompInd in Redis (TTL 15m).

• GET @getnotificationRedsys3DS/{order_id}/{three_dss_trans_id}: reads threeDSCompInd.

• POST @notificationRedsysChallenge/{order_id}/{three_dss_trans_id}: stores raw CRES in Redis (TTL 30m).

• POST @performNotificationRedsysChallenge/{order_id}/{three_dss_trans_id}: reads CRES and finalizes with ChallengeResponse; returns final authorization result.

Redis keys

• notification_3DS:{order}:{sid} → "Y" or "N" (TTL 15 minutes)

• notification_CRES:{order}:{sid} → base64url CRES (TTL 30 minutes)

Flow summary

1. Start: backend calls Redsys iniciaPeticionREST (CardData).

2. Optional 3DS Method: browser posts threeDSMethodData; backend receives method callback and records threeDSCompInd in Redis.

3. AuthenticationData: backend calls Redsys trataPeticionREST; either gets (acsURL + creq) for challenge or a frictionless final result.

4. Challenge: browser posts creq to ACS; ACS posts CRES to backend callback.

5. Finalization: backend reads CRES from Redis and calls Redsys trataPeticionREST with threeDSInfo="ChallengeResponse"; returns final authorization.

Security notes

• Use HTTPS for all public endpoints.

• Do not log PAN/CVV.

• If you store card data yourself, encrypt and keep a short TTL; purge after finalization.

• Ensure unique order ids to avoid Redsys duplicate-order errors (e.g. SIS0051).

1.0.0 (2025-11-19)

• Initial public release of guillotina_redsys.

• Core Redsys REST + 3DS v2 flow.

• Guillotina endpoints added.

• Utility added (async client + orchestration).

• Pydantic models added.

• Redis used to store short-lived threeDSCompInd and CRES.