Criar um Pagamento Autenticado com 3DS com Provedor Terceirizado

Este guia orienta você na criação de um pagamento autenticado com 3D Secure (3DS) usando uma solução 3DS externa de terceiros. Ao usar essa abordagem, a autenticação é realizada pelo seu provedor de terceiros, e você deve fornecer os dados de autenticação resultantes ao criar o pagamento por meio da Global API da GetNet.

Requisitos

Antes de seguir os passos, você precisa:

Crie sua conta entrando em contato com a Equipe de Suporte à Integração para obter suas credenciais da API (client_id e client_secret).
Gere seu Bearer token com suas credenciais usando o endpoint de Access Token.
Tenha uma integração ativa com um provedor 3DS de terceiros (ex: Cardinal Commerce, Adyen, Stripe, etc.).
Certifique-se de que o seu provedor de terceiros suporta as bandeiras de cartão e os países em que você opera.

Importante para transações europeias: Para todas as transações dentro do Espaço Econômico Europeu (EEE), a autenticação 3DS é obrigatória em conformidade com a PSD2 e os requisitos de Autenticação Forte do Cliente (SCA). Todos os pagamentos com cartão processados na Europa devem ser autenticados usando 3DS, a menos que uma isenção SCA válida seja aplicada e aceita pelo emissor do cartão. Para obter mais informações sobre isenções de SCA, consulte a documentação de referência de Taxes and Regulations.

Entendendo a Autenticação 3DS de Terceiros

Ao usar uma solução 3DS externa de terceiros, o fluxo de autenticação é tratado inteiramente pelo seu provedor de terceiros. O processo funciona da seguinte forma:

O cliente conclui a autenticação por meio do seu provedor 3DS de terceiros.
Você recebe os dados de resposta de autenticação do provedor de terceiros.
Você inclui esses dados de autenticação ao criar o pagamento por meio da API de pagamento da GetNet.

Essa abordagem permite que você use a sua infraestrutura 3DS existente enquanto ainda processa pagamentos através da GetNet.

O diagrama a seguir ilustra o fluxo de autenticação simplificado:

Quando Usar 3DS de Terceiros

Considere usar uma solução 3DS de terceiros se:

Você já possui uma integração 3DS existente com outro provedor
Você precisa manter a consistência em vários processadores de pagamento
Seu provedor de terceiros oferece recursos adicionais de prevenção a fraudes que você deseja aproveitar
Você exige recursos ou configurações específicas de 3DS não disponíveis na solução nativa da GetNet

Se você está começando do zero ou não possui uma integração de terceiros existente, considere usar a solução 3DS nativa da GetNet para uma experiência de integração mais simplificada.

Campos de Autenticação Obrigatórios

Ao usar autenticação 3DS externa, você deve capturar e fornecer os seguintes campos do seu provedor de terceiros:

Campo	Descrição	Obrigatório	Versão de Protocolo
tdsver	A versão do protocolo 3DS usada na autenticação (ex: “1.0.2” ou “2.2.0”)	Sim	Ambos
eci	Electronic Commerce Indicator - um código que indica o resultado e o nível da autenticação	Sim	Ambos
xid	Um identificador de transação único gerado no fluxo 3DS, vinculando a autenticação ao pagamento	Sim	Apenas 3DS 1.0
ucaf	Universal Cardholder Authentication Field - um valor criptográfico provando que a autenticação foi concluída	Condicional	Apenas 3DS 1.0
tdsdsxid	Um identificador de transação gerado pelo protocolo 3DS 2.x (equivalente a `ds_trans_id`)	Sim	Apenas 3DS 2.x
cavv	Cardholder Authentication Verification Value - prova criptográfica de autenticação	Condicional	Apenas 3DS 2.x

Os campos exatos exigidos podem variar dependendo da versão do protocolo 3DS (1.0 ou 2.x) e do seu provedor de terceiros. Consulte a documentação do seu provedor para os campos específicos que eles retornam e seus nomes de campo exatos.

Etapas de Implementação

Etapa 1: Concluir a Autenticação com o Provedor de Terceiros

Siga o guia de integração do seu provedor 3DS de terceiros para concluir o fluxo de autenticação. Isso normalmente envolve:

Iniciar a solicitação de autenticação com o seu provedor
Redirecionar o cliente para concluir a autenticação (se o Challenge for exigido)
Receber a resposta de autenticação com os campos obrigatórios

As etapas exatas dependem da API e do SDK do seu provedor de terceiros. Consulte a documentação deles para detalhes específicos de implementação.

Etapa 2: Extrair os Dados de Autenticação

Após a conclusão da autenticação, extraia os campos de autenticação obrigatórios da resposta do seu provedor de terceiros. Certifique-se de capturar todos os campos listados na seção Campos de Autenticação Obrigatórios acima.

Os nomes e a estrutura exata dos campos dependem da API do seu provedor de terceiros. Consulte a documentação do seu provedor para identificar onde cada campo obrigatório está localizado em sua resposta.

Etapa 3: Criar o Pagamento com os Dados de Autenticação

Depois de extrair os dados de autenticação do seu provedor de terceiros, crie o pagamento por meio da API da GetNet incluindo os campos de autenticação na sua requisição de pagamento.

Chame o endpoint Create - Authorize, incluindo:

Detalhes de pagamento padrão (valor, moeda, cliente, informações do cartão)
Os dados de autenticação 3DS obtidos do seu provedor de terceiros

Exemplo de requisição com dados do 3DS 2.x:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --header 'x-transaction-channel-entry: XX' \
  --data '{
  "idempotency_key": "16c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "request_id": "16ac03dc-73db-453f-9bea-b1391669d5d3",
  "order_id": "ORDER-12345",
  "data": {
    "amount": 118708,
    "currency": "EUR",
    "customer_id": "customer-123",
    "payment": {
      "payment_method": "CREDIT",
      "save_card_data": false,
      "transaction_type": "FULL",
      "number_installments": 1,
      "tdsver": "2.2.0",
      "eci": "05",
      "tdsdsxid": "f7e5f76e-6388-43e6-b8cd-49b251a1f89c",
      "cavv": "aglgsCXwXPJDRA1aTlXIMVQnQakX",
      "card": {
        "expiration_month": "05",
        "expiration_year": "25",
        "cardholder_name": "CARD HOLDER",
        "security_code": "282",
        "number_token": "775c2b646c11d5e0d0d75a722c558a14d24abdb1df3752fcbbe2d61e51fc25f28d028b3139622a78fb03256e7701c35f64cc4920bb2d5f3224c86f42e131a9f9"
      }
    }
  }
}'

Exemplo de requisição com dados do 3DS 1.0:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --header 'x-transaction-channel-entry: XX' \
  --data '{
  "idempotency_key": "16c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "request_id": "16ac03dc-73db-453f-9bea-b1391669d5d3",
  "order_id": "ORDER-12345",
  "data": {
    "amount": 118708,
    "currency": "EUR",
    "customer_id": "customer-123",
    "payment": {
      "payment_method": "CREDIT",
      "save_card_data": false,
      "transaction_type": "FULL",
      "number_installments": 1,
      "tdsver": "1.0.2",
      "xid": "VDdnR0kyU1g4ZXlxMkhWTlp0VnA=",
      "eci": "05",
      "ucaf": "Y2F2dlZhbHVlSW5IZXg=",
      "card": {
        "expiration_month": "05",
        "expiration_year": "25",
        "cardholder_name": "CARD HOLDER",
        "security_code": "282",
        "number_token": "775c2b646c11d5e0d0d75a722c558a14d24abdb1df3752fcbbe2d61e51fc25f28d028b3139622a78fb03256e7701c35f64cc4920bb2d5f3224c86f42e131a9f9"
      }
    }
  }
}'

Exemplo de resposta:

{
  "idempotency_key": "16c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "payment_id": "b4bd779a-98c3-4f99-a028-518de149ed16",
  "order_id": "ORDER-12345",
  "amount": 118708,
  "currency": "EUR",
  "status": "APPROVED",
  "payment_method": "CREDIT",
  "received_at": "2025-08-13T10:34:01.239Z",
  "transaction_id": "MCC50204G3010",
  "original_transaction_id": "MCC50204G3010",
  "authorized_at": "2025-08-13T10:34:01.239Z",
  "reason_code": "00",
  "reason_message": "captured",
  "acquirer": "GETNET",
  "brand": "MASTERCARD",
  "authorization_code": "105020",
  "acquirer_transaction_id": "305020602020306050404010"
}

Considerações Importantes

Ao usar autenticação 3DS externa, tenha o seguinte em mente:

Integridade de dados: Garanta a integridade e a autenticidade dos dados de autenticação recebidos do provedor de terceiros antes de enviá-los para a GetNet.
Validação de campos: As transações podem ser rejeitadas pelo emissor se os campos de autenticação estiverem ausentes ou inválidos. Sempre verifique se todos os campos obrigatórios estão presentes e formatados corretamente.
Compatibilidade do provedor: O provedor externo deve suportar as bandeiras de cartão e os países em que você opera. Verifique a compatibilidade antes de implementar.
Tratamento de erros: Implemente um tratamento de erros adequado para os casos em que a autenticação falhar ou campos obrigatórios estiverem ausentes.

Próximos Passos

Agora que você criou com sucesso um pagamento autenticado por 3DS usando um provedor de terceiros, você pode explorar mais recursos da Global API da GetNet:

Aprenda sobre Autenticação 3DS com a GetNet se você quiser usar a solução 3DS nativa da GetNet.
Revise os conceitos de Autenticação 3DS para obter mais informações sobre como o 3DS funciona.