Manual de Integração - Silent Order Post

Redirecionando para https://docs.cielo.com.br/gateway/docs/silent-order-post ...

As documentações do Silent Order Post estão em um novo portal

Acesse o novo portal de desenvolvedores E-commerce docs.cielo.com.br.

Atenção: O conteúdo desta página está sendo descontinuado e não receberá atualizações a partir de 14/08/2024. Visite a nova documentação em docs.cielo.br.

Silent Order Post

O Silent Order Post (SOP) é um serviço que oferece mais segurança ao comprador e controle sobre a experiência do checkout; é ideal para a loja que não possui estrutura para cumprir todos os requisitos de segurança do PCI DSS no uso de cartões de crédito.

O Silent Order Post possibilita o envio de dados do pagamento do seu cliente de forma segura, diretamente em nosso sistema. Os dados do cartão do comprador, tais como número do cartão e data de validade, não trafegam pelo ambiente da loja e são armazenados de forma criptografada (token) no ambiente da Braspag, que conta com a certificação PCI DSS 3.2.

O que é a certificação PCI DSS?
É um padrão global de segurança de dados de cartões. O PCI DSS foi desenvolvido para incentivar e aprimorar a segurança de dados de pagamento e facilitar a ampla adoção de medidas consistentes de segurança de dados. A certificação é obrigatória para que um e-commerce possa receber, tratar e armazenar dados de cartão.

Principais benefícios

• Coleta direta dos dados: a coleta dos dados do pagamento é feita diretamente para os sistemas da Braspag por um script, através dos campos definidos no seu checkout;
• Total compatibilidade: a solução é compatível com todos os meios de pagamento disponibilizados no Gateway (nacionais e internacionais);
• Certificação PCI DSS 3.2: a certificação da Braspag garante total conformidade com as normas da indústria de cartões, reduzindo o escopo de PCI DSS;
• Checkout personalizado: a personalização oferece controle total sobre a experiência de checkout e elementos da sua marca.

Meios de pagamento suportados

O Silent Order Post é capaz de criptografar cartões de crédito, débito, voucher e múltiplo, desde que atendam ao formato mod10.

Como funciona

A loja integra o script do Silent Order Post na página de checkout (client-side). Quando o comprador insere os dados do cartão no checkout, esses dados passam diretamente para o ambiente Braspag por meio do script instalado. A Braspag gera um token temporário para o cartão do comprador, o PaymentToken, que deverá ser usado pela loja para solicitar a autorização da transação. Assim, os dados sensíveis de cartão não passam pelo ambiente do seu e-commerce.

1. O comprador acessa a tela de checkout da loja;
2. O script da página de checkout solicita o access_token para o autenticador OAuth2;
3. O OAuth2 retorna o access_token;
4. O script da página de checkout solicita o AccessToken do Silent Order Post (AccessToken SOP), informando o access_token obtido na etapa anterior;
5. O Silent Order Post retorna o AccessToken SOP;
6. O comprador preenche os dados de pagamento na tela de checkout;
7. O script da página de checkout envia os dados do cartão para o Silent Order Post, informando o AccessToken SOP;
8. O Silent Order Post retorna o PaymentToken (cartão criptografado);
9. O script da página de checkout envia o PaymentToken para o servidor da loja, e o servidor envia a requisição de autorização da transação para a API do Gateway, informando o PaymentToken;
10. O Gateway retorna a resposta da autorização;
11. A loja confirma o pedido do comprador, se desejar.

O Silent Order Post permite mais segurança, sem interferir no layout da sua página.

Silent Order Post com VerifyCard

É possível habilitar o VerifyCard (verificação de cartão) junto com o Silent Order Post. Assim, a sua loja pode verificar se o cartão é válido antes de solicitar uma autorização.

O VerifyCard é composto por dois serviços: Zero Auth e Consulta BIN.

• Zero Auth: é um serviço que identifica se um cartão é válido ou não, através de uma operação semelhante a uma autorização, porém com valor R$ 0,00. O Zero Auth simula uma autorização sem afetar o limite de crédito ou alertar o portador do cartão sobre o teste;
• Consulta BIN: é um serviço disponível exclusivamente para clientes Cielo que retorna informações do cartão a partir do BIN (seis primeiros dígitos do cartão), tais como bandeira do cartão, se o cartão é de débito, crédito ou múltiplo, se é nacional ou internacional, se é cartão corporativo, banco emissor e se é cartão pré-pago.

1. O comprador acessa a tela de checkout da loja;
2. O script da página de checkout solicita o access_token para o autenticador OAuth2;
3. O OAuth2 retorna o access_token;
4. O script da página de checkout solicita o AccessToken do Silent Order Post (AccessToken SOP), informando o access_token obtido na etapa anterior;
5. O Silent Order Post retorna o AccessToken SOP;
6. O comprador preenche os dados de pagamento na tela de checkout;
7. O script da página de checkout envia os dados do cartão para o Silent Order Post, informando o AccessToken SOP;
8. O Silent Order Post solicita a validação do cartão ao VerifyCard;
9. O VerifyCard retorna o resultado do ZeroAuth e da Consulta BIN;
10. O Silent Order Post retorna o PaymentToken (cartão criptografado);
11. O script da página de checkout envia o PaymentToken para o servidor da loja, e o servidor envia a requisição de autorização da transação para a API do Gateway, informando o PaymentToken;
12. O Gateway retorna a resposta da autorização;
13. A loja confirma o pedido do comprador, se desejar.

Integrando o Silent Order Post

O funcionamento do SilentOrderPost ocorre em quatro etapas:

1. Autenticação da loja por meio da criação do access_token OAuth2 para acesso à API do Silent Order Post;
2. Criação do AccessToken do SOP na API do Silent Order Post para integrar o script;
3. Execução do script;
4. Envio da requisição de autorização da transação à API do Pagador informando o PaymentToken.

1. Obtendo o AccessToken OAuth2

Quando o comprador acessa o checkout, a loja deve gerar o access_token a partir da API de autenticação da Braspag (OAuth2). Em caso de sucesso, a API retornará um access_token que deverá ser utilizado na próxima camada de autenticação da ferramenta.

Para obter o access_token no padrão OAuth 2.0, envie requisição utilizando o VERBO HTTP POST para a seguinte URL, formada pela “URL base do ambiente + endpoint”, no modelo server-to-server:

Nota: O valor “{base64}” para a autorização do tipo “Basic” deve ser obtido da seguinte forma:

1. Concatene o ClientId e o ClientSecret (ClientId:ClientSecret).
2. Codifique o resultado da concatenação em base64.
3. Realize uma requisição ao servidor de autenticação utilizando o código alfanumérico gerado.

Solicite à equipe de suporte a criação do ClientId e do ClientSecret de sua loja para utilização nos ambientes sandbox e de produção. No chamado, informe que deseja realizar a integração do Silent Order Post e forneça seu MerchantId.

Requisição

--request POST "https://authsandbox.braspag.com.br/oauth2/token"
--header "Authorization: Basic {base64}"
--header "Content-Type: application/x-www-form-urlencoded" 
--data-binary "grant_type=client_credentials"

Resposta

{
  "access_token": "faSYkjfiod8ddJxFTU3vti_ ... _xD0i0jqcw",
  "token_type": "bearer",
  "expires_in": 599
}

{
  "access_token": "faSYkjfiod8ddJxFTU3vti_ ... _xD0i0jqcw",
  "token_type": "bearer",
  "expires_in": 599
}

2. Obtendo o AccessToken SOP

Crie o AccessToken do Silent Order Post (SOP) enviando uma requisição POST. Informe o access_token OAuth2 obtido na etapa anterior como o Bearer no cabeçalho da requisição.

O AccessToken do SOP será informado no script na etapa 3.

Requisição

--request POST "https://transactionsandbox.pagador.com.br/post/api/public/v2/accesstoken"
--header "Content-Type: application/json"
--header "MerchantId: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
--header "Authorization: Bearer faSYkjfiod8ddJxFTU3vti_ ... _xD0i0jqcw"
--data-binary
--verbose

Resposta

Como resposta, a loja receberá um JSON (“HTTP 201 Created”) contendo, entre outras informações, o token (AccessToken SOP).

{
    "MerchantId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "AccessToken": "MzA5YWIxNmQtYWIzZi00YmM2LWEwN2QtYTg2OTZjZjQxN2NkMDIzODk5MjI3Mg==",
    "Issued": "2023-08-05T08:50:04",
    "ExpiresIn": "2023-08-05T09:10:04"
}

--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "AccessToken": "MzA5YWIxNmQtYWIzZi00YmM2LWEwN2QtYTg2OTZjZjQxN2NkMDIzODk5MjI3Mg==",
    "Issued": "2023-08-05T08:50:04",
    "ExpiresIn": "2023-08-05T09:10:04"
}

Caso necessário, consulte o processo legado de autenticação, com geração do AccessToken utilizando MerchantId e IP do comprador.

3. Implementando o script

Mapeando classes

Faça o download do script do Silent Order Post e insira o script no formato JavaScript na sua página de checkout. Esse script permitirá à Braspag processar todas as informações de cartão sem intervenção da loja.

Parametrize os elementos de formulário com as seguintes classes:

*Se a classe bp-sop-cardtype não for informada, o script irá assumir que o cartão usado na compra é um cartão de crédito.

Definindo parâmetros

Parâmetros do script

Os parâmetros do script devem ser inseridos no HTML da página de checkout para referenciar o script.

* O serviço correspondente precisa estar habilitado.

Usando o Silent Order Post com o Cartão Protegido
O Cartão Protegido é o serviço de armazenamento de cartões criptografados da Braspag. Você pode usar o Silent Order Post para trafegar os dados de cartão pela Braspag e o Cartão protegido para armazenar o cartão de forma segura e criptografada na Braspag, que conta com a certificação PCI DSS.

Saiba mais no manual do Cartão Protegido.

Retornos do script

O script irá retornar um JSON com o PaymentToken (cartão tokenizado que deverá ser enviado na autorização) e informações sobre o cartão.

Exemplo de JSON de retorno do script

{
  "PaymentToken": "366f8470-54d0-43cb-95f5-c80a502afc27",
  "ForeignCard": false, 
  "BinQueryReturnCode": "00",
  "BinQueryReturnMessage": "Analise autorizada",
  "Brand": "Visa",
  "VerifyCardStatus": 1,
  "VerifyCardReturnCode": "00",
  "VerifyCardReturnMessage": "Transacao autorizada",
  "CardBin": "453202",
  "CardLast4Digits": "4044",
  "CardType": "Multiple",
  "Issuer": "Banco Santander",
  "IssuerCode": "033",
  "Prepaid": false   
}

Propriedades do retorno do script

Em Parâmetros do script, se enableTokenize for *true, o script irá retornar o CardToken em vez do PaymentToken. Saiba mais sobre CardToken no manual do Cartão Protegido.

Implementando eventos

O script fornecido pela Braspag oferece os seguintes três eventos para manipulação e tratamento por parte da loja:

Características do PaymentToken: Por questões de segurança, o PaymentToken poderá ser usado para uma única autorização e/ou dentro do período de 20 minutos. Após seu processamento, o PaymentToken será invalidado.

4. Autorizando com PaymentToken

Após a obtenção do PaymentToken através do script, execute o processo de autorização, enviando o PaymentToken no lugar de dados do cartão.

Para submeter uma transação de crédito, envie o parâmetro Payment.CreditCard.PaymentToken em vez de Payment.CreditCard. Saiba mais no manual do Pagador; Para submeter uma transação de débito, envie o parâmetro Payment.DebitCard.PaymentToken em vez de Payment.DebitCard. Saiba mais no manual do Pagador.

Veja o exemplo abaixo, descrevendo o envio dos dados de autenticação da requisição de autorização da API do Pagador.

Requisição

{  
   "MerchantOrderId":"2017051002",
   "Customer":
   {  
     (...)
   },
   "Payment":
   {  
     (...)
     "CreditCard":{  
         "PaymentToken":"eedcb896-40e1-465b-b34c-6d1119dbb6cf"
     }
   }
}

--request POST "https://apisandbox.braspag.com.br/v2/sales"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
--header "MerchantKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
--data-binary
--verbose
{  
   "MerchantOrderId":"2017051002",
   "Customer":
   {  
     (...)
   },
   "Payment":
   {  
     (...)
     "CreditCard":{  
         "PaymentToken":"eedcb896-40e1-465b-b34c-6d1119dbb6cf"
     }
   }
}

Resposta

Consulte o Manual da API do Pagador para exemplos de resposta a requisições de autorização.

Exemplo de integração

Compartilhamos no nosso GitHub um exemplo prático de como você deve mapear as classes e integrar o Silent Order Post ao seu checkout.