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:

1. Transaction Initiation: The customer enters their card details on your website.
2. Authentication Request: The transaction is sent to Localpayment, who evaluates whether authentication is needed.
3. 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.
4. 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.
5. 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.
• 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.

Before You Begin

Ensure you have:

Step 1: 3D Secure Authentication

Send the redirectUrl object when making a One-time payment or a Subscription , 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.

Example Request

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": "1600",
        "flow": "DIRECT"
    },
    "externalId": "dffbd2a6-6e65-469b-8bbe-dac269882220",
    "country": "MEX",
    "currency": "MXN",
    "amount": 1000,
    "accountNumber": "{{accountNumber}}",
    "conceptCode": "0001",
    "merchant": {
        "type": "COMPANY",
        "name": "Company",
        "document": {
            "type": "RFC",
            "id": "XXX840510XX1"
        },
        "email": "[email protected]"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "RFC",
            "id": "YYY180222YY6"
        },
        "email": "[email protected]"
    },
    "card": {
        "number": "4000000000000002",
        "cvv": "123",
        "expirationMonth": "12",
        "expirationYear": "2029"
    },
    "redirectUrl": {
        "onSuccess": "https://example.com/success/?id={externalId}",
        "onError": "https://example.com/error/?id={externalId}"
    }
}'

Step 2: Handle the Response

Successful Response

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": "dffbd2a6-6e65-469b-8bbe-dac269882220",
  "internalId": "22b29c98-92af-44bd-a164-1863ae2f1bb3",
  "paymentMethod": {
    "type": "CreditCard",
    "code": "1000",
    "flow": "DIRECT"
  },
  "country": "MEX",
  "currency": "MXN",
  "amount": 1000,
  "accountNumber": "{{accountNumber}}",
  "confirmed": {
    "currency": "MXN",
    "amount": 1000,
    "fxQuote": 1,
    "exchangeRateToken": null
  },
  "payment": {
    "installment": null,
    "currency": "MXN",
    "fxQuote": 1,
    "financingFee": 0,
    "amount": 1000
  },
  "localTaxes": [],
  "withHoldings": [],
  "fees": {
    "description": "Fee",
    "currency": "MXN",
    "fxSource": 210.8,
    "fxQuote": 1,
    "amount": 13.02,
    "account": "{{accountNumber}}"
  },
  "status": {
    "code": "103",
    "description": "APPROVED",
    "detail": "The payin was confirmed but not credited yet"
  },
  "ticket": null,
  "qr": null,
  "beneficiary": null,
  "merchant": {
    "type": "COMPANY",
    "name": "Company"
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "John",
    "lastname": "Doe",
    "document": {
      "id": "YYY180222YY6",
      "type": "RFC"
    },
    "email": "[email protected]",
    "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": "400000",
    "brand": "VISA",
    "country": "RS",
    "name": "John Doe",
    "last4": "0002",
    "expirationYear": 2029,
    "expirationMonth": 12
  },
  "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).