[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

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

Compatibilidade

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

Assim que as mudanças são mergeadas, antes de criar a release precisamos fazer o bump da versão para que o processo automatizado de deploy detecte. Segue pr de exemplo #326