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-ec.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 esitef-homologacao.softwareexpress.com.br 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âmetroDescriçãoFormatoObrigatório
merchant_keyChave de autenticação da loja no Carat. As chaves de produção e certificação serão diferentes.< 80 ANSIM

Exemplo#

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/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://esitef-homologacao.softwareexpress.com.br/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:

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âmetroDescriçãoFormatoObrigatório
amountValor total a ser pago pelo comprador.
Formato:
Deve ser enviado em centavos.
Ex.: 1000 (10 reais).
< 12 NSIM
authenticateParâ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 ANÃO
authorizer_idCódigo da Autorizadora (no Carat)< 10 ANÃO
installmentsNú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 NNÃO
installment_typeTipo do financiamento escolhido pelo cliente.
Valores permitidos:
3 – parcelado administradora (com juros)
4 – parcelado loja (sem juros)
Valor default = 4
= 1 NNÃO
merchant_idCódigo da loja no Carat< 15 ASIM
merchant_usn Código de identificação da transação pelo lojista.< 12 ANÃO
order_idCódigo do pedido (na loja)< 40 NNÃO
recharge_includedInforma 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 ANÃO
redirectTipo 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 ANÃO
soft_descriptorNome do estabelecimento que será apresentado na fatura do cartão. Saiba mais< 30 ANÃO
store_cardIndicador 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 ANÃO
styleCampo 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 ANÃO
transaction_typeTipo 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 ANÃO
payment_linkEste campo deve receber o valor true para ativar a funcionalidade de pagamento com link.< 5 ANÃO
additional_dataObjeto do tipo ADDITIONALDATANÃO
back_urlObjeto do tipo BACKURLNÃO
iataObjeto do tipo IATA. Contém informações sobre parcelamento IATA.NÃO
rechargeObjeto 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âmetroDescriçãoFormatoObrigatório
url_successURL de redirecionamento do cliente em caso de sucesso. Deve possuir apenas o caminho relativo ao domínio.< 200 ANÃO
url_failureURL de redirecionamento do cliente em caso de fracasso. Deve possuir apenas o caminho relativo ao domínio.< 200 ANÃO
url_cancelURL de redirecionamento do cliente em caso de cancelamento. Deve possuir apenas o caminho relativo ao domínio.< 200 ANÃO

IATA (iata)#

{
"departure_tax": "1000",
"first_installment": "20000"
}
ParâmetroDescriçãoFormatoObrigatório
departure_taxValor de taxa de embarque< 200 ANÃO
first_installmentValor de entrada< 200 ANÃO

ADDITIONALDATA (additional_data)#

{
"currency": "BRL",
"method": "",
"postpone_confirmation": "false",
"financing_plan": "",
"payer": { },
"allowed_payment_methods": [],
"max_installments_with_interest": ""
}
ParâmetroDescriçãoFormatoObrigatório
currencyMoeda 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 ANÃO
methodUsado para realizar uma transação diferenciada.

Valores permitidos:
split – Caso se deseje fazer uma transação SPLIT.
< 1024 ANNÃO
postpone_confirmationCampo que permite que loja mantenha a transação como Pendente de Confirmação, e posteriormente, confirmá-la ou desfazê-la.< 5 ANÃO
financing_planCó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 ANNÃO
max_installmentsMá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 NNÃO
max_installments_with_interestMá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 NNÃO
allowed_payment_methodsObjeto 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_splitObjeto 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
payerObjeto do tipo PAYERNÃO
mccO 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 NNÃO
subacquirer_merchant_idIdentificação da loja na subadquirente. É usado na subadquirência para roteamentos via SiTef.22 NNÃO
transaction_initiated_byIndica 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 ANNÃO
multiple_payment_methodsIndica 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/FNÃ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âmetroDescriçãoFormatoObrigatório
submerchant_codecódigo de estabelecimento BIN/Sipag< 15 ANNÃO
submerchant_amountvalor de transação referente ao estabelecimento.< 12 NNÃO

PAYER (payer)#

{
"store_identification": "card_1",
"identification_number": "123123123"
}
ParâmetroDescriçãoFormatoObrigatório
store_identificationIdentificaçã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.
< 20NÃO
identification_numberNúmero de identificação do comprador.

ALLOWED_PAYMENT_METHODS[] (allowed_payment_methods)#

[
{
"id":"CRD"
},
{
"id":"DBT"
},
{
"id":"WLT"
}
]
ParâmetroDescriçãoFormatoObrigatório
idCó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 ANNÃ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:// esitef-homologacao.softwareexpress.com.br/e-sitef/do.se?input['nit']= 1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"nsuesitef": "123456789012345",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
}

Os campos retornados são descritos na tabela abaixo:

ParâmetroDescriçãoFormato
responseCodeCódigo de resposta do Carat. Qualquer código diferente de 0(zero) significa falha. Saiba mais.< 5 N
descriptionDescrição da resposta< 1024 A
urlURL de redirecionamento para iniciar o pagamento.< 256 A
nitIdentificador da transação no Carat= 64 A
nsuesitefNSU (Número Sequencial Único) da transação no Carat= 15 A