Como criar um pagamento com conversão de moedas e autenticação 3DS

ℹ️

Saiba mais sobre essa funcionalidade na documentação.

Autenticação 3DS

O protocolo de autenticação 3DS está disponível na versão browser-based, ou seja, a loja deverá incluir o script do 3DS no arquivo HTML da página de pagamento (checkout). O protocolo 3DS, ao processar o script, permite a troca de dados entre a loja e o emissor para autenticar o portador do cartão.
A integração do script do protocolo de autenticação é composta por etapas, para saber mais acesse a documentação.

Conversor de moedas e-commerce com autenticação 3DS

A criação de uma pagamento com a conversão de moeda e autenticação de 3DS segue os seguintes passos:

1. Implementação do script 3DS;
2. Criar pagamento com conversor de moeda, incluindo o nó do 3DS. Os campos DynamicCurrencyConversion e Authenticate devem ser enviados como true;
3. Confirmar a conversão de moeda, que deve ser realizada em até vinte minutos.

Fluxo do conversor de moedas e-commerce com 3DS

1. O comprador escolhe pagar com cartão de crédito estrangeiro;
2. A loja executa um script, solicitando à Cielo autenticação através da solução 3DS;
3. A loja envia requisição com dados do comprador para a bandeira;
4. A bandeira envia a requisição para avaliação de risco do emissor;
5. O emissor avalia as informações e determina se o fluxo será com ou sem desafio ao portador;
6. O emissor envia o resultado da autenticação para o 3DS Server;
7. o 3DS server envia o resultado da autenticação;
8. O back-end da loja envia a requisição de autorização, informando o campo DynamicCurrencyConversion igual a true para verificar a elegibilidade do cartão ao conversor de moedas e o campo Authenticate igual a _true_ para autenticação do 3DS.
9. A API E-commerce Cielo retorna na resposta o nó CurrencyExchangeData, que informa se o cartão é elegível ao conversor de moedas e apresenta as opções de câmbio;
10. O front-end da loja exibe as opções de conversão na página de checkout, para decisão do comprador;
11. O comprador escolhe entre pagar em moeda estrangeira ou em real_;
12. Se o comprador escolheu a moeda estrangeira (diferente de real), a loja envia requisição de confirmação da conversão com o campo CurrencyConversion igual a true;
13. A API E-commerce Cielo envia retorno de sucesso;
14. A loja envia confirmação de pagamento ao comprador.

Criar pagamento com conversão de moedas com autenticação 3DS

{
    "MerchantOrderId": "507313793",
    "Customer": {
        "Name": "Aline de Souza"
    },
    "Payment": {
        "Type": "CreditCard",
        "Amount": 1000,
        "Provider": "Cielo",
        "Installments": 1,
         "Capture": true,
         "Authenticate": "true",
        "DynamicCurrencyConversion": true,
        "CreditCard": {
            "Holder": "Aline de Souza",
            "CardNumber": "4091688625337641",
            "ExpirationDate": "12/2035",
            "SecurityCode": "333",
            "Brand": "Visa"
        },
        "ExternalAuthentication": {
            "Cavv": "AAABB2gHA1B5EFNjWQcDAAAAAAB=",
            "Xid": "Uk5ZanBHcWw2RjRCbEN5dGtiMTB=",
            "Eci": "06",
            "Version": "2.2.0",
            "ReferenceID": "a24a5d87-b1a1-4aef-a37b-2f30b91274e6"
        }
    }
}

As tabelas a seguir apresentam os parâmetros que podem ser enviados para a API na criação de um pagamento com conversão de moedas e autenticação 3DS.

Parâmetros do header

Parâmetros do body

Resposta

{
  "MerchantOrderId": "507121234",
  "Customer": {
    "Name": "Aline de Souza"
  },
  "Payment": {
    "ServiceTaxAmount": 0,
    "Installments": 1,
    "Interest": 0,
    "Capture": true,
    "Authenticate": true,
    "Recurrent": false,
    "CreditCard": {
      "CardNumber": "409168******7641",
      "Holder": "Aline de Souza",
      "ExpirationDate": "12/2035
      "SaveCard": false,
      "Brand": "Visa"
    },
    "Tid": "28875720024AFF9F",
    "Provider": "Cielo",
    "Eci": "6",
    "ExternalAuthentication": {
      "Cavv": "AAABB2gHA1B5EFNjWQcDAAAAAAB=",
      "Xid": "Uk5ZanBHcWw2RjRCbEN5dGtiMTB=",
      "Eci": "06",
      "Version": "2.2.0",
      "ReferenceId": "24a5d87-b1a1-4aef-a37b-2f30b91274e6"
    },
    "IsQrCode": false,
    "DynamicCurrencyConversion": true,
    "CurrencyExchangeData": {
      "CurrencyExchanges": [
        {
          "ConvertedAmount": 21,
          "ConversionRate": 0.206799,
          "Currency": "USD"
        }
      ]
    },
    "Amount": 100,
    "ReceivedDate": "2025-05-15 09:43:32",
    "Status": 12,
    "IsSplitted": false,
    "ReturnMessage": "Deseja pagar na moeda do seu País? Would you like to pay in your currency? ¿Quieres pagar en la moneda de tu país?",
    "ReturnCode": "1",
    "PaymentId": "cedbc789647eb-ba5d-609955d582ff34"
    "Type": "CreditCard",
    "Currency": "BRL",
    "Country": "BRA",
    "Links": [
      {
        "Method": "GET",
        "Rel": "self",
        "Href": "https://apiquery.cieloecommerce.cielo.com.br/1/sales/cedbc48e-81ba-47eb-ba5d-609955d344ee"
      },
      {
        "Method": "PUT",
        "Rel": "confirm",
        "Href": "https://api.cieloecommerce.cielo.com.br/1/sales/cedbc48e-81ba-47eb-ba5d-609955d344ee/confirm"
      }
    ]
  }
}

A tabela a seguir apresenta os principais parâmetros que podem ser retornados pela API na criação de um pagamento com conversão de moedas e autenticação 3DS.

*Para verificar se a transação foi autorizada com sucesso consulte o Retuncode , ReturnMessage e o Status.

*Status 12: indica que a transação está pendente, aguardando uma requisição de confirmação da loja para prosseguir com a transação.

A loja deve preparar a página de checkout para apresentar uma tela com as opções de conversão de moedas ao comprador, com base nas opções retornadas no nó CurrencyExchangeData.

Atenção: O exemplo desta página apresenta os parâmetros necessários para o Conversor de Moedas E-commerce e a autenticação 3DS e apenas os parâmetros obrigatórios para uma transação de cartão de crédito. Para verificar todos os parâmetros possíveis, vá para Criar pagamento com cartão de crédito.

⚠️

Importante

• O valor da transação aparecerá em reais (R$) ao fazer consultas;
• No site Cielo em pesquisa de transações o valor capturado aparecerá em reais (R$);
• Para o comprador após confirmar a conversão de moeda o valor aparecerá convertido na moeda escolhida;
• A operação de captura pode ser automática ou posterior mas deve ser feita em até 20 minutos.

Confirmar conversão da moeda

{
    "CurrencyConversion": true
}

A tabela a seguir apresenta os parâmetros que podem ser enviados para a API na confirmação da conversão da moeda.

Parâmetros do header

Parâmetro do Path

Parâmetro do body

Resposta

{
  "Status": 2,
  "ReasonCode": 0,
  "ReasonMessage": "Successful",
  "ProviderReturnCode": "6",
  "ProviderReturnMessage": "Transacao capturada com sucesso",
  "ReturnCode": "6",
  "ReturnMessage": "Transacao capturada com sucesso",
  "Tid": "28FGHJKTIOLPDSD28GM88FC",
  "ProofOfSale": "027113",
  "AuthorizationCode": "025930",
  "Links": [
    {
      "Method": "GET",
      "Rel": "self",
      "Href": "https://apiquery.cieloecommerce.cielo.com.br/1/sales/cedbc48e-81ba-47eb-ba5d-609955d344ee"
    },
    {
      "Method": "PUT",
      "Rel": "void",
      "Href": "https://api.cieloecommerce.cielo.com.br/1/sales/cedbc48e-81ba-47eb-ba5d-609955d344ee/void"
    }
  ]
}

Depois que o comprador decide pagar na moeda estrangeira, a loja deve enviar a requisição de confirmação da conversão com o campo CurrencyConversion igual a true. Após a confirmação, a API E-commerce Cielo irá submeter a transação para autorização.

⚠️

Atenção ao tempo limite para confirmação

A confirmação deve ser feita em até vinte minutos.

Se o tempo para confirmação da moeda desejada for superior a vinte minutos, a API irá retornar o código 020 com a mensagem “Status não permite autorização”.

Se a captura não for automática (Payment.Capture igual a true), a captura posterior também deve se feita em até 20 minutos, para garantir o câmbio ao comprador.