3D Secure

3D Secure (3DS) is an authentication protocol designed to enhance the security of online card transactions. It helps prevent unauthorized card use by requiring additional verification from the cardholder during the payment process. This extra authentication layer reduces fraud and ensures that the transaction is being carried out by the rightful owner of the card.

3D Secure is widely used by merchants, payment providers, and financial institutions to improve transaction security while maintaining a smooth customer experience.

How 3D Secure Works

When a customer initiates an online purchase and the processor has 3D Secure enabled, the following process occurs:

Transaction Initiation: The customer enters their card details on your website.
Authentication Request: The transaction is sent to Localpayment, who evaluates whether authentication is needed.
User Verification: If authentication is required, the customer is redirected to a secure page where they must verify their identity (e.g., using a one-time password, biometrics, or bank app authentication). If no cardholder authentication is required (frictionless flow), the payment flow established on your website continues according to the result of the request processing.
Authentication Result:
- If authentication is successful, the customer will be redirected to the URL specified in the redirectUrl.onSuccess property of the request.
- If authentication fails, the customer will be redirected to the URL specified in the redirectUrl.onError property.
- The authentication result will also be returned in the API response.
Payment Completion: If successfully authenticated, the transaction proceeds as usual. If authentication fails, the payment is declined.

Key Actors Involved

Several entities are involved in the 3D Secure process:

Cardholder: The person making the transaction with their credit or debit card.
Merchant: The online business accepting card payments.
Issuer: The financial institution that issued the customer’s card (e.g., a bank).
Acquirer: The financial institution that manages the merchant’s transactions (Localpayment).
3D Secure Server (3DSS): A system that facilitates authentication between the merchant, issuer, and payment networks.
Access Control Server (ACS): A system managed by the issuer that verifies the cardholder’s identity during authentication.
Directory Server: A system managed by the card network (e.g., Visa, Mastercard) that helps route authentication requests to the correct issuer.

Benefits of 3D Secure

Implementing 3D Secure offers multiple benefits for both merchants and customers:

Enhanced Security: Reduces the risk of fraudulent transactions by ensuring only the cardholder can authorize payments.
Chargeback Protection: Transactions authenticated via 3D Secure may shift liability for fraudulent chargebacks from the merchant to the card issuer.
Improved Customer Trust: Provides an added layer of protection, giving customers confidence when shopping online.
Reduced Fraud Rates: Significantly lowers unauthorized transactions and potential financial losses.

Availability

3D Secure is available in the following countries:

🇦🇷 Argentina: Visa, Mastercard, American Express, Diners, Argencard, Cabal.
🇧🇴 Bolivia: Visa.
🇧🇷 Brazil: Visa, Mastercard, American Express, Elo, Hipercard.
🇨🇱 Chile: Visa, Mastercard, American Express, Diners, Magna.
🇨🇴 Colombia: Visa, Mastercard, American Express, Diners.
🇩🇴 Dominic Republic: Visa.
🇲🇽 Mexico: Visa, Mastercard, American Express.
🇵🇦 Panama: Visa.
🇵🇪 Peru: Visa, Mastercard, American Express, Diners.

3D Secure Authentication

Send the redirectUrl object when making a One-time payment, a Recurring payment, or a Pre-authorization, including the properties onSuccess and onError. These properties define the URLs where your customer will be redirected upon successful authentication or in case of an error, respectively.

Request Example

Below is an example using curl:

curl --request POST \
  --url https://api.stage.localpayment.com/api/payin/ \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "paymentMethod": {
        "type": "CreditCard",
        "code": "1000",
        "flow": "DIRECT"
    },
    "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
    "country": "ARG",
    "currency": "ARS",
    "amount": 1000,
    "accountNumber": "032.032.00000000",
    "conceptCode": "0001",
    "merchant": {
        "type": "COMPANY",
        "name": "Company",
        "document": {
            "type": "CUIT",
            "id": "3000091105"
        },
        "email": "[email protected]",
        "phone": {
            "countryCode": "54",
            "areaCode": "351",
            "number": "1234567"
        }
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "DNI",
            "id": "37993123"
        },
        "email": "[email protected]",
        "phone": {
            "countryCode": "1",
            "areaCode": "11",
            "number": "98189123"
        },
        "bank": {
            "name": "BANCO BBVA ARGENTINA S.A.",
            "code": "017",
            "account": {
                "type": "S",
                "number": "19101196551119123456789"
            }
        }
    },
    "commercialData": {
        "items": [
            {
                "id": "12345",
                "quantity": "1",
                "description": "Test product",
                "title": "Test",
                "unitPrice": "1000"
            }
        ]
    },
    "card": {
        "number": "4000000000000002",
        "cvv": "123",
        "expirationMonth": "12",
        "expirationYear": "2029"
    },
    "redirectUrl": {
        "onSuccess": "https://example.com/success/?id={externalId}",
        "onError": "https://example.com/error/?id={externalId}"
    }
}'

Successful response example

If additional authentication is required during the payment process, the API response will include the redirectUrl property. This URL points to a modal or page that should be displayed to the cardholder, enabling them to complete the authentication challenge with their card issuer.

{
  "transactionType": "PayIn",
  "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
  "internalId": "22b29c98-92af-44bd-a164-1863ae2f1bb3",
  "paymentMethod": {
    "type": "CreditCard",
    "code": "1000",
    "flow": "DIRECT"
  },
  "country": "ARG",
  "currency": "ARS",
  "amount": 1000,
  "accountNumber": "032.032.00000000",
  "confirmed": {
    "currency": "ARS",
    "amount": 1000,
    "fxQuote": 1,
    "exchangeRateToken": null
  },
  "payment": {
    "installment": null,
    "currency": "ARS",
    "fxQuote": 1,
    "financingFee": 0,
    "amount": 1000
  },
  "localTaxes": [],
  "withHoldings": [],
  "fees": {
    "description": "Fee",
    "currency": "ARS",
    "fxSource": 210.8,
    "fxQuote": 1,
    "amount": 13.02,
    "account": "032.032.00000001"
  },
  "status": {
    "code": "100",
    "description": "INPROGRESS",
    "detail": "The payin is pending the confirmation"
  },
  "ticket": null,
  "qr": null,
  "beneficiary": null,
  "merchant": {
    "type": "COMPANY",
    "name": "Company"
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "John",
    "lastname": "Doe",
    "document": {
      "id": "37895247",
      "type": "DNI"
    },
    "email": "[email protected]",
    "phone": {
      "countryCode": "1",
      "areaCode": "11",
      "number": "98789632"
    },
    "address": null,
    "birthdate": null,
    "nationality": null
  },
  "intermediaries": [],
  "wireInstructions": null,
  "date": {
    "creationDate": "2024-05-19T19:02:44.018+00:00",
    "processedDate": "2024-05-19T19:02:44.799618",
    "expirationDate": "0001-01-01T00:00:00"
  },
  "card": {
    "bin": "402670",
    "brand": "VISA",
    "country": "RS",
    "name": "John Doe",
    "last4": "3263",
    "expirationYear": 2029,
    "expirationMonth": 9
  },
  "errors": [],
  "redirectUrl": "https://web-checkout.stage.localpayment.com/redirect/aXX0cXX6Ly9ob29xxx5zdHJpcXXuY29tLzNkX3NlY0VyXX0yL0hvc3RlZD9tZXJjaGFudX1hY0N0XzFKdHJmYkw5RVZiU1oySkgmcGF5bWVudF9xxxRlbnQ9cXlfM05weERZTDlFVmXXXjXXXXXXXXXXa2kyJnBheW1lbnRfaW50ZW50X2NsaWVudF9zXXXyZXQ9cGlfM05weERZTDlFVmJTWjXXXXXXXXXXXa2kyX3NlY3JldF9hek5FV1cyQm1BU3RDZHpjRzF0MkVTQ3BuJnB1Ymxpc2hhYmxlX2tleT1wa190ZXN0XzUxSnRyZmJMOUVWYlNaMkpISUF2WjJGREh0aWpwd0JFUWE5SG4xbTA1WHlPS0d3MjlncW1PTGJ6R3hUTm01M0V6VGVBbkk0aTRHWnFpUDliNkJuME5DWDFjMDBrbFNZdmwxQiZzb3VyY2U9cGF5YXR0XzNOcHhXXXw5RVZiU1oySkgxbXX1Q3XrxX"
}

If the transaction requires authentication by the cardholder, it will remain in the INPROGRESS status until successful authentication is completed (COMPLETED), or if there is an issue with the authentication or it expires (REJECTED).

Following customer authentication (whether successful or failed), the customer will be redirected to the URL specified in the request based on the outcome. The internalId and externalId properties will be included as query parameters, enabling you to implement necessary logic (e.g., checking the transaction status and displaying a message to the user).