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://<URLPOSTMANPROD/>/e-sitef/api

URL base de Homologação:

https://<URLPOSTMAN/>/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 <URLPOSTMANPROD/>. 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<br/> <URLPOSTMAN/>

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

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

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