Pré-requisitos e configurações

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

Capacidade exigida no provedor

Cobranças com threeDSecure2.setupId exigem provedor cujo paymentTypes inclua 3ds2_malga. Essa capacidade não exige operation=3ds2 (reservada ao 3DS nativo). Consulte a tabela de provedores e meios de pagamento e o hub de modalidades para comparar 3DS nativo, Malga, MPI externo e Data Only.

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 o merchant possui ao menos um provedor com paymentTypes contendo 3ds2_malga. A lista de suporte está na tabela de provedores.

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.

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.

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):

Criar Merchant
Atualizar Merchant

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
  }'

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"
            }
          ]
        }
      }
    ]
  }'

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. Você pode criar (ou atualizar) um fluxo com paymentMethod igual a "3ds2_malga", apontando apenas para provedores cujo paymentTypes inclui 3ds2_malga. A criação do fluxo não exige que esses provedores tenham operation=3ds2.

Se o merchant não tiver um fluxo ativo para a cobrança, a Malga ainda aplica o gate inicial de elegibilidade: cobranças com setupId só seguem com provedores cujo paymentTypes inclui 3ds2_malga, sem exigir operation=3ds2. Com fluxo ativo, configure paymentMethod=3ds2_malga apontando apenas para provedores compatíveis. Esse gate não garante preservação da ordem do fluxo nem retentativas limitadas à lista filtrada na autorização posterior.

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

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.

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

Comece na Malga

Conexões

Guias

Serviços adicionais

Pré-requisitos e configurações

Capacidade exigida no provedor

Habilitando o 3DS2 na conta Malga

Criando um Merchant com suporte a 3DS2

Configurando o fluxo de pagamento 3DS2

​Capacidade exigida no provedor

​Habilitando o 3DS2 na conta Malga

​Criando um Merchant com suporte a 3DS2

​Configurando o fluxo de pagamento 3DS2

Capacidade exigida no provedor

Habilitando o 3DS2 na conta Malga

Criando um Merchant com suporte a 3DS2

Configurando o fluxo de pagamento 3DS2