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:

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).
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==",
        "wallet_type": "network_token"
    }
}'

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#