Desafio 3DS

Trate o desafio 3DS (Challenge) no pagamento com cartão da My Gateway: leitura da resposta, exibição pelo SDK e validação do resultado.

Nesta página

Quando a criação do pagamento no cartão devolve data.status igual a Challenge, o emissor pede uma autenticação adicional do portador. O desafio é exibido pelo SDK 3DS e o resultado é validado na API.

Tratar o desafio#

1
Leia os dados do 3DS
Converta data.antifraud[].value de string para JSON.
Exemplo conceitual
const threeDs = data.antifraud.find((item) => item.name === "threeDs"); const { acsUrl, pareq, authenticationTransactionId } = JSON.parse(threeDs.value);
Apresente o desafio
Chame o SDK com InitChallenge(acsUrl, pareq, authenticationTransactionId).
Aguarde o callback
O SDK chama o callback informado na inicialização quando o portador conclui ou cancela o desafio.
Trate o cancelamento
Se o callback indicar cancelamento, encerre a tentativa e informe o usuário.

Valide o resultado
Envie o JWT recebido no callback como validateToken, junto com o code3DS original e o paymentId.

Dados do 3DS na resposta#

O JSON contido em data.antifraud[].value pode ter os atributos abaixo.

Atributo	Descrição
`status`	Resultado do enrollment 3DS, como `Challenge`, `Success`, `Attempt`, `Silent` ou `Fail`.
`threeDsVersion`	Versão do protocolo 3DS.
`eci`	Indicador de comércio eletrônico retornado pela autenticação.
`veresEnrolled`	Participação ou elegibilidade do cartão no 3DS.
`paresStatus`	Resultado da autenticação do portador.
`threeDsStatus`	Status textual detalhado do processamento 3DS.
`acsUrl`	URL do servidor de controle de acesso usada pelo SDK para exibir o desafio.
`authenticationTransactionId`	Identificador da transação de autenticação.
`pareq`	Conteúdo opaco do desafio fornecido ao SDK.
`reason`	Motivo textual informado pelo processamento 3DS, quando disponível.

Validar o desafio#

POST/payments/v1/creditcard/antifraud/validate/3ds

Valida o resultado do desafio 3DS de um pagamento.

Cabeçalhos

Authorizationstringobrigatório
Valor de authenticationToken retornado na autenticação, sem o prefixo Bearer.
x-api-keystringobrigatório
Chave do API Gateway do ambiente.

Content-Typestringobrigatório
Sempre application/json.

Corpo da requisição

code3DSstringobrigatório
Mesmo código enviado na criação do pagamento. A API também aceita a variante code3ds, mas code3DS é a grafia canônica.
validateTokenstringobrigatório
JWT entregue pelo callback do SDK depois do desafio.
paymentIdUUIDobrigatório
ID retornado na criação do pagamento.

Requisição

curl --request POST \
  --url 'https://api.mygateway.com.br/payments/v1/creditcard/antifraud/validate/3ds' \
  --header 'Authorization: TOKEN_DE_AUTENTICACAO' \
  --header 'x-api-key: SUA_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"code3DS":"CODIGO_GERADO_PELO_SDK","validateToken":"JWT_RETORNADO_PELO_CALLBACK_DO_SDK","paymentId":"f3da8969-3db8-49f1-91cf-50ff444252e7"}'

const response = await fetch("https://api.mygateway.com.br/payments/v1/creditcard/antifraud/validate/3ds", {
  method: "POST",
  headers: {
    Authorization: token,
    "x-api-key": process.env.MYGATEWAY_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    code3DS: "CODIGO_GERADO_PELO_SDK",
    validateToken: "JWT_RETORNADO_PELO_CALLBACK_DO_SDK",
    paymentId: "f3da8969-3db8-49f1-91cf-50ff444252e7"
  }),
});

const result = await response.json();

<?php
$ch = curl_init('https://api.mygateway.com.br/payments/v1/creditcard/antifraud/validate/3ds');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: ' . $token,
        'x-api-key: ' . getenv('MYGATEWAY_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'code3DS' => 'CODIGO_GERADO_PELO_SDK',
        'validateToken' => 'JWT_RETORNADO_PELO_CALLBACK_DO_SDK',
        'paymentId' => 'f3da8969-3db8-49f1-91cf-50ff444252e7',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);

import os
import requests

response = requests.post(
    "https://api.mygateway.com.br/payments/v1/creditcard/antifraud/validate/3ds",
    headers={
        "Authorization": token,
        "x-api-key": os.environ["MYGATEWAY_API_KEY"],
    },
    json={
        "code3DS": "CODIGO_GERADO_PELO_SDK",
        "validateToken": "JWT_RETORNADO_PELO_CALLBACK_DO_SDK",
        "paymentId": "f3da8969-3db8-49f1-91cf-50ff444252e7",
    },
)
result = response.json()

Respostas

Desafio validado.

JSON

{
  "data": {
    "paymentId": "f3da8969-3db8-49f1-91cf-50ff444252e7",
    "situation": "WaitingPayment",
    "external3dsId": "IDENTIFICADOR_EXTERNO_3DS"
  }
}

Payload inválido ou regra de negócio não atendida.

ValidationError

{
  "notificationErrors": {
    "error": {
      "erros": [
        {
          "propertyName": "items.value",
          "propertyErrors": [
            "O valor informado é inválido."
          ]
        }
      ]
    }
  },
  "errorTypeDescription": "ValidationError",
  "errorType": 1
}

Atributos da resposta

data.paymentIdUUIDobrigatório
Pagamento validado.
data.situationstringobrigatório
Situação depois da validação. Ainda pode ser WaitingPayment.
data.external3dsIdstringobrigatório
Referência externa da validação 3DS. Trate como valor opaco.

Última atualização em 29 de outubro de 2026

Desafio 3DS

Tratar o desafio#

Dados do 3DS na resposta#

Validar o desafio#

Soluções

Taxa

Empresa

Políticas

Suporte