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

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ámetroDescripciónFormatoObligatorio
amountImporte total a pagar por el comprador.
Formato:
Debe enviarse en centavos.
Ex.: 1000 (10 reales).
< 12 NSI
authenticatePará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 ANO
authorizer_idCódigo de autorizador (en Portal Carat) < 10 ANO
installmentsNú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 NNO
installment_typeTipo 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 NNO
merchant_idCódigo de tienda de Portal Carat < 15 ASI
merchant_usnCódigo de identificación de la transacción por parte del comerciante. < 12 ANO
order_idCódigo de pedido (en tienda) < 40 NNO
recharge_includedInforma si se realizará una recarga.
Valores permitidos:
true - si quieres hacer una recarga
false - si no quieres hacer una recarga
Valor predeterminado - false
= 5 ANO
redirectTipo 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 ANO
soft_descriptorNome do estabelecimento que será apresentado na fatura do cartão. Saiba mais< 30 ANO
store_cardIndicador 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) .
< 5 ANO
styleCampo 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 ANO
transaction_typeTipo 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 ANO
payment_linkEste campo debe recibir el valor true para habilitar la función de pago por link. < 5 ANO
additional_dataObjeto del tipo ADDITIONALDATANO
back_urlObjeto del tipo BACKURLNO
iataObjeto del tipo IATA. Contém informações sobre parcelamento IATA.NO
rechargeObjeto 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ámetroDescripciónFormatoObrigatorio
url_successURL de redireccionamiento del cliente en caso de éxito. Solo debe tener la ruta relativa al dominio. < 200 ANO
url_failureURL de redireccionamiento del cliente en caso de error. Solo debe tener la ruta relativa al dominio. < 200 ANO
url_cancelURL de redireccionamiento del cliente en caso de cancelación. Solo debe tener la ruta relativa al dominio. < 200 ANO

IATA (iata)#

{
"departure_tax": "1000",
"first_installment": "20000"
}
ParámetroDescripciónFormatoObrigatorio
departure_taxValor de la tarifa de embarque< 200 ANO
first_installmentValor de entrada< 200 ANO

ADDITIONALDATA (additional_data)#

{
"currency": "BRL",
"method": "",
"postpone_confirmation": "false",
"financing_plan": "",
"payer": { },
"allowed_payment_methods": [],
"max_installments_with_interest": ""
}
ParámetroDescripciónFormatoObrigatorio
currencyMoneda 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 ANO
methodSe utiliza para realizar una transacción diferenciada.

Valores permitidos:
split: si desea realizar una transacción SPLIT.
< 1024 ANNO
postpone_confirmationCampo que permite a la tienda mantener la transacción como Pendiente de Confirmación, y luego confirmarla o deshacerla. < 5 ANO
financing_planCó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 ANNO
max_installmentsCuotas 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 NNO
max_installments_with_interestCuotas 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 NNO
allowed_payment_methodsObjeto 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
mccEl 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 NNO
subacquirer_merchant_idIdentificación de la tienda en el sub adquirente. Se utiliza en sub-adquisiciones para enrutamiento a través de SiTef.22 NNO
transaction_initiated_byIndica 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 ANNO
multiple_payment_methodsIndica 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/FNO
ParámetroDescripciónFormatoObligatorio
store_identificationIdentificació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.
< 20NO
identification_numberNúmero de identificación del comprador.

ALLOWED_PAYMENT_METHODS[] (allowed_payment_methods)#

[
{
"id":"CRD"
},
{
"id":"DBT"
},
{
"id":"WLT"
}
]
ParámetroDescripciónFormato
idCó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ámetroDescripciónFormato
responseCodeCó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
descriptionRespuesta Descripción < 1024 A
urlRedirigir URL para iniciar el pago. < 256 A
nitIdentificador de transacción en Portal Carat= 64 A
nsuesitefNSU (Número secuencial único) de la transacción de Portal Carat= 15 A