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

# Pré-requisitos e configurações

Antes de realizar transações com 3DS2, é necessário preparar sua conta Malga com as configurações adequadas:

## Habilitando o 3DS2 na Conta Malga

* **Solicite a ativação do 3DS2:** Entre em contato com a equipe Malga para habilitar a funcionalidade 3D Secure 2 em sua conta. A Malga irá configurar o suporte ao 3DS2 para o seu ambiente. Somente após essa habilitação você poderá prosseguir com os próximos passos.
* **Provedor de pagamento compatível:** Verifique se você possui ou configurou um provedor de pagamento que suporte 3DS2 em sua conta Malga. Você pode consultar a lista de provedores suportados nesse link [Introdução - Malga (3DS2\_Malga)](/documentations/3ds2-malga/intro)

## Criando um Merchant com Suporte a 3DS2

Após ter o 3DS2 habilitado e um provedor compatível, você deve criar ou atualizar o **Merchant** com informações adicionais exigidas. A criação de um merchant na Malga segue o padrão usual, porém alguns campos extras são necessários:

* `merchantUrl` – URL do site da loja que está usando 3DS2 (geralmente a página inicial ou domínio do e-commerce).
* `merchantName` – Nome do estabelecimento que aparecerá para o cliente durante o desafio 3DS.
* `providers.acquirer.merchantId` – O identificador do seu merchant junto ao provedor de pagamento. Muitos provedores usam um único Merchant ID para todas as bandeiras de cartão;
* `providers.acquirer.bin` – Lista de BINs do adquirente cadastrados para cada bandeira de cartão. Inclui:
  * `brand`: Nome da bandeira (por exemplo, "Visa", "Mastercard", "Elo").
  * `value`: BIN (Bank Identification Number) do adquirente associado àquela bandeira.
  * `merchantId` (opcional por bandeira): Se o seu provedor utilizar um Merchant ID diferente para cada bandeira, você pode especificá-lo aqui. Caso contrário, se for igual para todas as bandeiras, use apenas o campo principal `providers.acquirer.merchantId`.

<Note>
  **Importante:** As configurações de `acquirer` (BINs e MerchantIDs) devem ser fornecidas pelo seu provedor de pagamento. Certifique-se também de que o provedor confirmou o cadastro desses dados junto às **bandeiras de cartão**. Sem esse cadastro adequado, as tentativas de transação com 3DS podem resultar em erro.
</Note>

A seguir, um exemplo de requisição cURL para criar um merchant e atualizar com as configurações 3DS2 (substitua `<SEU_API_KEY>` e `<SEU_CLIENT_ID>` pelos valores da sua conta, e ajuste os dados conforme o seu caso):

<Tabs>
  <Tab title="Criar Merchant">
    ```bash theme={null}
    curl --request POST 'https://api.malga.io/v1/merchants' \
      --header 'x-api-key: <SEU_API_KEY>' \
      --header 'x-client-id: <SEU_CLIENT_ID>' \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "mcc": "4814",
        "merchantUrl": "https://www.sualoja.com.br",
        "merchantName": "Minha Loja Online",
        "name": "Minha Loja Online",
        "providers": [
          {
            "priority": 1,
            "name": "SandboxProvider",
            "credentials": {
              "type": "SANDBOX",
              "apiKey": "SUaChaveDeAPI_Provedor"
            },
            "acquirer": {
              "merchantId": "ABC123MERCHANTID",
              "bin": [
                {
                  "brand": "Visa",
                  "value": "000001"
                },
                {
                  "brand": "Mastercard",
                  "value": "000002"
                }
              ]
            }
          }
        ],
        "status": true
      }'
    ```
  </Tab>

  <Tab title="Atualizar Merchant">
    ```bash theme={null}
    curl --request PATCH 'https://api.malga.io/v1/merchants/<MERCHANT_ID>' \
      --header 'x-api-key: <SEU_API_KEY>' \
      --header 'x-client-id: <SEU_CLIENT_ID>' \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "merchantUrl": "https://www.sualoja.com.br",
        "merchantName": "Minha Loja Online",
        "name": "Minha Loja Online",
        "providers": [
          {
            "priority": 1,
            "name": "SandboxProvider",
            "credentials": {
              "type": "SANDBOX",
              "apiKey": "SUaChaveDeAPI_Provedor"
            },
            "acquirer": {
              "merchantId": "ABC123MERCHANTID",
              "bin": [
                {
                  "brand": "Visa",
                  "value": "000001"
                },
                {
                  "brand": "Mastercard",
                  "value": "000002"
                }
              ]
            }
          }
        ]
      }'
    ```
  </Tab>
</Tabs>

No exemplo acima, o merchant é criado com um provedor de pagamento sandbox e informações fictícias (MCC, nome, URLs, Merchant ID e BINs). Ajuste esses campos para os valores reais fornecidos pelo seu provedor.

## Configurando o Fluxo de Pagamento 3DS2

A Malga utiliza Fluxos de Pagamento para orquestrar qual provedor será usado em cada transação. É necessário criar (ou atualizar) um fluxo de pagamento específico para 3DS2, indicando o merchant e o provedor configurado acima. Defina o atributo `paymentMethod` como "3ds2\_malga" para que a Malga saiba que esse fluxo usará a solução 3DS2 própria.

Exemplo de requisição cURL para criar um fluxo 3DS2 apontando para um provedor específico:

```bash theme={null}
curl --request POST 'https://api.malga.io/v1/flows' \
  --header 'x-api-key: <SEU_API_KEY>' \
  --header 'x-client-id: <SEU_CLIENT_ID>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "Fluxo 3DS2",
    "merchantId": "<MERCHANT_ID_CRIADO>",
    "paymentMethod": "3ds2_malga",
    "flow": {
      "root": [
        {
          "rule": "provider",
          "id": "<1__ID_DO_PROVEDOR_COM_SUPORTE_3DS2>"
        },
        {
          "rule": "provider",
          "id": "<2__ID_DO_PROVEDOR_COM_SUPORTE_3DS2>"
        }
      ]
    }
  }'
```

Nesse exemplo, substitua `<MERCHANT_ID_CRIADO>` pelo ID do merchant criado no passo anterior, e `<1__ID_DO_PROVEDOR_COM_SUPORTE_3DS2>` pelo identificador do provedor (conforme retornado na criação do merchant ou obtido via API). O fluxo acima direciona todas as transações 3DS2 do merchant para o provedor especificado. Após essa configuração, sua conta Malga está pronta para realizar transações com autenticação 3DS2.

<Note>
  **Recomendação:** Esta etapa pode ser feita pelo Dashboard Malga, para tornar a configuração mais simples e prática.
</Note>