[Feature] Orders 3DS

[aqudsilva]

🔐 Implementação de 3DS (3D Secure) em Orders

📋 Processo de Descoberta e Implementação

1. Monitoramento de Mudanças

• Anúncio: Feature de 3DS (3D Secure) para Orders

2. Verificação no Fury Spec Hub

• Versão: Stable
• Exemplo identificado: "POST /v1/orders - Online with 3DS"

3. Análise da Especificação

Nós JSON identificados:

Request:

{
  "config": {
    "online": {
      "transaction_security": {
        "validation": "on_fraud_risk",
        "liability_shift": "required"
      }
    }
  }
}

Response:

{
  "payment_method": {
    "transaction_security": {
      "url": "",
      "validation": "on_fraud_risk", 
      "liability_shift": "required"
    }
  }
}

4. Mapeamento para Estrutura do SDK Java

Estrutura de pastas afetada:

src/main/java/com/mercadopago/
├── client/order/
│   ├── OrderOnlineConfig.java          [MODIFICADO]
│   └── OrderTransactionSecurity.java   [NOVO]
├── resources/order/
│   ├── OrderPaymentMethod.java         [MODIFICADO]
│   ├── OrderOnlineConfig.java          [NOVO]
│   ├── OrderTransactionSecurity.java   [NOVO]
│   └── OrderDifferentialPricing.java   [NOVO]
├── example/apis/order/
│   └── CreateOrderWith3DS.java         [NOVO]
└── test/java/com/mercadopago/client/order/
    └── OrderClientWith3DSTest.java     [NOVO]

🔧 Alterações Implementadas

Classes de Request (Client)

OrderTransactionSecurity.java

@Getter
@Builder
public class OrderTransactionSecurity {
    private String validation;      // "always", "on_fraud_risk", "never"
    private String liabilityShift;  // "required", "preferred"
}

Classes de Response (Resources)

OrderTransactionSecurity.java

@Getter
public class OrderTransactionSecurity {
    private String url;             // URL do Challenge 3DS
    private String validation;      // Validação utilizada
    private String liabilityShift;  // Configuração de liability shift
}

Integrações

• OrderOnlineConfig (client): Adicionado campo transactionSecurity
• OrderPaymentMethod (resources): Adicionado campo transactionSecurity

🎯 Como Funciona

1. Configuração no Request

OrderTransactionSecurity transactionSecurity = OrderTransactionSecurity.builder()
    .validation("on_fraud_risk")  // Recomendado: baseado em risco
    .liabilityShift("required")   // Transferência de responsabilidade
    .build();

OrderCreateRequest request = OrderCreateRequest.builder()
    .config(OrderConfigRequest.builder()
        .online(OrderOnlineConfig.builder()
            .transactionSecurity(transactionSecurity)
            .build())
        .build())
    // ... demais campos
    .build();

2. Processamento da Resposta

Order order = client.create(request);

// Verificar se Challenge é necessário
if ("action_required".equals(order.getStatus()) && 
    "pending_challenge".equals(order.getStatusDetail())) {
    
    String challengeUrl = order.getTransactions()
        .getPayments().get(0)
        .getPaymentMethod()
        .getTransactionSecurity()
        .getUrl();
    
    // Exibir URL em iframe para o usuário completar o challenge
    System.out.println("Challenge URL: " + challengeUrl);
}

3. Estados Possíveis

• Sem Challenge: status = "processed" → Aprovado diretamente
• Com Challenge: status = "action_required" + status_detail = "pending_challenge"
• Challenge OK: Status atualiza para processed
• Challenge Falha: Status atualiza para failed

Exemplos

Exemplo Completo

• Arquivo: CreateOrderWith3DS.java
• Funcionalidades:
  • Configuração completa de 3DS
  • Tratamento de diferentes cenários
  • Documentação inline detalhada

✅ Validações e Testes

Testes Realizados

• [x] Construção de objetos com builders
• [x] Serialização/deserialização JSON
• [x] Integração com classes existentes
• [x] Diferentes cenários de configuração
• [x] Lint e formatação

Compatibilidade

• [x] Retrocompatível: Não quebra implementações existentes
• [x] Campos opcionais: 3DS é opcional por padrão
• [x] API Compliant: Segue especificação do swagger

🚀 Impacto

Segurança

• ✅ Autenticação 3D Secure para transações
• ✅ Redução de chargebacks via liability shift
• ✅ Conformidade com regulamentações PCI DSS

Desenvolvedores

• ✅ API simples e intuitiva
• ✅ Documentação completa com exemplos
• ✅ Testes unitários abrangentes
• ✅ Backward compatibility mantida

Performance

• ✅ Campos opcionais sem overhead
• ✅ Serialização eficiente com Lombok
• ✅ Sem impacto em transações sem 3DS

📋 Checklist de Review

• [x] Análise da spec do swagger
• [x] Mapeamento correto JSON → Classes Java
• [x] Implementação de classes request/response
• [x] Atualização de classes existentes
• [x] Exemplo prático funcional
• [x] Testes unitários abrangentes
• [x] Documentação atualizada
• [x] Lint/formatação verificada
• [x] Compatibilidade backward testada