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://sandbox.ecomm-bin.fiserv.com.br/e-sitef-hml/init/[tipo_de_retorno].se
Ambiente de Produção
https://ecomm-bin.fiserv.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
sandbox.ecomm-bin.fiserv.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",

"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:

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).	< 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": "",

"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
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

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