Pagamento REST

Visão Geral#

O Carat possui duas interfaces para integração com a loja virtual, POST/HTML e Web Services (REST), possibilitando a maneira adequada de interação da loja com o Carat, conforme a linguagem e plataforma de execução da loja virtual.

Na interface REST, a coleta dos dados do cartão e do pagamento será realizada pela Loja Virtual e o Carat apenas se encarregará de efetuar o pagamento com a instituição financeira.

Nessa interface estão disponíveis os pagamentos com cartão de crédito, débito ou voucher. Para pagamentos via banco como transferência bancária, boleto, utilize a interface POST/HTML.

E para saber mais sobre essas nomenclaturas (Bin, Software Express, Carat, e-Sitef) Saiba mais

Comunicação#

Para realizar uma transação Web Service, toda a comunicação será realizada via HTTPS/SSL. É importante que o servidor do lojista suporte criptografia com no mínimo 128 bits. O servidor da loja deverá realizar chamadas em endereços específicos para transações REST.

Cada serviço deve ser chamado utilizando a URL base concatenada do recurso desejado (veja o capítulo referente ao serviço a ser consumido). O método HTTP (GET, POST ou PUT) indica a ação esperada sobre o recurso escolhido. Abaixo estão as URLs base do Carat:

URL base de Produção:

https://esitef.softwareexpress.com.br/e-sitef/api

URL base de Homologação:

https://esitef-homologacao.softwareexpress.com.br/e-sitef/api

Todas as chamadas realizadas para os serviços serão respondidas de forma síncrona.

Atenção:

Nunca utilize o IP ao invés do domínio esitef.softwareexpress.com.br. O IP pode mudar a qualquer momento e sem aviso prévio, portanto é importante a utilização do domínio para acesso ao Carat.

Importante:

Além dos parâmetros de retorno dos serviços descritos nesta especificação o Carat poderá devolver outros parâmetros sem aviso prévio.

É importante que o aplicativo esteja preparado para receber os parâmetros desconhecidos além dos parâmetros já especificados e simplesmente desprezá-los.

Fluxo#

O fluxo de pagamento será iniciado pela aplicação da loja virtual após o cliente finalizar a compra e preencher suas informações de pagamento.

Existem dois tipos de fluxo de pagamento: com confirmação automática, onde o Carat se responsabiliza por confirmar o pagamento com a adquirente, e com confirmação tardia, onde a aplicação se responsabiliza por confirmar o pagamento, consumindo o serviço de confirmação.

A confirmação tardia geralmente é utilizada quando a aplicação da loja virtual permite o pagamento com mais de um cartão ou se realiza alguma validação antes de efetuar o pagamento.

Pagamento com confirmação automática#

Descrição do fluxo:

  1. O lojista cria uma transação via API passando informações como código da loja, número de parcelas e código de pedido e obtém como resposta um NIT (Número Identificador de Transação).
  2. A loja virtual prossegue então consumindo o serviço de efetivação do pagamento, passando o NIT e os dados do cartão do comprador. Em caso de sucesso, a transação de pagamento mudará seu status para CON (confirmada).

Exemplo

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

Requisição:

curl --location 'https://{{url}}/e-sitef/api/v2/payments/' --header 'Content-Type: application/json' --header 'merchant_id: xxxxxxxxx' --header 'merchant_key: xxxxxxxxxxxxxx' --data '{
"merchant_usn": "12050620649",
"order_id":"1686591679260",
"installments": "1",
"installment_type": "4",
"authorizer_id": "2",
"amount": "1100",
"card": {
"expiry_date": "1222",
"security_code": "123",
"number": "5555555555555555",
"cryptogram": "ALRzlt6NKQtPAAZAkOuIAAADFA=="
}
}'

Resposta obdita: (Repare no status da transação, que é CON de Confirmada)

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "000",
"authorizer_message": "APROVADA",
"status": "CON",
"nit": "dc8a370d394e3868de756b53b912a3b41cffdf28e26bff405ddb20737bce5e06",
"order_id": "1686591679260",
"customer_receipt": "==== customer receipt ====",
"merchant_receipt": "==== merchant receipt ====",
"authorizer_id": "2",
"acquirer_id": "229",
"acquirer_name": "Bin",
"authorizer_date": "12/06/2023T14:41",
"authorization_number": "000026",
"merchant_usn": "12050620649",
"esitef_usn": "230612015722270",
"sitef_usn": "000026",
"host_usn": "006000026 ",
"amount": "1100",
"payment_type": "C",
"issuer": "2",
"authorizer_merchant_id": "000000000000000",
"terminal_id": "ES000001",
"payment_date": "12/06/2023T14:41",
"recurrency_tid": "999988887777666"
}
}

Pagamento com confirmação tardia#

Descrição do fluxo:

  1. Assim como no fluxo de pagamento com confirmação automática, o lojista cria uma transação na API passando os dados do pagamento. Adicionalmente, ele deve enviar o parâmetro postpone_confirmation com valor true.
  2. A loja virtual prossegue então consumindo o serviço de efetivação do pagamento, passando o NIT e os dados do cartão do comprador. Em caso de sucesso, a transação de pagamento mudará seu status para PPC (pagamento pendente de confirmação).
  3. Concluindo, a loja virtual chama o serviço de confirmação do pagamento, passando o NIT novamente e o parâmetro confirm com valor true, resultando numa transação com status CON (confirmada). Também existe a possibilidade do lojista desfazer a transação em vez de confirmar. Para isso, o parâmetro confirm deve ser enviado com valor false, o que resultará numa transação com status PPN (desfeita).

Exemplo

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

Note o parâmetro postpone_confirmation incluído com o valor true, bem como o status retornado, que agora é PPC.

curl --location 'https://{{url}}/e-sitef/api/v2/payments/' --header 'Content-Type: application/json' --header 'merchant_id: xxxxxxxxx' --header 'merchant_key: xxxxxxxxxxxxxx' --data '{
"merchant_usn": "12050620649",
"order_id":"1686592079260",
"installments": "1",
"installment_type": "4",
"authorizer_id": "2",
"amount": "1100",
"card": {
"expiry_date": "1222",
"security_code": "123",
"number": "5555555555555555",
"cryptogram": "ALRzlt6NKQtPAAZAkOuIAAADFA=="
},
"additional_data": {
"postpone_confirmation": "true"
}
}'

Resposta obdita:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "000",
"authorizer_message": "APROVADA",
"status": "PPC",
"nit": "7321992585edcd4683b3a242426cb30f9a1643dbcea634a55ae81599d8ea5081",
"order_id": "1686592079260",
"customer_receipt": " ==== customer receipt ====",
"merchant_receipt": " ==== merchant receipt ====",
"authorizer_id": "2",
"acquirer_id": "229",
"acquirer_name": "Bin",
"authorizer_date": "12/06/2023T14:48",
"authorization_number": "000027",
"merchant_usn": "12050620649",
"esitef_usn": "230612015722290",
"sitef_usn": "000027",
"host_usn": "006000027 ",
"amount": "1100",
"payment_type": "C",
"issuer": "2",
"authorizer_merchant_id": "000000000000000",
"terminal_id": "ES000001",
"payment_date": "12/06/2023T14:48",
"recurrency_tid": "999988887777666"
}
}