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:

AmbienteURL base + endpointAuthorization
SANDBOXhttps://authsandbox.braspag.com.br/oauth2/token"Basic {base64}"
PRODUÇÃOhttps://auth.braspag.com.br/oauth2/token"Basic {base64}"

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"
ParâmetrosFormatoEnvio
Authorization"Basic {base64}"Envio no header.
Content-Type"application/x-www-form-urlencoded"Envio no header.
grant_type"client_credentials"Envio no body.

Resposta

{
  "access_token": "faSYkjfiod8ddJxFTU3vti_ ... _xD0i0jqcw",
  "token_type": "bearer",
  "expires_in": 599
}
Propriedades da RespostaDescrição
access_tokenO token de autenticação solicitado. Ele será utilizado no passo de obtenção do AccessToken do SOP.
token_typeIndica o tipo de token.
expires_inExpiração do token de acesso, em segundos. Quando o token expira, é necessário obter um novo.

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.

AmbienteURL base + endpoint
Sandboxhttps://transactionsandbox.pagador.com.br/post/api/public/v2/accesstoken
Produçãohttps://transaction.pagador.com.br/post/api/public/v2/accesstoken

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
PropriedadeDescriçãoTipoTamanhoObrigatório?
MerchantIdIdentificador da loja no Pagador.GUID36Sim
AuthorizationBearer [AccessToken OAuth2]texto36Sim

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"
}
PropriedadeDescriçãoTipoTamanhoFormato
MerchantIdIdentificador da loja no Pagador.GUID36xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
AccessTokenToken de acesso do Silent Order Post (AccessToken SOP). Por questões de segurança, este token dará permissão para o estabelecimento salvar apenas um cartão dentro de um prazo já estipulado na resposta, através do atributo ExpiresIn (por padrão, 20 minutos). O que acontecer primeiro invalidará esse mesmo token para impedir um uso futuro.texto--NjBhMjY1ODktNDk3YS00NGJkLWI5YTQtYmNmNTYxYzhlNjdiLTQwMzgxMjAzMQ==
IssuedData e hora da geração do AccessToken.texto--AAAA-MM-DDTHH:MM:SS
ExpiresInData e hora da expiração do AccessToken.texto--AAAA-MM-DDTHH:MM:SS

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:

PropriedadeNome da ClasseObrigatório?
Nome do portador do cartão de crédito/débitobp-sop-cardholdernameSim
Número do cartão de crédito/débitobp-sop-cardnumberSim
Data de validade do cartão de crédito/débitobp-sop-cardexpirationdateSim
Código de segurança do cartão de crédito/débitobp-sop-cardcvvcSim
Modalidade do cartão a ser verificada ("debitCard" ou "creditCard").bp-sop-cardtypeNão*

*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.

PropriedadeDescrição
accessTokenToken de acesso do Silent Order Post (AccessToken SOP).
environmentTipo de ambiente: "sandbox" para teste / "production" para produção.
languageIdioma: "pt" para português/ "en" para inglês/ "es"para espanhol.
enableBinQuery"true" (habilita o Consulta BIN, retornando as características do cartão) / "false" (caso contrário). Saiba mais sobre Consulta BIN no manual VerifyCard. Obs.: Disponível somente para Cielo 3.0.*
enableVerifyCard"true" (habilita o ZeroAuth, retornando se o cartão é válido ou não) / "false" (caso contrário).* Saiba mais no manual VerifyCard
enableTokenize"true" (salva o cartão diretamente no Cartão Protegido, retornando um CardToken ao invés de um PaymentToken) / "false" (caso contrário).*
cvvRequired"false" (desliga a obrigatoriedade de envio do CVV) / "true" (caso contrário). A loja precisa ter autorização da adquirente para transacionar sem o CVV.
cardTypeUse "creditCard" ou "debitCard" para forçar a verificação da modalidade do cartão. Importante para validar cartões múltiplos. Se nada for enviado, o emissor considerará apenas a modalidade "Crédito".

* O serviço correspondente precisa estar habilitado.

ℹ️

Para habilitar a Consulta BIN, VerifyCard ou o Cartão Protegido, entre em contato com o Atendimento.

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 em 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

PropriedadeDescriçãoCondição
PaymentToken*Token efêmero utilizado para pagamento no formato de um GUID (36). Tem duração de 20 minutos e pode ser usado apenas uma vez. É o valor que deve ser enviado na requisição de autorização.***
CardTokenToken permanente utilizado para pagamento no formato de um GUID (36).Quando enableTokenize for "true".
BrandNome da bandeira do cartão (Visa, Master, Elo, Amex, Diners, JCB, Hipercard).Quando enableBinQuery for "true". Disponível somente para Cielo 3.0.
BinQueryReturnCode"00" se a análise do BIN for um sucesso.Quando enableBinQuery for "true". Disponível somente para Cielo 3.0.
BinQueryReturnMessageEx.: “Transacao Autorizada” se a análise do BIN for um sucesso.Quando enableBinQuery for "true". Disponível somente para Cielo 3.0.
CardBinEx.: “455187”.Quando enableBinQuery for "true". Disponível somente para Cielo 3.0.
CardLast4DigitsEx.: “0181”.Quando enableBinQuery for "true". Disponível somente para Cielo 3.0.
ForeignCardO campo retorna "true" se é um cartão emitido fora do Brasil. "false" caso contrário.Quando enableBinQuery for "true". Disponível somente para Cielo 3.0.
IssuerO campo retorna nome do emissor do cartão.Quando enableBinQuery for "true". Disponível somente para Cielo 3.0.
IssuerCodeO campo retorna código do emissor do cartão.Quando enableBinQuery for "true". Disponível somente para Cielo 3.0.
CardTypeRetorna o tipo do cartão, por exemplo: Crédito, Débito, Múltiplo, Voucher, etc.Quando enableBinQuery for "true". Disponível somente para Cielo 3.0.
VerifyCardReturnCodeEsse é o mesmo código retornado pelo provedor durante uma autorização padrão. Ex: provedor Cielo30 código "00" significa sucesso na validação.Quando enableBinQuery for "true". Disponível somente para Cielo 3.0.
VerifyCardReturnMessageEx.: “Transacao Autorizada”.Quando enableBinQuery for "true". Disponível somente para Cielo 3.0.
VerifyCardStatus"0"- Cartão Inválido; "1"- Cartão Válido; "99"- Situação Desconhecida.Quando enableVerifyCard for "true".
PrepaidRetorna “true” se é um cartão pré-pago e "false" se não for cartão pré-pago.***

_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:

EventoDescrição
onSuccessEvento em caso de sucesso. Retorna o PaymentToken e também os dados do cartão, caso tenha solicitado realizar a verificação do cartão. Por questões de segurança, esse PaymentToken poderá ser usado para uma única autorização. Após seu processamento, ele será invalidado.
onErrorEvento em caso de erro. Retorna o código e a descrição do erro.
onInvalidEvento em caso de fornecimento de dados incorretos. Retorna detalhes de campos com erro. As mensagens retornadas no resultado da validação são disponibilizadas nas seguintes linguagens: português (default), inglês e espanhol.

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"
     }
   }
}
CampoDescriçãoTipo/TamanhoObrigatório?
Payment.CreditCard.PaymentTokenFornece o PaymentToken gerado através do script. Esta informação substitui os dados do cartão. Substituir por DebitCard se for utilizar um cartão de débitoGUID / 36Sim

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.