> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 3D Secure

Aprimore a segurança dos seus pagamentos online com o 3D Secure, o protocolo de autenticação padrão. Reduza as transações não autorizadas com uma camada extra de verificação, protegendo sua empresa e seus clientes sem comprometer a experiência do usuário.

O 3D Secure (3DS) é um protocolo de autenticação desenvolvido para aumentar a segurança das transações online com cartão. Ele ajuda a prevenir o uso não autorizado do cartão, exigindo verificação adicional do titular durante o processo de pagamento. Essa camada extra de autenticação reduz a fraude e garante que a transação esteja sendo realizada pelo legítimo proprietário do cartão.

O 3D Secure é amplamente utilizado por comerciantes, provedores de pagamento e instituições financeiras para melhorar a segurança das transações, mantendo uma experiência tranquila para o cliente.

***

## Como funciona o 3D Secure

Quando um cliente inicia uma compra online e o processador de pagamentos tem o 3D Secure ativado, ocorre o seguinte processo:

1. **Iniciação da transação**: O cliente insere os dados do cartão no seu site.
2. **Solicitação de autenticação**: A transação é enviada para a Localpayment, que avalia se a autenticação é necessária.
3. **Verificação do usuário**: Se a autenticação for necessária, o cliente será redirecionado para uma página segura onde deverá verificar sua identidade (por exemplo, usando uma senha de uso único, biometria ou autenticação por aplicativo bancário). Se nenhuma autenticação do titular do cartão for necessária (fluxo sem atrito), o fluxo de pagamento estabelecido em seu site continua de acordo com o resultado do processamento da solicitação.
4. **Resultado da autenticação**:
   * Se a autenticação for bem-sucedida, o cliente será redirecionado para o URL especificado na propriedade `redirectUrl.onSuccess` da solicitação.
   * Caso a autenticação falhe, o cliente será redirecionado para o URL especificado na propriedade `redirectUrl.onError`.
   * O resultado da autenticação também será retornado na resposta da API.
5. **Conclusão do pagamento**: Se a autenticação for bem-sucedida, a transação prossegue normalmente. Se a autenticação falhar, o pagamento é recusado.

### Diagrama de fluxo de autenticação

A sequência abaixo mostra os dois resultados possíveis: o fluxo sem atrito (sem desafio) e o fluxo com desafio, onde o titular do cartão deve inserir uma senha de uso único (OTP) na página de autenticação do emissor.

```mermaid theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#31467c', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0c1a29', 'actorBkg': '#31467c', 'actorBorder': '#0c1a29', 'actorTextColor': '#ffffff', 'actorLineColor': '#0c1a29', 'signalColor': '#0c1a29', 'signalTextColor': '#0c1a29', 'labelBoxBkgColor': '#31467c', 'labelBoxBorderColor': '#0c1a29', 'labelTextColor': '#ffffff', 'loopTextColor': '#0c1a29', 'noteBkgColor': '#ffffff', 'noteBorderColor': '#31467c', 'noteTextColor': '#0c1a29'}}}%%
sequenceDiagram
    actor Cardholder as Portador do cartão
    participant Merchant as Lojista
    participant LP as Localpayment
    participant Issuer as Emissor do cartão

    Cardholder->>Merchant: Paga com cartão
    Merchant->>LP: Cria o payin
    LP->>Issuer: Solicita autenticação

    alt Sem fricção
        Issuer-->>LP: Aprovado, sem desafio
        LP-->>Merchant: Resposta com status final
    else Desafio (OTP)
        Issuer-->>LP: Desafio obrigatório
        LP-->>Merchant: Resposta com status INPROGRESS e redirectUrl
        Issuer-->>Cardholder: Redireciona para a página do desafio
        Cardholder->>Issuer: Informa o OTP
        alt OTP válido
            Issuer-->>LP: Autenticado
            LP->>Merchant: Webhook com status final
        else OTP inválido ou expirado
            Issuer-->>LP: Falha na autenticação
            LP->>Merchant: Webhook com status REJECTED
        end
    end
```

O status final que o Localpayment envia ao comerciante (na resposta da API ou no webhook) depende do fluxo de captura do pagamento:

* **AUTHORIZED**: para transações em duas etapas (autorização e captura ocorrem separadamente).
* **APPROVED**: a transação foi confirmada, mas os fundos ainda não foram liquidados. Você pode sacar os fundos quando o status mudar para COMPLETE, geralmente em 1 a 2 dias, dependendo do provedor.
* **COMPLETE**: os fundos foram liquidados em tempo real.
* **REJECTED**: a autenticação falhou ou expirou, ou a transação foi recusada por outro motivo (por exemplo, fundos insuficientes).

### O que o titular do cartão vê durante o fluxo do desafio

> [!NOTE]
>
> As telas de desafio abaixo pertencem ao banco emissor do cartão e à rede do cartão (por exemplo, Visa ou Mastercard), não à Localpayment. A redação, a marca e o layout exatos variam de acordo com o emissor. Os exemplos abaixo usam dados fictícios para ilustrar o padrão geral.

**Passo 1 — Escolha um método de verificação**

Dependendo da emissora do cartão, o fluxo de verificação pode permitir que o titular do cartão escolha como receber o código OTP (por exemplo, por e-mail ou SMS), conforme mostrado abaixo. Outras emissoras omitem essa opção e enviam o código por um único canal fixo.

![](https://mintcdn.com/localpayment-1fee3d41/oFZuSE0fcOk5ECyA/images/docs/d3bf89f19e47d8647762da8849ef88e9717ba27cc239695a4a2c1630254774e9-3ds-otp-step1-method.png?fit=max\&auto=format\&n=oFZuSE0fcOk5ECyA\&q=85\&s=2d9d706d0652b4772d946eff72e43e01)

**Passo 2 — Insira o código de verificação**

![](https://mintcdn.com/localpayment-1fee3d41/x0nXcqwNUmbD9R8W/images/docs/6654bf3f70288b52620dd59666ea4e8d743cebccbb3d3f2bb296c9be6c37e5aa-3ds-otp-step2-code.png?fit=max\&auto=format\&n=x0nXcqwNUmbD9R8W\&q=85\&s=ef48f418780ebd9d43d0a993d7ac45c5)

Se o titular do cartão não concluir o desafio ou inserir um código inválido, a transação será rejeitada e ele será redirecionado para `redirectUrl.onError`, conforme descrito na Etapa 2 abaixo.

### Principais atores envolvidos

Diversas entidades estão envolvidas no processo 3D Secure:

* **Titular do cartão**: A pessoa que realiza a transação com seu cartão de crédito ou débito.
* **Comerciante**: a empresa online que aceita pagamentos com cartão.
* **Emissor**: A instituição financeira que emitiu o cartão do cliente (por exemplo, um banco).
* **Adquirente**: A instituição financeira que gerencia as transações do comerciante (Localpayment).
* **Servidor 3D Secure (3DSS)**: Um sistema que facilita a autenticação entre o comerciante, o emissor e as redes de pagamento.
* **Servidor de Controle de Acesso (ACS)**: Um sistema gerenciado pela instituição emissora que verifica a identidade do titular do cartão durante a autenticação.
* **Servidor de diretório**: Um sistema gerenciado pela rede de cartões (por exemplo, Visa, Mastercard) que ajuda a encaminhar as solicitações de autenticação para o emissor correto.

### Benefícios do 3D Secure

A implementação do 3D Secure oferece diversos benefícios tanto para comerciantes quanto para clientes:

* **Segurança reforçada**: Reduz o risco de transações fraudulentas, garantindo que somente o titular do cartão possa autorizar pagamentos.
* **Maior confiança do cliente**: Oferece uma camada adicional de proteção, dando aos clientes confiança ao fazer compras online.
* **Redução das taxas de fraude**: Diminui significativamente as transações não autorizadas e as potenciais perdas financeiras.

***

## Antes de começar

Certifique-se de ter:

> [card] [Credenciais da API](https://docs.localpayment.com/pt-br/docs/api-keys-and-environments.md)
>
> Credenciais de API e token de acesso válidos para autenticação.

> [card] [Configuração da conta](https://docs.localpayment.com/pt-br/docs/make-your-first-test-payment.md)
>
> Configuração adequada da conta para o país de destino e verificação da empresa.

> [card] [Lista branca de IPs](https://docs.localpayment.com/pt-br/docs/dashboard-whitelist-your-ips.md)
>
> Adicione os endereços IP do seu servidor à lista de permissões para acesso à API.

> [card] [Endpoint do webhook](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Configure um URL de webhook para receber notificações de pagamento.

***

## Etapa 1: Autenticação 3D Secure

Envie o objeto `redirectUrl` ao fazer um [Pagamento único](https://docs.localpayment.com/pt-br/reference/payins.md) ou uma [Assinatura](https://docs.localpayment.com/pt-br/reference/create-a-subscription.md) , incluindo as propriedades `onSuccess` e `onError`. Essas propriedades definem os URLs para onde seu cliente será redirecionado em caso de autenticação bem-sucedida ou de erro, respectivamente.

O `paymentMethod.code` depende do país, da bandeira do cartão e do produto (crédito ou débito). No Peru, ele também depende da moeda. Consulte [Códigos de método de pagamento com cartão](https://docs.localpayment.com/pt-br/docs/card-payment-methods.md) para ver a lista completa.

### Exemplo de solicitação

Abaixo está um exemplo usando `curl`:

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
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": "mail@company.com"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "RFC",
            "id": "YYY180222YY6"
        },
        "email": "john.doe@example.com"
    },
    "card": {
        "number": "4000000000000002",
        "cvv": "123",
        "expirationMonth": "12",
        "expirationYear": "2029"
    },
    "redirectUrl": {
        "onSuccess": "https://example.com/success/?id={externalId}",
        "onError": "https://example.com/error/?id={externalId}"
    }
}'
```

***

## Etapa 2: Lidar com a resposta

### Resposta bem-sucedida

Se for necessária autenticação adicional durante o processo de pagamento, a resposta da API incluirá a propriedade `redirectUrl`. Esse URL aponta para um modal ou página que deve ser exibido ao titular do cartão, permitindo que ele conclua o desafio de autenticação com o emissor do cartão.

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "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": "john.doe@example.com",
    "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"
}
```

Se a transação exigir autenticação pelo titular do cartão, ela permanece com o status `INPROGRESS` até que a autenticação seja concluída. Dependendo do fluxo de captura do pagamento, uma autenticação bem-sucedida move a transação para `AUTHORIZED` (transações em duas etapas aguardando captura), `APPROVED` (aguardando liquidação) ou `COMPLETE` (fundos liquidados em tempo real). Se a autenticação falhar, expirar ou a transação for recusada por outro motivo (por exemplo, fundos insuficientes), o status será `REJECTED`.

Após a autenticação do cliente (bem-sucedida ou não), o cliente será redirecionado para o URL especificado na solicitação, de acordo com o resultado. As propriedades `internalId` e `externalId` serão incluídas como parâmetros de consulta, permitindo que você implemente a lógica necessária (por exemplo, verificar o status da transação e exibir uma mensagem ao usuário).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.