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

O lojista cria a transação no Carat 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 Carat 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 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:

Parâmetro	Descrição	Formato	Obrigatório
additional_data	<td colspan="3" />
`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[]	<td colspan="3" /> 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[]	<td colspan="3" />
`ean`	Código EAN do produto.<br/><br/>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.<br/><br/>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<br/> <URLPOSTMAN/>

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<br/> <URLPOSTMAN/>

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
&#123;&#125;
--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

Observação:

Esses campos adicionais também serão mostrados ao serem efetuadas consultas posteriores.

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
`e2eid`	Id enviado pelo PSP na confirmação de pagamento.	< 130 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",
    "e2eid": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  }
}

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<br/> <URLPOSTMAN/>

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:

-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", e preencha as informações referente a chave Pix com a credencial e clique em "Salvar".

-no-filter

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

-no-filter

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

-no-filter

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

-no-filter

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

-no-filter

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

-no-filter

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

-no-filter