Serviço de criar transação

Processo de criação da transação#

O processo de criação de transação deverá seguir os seguintes passos:

A transação é criada conforme os parâmetros enviados na chave request e representados por um objeto JSON via POST na requisição;
A loja recebe uma mensagem de sucesso ou erro, formatada como XML ou JSON, conforme o parâmetro "tipo de retorno" na URL enviada ao se iniciar uma transação.

URL para iniciar uma transação via POST HTTPS:

Ambiente de Homologação:
https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/init/[tipo_de_retorno].se
Ambiente de Produção
https://esitef.softwareexpress.com.br/e-sitef/init/[tipo_de_retorno].se

Atenção: Nunca deve ser usado o IP ao invés do domínio esitef-ec.softwareexpress.com.br (ou {{url}} para ambiente de homologação). O IP pode mudar a qualquer instante e sem aviso prévio, logo é importante sempre utilizar o domínio para acessar o Carat.

Parâmetros de cabeçalho:

Parâmetro	Descrição	Formato	Obrigatório
`merchant_key`	Chave de autenticação da loja no Carat. As chaves de produção e certificação serão diferentes.	< 80 AN	SIM

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-hml/init/json.se"
--header "merchant_key: xxxxxxxxxxx"
--verbose

Parâmetros do POST:

Key/chave: request;
Value/valor: objeto JSON;
[tipo_de_retorno]: json ou xml;

Exemplo de requisição JSON (JavaScriptObjectNotation):

URL: https://{{url}}/e-sitef-hml/init/json.se

Objeto JSON request mínimo:

{
    "merchant_id": "codigoDaLoja",
    "amount": "1800"
}

Objeto JSON "request" com alguns parametros adicionais:

{
    "merchant_id": "codigoDaLoja",
    "order_id": "123456",
    "redirect": "A",
    "installments": "3",
    "installment_type": "4",
    "authorizer_id": "1",
    "amount": "1800",
    "transaction_type":"payment",
    "back_url": {
        "url_success": "",
        "url_failure": "",
        "url_cancel": ""
    },
    "additional_data": {
        "currency": "BRL",
        "method": "",
        "postpone_confirmation": "false",
        "payer": {
            "identification_number": "22222222222",
             "store_identification": "22222222222"
        },
        "max_installments_with_interest":"12",
        "allowed_payment_methods":[
            {"id":"CRD"},
            {"id":"DBT"}
        ]
    }
}

Ferramentas para testes#

Para testes iniciais nesta interface, caso necessário, podem ser usadas algumas ferramentas a fim de um melhor entendimento da comunicação via REST:

Aplicação para Windows/Linux/Mac:
- POSTMAN
Extensão para Firefox:
- RESTClient

Abaixo seguem exemplos de tela destas ferramentas:

POSTMAN -no-filter

RESTClient -no-filter

Parâmetros de requisição#

O objeto JSON additional_data possui campos que se alteram conforme a autorizadora utilizada para o pagamento, pelo campo authorizer_id. Para mais detalhes do campo additional_data, por favor consulte a documentação específica para cada autorizadora suportada pela Interface de Pagamento HTML 2.0.

Para iniciar uma transação na nova interface de pagamento HTML, inicialmente podem ser preenchidos os seguintes parâmetros no formato JSON.

{
  "amount": "120000",
  "authenticate": "false",
  "authorizer_id": "1",
  "installments": "1",
  "installment_type": "4",
  "merchant_id": "LOJATESTE",
  "merchant_usn": "999888",
  "order_id": "order123",
  "recharge_included": "false",
  "redirect": "M",
  "soft_descriptor": "softDescriptor",
  "store_card": "false",
  "style": "N",
  "transaction_type": "payment",
  "payment_link":"false",
  "additional_data": { },
  "back_url": { },
  "iata": { },
  "recharge": { }
}

Parâmetro	Descrição	Formato	Obrigatório
`amount`	Valor total a ser pago pelo comprador. Formato: Deve ser enviado em centavos. Ex.: 1000 (10 reais).	< 12 N	SIM
`authenticate`	Parâmetro que deve ser enviado caso seja necessária a autenticação dos dados de pagamento do cliente. Valores permitidos: `0`, `1`, `2`, `3` e `4`. Valor default – `0` Observação: Transações de débito habilitarão a autenticação por padrão caso a loja esteja configurada com dados de 3DS, sobrescrevendo assim quaisquer outras opções que possam desabilitar esse método de autenticação.	< 1 A	NÃO
`authorizer_id`	Código da Autorizadora (no Carat)	< 10 A	NÃO
`installments`	Número de parcelas do pagamento. As seguintes autorizadoras não permitem a definição prévia do número de parcelas, logo nesses casos este parâmetro não deve ser enviado: PayPal Mercado Pago PagSeguro Enviar o valor `1` para pagamentos à vista.	< 2 N	NÃO
`installment_type`	Tipo do financiamento escolhido pelo cliente. Valores permitidos: `3` – parcelado administradora (com juros) `4` – parcelado loja (sem juros) Valor default = `4`	= 1 N	NÃO
`merchant_id`	Código da loja no Carat	< 15 A	SIM
`merchant_usn`	Código de identificação da transação pelo lojista.	< 12 A	NÃO
`order_id`	Código do pedido (na loja)	< 40 N	NÃO
`recharge_included`	Informa se uma recarga será feita. Valores permitidos: `true` – caso se deseje fazer uma recarga `false` – caso não se deseje fazer uma recarga Valor default – `false`	= 5 A	NÃO
`redirect`	Tipo de redirecionamento que será realizado ao finalizar o fluxo de transação no Carat. Valores permitidos: `A` – (Automático) redirecionamento automático: não mostra a tela final do pagamento (incluindo o comprovante) e redireciona o cliente automaticamente para uma das URL's do parâmetro `back_url`. O parâmetro nit também é enviado na requisição via HTTP GET. `M` – (Manual) redirecionamento manual: Mostra a tela final do pagamento incluindo o comprovante e apresenta um link para o cliente clicar caso deseje ser redirecionado para a loja. O parâmetro `nit` também é enviado na requisição via HTTP POST. Valor default – `M` (Manual)	= 1 A	NÃO
`soft_descriptor`	Nome do estabelecimento que será apresentado na fatura do cartão. Saiba mais	< 30 A	NÃO
`store_card`	Indicador de armazenamento de cartão utilizado no pagamento. Valores permitidos: `true` – indica que o cartão utilizado será armazenado. `false` – indica que o cartão utilizado não será armazenado. Valor default – `false` (não será realizado o armazenamento) Caso a loja envie este campo igual a `true`, o campo `additional_data`.`payer`.`store_identification` passa a ser obrigatório.	< 5 A	NÃO
`style`	Campo informativo para o estilo de redirecionamento para o Carat. Valores permitidos: `N` – Redirecionamento no mesmo frame. `P` – Um pop-up será aberto. Valor default – `N` A loja deve informar o valor correspondente à forma de redirecionamento escolhida na integração, para que o Carat faça um tratamento adequado das janelas ao final da transação de pagamento.	= 1 A	NÃO
`transaction_type`	Tipo de transação que será realizada. Valores permitidos: `payment` – Caso seja realizado um Pagamento `preauthorization` – Caso seja realizada uma Pré Autorização Valor default – `payment`	< 32 A	NÃO
`payment_link`	Este campo deve receber o valor `true` para ativar a funcionalidade de pagamento com link.	< 5 A	NÃO
`additional_data`	Objeto do tipo ADDITIONALDATA		NÃO
`back_url`	Objeto do tipo BACKURL		NÃO
`iata`	Objeto do tipo IATA. Contém informações sobre parcelamento IATA.		NÃO
`recharge`	Objeto do tipo RECHARGE. Contêm dados relacionados a uma transação de recarga.		NÃO

BACKURL (`back_url`)#

{
    "url_cancel": "/cancel",
    "url_failure": "/failure",
    "url_success": "/success"
}

Parâmetro	Descrição	Formato	Obrigatório
`url_success`	URL de redirecionamento do cliente em caso de sucesso. Deve possuir apenas o caminho relativo ao domínio.	< 200 A	NÃO
`url_failure`	URL de redirecionamento do cliente em caso de fracasso. Deve possuir apenas o caminho relativo ao domínio.	< 200 A	NÃO
`url_cancel`	URL de redirecionamento do cliente em caso de cancelamento. Deve possuir apenas o caminho relativo ao domínio.	< 200 A	NÃO

IATA (`iata`)#

{
    "departure_tax": "1000",
    "first_installment": "20000"
}

Parâmetro	Descrição	Formato	Obrigatório
`departure_tax`	Valor de taxa de embarque	< 200 A	NÃO
`first_installment`	Valor de entrada	< 200 A	NÃO

ADDITIONALDATA (`additional_data`)#

{
    "currency": "BRL",
    "method": "",
    "postpone_confirmation": "false",
    "financing_plan": "",
    "payer": { },
    "allowed_payment_methods": [],
    "max_installments_with_interest": ""
}

Parâmetro	Descrição	Formato	Obrigatório
`currency`	Moeda utilizada padrão para todos itens da compra. Código da moeda segundo a ISO 4217. Alguns valores permitidos: `BRL` – Real `VEF` – Venezuelan bolívar fuerte `USD` – Dólar Americano `GBP` – Libra Esterlina Entre outros. Caso esse parâmetro não seja enviado, o Carat utilizará a configuração da loja, e se a loja não estiver configurada, será utilizado como padrão o valor `BRL`.	= 3 A	NÃO
`method`	Usado para realizar uma transação diferenciada. Valores permitidos: `split` – Caso se deseje fazer uma transação SPLIT.	< 1024 AN	NÃO
`postpone_confirmation`	Campo que permite que loja mantenha a transação como Pendente de Confirmação, e posteriormente, confirmá-la ou desfazê-la.	< 5 A	NÃO
`financing_plan`	Código de plano de financiamento. Necessário apenas para pagamentos com parcelamento com juros efetuados com roteamento Via Certa Financiadora via SiTef. Deve ser enviado se e somente se forem definidos, nesta etapa, a autorizadora (campo authorizer_id) com roteamento Via Certa Financiadora, as parcelas e o parcelamento com juros.	< 4 AN	NÃO
`max_installments`	Máximo de parcelas sem juros que será apresentado para o comprador no momento do checkout. Caso informado, sobrescreverá o valor configurado na loja do Carat. Caso a adquirente também retorne um valor máximo de parcelas, o valor a ser utilizado será sempre o menor.	< 3 N	NÃO
`max_installments_with_interest`	Máximo de parcelas com juros que será apresentado para o comprador no momento do checkout. Caso informado, sobrescreverá o valor configurado na loja do Carat. Caso a adquirente também retorne um valor máximo de parcelas, o valor a ser utilizado será sempre o menor.	< 2 N	NÃO
`allowed_payment_methods`	Objeto do tipo ALLOWED_PAYMENT_METHODS Consiste em um array contendo todos os métodos de pagamento que serão exibidos na tela de seleção de autorizadora do fluxo de pagamento. Saiba mais.		NÃO
`submerchant_split`	Objeto do tipo SUBMERCHANT_SPLIT Consiste em um array para pagamentos split, exclusivos para roteamentos BIN e Sipag, ambos via SiTef. Permite a divisão de partes do valor total do pagamento entre outras empresas. Funcionalidade exclusiva para pagamentos (`transaction_type`:`payment`). O máximo de itens permitido neste array é de 5 itens. Este não deve ser usado juntamente com o campo `method`:`split` citado acima, e são funcionalidades diferentes.		NÃO
`payer`	Objeto do tipo PAYER		NÃO
`mcc`	O MCC (Merchant Category Code) é um código que classifica um negócio pelo tipo de bens ou produtos fornecidos. É usado na subadquirência para roteamentos via SiTef.	4 N	NÃO
`subacquirer_merchant_id`	Identificação da loja na subadquirente. É usado na subadquirência para roteamentos via SiTef.	22 N	NÃO
`transaction_initiated_by`	Indica se a transação foi iniciada pelo Lojista ou pelo Comprador. Valores permitidos: `customer` – Transação iniciada pelo Comprador. `merchant` – Transação iniciada pelo Lojista.	< 8 AN	NÃO
`multiple_payment_methods`	Indica se o lojista deseja permitir que o comprador visualize a opção de pagar usando dois meios de pagamento. Não enviar este campo com valor `true` quando prefixar autorizadora.	< 5 T/F	NÃO

SUBMERCHANT_SPLIT[] (`submerchant_split`)#

[
   {
      "submerchant_code":"empresa01",
      "submerchant_amount":"120"
   },
   {
      "submerchant_code":"empresa02",
      "submerchant_amount":"420"
   },
   {
      "submerchant_code":"empresa03",
      "submerchant_amount":"300"
   },
   {
      "submerchant_code":"empresa04",
      "submerchant_amount":"400"
   },
   {
      "submerchant_code":"empresa05",
      "submerchant_amount":"250"
   }
]

Parâmetro	Descrição	Formato	Obrigatório
`submerchant_code`	código de estabelecimento BIN/Sipag	< 15 AN	NÃO
`submerchant_amount`	valor de transação referente ao estabelecimento.	< 12 N	NÃO

PAYER (`payer`)#

{
    "store_identification": "card_1",
    "identification_number": "123123123"
}

Parâmetro	Descrição	Formato	Obrigatório
`store_identification`	Identificação do comprador para armazenamento de cartão. Esta identificação deve ser única para cada usuário da loja. Mas atenção, essa garantia de unicidade é de total responsabilidade da loja, o Carat não realizará nenhuma validação.	< 20	NÃO
`identification_number`	Número de identificação do comprador.

ALLOWED_PAYMENT_METHODS[] (`allowed_payment_methods`)#

[
   {
      "id":"CRD"
   },
   {
      "id":"DBT"
   },
   {
      "id":"WLT"
   }
]

Parâmetro	Descrição	Formato	Obrigatório
`id`	Código identificador do método de pagamento a ser exibido na tela do comprador. São aceitos os seguintes valores: `CRD` - Crédito, `DBT` - Débito, `BLT` - Boleto, `PIX` - Pix, `WLT` - Wallet, `GFT` - Pré-pago ou voucher. Caso nenhum valor seja enviado, são exibidos todos os campos permitidos pela configuração da loja.	< 3 AN	NÃO

Nota 1: A especificação dos parâmetros do objeto additional_data pode variar conforme autorizadora. Consulte a documentação específica para este detalhamento.

Nota 2: No caso de parcelamento pré-fixado pelos campos installments e installment_type, sem a definição do campo authorizer_id, as seguintes regras serão aplicadas em relação à apresentação de opções de autorizadoras para o comprador:
As opções de wallets (Visa Checkout, Masterpass, GooglePay), PayPal, PagSeguro e MercadoPago serão omitidas, pois as opções de parcelamento podem ser escolhidas pelo comprador no ambiente do próprio meio de pagamento.
No caso de pagamentos parcelados (installments > 1), serão apresentadas apenas as opções de crédito e, dentro destas, somente serão mostradas as que as configurações de parcelamento feitas no cadastro da loja no Carat correspondam ao valor fixado.
Sugestão: Ajuste estas configurações no Carat conforme o acordado com as adquirentes / meios de pagamento. Para mais detalhes, entre em contato com a equipe de atendimento Carat ou acesse o Portal do Lojista.

Atenção: No caso de pagamentos roteados por iCards via SiTef, os campos authorizer_id, installments e installment_type devem ser pré-fixados na criação da transação, não sendo possível para o usuário comprador efetuar esta escolha (autorizadora, parcelas e tipo de parcelamento) durante a navegação.

Parâmetros de resposta#

O retorno da operação de criação de transação se dá na forma solicitada no [tipo de retorno].

Abaixo segue um exemplo de retorno JSON:

{
  "responseCode": 0,
  "description": "OK. Transaction successful.",
  "url": "https:// {{url}}/e-sitef/do.se?input['nit']= 1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
  "nsuesitef": "123456789012345",
  "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
}

Os campos retornados são descritos na tabela abaixo:

Parâmetro	Descrição	Formato
`responseCode`	Código de resposta do Carat. Qualquer código diferente de `0`(zero) significa falha. Saiba mais.	< 5 N
`description`	Descrição da resposta	< 1024 A
`url`	URL de redirecionamento para iniciar o pagamento.	< 256 A
`nit`	Identificador da transação no Carat	= 64 A
`nsuesitef`	NSU (Número Sequencial Único) da transação no Carat	= 15 A

Home

Processo de criação da transação#

Exemplo#

Ferramentas para testes#

Parâmetros de requisição#

BACKURL (back_url)#

IATA (iata)#

ADDITIONALDATA (additional_data)#

SUBMERCHANT_SPLIT[] (submerchant_split)#

PAYER (payer)#