Servicio de creación de transacciones

Proceso de creación de transacciones#

El proceso de creación de la transacción debe seguir los siguientes pasos:

La transacción se crea de acuerdo con los parámetros enviados en la clave request y se representa mediante un objeto JSON a través de POST en la solicitud;
La tienda recibe un mensaje de éxito o error, con formato XML o JSON, según el parámetro "tipo de retorno" en la URL enviada al iniciar una transacción.

URL para iniciar una transacción a través de HTTPS POST:

Ambiente de Homologación:
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

Atención: Nunca se debe utilizar la IP en lugar del dominio esitef-ec.softwareexpress.com.br (ou esitef-homologacao.softwareexpress.com.br para ambiente de homologação). La IP puede cambiar en cualquier momento y sin previo aviso, por lo que es importante utilizar siempre el dominio para acceder a Portal Carat .

Parámetros POST:

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

Ejemplo de solicitud 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" con algunos parámetros adiccionales:

{
  "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" }]
  }
}

Herramientas de pruebas#

Para las pruebas iniciales en esta interfaz, si es necesario, se pueden utilizar algunas herramientas para comprender mejor la comunicación via REST:

Aplicación para Windows/Linux/Mac:
- POSTMAN
Extención para Firefox:
- RESTClient

Abaixo seguem exemplos de tela destas ferramentas:

POSTMAN -no-filter

RESTClient -no-filter

Parámetros de solicitud#

El objeto JSON additional_data tiene campos que cambian según el autorizador utilizado para el pago, por el campo authorizer_id. Para obtener más detalles sobre el campo additional_data, consulte la documentación específica de cada autorizador compatible con la interfaz de pago HTML 2.0.

Para iniciar una transacción en la nueva interfaz de pago HTML, inicialmente se pueden completar los siguientes parámetros en 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	Descripción	Formato	Obligatorio
`amount`	Importe total a pagar por el comprador. Formato: Debe enviarse en centavos. Ex.: 1000 (10 reales).	< 12 N	SI
`authenticate`	Parámetro que debe enviarse si se requiere la autenticación de los datos de pago del cliente. Valores permitidos: `0`, `1`, `2`, `3` y `4`. Valor predeterminado: `0`	< 1 A	NO
`authorizer_id`	Código de autorizador (en Portal Carat)	< 10 A	NO
`installments`	Número de cuotas de pago. Los siguientes autorizadores no permiten la definición previa del número de cuotas, por lo que en estos casos no se debe enviar este parámetro: PayPal Mercado Pago PagSeguro Envíe el valor `1` para pagos en efectivo.	< 2 N	NO
`installment_type`	Tipo de financiación elegido por el cliente. Valores permitidos: `3` - cuota del administrador (con intereses) `4` - cuota de la tienda (sin intereses) Valor default = `4`	= 1 N	NO
`merchant_id`	Código de tienda de Portal Carat	< 15 A	SI
`merchant_usn`	Código de identificación de la transacción por parte del comerciante.	< 12 A	NO
`order_id`	Código de pedido (en tienda)	< 40 N	NO
`recharge_included`	Informa si se realizará una recarga. Valores permitidos: `true` - si quieres hacer una recarga `false` - si no quieres hacer una recarga Valor predeterminado - `false`	= 5 A	NO
`redirect`	Tipo de redireccionamiento que se realizará al final del flujo de transacción en Portal Carat. Valores permitidos: `A` - Redirección automática (automática): no muestra la pantalla de pago final (incluido el cupón) y redirige automáticamente al cliente a una de las URL en el parámetro `back_url`. El parámetro nit también se envía en la solicitud a través de HTTP GET. `M` - Redirección manual (manual): muestra la pantalla de pago final que incluye el recibo y presenta un enlace para que el cliente haga clic si desea ser redirigido a la tienda. El parámetro `nit` también se envía en la solicitud a través de HTTP POST . Valor predeterminado - `M` (Manual)	= 1 A	NO
`soft_descriptor`	Nome do estabelecimento que será apresentado na fatura do cartão. Saiba mais	< 30 A	NO
`store_card`	Indicador de almacenamiento de la tarjeta utilizada para el pago. Valores permitidos: `true` - indica que la tarjeta utilizada se almacenará. `false` - indica que la tarjeta utilizada no se almacenará. Valor predeterminado - `false` (no se realizará el almacenamiento) Si la tienda envía este campo igual a `true`, el campo`additional_data`.`payer`.`store_identification` se vuelve obligatorio.	< 5 A	NO
`style`	Campo de información para el estilo de redireccionamiento para Portal Carat. Valores permitidos: `N`: redireccionamiento en el mismo marco. `P`: se abrirá una ventana emergente. Valor predeterminado - `N` La tienda debe informar el valor correspondiente a la forma de redirección elegida en la integración, para que Portal Carat pueda manejar adecuadamente las ventanas al final de la transacción. .pago.	= 1 A	NO
`transaction_type`	Tipo de transacción que se llevará a cabo. Valores permitidos: `pago` - Si se realiza un Pago `preautorización` - Si se realiza una Preaautorización <br / > Importe predeterminado - `pago`	< 32 A	NO
`payment_link`	Este campo debe recibir el valor `true` para habilitar la función de pago por link.	< 5 A	NO
`additional_data`	Objeto del tipo ADDITIONALDATA		NO
`back_url`	Objeto del tipo BACKURL		NO
`iata`	Objeto del tipo IATA. Contém informações sobre parcelamento IATA.		NO
`recharge`	Objeto del tipo RECHARGE. Contêm dados relacionados a uma transação de recarga.		NO

BACKURL (`back_url`)#

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

Parámetro	Descripción	Formato	Obrigatorio
`url_success`	URL de redireccionamiento del cliente en caso de éxito. Solo debe tener la ruta relativa al dominio.	< 200 A	NO
`url_failure`	URL de redireccionamiento del cliente en caso de error. Solo debe tener la ruta relativa al dominio.	< 200 A	NO
`url_cancel`	URL de redireccionamiento del cliente en caso de cancelación. Solo debe tener la ruta relativa al dominio.	< 200 A	NO

IATA (`iata`)#

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

Parámetro	Descripción	Formato	Obrigatorio
`departure_tax`	Valor de la tarifa de embarque	< 200 A	NO
`first_installment`	Valor de entrada	< 200 A	NO

ADDITIONALDATA (`additional_data`)#

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

Parámetro	Descripción	Formato	Obrigatorio
`currency`	Moneda predeterminada utilizada para todos los artículos de compra. Código de moneda según [ISO 4217] (http://pt.wikipedia.org/wiki/ISO_4217). Algunos valores permitidos: `BRL` - Real `VEF` - Venezuelan bolívar fuerte `USD` - Dólar Americano `GBP` - Libra esterlina Entre otros. <br / > Si no se envía este parámetro, el Portal Carat usará la configuración de la tienda, y si la tienda no está configurada, se usará el valor `BRL` por defecto.	= 3 A	NO
`method`	Se utiliza para realizar una transacción diferenciada. Valores permitidos: `split`: si desea realizar una transacción SPLIT.	< 1024 AN	NO
`postpone_confirmation`	Campo que permite a la tienda mantener la transacción como Pendiente de Confirmación, y luego confirmarla o deshacerla.	< 5 A	NO
`financing_plan`	Código del plan de financiación. Obligatorio solo para pagos a plazos que devengan intereses realizados a través de Via Certa Financiadora a través de SiTef . Debe enviarse si y solo si el autorizador (campo authorizer_id) con el enrutamiento de Via Certa Financier, las cuotas y las cuotas con interés se definen en esta etapa.	< 4 AN	NO
`max_installments`	Cuotas máximas sin intereses que se presentarán al comprador al finalizar la compra. De ser informado, sobrescribirá el valor configurado en la tienda Portal Carat. Si el adquirente también devuelve una cantidad máxima de cuotas, el valor a utilizar siempre será el menor.	< 3 N	NO
`max_installments_with_interest`	Cuotas máximas con intereses que se presentarán al comprador en el momento del checkout. De ser informado, sobrescribirá el valor configurado en la tienda Portal Carat. Si el adquirente también devuelve una cantidad máxima de cuotas, la cantidad a utilizar siempre será la menor.	< 2 N	NO
`allowed_payment_methods`	Objeto de tipo ALLOWED_PAYMENT_METHODS Consiste en una matriz que contiene todos los métodos de pago que se mostrarán en la pantalla de selección del autorizador del flujo de pago. [Más información.] (# Métodos_de_pago_permitidos-métodos_de_pago_permitidos)		NO
`submerchant_split`	Objeto de tipo SUBMERCHANT_SPLIT Consiste en un arreglo para pagos fraccionados, exclusivo para enrutamiento BIN y Sipag, ambos vía SiTef. Permite la división de partes del monto total del pago entre otras empresas. Funcionalidad exclusiva para pagos (`transaction_type`: `payment`). El número máximo de elementos permitidos en esta Arry es de 5 elementos. Esto no debe usarse junto con el campo `method`:`split` citado anteriormente, y son características diferentes.		NO
`payer`	Objeto de tipo PAGADOR		NO
`mcc`	El MCC (Código de categoría de comerciante) es un código que clasifica una empresa por el tipo de bienes o productos suministrados. Se utiliza en sub-adquisiciones para enrutamiento a través de SiTef.	4 N	NO
`subacquirer_merchant_id`	Identificación de la tienda en el sub adquirente. Se utiliza en sub-adquisiciones para enrutamiento a través de SiTef.	22 N	NO
`transaction_initiated_by`	Indica si la transacción fue iniciada por el comerciante o el comprador. Valores permitidos: `customer`– transacción iniciada por el comprador. `merchant`: transacción iniciada por el comerciante.	< 8 AN	NO
`multiple_payment_methods`	Indica si el comerciante desea permitir que el comprador vea la opción de pago mediante dos métodos de pago. No envíe este campo con el valor "verdadero" al anteponer el autorizador.	< 5 T/F	NO

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	Descripción	Formato	Obligatorio
`submerchant_code`	Código de establecimiento BIN / Sipag	< 15 AN	NO
`submerchant_amount`	valor de transacción para el establecimiento.	< 12 N	NO

PAYER (`payer`)#

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

Parámetro	Descripción	Formato	Obligatorio
`store_identification`	Identificación del comprador para el almacenamiento de la tarjeta. Esta identificación debe ser única para cada usuario de la tienda. Pero atención, esta garantía de unicidad es responsabilidad exclusiva de la tienda, Portal Carat no realizará ninguna validación.	< 20	NO
`identification_number`	Número de identificación del comprador.

ALLOWED_PAYMENT_METHODS[] (`allowed_payment_methods`)#

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

Parámetro	Descripción	Formato
`id`	Código de identificación de la forma de pago que se mostrará en la pantalla del comprador. Se aceptan los siguientes valores: `CRD` - Crédito, `DBT` - Débito, `BLT` - Boleto, `PIX` - Pix, `WLT` - Wallet, `GFT` - Prepago o cupón. Si no se envía ningún valor, se muestran todos los campos permitidos por la configuración de la tienda.	< 3 AN

Nota 1: La especificación de los parámetros del objeto additional_data puede variar según el autorizador. Consulte la documentación específica para este detalle.

Nota 2: En el caso de cuotas prefijadas por los campos installments y installment_type, sin la definición del campo authorizer_id, se aplicarán las siguientes reglas en relación con la presentación de las opciones del autorizador al comprador:
Las opciones de wallets (Visa Checkout, Masterpass, GooglePay), PayPal, PagSeguro e MercadoPago serán omitidas, ya que las opciones de pago a plazos pueden ser elegidas por el comprador en el ambiente del propio método de pago.
En el caso de pagos a plazos (installments > 1), sólo se mostrarán las opciones de crédito y, dentro de estas, solo se mostrarán las configuraciones de cuotas realizadas en el registro de la tienda en Portal Carat corresponden al valor fijo.
Sugerencia: Ajuste esta configuración en Portal Carat según lo acordado con los compradores / métodos de pago. Para más detalles, comuníquese con el equipo de servicio de Portal Carat o acceda al [Portal del comerciante] (portal-lojista-configuracao-autorizadora.md).

Atención: En el caso de pagos enrutados por iCards a través de SiTef, los campos authorizer_id, installments y installment_type deben estar preestablecidos al crear la transacción, no es es posible que el usuario comprador haga esta elección (autorizador, cuotas y tipo de cuota) durante la navegación.

Parámetros de respuesta#

La devolución de la operación de creación de la transacción se da en el formulario solicitado en [tipo de devolución].

A continuación se muestra un ejemplo de un 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"
}

Los campos devueltos se describen en la siguiente tabla:

Parámetro	Descripción	Formato
`responseCode`	Código de respuesta de Portal Carat. Cualquier código que no sea "0" (cero) significa falla. [Más información.] (codigos-da-api.md#codigos-de-resposta)	< 5 N
`description`	Respuesta Descripción	< 1024 A
`url`	Redirigir URL para iniciar el pago.	< 256 A
`nit`	Identificador de transacción en Portal Carat	= 64 A
`nsuesitef`	NSU (Número secuencial único) de la transacción de Portal Carat	= 15 A

Home

Proceso de creación de transacciones#

Herramientas de pruebas#

Parámetros de solicitud#

BACKURL (back_url)#

IATA (iata)#

ADDITIONALDATA (additional_data)#

SUBMERCHANT_SPLIT[] (submerchant_split)#

PAYER (payer)#