Pix via CardSE

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

Informações cadastrais#

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

CampoDescriçãoFormatoObrigatório
pspPrestador de serviços de pagamento. Se não for enviado, será utilizado o valor cadastrado no SiTef.< 8 NNÃO

Pagamento REST#

Fluxo#

  1. O lojista cria a transação no Pagamento Online passando algumas informações adicionais do Pix e recebe o NIT como resposta.
  2. A loja chama o serviço de efetivação de pagamento e recebe um QR code e a transação com status PEN (pendente).
  3. A loja virtual exibe o QR code para o comprador.
  4. O comprador escaneia o QR code com o aplicativo Pix e passa pelo procedimento de confirmação do pagamento solicitado pelo autorizador.
  5. Enquanto o comprador finaliza o pagamento, o Pagamento Online sondará a situação da compra no autorizador até que a transação se encerre.
  6. A loja, por sua vez, deve consultar o status da transação do Pagamento Online 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 Pagamento Online 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:

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.
ParâmetroDescriçãoFormatoObrigatório
additional_data
pix_pspPrestador de serviços de pagamento. Se não for enviado, será utilizado o valor cadastrado no Pagamento Online.< 8 ANNÃO
pix_questionPergunta do lojista para o comprador (será exibida no aplicativo).< 140 ANNÃO
additional_data.pix_data[]
keyIdentificação do campo.< 50 ANNÃO
valueValor do campo.< 200 ANNÃO
additional_data.items[]
eanCódigo EAN do produto.

Atenção: caso o EAN e o SKU sejam enviados simultaneamente, apenas o EAN será considerado.
< 255 ANNÃO
skuCódigo SKU do produto.

Atenção: caso o EAN e o SKU sejam enviados simultaneamente, apenas o EAN será considerado.
< 255 ANNÃO
descriptionDescrição do produto.< 255 ANNÃO
quantityQuantidade do produto a ser adquirido.< 15 NNÃO
quantity_typeTipo da quantidade:
  • u - Unidades
  • g - Gramas
  • ml - Mililitros
< 2 ANNÃO
unit_pricePreço unitário do produto em centavos.< 12 NNÃ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âmetroDescriçãoFormato
authorization_numberNúmero de autorização.< 100 AN

Retornos adicionais na efetivação do pagamento#

ParâmetroDescriçãoFormato
payment
pix_pspPrestador de serviços de pagamento.< 8 AN
pix_answerResposta ao pix_question.< 140 AN
qr_codeQR 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âmetroDescriçãoFormato
cancellation
pix_pspPrestador 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 -no-filter Pix, será exibido um botão para cadastrar suas chaves Pix:

 -no-filter 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 -no-filter.

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

 -no-filter

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

 -no-filter

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

 -no-filter

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