Pagamento

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

Informações cadastrais

Além das informações usuais para cadastro no Carat, 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

1. O lojista cria a transação no Carat 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 Carat 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 Carat 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 Carat 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â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 Carat.	< 8 AN	NÃO
pix_question	Pergunta do lojista para o comprador (será exibida no aplicativo).	< 140 AN	NÃO
ecomm_pos_ref	Este campo enviará uma identificação que constará no relatório do SiTef Web para transações e-commerce.	< 8 AN	NÂO
additional_data.pix_data[]
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.	< 17 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.	< 17 AN	NÃO
description	Descrição do produto.	< 30 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:

Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br

curl

--request POST "https://{{url}}/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"

}

],

"ecomm_pos_ref":"12345678"

}

}

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

Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br

curl

--request POST "https://{{url}}/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
host_usn	NSU da autorizadora.	< 30 AN

Retornos adicionais na efetivação do pagamento

Parâmetro	Descrição	Formato
payment
pix_psp	Prestador de serviços de pagamento. Só é retornado para o Pix com expiração Longa	< 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 do cancelamento

(Modelo V1 - Dupla requisição: Criação + Efetivação)

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

Assim como no Cancelamento REST serviço-criação-de-cancelamento, é necessário criar o serviço inicial de cancelamento Pix antes de efetivar o cancelamento, usando o mesmo formato.

Exemplo efetivação de cancelamento:

Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br

curl

--request PUT "https://{{url}}/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. Só é retornado para o Pix com expiração Longa	< 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:

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:

Selecione o PSP (prestador de serviços de pagamento) que deseja utilizar e clique em "Adicionar", e preencha as informações referente a chave Pix com a credencial e clique em "Salvar".

Alguns PSPs solicita o CNPJ com credencial habilita para transacionar, incluir o CNPJ e clique em "Confirmar".

Caso deseja alterar as informações da credencial, clique em "Editar credencial".

Após clicar em "Editar credencial" será exibido os campos referente a credencial, conforme abaixo.

Caso não queira realizar alterações referente a credencial, clicar em "Cancelar", assim não será alterado a credencial.

Se quiser apagar uma chave Pix cadastrada, clicar em "Remover".

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