Uruguay

Rates

For all requests involving transactions in Uruguay, it is mandatory to include an object called rates. This object allows specifying a particular tax rate through two properties. The key property identifies the tax name—in Uruguay, this corresponds to the IVA (Value Added Tax), so the value must be "iva". The value property indicates the percentage of the applied tax rate, expressed as a numeric value.

Uruguay has the following main IVA categories:

• Standard: 22%
• Reduced: 10%
• Exempt: 0%

The value should reflect the appropriate rate based on the transaction, although other values may also be declared when applicable, such as promotional rates or tax benefits.

Example with a Standard category value:

"rates": [
  {
    "key": "iva",
    "value": 22.0
  }
]

Regulation Code

For all requests involving transactions in Uruguay, it is mandatory to include the regional_regulation_code field to ensure the correct application of regional regulations during processing. The following law codes are currently supported:

• "17934": applies to both credit and debit cards
• "19210": applies to debit cards only

If the value provided corresponds to one of these recognized codes, the corresponding discount or special treatment will be applied during post-processing, as defined by the processing rules.

Example:

"regional_regulation_code": "17934"

Spain

Introduction to PSD2 and Strong Customer Authentication (SCA)

The Revised Payment Services Directive (PSD2) is a European regulation introduced to increase security, transparency, and innovation within electronic payments. In effect since September 2019, PSD2 requires Payment Service Providers (PSPs) to implement Strong Customer Authentication (SCA) for most online transactions within the European Economic Area (EEA).

SCA is intended to reduce fraud and improve consumer protection by requiring users to verify their identity using multi-factor authentication during payment transactions. This applies to a wide range of operations, including:

• Online card payments
• Access to account information
• Bank transfers initiated through electronic channels SCA is mandatory unless a valid exemption is applied and accepted by the card issuer.

What is Strong Customer Authentication (SCA)?

Under PSD2, SCA requires that authentication be based on at least two of the following independent factors:

• Knowledge: something the user knows (e.g., password or PIN)
• Possession: something the user has (e.g., mobile device or hardware token)
• Inherence: something the user is (e.g., fingerprint or facial recognition) This is commonly known as two-factor authentication (2FA). The goal is to prevent unauthorized access even if one of the factors is compromised.

When is SCA Required?

SCA must be applied in the following cases:

• Accessing account information
• Initiating electronic payments
• Any action that may imply a risk of payment fraud or abuse However, several exemptions are allowed under certain risk and transaction conditions, which can help improve user experience by avoiding unnecessary friction in low-risk scenarios.

SCA Exemptions

While Strong Customer Authentication (SCA) is required for most electronic payments, PSD2 defines several exemptions that allow transactions to be processed without triggering customer authentication. These exemptions are intended to reduce friction and optimize user experience when the associated fraud risk is considered low.

Important: The application of any exemption is subject to acceptance by the card issuer. Even if an exemption is requested, the issuer may still require SCA based on its own risk assessment.

Low-Risk Transactions (TRA – Transaction Risk Analysis)

Transactions may be exempt from SCA if both the Payment Service Provider (PSP) and the issuer meet the required fraud rate thresholds and have real-time risk analysis mechanisms in place.

If either the PSP or the issuer exceeds these fraud rates, the exemption may be rejected, and the transaction will require SCA.

Low-Value Payments (LWV)

Transactions not exceeding €30 may be exempt from SCA. However, this exemption has limits:

• SCA is required after 5 consecutive uses of this exemption without authentication, or
• If the cumulative amount of exempted transactions exceeds €100 These limits are tracked by the issuer, who may choose to prompt for SCA even within those thresholds. In most cases, the TRA exemption is preferred over LWV due to its greater flexibility.

Recurring Transactions and Subscriptions

Recurring payments of fixed amount and frequency are only subject to SCA on the first transaction. Subsequent charges are exempt, provided they match the original terms and were initiated with customer consent.

Trusted Beneficiaries

Customers may add specific merchants to a trusted list maintained by their bank. Transactions from trusted beneficiaries can be exempted from SCA automatically, subject to issuer support and customer opt-in.

MIT – Merchant-Initiated Transactions

Merchant-Initiated Transactions (MITs), such as those using stored credentials or references, occur without the cardholder present. These are technically out of scope for SCA, but in practice they are often treated as exemptions. Conditions:

• The initial transaction (when credentials were stored) must have been authenticated
• The customer must have agreed to future charges (known as a mandate) As with all exemptions, issuers can reject MITs and request SCA at their discretion.

Additional Exemptions

Other scenarios may be exempt from SCA under PSD2, including:

• Mail Order / Telephone Order (MO/TO: Transactions where card details are collected by phone are out of scope, but must be flagged accordingly.
• Corporate Payments: Transactions made using corporate cards through channels not accessible to consumers may be exempt, depending on issuer policy.

Full Technical Flow

This process includes several steps involving the exchange of information between the merchant's backend and the issuer. At a high level, the flow includes:

1. Initialize 3DS Authentication
2. Execute 3DS Method (if required)
3. Authentication Data Submission
4. Handle challenge response (if required)
5. Final Transparent Authorization with CRes

Below is a breakdown of each step, including JSON examples, expected responses, and key fields.

Step 1: /3ds/lookup – Initialize 3DS Authentication

Send an initial request to start the 3DS authentication process and retrieve card configuration and method URLs (if needed).

Request:

{
  "transactionId": "test3ds102",
  "transactionType": "payment",
  "returnUrl": "https://google.com",
  "notificationUrl": "https://google.com",
  "paymentId": "test3ds101",
  "orderId": "test3ds101",
  "version": "v2",
  "payment": {
    "amount": {
      "total": 1010,
      "currency": "EUR"
    }
  },
  "customer": {
    "id": "12",
    "name": "Ms. Carla Denisse",
    "lastName": "Luna",
    "email": "carla.luna@conexa.ai",
    "phone": "5491136195323",
    "documentType": "dni",
    "documentNumber": "43087793",
    "address": {
      "street": "Cornelio Saavedra",
      "observation": "",
      "phone": "5491136195323",
      "postalCode": "1832",
      "city": "Lomas de Zamora",
      "number": "188",
      "country": "AR",
      "state": "Buenos Aires"
    }
  },
  "card": {
    "number": "4548810000000003",
    "name": "Ms. Nelle Beahan DVM",
    "expirationDate": "12/49",
    "securityCode": "123",
    "type": "string",
    "brand": "string",
    "installments": 1
  }
}

Response – Without 3DS Method Execution:

{
  "protocolVersion": "2.2.0",
  "threeDSServerTransID": "7bedea54-713f-4533-8ac5-fc43ef0fd9ef",
  "threeDSInfo": "CardConfiguration"
}

Response – With 3DS Method Execution Required:

{
  "protocolVersion": "2.2.0",
  "threeDSServerTransID": "7bedea54-713f-4533-8ac5-fc43ef0fd9ef",
  "threeDSMethodURL": "https://sis-d.redsys.es:25443/sis-simulador-web/threeDsMethod.jsp",
  "threeDSInfo": "CardConfiguration"
}

Step 2: 3DS Method Execution (If Required)

If threeDSMethodURL is present in the previous response, execute a POST from the client browser to that URL via an invisible iframe. You must submit a base64-encoded JSON payload containing:

{
  "threeDSServerTransID": "<value_from_previous_response>",
  "threeDSMethodNotificationURL": "https://yourdomain.com/notify"
}

Once the card issuer completes device fingerprinting, it will send a POST to your threeDSMethodNotificationURL. If the notification is not received within 10 seconds, or if threeDSMethodURL was not returned, consider the method as not validated.

Step 3: /3ds/query – Authentication Data Submission

Submit the 3DS authentication request including browser and device context information, and the data obtained earlier (threeDSServerTransID, etc.).

Request:

{
  "transactionId": "test3ds102",
  "transactionType": "payment",
  "payment": {
    "amount": {
      "total": 1010,
      "currency": "EUR"
    }
  },
  "card": {
    "number": "4548810000000003",
    "name": "Ms. Nelle Beahan DVM",
    "expirationDate": "12/49",
    "securityCode": "123",
    "type": "string",
    "brand": "string",
    "installments": 1
  },
  "data": {
    "protocolVersion": "2.2.0",
    "threeDSServerTransID": "7bedea54-713f-4533-8ac5-fc43ef0fd9ef",
    "threeDSInfo": "CardConfiguration",
    "browserJavascriptEnabled": "true",
    "browserAcceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8,application/json",
    "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36",
    "browserJavaEnabled": "false",
    "browserLanguage": "ES-es",
    "browserColorDepth": "24",
    "browserScreenHeight": "1250",
    "browserScreenWidth": "1320",
    "browserTZ": "52",
    "threeDSCompInd": "Y",
    "notificationURL": "https://sis-d.redsys.es/sis-simulador-web/SisRESTCreqCres_3DSecureV2.jsp"
  }
}

threeDSCompInd: Use Y if Step 2 completed successfully. Otherwise, use N.

Step 4: Challenge Flow (If Required)

If the response to /3ds/query includes a Challenge, it will look like:

{
  "threeDSInfo": "ChallengeRequest",
  "protocolVersion": "2.2.0",
  "acsURL": "https://sis-d.redsys.es/sis-simulador-web/authenticationRequest.jsp",
  "creq": "eyJ0..."
}

From the client browser, initiate a POST to acsURL using an invisible iframe, submitting creq as a parameter. The cardholder will be prompted by the issuer to authenticate (e.g., via OTP, biometric, app push).

Once complete, the issuer will POST a response to your notificationURL containing the CRes.

Step 5: Final Transparent Authorization with CRes

Use the final CRes received in the previous step to finalize the payment by submitting a transparent payment authorization.

Request:

{
  "transactionId": "test3ds102",
  "checkoutId": "Credential2",
  "paymentId": "Credential2",
  "orderId": "Credential2",
  "notificationUrl": "https://miweb.com/notify",
  "deviceFingerPrint": "string",
  "transactionType": "string",
  "payment": {
    "amount": {
      "total": 1010,
      "currency": "EUR"
    }
  },
  "customer": {
    "id": "12",
    "name": "Ms. Carla Denisse",
    "lastName": "Luna",
    "email": "carla.luna@conexa.ai",
    "phone": "5491136195323",
    "documentType": "dni",
    "documentNumber": "43087793",
    "address": {
      "street": "Cornelio Saavedra",
      "observation": "",
      "phone": "5491136195323",
      "postalCode": "1832",
      "city": "Lomas de Zamora",
      "number": "188",
      "country": "AR",
      "state": "Buenos Aires"
    }
  },
  "shipping": {
    "phone": "5491136195323",
    "city": "Lomas de Zamora",
    "country": "AR",
    "address": "Cornelio Saavedra",
    "postalCode": "1832",
    "state": "Buenos Aires",
    "street": "Cornelio Saavedra"
  },
  "products": {
    "items": [
      {
        "id": "1",
        "unitPrice": 1500,
        "name": "REMERA",
        "quantity": 2
      }
    ]
  },
  "tenantIntegrationCode": "string",
  "card": {
    "number": "4548810000000003",
    "name": "Ms. Nelle Beahan DVM",
    "expirationDate": "12/49",
    "securityCode": "123",
    "type": "string",
    "brand": "string",
    "installments": 1
  },
  "softDescriptor": "string",
  "modifiers": null,
  "invoice": "string",
  "data": {
    "threeDSInfo": "ChallengeResponse",
    "protocolVersion": "2.2.0",
    "cres": "eyJ0aHJlZURTU..."
  }
}

Status Reference: transStatus

Error Handling in 3DS Authentication

Proper error handling is critical to ensure resilience and a smooth user experience. During the 3-D Secure flow via REST integration, errors may occur in various stages—such as request formatting, device fingerprinting, challenge completion, or final authorization. Below is a guide to understanding and responding to common error scenarios.

General HTTP/Transport Errors