Manual Checkout

Versão 1.0

SUMÁRIO
HISTÓRICO DE REVISÕES .....................................................................................................3
1. COMO FUNCIONA? ...........................................................................................................4
2. CREDENCIAIS ....................................................................................................................4
3. INICIANDO CHECKOUT ...................................................................................................4
3.1. PARÂMETRO PARA INICIAR AMBIENTE .............................................................4
3.2. RETORNO DE PAGAMENTO ..................................................................................7
4. GERAÇÃO DA ASSINATURA ..........................................................................................9
4.1. GERAÇÃO PARA A REQUISIÇÃO DE PAGAMENTO ........................................9
4.2. RETORNO DA SOLICITAÇÃO DE PAGAEMNTO..............................................10
5. GERAÇÃO DE TOKEN DO CARTÃO PARA PAGAMENTO ....................................11
5.1. RETORNO DA SOLICTAÇÃO DE GEFRAÇÃO DE TOKEN ............................12
6. PROCESSO DE PAGAMENTO (Visualização geral) .................................................13
HISTÓRICO DE REVISÕES

VERSÃO DATA HISTÓRICO

1.0 01/08/2019 ELABORAÇÃO DO MANUAL
 1. COMO FUNCIONA?

• O cliente, após o credenciamento, receberá um par de chave, chamado de

“UserName” e “Password”, devendo ser enviado sempre em todas as
requisições, tanto em ambiente de teste quanto no ambiente em produção.
• Além de utilizar conexões HTTPs, o checkout trabalha com um modelo de
assinatura, que será explicado como a mesma deverá ser gerada, também
deve ser enviada em todas as requisições, sendo necessário à sua geração
para cada requisição.
• Opcionalmente o cliente poderá enviar um parâmetro adicional chamado
“ContractNumber” onde previamente poderá solicitar configurações
adicionais, como por exemplo: valor mínimo de parcelamento, quantidade
mínima de parcelas, etc.

2. CREDENCIAIS

São enviadas por e-mail, caso ainda não tenha recebido pode ser solicitada
entrando em contato com o suporte.

3. INICIANDO CHECKOUT

O ambiente de pagamento é iniciado através do envio de um formulário, com

os dados necessários, abaixo segue campos que podem ser enviados no
formulário, qualquer campo que não esteja listado aqui será desprezado:

3.1. PARÂMETRO PARA INICIAR AMBIENTE

Campo Tipo Obrigatório Descrição

Não (se
Ecommerce
EcommerceId Inteiro
integration
informado)
Número do pedido, mesmo
valor será retornado após o
OrderNumber Alfanumérico Sim
pagamento. Não pode ser
repetido
 Contém o par de chaves para
identificação. (Se o campo
EcommerceIntegration Objeto Sim EcommerceId for
informado, este será
desconsiderado)

Dados do cliente que está

Client Objeto Não
efetuando o pagamento

Lista com a descrição e valor

dos itens que estão sendo
Products Lista<Objeto> Sim
pagos. * Pelo menos 1 item
deve ser informado.

Habilita a divisão de
recebíveis do pagamento
solicitado. Deve informar o
EnableSplit Booleano Sim
suporte a necessidade da
utilização. O valor padrão é
false.

Informar o valor do split (caso

seja uma operação com
AmountSplit Inteiro Sim
divisão de recebíveis). O
valor padrão é 0.

Define regras específicas de

pagamento, quando
ContractNumber Alfanumérico Não solicitado pelo cliente.
Restrições devem ser
informadas ao suporte.

Url que será chamada após o

pagamento.
UrlCallBack Alfanumérico Sim Obrigatoriamente deve
permitir uma chamada post,
verifique o item 3.2
Campo para validar
Signature Alfanumérico Sim integridade dos dados
enviados. Ver item 4

Objeto para receber

CustomParams Objeto Não configurações de exibição
adicional.

Objeto “EcommerceIntegration”: informações adicionais do pagador.

 Campo Tipo Obrigatório Descrição

Name Alfanumérico Sim Identificador da loja

Password Alfanumérico Sim Senha da loja

Objeto “Client”: informações adicionais do pagador.

Campo Tipo Obrigatório Descrição

Nome do cliente que está

Name Alfanumérico Não
efetuando o pagamento.

Email do cliente que está

Email Alfanumérico Não
efetuando o pagamento.

Objeto “Products”: No ambiente de pagamento será exibido a lista com os dados das
descrições passadas de cada item e seu respectivo valor.

Campo Tipo Obrigatório Descrição

Identificador do produto ou
ProductItemId Inteiro Não serviço que está sendo pago,
definido pela loja

Descrição do produto ou
Description Alfanumérico Sim
serviço que está sendo pago.

Valor do produto ou serviço

Amount Inteiro Sim que está sendo pago, deve
ser informado em centavos

Objeto “CustomParams”: No ambiente de pagamento permite a configuração de

alguns elementos, sendo eles listado abaixo.

Campo Tipo Obrigatório Descrição

Url para exibição da logo
UrlLogo Alfanumérico Não acima do formulário de
pagamento, quando não
 informada é exibida o nome
fantasia.

Valor em pixels para a largura

da imagem passada na
LogoWidth Inteiro Não UrlLogo, caso nenhum valor
seja passado o padrão será
300px.

Exemplo:

<form action="{UrlChamadaCheckout}" method="POST">

<input type="text" name="EcommerceId" value="{EcommerceId}">
<input type="text" name="OrderNumber" value="{OrderNumber}">
<input type="text" name="EcommerceIntegration.UserName" value="{UserName}">
<input type="text" name="EcommerceIntegration.Password" value="{Password}">
<input type="text" name="Client.Name" value="{Name}">
<input type="text" name="Client.Email" value="{Email}">
<input type="text" name="Products[0].ProductItemId" value="{ProductItemId}" />
<input type="text" name="Products[0].Description" value="{Description}" />
<input type="text" name="Products[0].Amount" value="{Amount}" />
<input type="text" name="Products[1].ProductItemId" value="{ProductItemId}" />
<input type="text" name="Products[1].Description" value="{Description}" />
<input type="text" name="Products[1].Amount" value="{Amount}" />
<input type="text" name="EnableSplit" value="false" />
<input type="text" name="AmountSplit" value="{AmountSplit}" />
<input type="text" name="ContractNumber" value="{ContractNumber}" />
<input type="text" name="UrlCallBack" value="{UrlCallBack}">
<input type="text" name="Signature" value="{Signature}">
<input type="text" name="CustomParams.UrlLogo" value="{UrlLogo}">
<input type="submit" value="Submit">
</form>

3.2. RETORNO DE PAGAMENTO

Após um pagamento (independente do status), para retornar à aplicação do
cliente que realizou a requisição, O ambiente fará o envio do formulário para URL
especificada no call-back (“UrlCallBack”), na solicitação de pagamento, a página da url
especificada deverá esperar um método POST, com um formulário que contenha os
campos abaixo:

Campo Tipo Descrição

URL informada como call-back (caminho web onde a
UrlCallBack Alfanumérico página deverá ser direcionada após a tentativa de
pagamento.
Identificador único da transação. * Obrigatório para
TransactionUuid Guid
solicitação de cancelamentos.
 Número do pedido enviado na requisição de
OrderNumber Alfanumérico
pagamento.

Amount Inteiro Valor do pagamento em centavos

Installments Inteiro Quantidade de parcelas, 1 = à vista

Número do cartão, contendo apenas o início e o final

CardNumber Alfanumérico
do mesmo

CardBrand Inteiro Código da bandeira do cartão utilizado

OperationType Inteiro Código do tipo de operação. 1 = Débito, 2 = Crédito

Campo para validar integridade dos dados enviados.

Signature Alfanumérico
Ver item 4

Define se o pagamento foi realizado. True =

Success Booleano pagamento efetuado com sucesso
False = Falha no pagamento

Detalhes adicionais sobre um pagamento, (retornado

Message Alfanumérico
em situações de falha no pagamento)

Código das
bandeiras
Código Bandeira
1 VISAELECTRON
2 MAESTRO
3 VISA
4 MASTERCARD
6 ELO
7 HIPERCARD

Exemplo:
 <form id="FinishPayment" action="{UrlCallback}" target="_parent" method="POST">
<input type="hidden" name="TransactionUuid" value="{TransactionUuid}">
<input type="hidden" name="OrderNumber" value="{OrderNumber}">
<input type="hidden" name="Amount" value="{Amount}">
<input type="hidden" name="Installments" value="{Installments}">
<input type="hidden" name="CardNumber" value="{CardNumber}">
<input type="hidden" name="CardBrand" value="{CardBrand}">
<input type="hidden" name="OperationType" value="{OperationType}">
<input type="hidden" name="Success" value="{Success}">
<input type="hidden" name="Message" value="{Message}">
<input type="hidden" name="Signature" value="{Signature}" />
</form>

4. GERAÇÃO DA ASSINATURA
O parâmetro “Signature” tanto na requisição quanto no retorno, deverá estar
presente, neste item será especificado como esse campo é gerado é como
deverá ser manipulado. Ele é importante para garantir que as requisições estão
partindo de uma fonte conhecida e que durante a troca de informações os valores
não foram alterados, garantindo dessa forma a autenticidade dos dados.

4.1. GERAÇÃO PARA A REQUISIÇÃO DE PAGAMENTO

Ao enviar o formulário para iniciar o ambiente de pagamento, o campo
“Signature” deverá ser formado através da concatenação de todos os
parâmetros, desconsiderando espaços em branco, exemplo:
 <form action="{UrlChamadaCheckout}" method="POST">
<input type="text" name="OrderNumber" value="{OrderNumber}">
<input type="text" name="EcommerceIntegration.UserName" value="{UserName}">
<input type="text" name="EcommerceIntegration.Password" value="{Password}">
<input type="text" name="Client.Name" value="{Name}">
<input type="text" name="Client.Email" value="{Email}">
<input type="text" name="Products[0].ProductItemId" value="{ProductItemId}" />
<input type="text" name="Products[0].Description" value="{Description}" />
<input type="text" name="Products[0].Amount" value="{Amount}" />
<input type="text" name="Products[1].ProductItemId" value="{ProductItemId2}" />
<input type="text" name="Products[1].Description" value="{Description}" />
<input type="text" name="Products[1].Amount" value="{Amount}" />
<input type="text" name="EnableSplit" value="{false}" />
<input type="text" name="AmountSplit" value="{AmountSplit}" />
<input type="text" name="ContractNumber" value="{ContractNumber}" />
<input type="text" name="UrlCallBack" value="{UrlCallBack}">
<input type="text" name="Signature" value="{Signature}">
<input type="submit" value="Submit">
</form>

Para o exemplo acima, o primeiro passo da assinatura ficaria da seguinte forma:

OrderNumberUserNamePasswordNameEmailProductItemIdDescriptionAmountProductItemI
d2DescriptionAmountfalseAmountSplitContractNumberUrlCallBack

O Segundo passo para geração da assinatura é deixar todas as letras minúsculas e

remover qualquer espaço em branco entre os caracteres:
ordernumberusernamepasswordnameemailproductitemiddescriptionamountproductitemid2d
escriptionamountfalseamountsplitcontractnumberurlcallback
Para o último passo, deve ser utilizado o algoritmo de criptografia SHA256, gerando a
sequência de caracteres abaixo:

3feb6918d97931b4c82dcfe126655ca375f95f995caecd481d661dcb4ced0ac7

A assinatura será comparada no ambiente de pagamento, caso esteja em

inconformidade ou não seja informada, no retorno haverá a informação de “Transação
negada, assinatura inválida”.

4.2. RETORNO DA SOLICITAÇÃO DE PAGAEMNTO

Para o retorno, na chamada callback é enviada uma assinatura formada utilizando
a mesma regra especificada no item anterior é utilizada, onde todos parâmetros serão
concatenados e utilizará o mesmo processo de criptografia, o cliente fica responsável
em realizar esse procedimento para garantir que uma chamada de call-back está
consistente, garantindo que o ambiente de checkout que realizou a chamada.
Exemplo:
 <FORM ACTION="{URLCALLBACK}">
<input type="hidden" name="TransactionUuid" value="{TransactionUuid}">
<input type="hidden" name="OrderNumber" value="{OrderNumber}">
<input type="hidden" name="Amount" value="{Amount}">
<input type="hidden" name="Installments" value="{Installments}">
<input type="hidden" name="CardNumber" value="{CardNumber}">
<input type="hidden" name="CardBrand" value="{CardBrand}">
<input type="hidden" name="OperationType" value="{OperationType}">
<input type="hidden" name="Success" value="{Success}">
<input type="hidden" name="Message" value="{Message}">
<input type="hidden" name="Signature" value="{Signature}" />
</FORM>

Para a chamada acima, o campo “Signature” foi formado da seguinte maneira:

UrlCallbackTransactionUuidOrderNumberAmountInstallmentsCardNumberCardBrand
OperationTypeSuccessMessage

Primeiro passo da assinatura ficaria da seguinte forma:

urlcallbacktransactionuuidordernumberamountinstallmentscardnumbercardbrandoperationty
pesuccessmessage

Para o último passo, deve ser utilizado o algoritmo de criptografia SHA256, gerando a
sequência de caracteres abaixo:
4956cea198bfbd637256d836a19f2b8896b8a36597a8ce522fed1a2d0d1a5d5a

É recomendado que o cliente gere a assinatura e compare com a sequência enviada

no campo “Signature”, caso não sejam idênticas, essa operação deve ser
desconsiderada, evitando possíveis tentativas de fraudes.

5. GERAÇÃO DE TOKEN DO CARTÃO PARA PAGAMENTO

O ambiente de geração de token também é iniciado através do envio de um
formulário, segue campos que podem ser enviados no formulário, qualquer
campo que não esteja listado aqui será desprezado:

Campo Tipo Obrigatório Descrição

Identificador da requisição,
OrderNumber Alfanumérico Sim mesmo valor será retornado
no callback.
 Contém o par de chaves para
EcommerceIntegration Objeto Sim
identificação

Url que será chamada após a

geração do token.
UrlCallBack Alfanumérico Sim
Obrigatoriamente deve
permitir uma chamada post

Objeto para receber

CustomParams Objeto Não configurações de exibição
adicional.

Objeto “EcommerceIntegration”: informações adicionais do pagador.

Campo Tipo Obrigatório Descrição

Name Alfanumérico Sim Identificador da loja

Password Alfanumérico Sim Senha da loja

Objeto “CustomParams”: No ambiente de pagamento permite a configuração de

alguns elementos, sendo eles listado abaixo.

Campo Tipo Obrigatório Descrição

Url para exibição da logo
acima do formulário de
UrlLogo Alfanumérico Não pagamento, quando não
informada é exibida o nome
fantasia.

5.1. RETORNO DA SOLICTAÇÃO DE GEFRAÇÃO DE TOKEN

Após a geração do token o ambiente fará o envio de um formulário para URL

especificada no call-back (“UrlCallBack”), na solicitação de token, a página da url
especificada deverá esperar um método POST, com um formulário que espere os
campos abaixo:
 Campo Tipo Descrição

Número do pedido enviado na requisição da geração

OrderNumber Alfanumérico
do token.

Token gerado para o cartão informado (pode ser

PaymentToken Alfanumérico utilizada no lugar e um cartão para efetuar
pagamentos).

Success Boolean Indica se o token foi gerado ou não

Message Alfanumérico Mensagem adicional para situações de falha

6. PROCESSO DE PAGAMENTO (Visualização geral)