Pix via CardSE · e-SiTef

Esta documentação descreve a integração com PIX através do e-SiTef, utilizando o roteamento CardSE via SiTef.

Informações cadastrais

Além das informações usuais para cadastro no e-SiTef, para integração com Pix será necessário mais um dado:

Campo	Descrição	Formato	Obrigatório
`psp`	Prestador de serviços de pagamento. Se não for enviado, será utilizado o valor cadastrado no SiTef.	< 8 N	NÃO

Pagamento REST

Fluxo

O lojista cria a transação no e-SiTef passando algumas informações adicionais do Pix e recebe o NIT como resposta.
A loja chama o serviço de efetivação de pagamento e recebe um QR code e a transação com status PEN (pendente).
A loja virtual exibe o QR code para o comprador.
O comprador escaneia o QR code com o aplicativo Pix e passa pelo procedimento de confirmação do pagamento solicitado pelo autorizador.
Enquanto o comprador finaliza o pagamento, o e-SiTef sondará a situação da compra no autorizador até que a transação se encerre.
A loja, por sua vez, deve consultar o status da transação do e-SiTef até que ela saia do status PEN.

Atenção:

Se o status da transação permanecer pendente (PEN) após aproximadamente 3 (três) minutos, o e-SiTef irá desfazer a transação junto ao Pix.

Informações adicionais na criação da transação

Para transações com Pix, deve ser utilizado authorizer_id = 440.

Abaixo estão parâmetros adicionais que podem ser enviados em transações Pix:

Parâmetro	Descrição	Formato	Obrigatório
additional_data
`pix_psp`	Prestador de serviços de pagamento. Se não for enviado, será utilizado o valor cadastrado no e-SiTef.	< 8 AN	NÃO
`pix_question`	Pergunta do lojista para o comprador (será exibida no aplicativo).	< 140 AN	NÃO
additional_data.pix_data[]	Lista de conteúdo livre. Permite enviar dados ao aplicativo do cliente como lista de serviços adquiridos, informações promocionais ou outros dados desejados.
`key`	Identificação do campo.	< 50 AN	NÃO
`value`	Valor do campo.	< 200 AN	NÃO
additional_data.items[]
`ean`	Código EAN do produto. Atenção: caso o EAN e o SKU sejam enviados simultaneamente, apenas o EAN será considerado.	< 255 AN	NÃO
`sku`	Código SKU do produto. Atenção: caso o EAN e o SKU sejam enviados simultaneamente, apenas o EAN será considerado.	< 255 AN	NÃO
`description`	Descrição do produto.	< 255 AN	NÃO
`quantity`	Quantidade do produto a ser adquirido.	< 15 N	NÃO
`quantity_type`	Tipo da quantidade: `u` - Unidades `g` - Gramas `ml` - Mililitros	< 2 AN	NÃO
`unit_price`	Preço unitário do produto em centavos.	< 12 N	NÃO

Exemplo:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "merchant_usn":"12042142155",
   "order_id":"12042142155",
   "installments":"1",
   "installment_type":"4",
   "authorizer_id":"440",
   "amount":"1000",
   "additional_data":{
      "pix_psp":"12345678",
      "pix_question":"Deseja receber 10% de desconto para sua proxima compra?",
      "pix_data":[
         {
            "key":"Pontos Ganhos",
            "value":"23"
         },
         {
            "key":"NumPromo",
            "value":"234523452345"
         }
      ],
      "items":[
         {
            "description":"ItemTeste",
            "quantity":"1",
            "sku":"1487337308522",
            "unit_price":"1000",
            "quantity_type":"u"
         },
         {
            "description":"ItemTeste2",
            "quantity":"3",
            "ean":"9283746529384675",
            "unit_price":"2500",
            "quantity_type":"g"
         }
      ]
   }
}
--verbose

Requisição da efetivação do pagamento

Na integração com Pix, não será necessário o envio de nenhum dado do cartão.

Exemplo:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{}
--verbose

Retornos na efetivação do pagamento com tamanho diferente do padrão

Parâmetro	Descrição	Formato
`authorization_number`	Número de autorização.	< 100 AN

Retornos adicionais na efetivação do pagamento

Parâmetro	Descrição	Formato
payment
`pix_psp`	Prestador de serviços de pagamento.	< 8 AN
`pix_answer`	Resposta ao `pix_question`.	< 140 AN
`qr_code`	QR code a ser exibido ao comprador.	< 9999 AN

Atenção:

Em caso de erro de comunicação nesta operação, será necessário criar outra transação.

Exemplo:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"PEN",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"13034649671",
      "authorizer_id":"2",
      "acquirer_id":"1271",
      "acquirer_name":"CardSE",
      "authorizer_date":"13/07/2017T15:52",
      "authorization_number":"132030",
      "merchant_usn":"13034649671",
      "esitef_usn":"170713097340300",
      "sitef_usn":"132030",
      "host_usn":"000000000",
      "payment_date":"13/07/2017T15:52",
      "amount":"1000",
      "authorizer_merchant_id":"000000000000005",
      "pix_psp":"12345678",
      "pix_answer":"No",
      "qr_code":"The quick brown fox jumps over the lazy dog"
   }
}

Pagamento HTML

Não há diferenças no fluxo para a loja.

Assim como no Pagamento REST, podem ser enviados parâmetros adicionais na criação da transação, usando o mesmo formato.

Cancelamento REST

Requisição da efetivação do cancelamento

Na integração com Pix, não será necessário o envio de nenhum dado do cartão.

Exemplo:

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/cancellations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "amount":"1000"
}
--verbose

Retornos adicionais na efetivação do cancelamento

Parâmetro	Descrição	Formato
cancellation
`pix_psp`	Prestador de serviços de pagamento.	< 8 AN

Exemplo:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "cancellation":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":" 1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"09062259711",
      "customer_receipt":"=== COMPROVANTE ===",
      "merchant_receipt":"=== COMPROVANTE ===",
      "authorizer_id":"2",
      "acquirer_id":"1271",
      "acquirer_name":"CardSE",
      "authorizer_date":"09/11/2017T18:23",
      "authorization_number":"092423",
      "merchant_usn":"9062259711",
      "esitef_usn":"171109108051261",
      "sitef_usn":"092424",
      "host_usn":"999092424   ",
      "amount":"1000",
      "payment_type":"O",
      "authorizer_merchant_id":"000000000000000",
      "esitef_date":"09/11/2017T18:23",
      "pix_psp":"12345678"
   }
}

Geração de link de pagamento no Portal do Lojista

Também é possível fazer pagamentos com Pix através de funcionalidade de link de pagamento do Portal Lojista. No entanto, ainda não está disponível a possibilidade do envio das informações adicionais do Pix.

Cadastro de chaves Pix no Portal do Lojista

Ao acessar a configuração de uma autorizadora Pix, será exibido um botão para cadastrar suas chaves Pix:

Ao clicar no botão "Cadastrar Chaves", será exigido o código de autenticação em duas etapas para prosseguir com a operação. Caso esse método de autenticação não esteja habilitado, será exibida na tela instruções sobre qual procedimento deve ser tomado para continuar.

Para mais informações sobre a autenticação em duas etapas e como habilitá-la para realizar cadastro de chaves PIX, clique aqui.

Concluída a autenticação anterior, o usuário será redirecionado para uma tela contendo informações da loja e uma listagem de PSPs:

Selecione o PSP (prestador de serviços de pagamento) que deseja utilizar e clique em "Adicionar":

Preencha a sua chave Pix e suas informações de credencial e clique em "Salvar". Após submeter os seus dados, caso deseje alterar suas informações, clique em "Editar". Se quiser apagá-las, clique em "Remover":

Após realizar todas as alterações desejadas, clique em "Salvar".