Preautorización
Descripción general#
Portal Carat es una gateway de pago multiservicio capaz de procesar transacciones con tarjetas de crédito, transferencias bancarias, generación de facturas, integración con opciones de mobile payment,, entre otros servicios que se pueden agregar fácilmente a la plataforma.
Portal Carat tiene dos interfaces para la integración con la Tienda Virtual, la Interfaz HTML y Web Services, permitiendo la forma adecuada de interacción de la tienda con el Portal Carat, según el idioma y la plataforma de ejecución de la tienda virtual.
La interfaz REST proporciona pagos con tarjeta de crédito, preautorización, captura de preautorización y recarga móvil de prepago.
Para pagos a través de banco, como transferencia bancaria, boleto, utilice la interfaz HTML; La recarga móvil prepago también está disponible en la interfaz HTML.
Proceso de certificación#
El proceso de certificación de la aplicación integrada al Portal Carat será realizado por el equipo de Soporte de Authorizadores/Portal Carat. Es responsabilidad del cliente informar al Soporte Técnico que se ha completado el desarrollo de la aplicación, para que se realicen las mediadas necesarias para realizar la certificación.
Para hacerlo, el cliente debe contactar autorizadores5317@softwareexpress.com.br
Solo la aplicación que complete con éxito el proceso de Certificación podrá entrar en producción; La certificación, por tanto, es un proceso obligatorio
Enrutamiento compatible#
La función de preautorización de Portal Carat admite las siguientes enrutamientos:
- Rede (via SiTef)
- Cielo (via SiTef)
- Amex (via SiTef)
- GetNetLac (via SiTef)
- Safra (via SiTef)
- Adiq (via SiTef)
- BIN (via SiTef)
- Sipag (via SiTef)
- iCards (via SiTef)
- e-Rede
- GetNet WS
- GlobalPayments WS
- Cielo e-Commerce
- Stone WS
- EPX
##Configuración de Portal Carat necesaria
El uso de la funcionalidad de preautorización siempre debe tener su permiso habilitado por los equipos de soporte (entorno de certificación) y Producción (entorno de producción).
Integración de preautorización, captura de preautorización y cancelación a través del Web Service REST#
El propósito de este documento es describir la interfaz de preautorización a través de REST donde la recopilación de parámetros será realizado por la Tienda Virtual y el Portal Carat solo realizará la transacción con la red adquirente/enrutamiento.
La preautorización es una transacción cuyo valor se reservará del límite de la tarjeta, pero no se debitará inmediatamente, pudiendo ser capturado posteriormente por un monto igual o menor al monto autorizado. El plazo para realizar la captura, así como la posibilidad de capturar valores menores dependerá de la negociación con la red adquirente/enrutamiento, dependerá de la Tienda Virtual consultar a la red adquirente/enrutamiento.
La cancelación de la preautorización puede realizarse para volver a disponer del valor reservado del límite de la tarjeta, si aún no se ha realizado la captura de la preautorización.
Una vez finalizada la operación de captura de la preautorización, ésta también puede ser anulada. Para más detalles sobre la cancelación y el extorno, el documento Interfaz de servicios web REST de pago, documento de programación y anulación. Si el comerciante no lo tiene a mano, debe pedir al Equipos de servicio de Portal Carat.
Flujo de solicitud de autorización previa, captura y Status#
El flujo de preautorización será iniciado por la Tienda Virtual cuando la aplicación envíe la operación beginTransaction (Figura 1), en la respuesta a la solicitud, la aplicación recibirá el nit (identificador de transacción) y otros parámetros (Tabla dos). El nit recibido en beginTransaction junto con otros parámetros (Tabla 3), serán enviados por la Tienda Virtual en la operación doPreAuthorization y deberá manejar los parámetros recibidos en la respuesta a la solicitud de beginTransaction . Posteriormente (según la regla de negocio) el mismo nit enviado en la preautorización debe enviarse en la operación de capture junto con otros parámetros (Tabla 9) y deberá manejar los parámetros recibidos en el webservice response.
Si hay una falla en la recepción de la respuesta webservice response (i.e, timeout) do doPreAuthorization o capture, la aplicación de la tienda obrigatoriamente debe realizar la consulta de Status con la operación getStatus, para verificar el resultado de la transacción.
En caso de que la aplicación no reciba la respuesta de operación beginTransaction, no será necesario realizar la Operación getStatus, solo que la aplicación vuelve a realizar beginTransaction. Porque ahora mismo, todavía no se envió la transacción que comprometerá el límite o el cargo en la factura de la tarjeta del cliente.
La consulta de Status (getStatus) es extremadamente importante para evitar un cargo indebido (posible doble facturación o facturación sin recibo del producto/servicio) en la factura del cliente. Las figuras abajo ilustran los flujos:
Preautorización#
Toda la comunicación será a través de HTTPS/TLS, y es importante que el servidor del comerciante soporte la criptografía con al menos 128 bits y protocolo TLS 1.2 mínimo. El servidor de aplicaciones de la Tienda Virtual hará la llamada en el dirección para preautorización vía Web Service, como se describe abajo, según el entorno en cuestión.
URL del entorno de certificación/prueba:
https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/
URL del entorno de producción:
https://esitef-ec.softwareexpress.com.br/e-sitef/api/
Atención: Nunca use la IP en lugar del dominio esitef-ec.softwareexpress.com.br, porque la IP puede cambiar en cualquier momento y sin previo aviso, por lo que es Es importante utilizar el dominio para acceder al Portal Carat.
Web Service tiene las siguientes operaciones: beginTransaction, doPreAuthorization, capture, doCardQuery y getStatus.
Se pueden incluir otras operaciones sin previo aviso.
Importante: además de los parámetros de respuesta del webservice descritos en este especificación, Portal Carat puede devolver otros parámetros sin previo aviso. ES importante que la aplicación esté preparada para recibir parámetros adicionales además de los parámetros ya especificados y simplemente despreciarlos.
Operación beginTransaction - creación de transacciones#
Parámetros de solicitud de la operación beginTransaction_#
El flujo de la transacción de autorización previa se inicia consumiendo la operación beginTransaction, que generará una registro en Portal Carat de una transacción con Status = NOV, y el parámetro nit volverá a la aplicación, que identificará esa transacción.
La nit tiene un período de uso configurado en Portal Carat, si este límite de tiempo excede la transacción pasará de status “NOV” al status “EXP”. En este caso, ya no se permitirá el uso de las mismas nit, si es necesario consumir la operación beginTransaction nuevamente para generar otra nit válida.
La operación beginTransaction debe enviarse con los parámetros de la tabla abajo.
- Recurso: /v1/transactions
- Operación HTTP: POST
- Formato de solicitud:
JSON - Formato de respuesta:
JSON - Parámetros de encabezado:
| Nombre del parámetro
| Descripción | Tamaño | Obligatorio |
| ----------------- | --------------------------------------------------------------------------------------------------------- | ------- | ----------- |
| Content-Type | Valor fijo "application/json"
| = 15 A | Sí |
| merchant_id | Código de tienda de Portal Carat. Los códigos de producción y certificación serán distintos | ≤ 15 A | Sí |
| merchant_key | Clave de autenticación para la tienda de Portal Carat. Las claves de producción y certificación serán distintos.
| < 80 A | Sí |
| Nombre del parámetro
| Descripción | Tamaño | Obligatorio |
| - | - | - | - |
| amount | Monto total de la compra (en centavos). Ejemplo: 1,00 = 100 o 1,100,00 = 110000 - envíe el valor sin la coma y el punto | < 12N | Sí |
| encrypted_card | Este campo debe enviarse con un valor "true" si el número de tarjeta que se va a enviar en el siguiente paso del flujo utiliza la codificación SiTef.
La opción de enviar la tarjeta codificada sólo será posible con el enrutamiento vía SiTef y es necesaria la configuración previa del SiTef en cuestión.
Opciones:
1. "true "
2. "false " (valor defalt) | < 5 AN | No |
| merchant_usn | Número secuencial único para cada pedido, creado por la tienda.
La NSU se utilizará en todas las comunicaciones con la tienda, con el fin de identificar el pedido. Como esta es una clave posible para el acceso desde el lado de la tienda, aunque es opcional para el Portal Carat, se recomienda encarecidamente que el campo sea formateado y enviado por la aplicación de la tienda. < 12 N | No |
| order_id | Código de pedido que se mostrará al comprador, definido por el comerciante. Se recomienda que sea diferente para cada pedido para facilitar la trazabilidad.
Si la integración de la Tienda con las redes de adquisición/enrutamiento (Cielo, Redecard, etc.) es vía SiTef (TEF), el campo orderId que tiene una longitud máxima de 40 caracteres, se reducirá a 12 caracteres, debido a una restricción de SiTef. Esta reducción se realizará manteniendo los caracteres de izquierda a derecha (ej .: si un código de pedido ingresado es 12345678901234567890 en Portal Carat, en SiTef será solo 123456789012). | ≤ 40 A | No |
| transaction_type | Valor fijo “preauthorization” | = 15 A | Sí |
Título del tipo de campo "Tamaño":
A = alfanumérico
N = numérico
N A = no utilizado
Parámetros de respuesta de la operación de inicio de transacción#
La tabla abajo muestra los parámetros de respuesta de la operación beginTransaction:
| Nombre del parámetro | Descripción | Tamaño | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | code | Código de respuesta de Portal Carat. Cualquier código que no sea "0" significa error. Para obtener más información, consulte el documento "Anexo A-2 - Códigos de respuesta". | < 4 N | | message | Mensaje de respuesta de Portal Carat. | < 500 A | | amount | Valor de la transacción especificado por la tienda (en céntimos) al crear la transacción. | < 12 N | | merchant_usn | Número secuencial único enviado por la tienda al crear la transacción. | < 12 N | | nit | Identificador de la transacción de preautorización de Portal Carat. | = 64 A | | order_id | Código de pedido enviado por la tienda en la creación de la transacción | < 40 A | | status | Status de la transacción de preautorización de Portal Carat. | = 3 A |
Ejemplo de solicitud
Ejemplo de respuesta
Operación doPreAuthorization: efecto de la autorización previa#
El nit obtenido en la devolución de la operación beginTransaction debe enviarse en la operación doPreAuthorization junto con los parámetros descritos en la tabla siguiente (según la necesidad de cada aplicación):
- Recurso: / v1 / preauthorizations / {nit}
- Método HTTP: POST
- Formato de solicitud: JSON
- Formato de respuesta: JSON
- Parámetros de encabezado:
| Nombre del parámetro | Descripción | Tamaño | Obligatorio |
|---|---|---|---|
| Content-Type | Valor fijo “application/json” | = 15 A | Sim |
| merchant_id | Código de la tienda en el Portal Carat. Los códigos de producción y certificación seran diferentes | ≤ 15 A | Si |
| merchant_key | Clave de autenticación para la tienda de pagos online. Las claves de producción y certificación serán diferentes. | < 80 A | Sim |
Parámetros de solicitud de operación doPreAuthorization
| Nombre del parámetro | Descripción | Tamaño | Obligatorio |
|---|---|---|---|
| authorizer_id | Código de autorizador en el Portal Carat. Consulte el documento Anexo A: Autorizadores Pagos Online. | ≤ 3 N | Si |
| customer_id | Documento de identidad del comprador. Utilice solo caracteres alfanuméricos (sin puntos, guiones u otros caracteres especiales). | ≤ 20 A | No |
| discount | Importe del descuento, en centavos. En caso de preautorizaciones con valores promocionales para el uso de Visa Checkout, VISA sugiere que este campo se envíe adicionalmente. | N | No |
| installments | Junto con el campo installmenttype, indica parcelamento (**), utilizados _APENAS com autorizadoras roteadas, e-Rede, GetNetLac via SiTef, Rede via SiTef e iCards via SiTef. Envie ‘1’ para transacciones en efectivo. | <2 N | Condicional |
| installment_type | Junto con el campo de cuotas, indica cuotas(**), utilizados APENAS con autorizadores enrutados a través de e-Rede, GetNetLac a través de SiTef, Rede a través de SiTef e iCards a través de SiTef. Para el resto de rutas, el abono solo es posible en captura. Los valores posibles para elinstallmenttype são: 3: Cuota con interés de la compañía de tarjeta ** 4 \ \ _: Cuota realizada por la tienda y sin interés (adoptar este valor por defecto / por defecto para transacciones al contado) | = 1 N | Condicional |
| mcc | Código de categoría de comerciante: indica el código de categoría de la tienda. Obligatorio cuando se utiliza Stone WS subacquiring. | <4 N | Obligatorio solo para la subcompra de Stone WS |
| merchant_email | e-mail de la tienda. Este parámetro, cuando se envía, sobrescribe el e-mail de registro de la tienda. | ≤ 40 A | Opcional |
| nit | Identificador de transacción en el Portal Carat (encriptado). Recibí la devolución de llamada para comenzar la transacción. | = 64 A | Si |
| promo_code | Código de promoción de Visa Checkout utilizado en la preautorización. En caso de preautorizaciones con valores promocionales para el uso de Visa Checkout, VISA sugiere que este campo se envíe adicionalmente. | A | No |
| soft_descriptor | Texto adicional que aparecerá con el nombre del establecimiento en el extracto de la tarjeta de crédito del comprador. La funcionalidad solo está disponible para las redes adquirientes/enrutamientos e-Rede y Bin via SiTef. | ≤ 30 A | No |
| subtotal | Importe subtotal, en centavos. En caso de preautorizaciones con valores promocionales para el uso de Visa Checkout, VISA sugiere que este campo se envíe adicionalmente. | N | No |
| expiry_date | Fecha de vencimiento de la tarjeta en formato MMYY. | = 4 N | Si |
| holder | Nombre del tarjetahabiente. Requerido solo para enrutamientos e-Rede, GetNet WS y VR (SmartNet). | ≤ 30 A | Condicional |
| security_code | Código de seguridad. | ≤ 5 N | Si |
| número (\ ) | Número de tarjeta del comprador (PAN). Obligatorio utilizar uno de los campos (number, token ou initial_wallet_transaction_id) | ≤ 19 N | Si |
| token (\ ) | Se utiliza para casos recurrentes de preautorización, en los que la tarjeta ya debe estar almacenada en la base de datos en línea de Portal Carat | = 88 A | Condicional |
| wallet_transaction_id (\ *) | Código de identificación de transacción con billetera Visa Checkout. Acerca del uso de Visa Checkout, consulte el documento Adjunto M-1 - VisaCheckout via WS | <25 A | Condicional |
| initial_wallet_transaction_id | Informa si la ID de billetera (WALLET_TRANSACTION_ID) se está utilizando por primera vez. Si es la primera vez, envíe verdadero, de lo contrario, envíe falso.
Possíveis valores: true/false
Valor default: true | <5 A | Requerido solo para Visa Checkout |
(\ *) Uso obligatorio solo uno entre campos: number, token o initial_wallet_transaction_id
() Cuota enrutada por GetNetLac a través de SiTef: En este caso, la tienda será responsable de controlar la pago en cuotas, pronto las reglas de cuotas configuradas para la interfaz de pago no entrarán en vigencia Portal Carat HTML, solo se verificarán y aplicarán las reglas de pago a plazos de la empresa autorizante. para éstos redes mencionadas, si la preautorización se realiza a la vista, la captura no se puede fraccionar. Aún así, pre las autorizaciones enrutadas por GetNetLac via SiTef, cuando se pagan a plazos, solo se aceptan sin intereses, es decir, con el parámetro installment_type = 4**. No se aceptan pagos a plazos sin intereses para esta ruta.
Parámetros de respuesta de la operación doPreAuthorization#
La siguiente tabla contiene los parámetros de respuesta de la operación doPreAuthorization. La aplicación debe Almacene tantos parámetros como considere necesarios. Sugerimos almacenar los parámetros: order_id, authorization_number, merchant_usn, esitef_usn, sitef_usn, host_usn, status, code, amount, message (el parámetro de mensaje se puede mostrar al cliente).
| Nombre del parámetro | Descripción | Tamaño |
|---|---|---|
| code Código de respuesta de Portal Carat. Cualquier código que no sea "0" significa falla. Para obtener más información, consulte el documento Anexo A-2 - Códigos de respuesta. | <4 N | |
| message | Mensaje de respuesta de Portal Carat. | <500 AN |
| acquirer_id | Adquiriente / código de enrutamiento utilizado en la transacción. | <4 N |
| acquirer_name | Nombre del adquirente / enrutamiento utilizado en la transacción. | <100 AN |
| amount | Importe de la compra especificado por la tienda (en centavos) al momento de la creación de la transacción. | <12 AN |
| authorization_number | Numero de autorización. | <6 AN |
| authorizer_code | Código de respuesta del autorizador. | <10 AN |
| authorizer_date | Fecha de vigencia de la preautorización devuelta por el autorizador en formato DD / MM / AAAA'T'HH: mm. Ejemplo: 07/13 / 2017T16: 03 | = 16 D |
| authorizer_id | Código de autorización utilizado en la transacción. | <4 N |
| authorizer_merchant_id | Código de afiliación del comerciante con la agencia autorizadora. | <100 AN |
| authorizer_message | Mensaje de respuesta del autorizador. | <500 AN |
| customer_receipt | Cupón (a través del cliente). | <4000 AN |
| eci | Eletronic Commerce Indicator (indicador del nivel de seguridad de la transacción de preautorización a través de Cielo e-Commerce). | <3 AN |
| esitef_usn | Número secuencial único de la transacción de preautorización en Portal Carat. | = 15 N |
| host_usn | Autorizador NSU. | <15 AN |
| issuer | Marca el código devuelto por el autorizador. | <5 AN |
| merchant_receipt | Cupón (vía establecimiento). | <4000 AN |
| merchant_usn | Número secuencial único enviado por la tienda al crear la transacción. | <12 AN |
| nit | Identificador de la transacción de preautorización en Portal Carat. | = 64 AN |
| order_id | Código de pedido enviado por la tienda al crear la transacción. | <40 AN |
| payment_type | Tipo de pago del autorizador elegido: B = comprobante bancario, C = crédito, D = débito, P = tarjeta de crédito Private Label , T = transferencia bancaria, G = tarjeta gift, O = otros medios y pagos, W = Boleto NR via Web Service | = 1 A |
| sitef_usn | Número secuencial único de la transacción de preautorización en SiTef. | = 6 N |
| status | Estado de la transacción de preautorización en Portal Carat. | = 3 AN |
| tid | ID de transacción en adquirente / enrutamiento. Este campo solo se devuelve en transacciones con adquirentes externos al SiTef. | <40 AN |
| xid | Campo XID devuelto en autenticaciones 3DS o ciertos adquirientes / rutas. | <40 AN |
Ejemplo de solicitud#
Ejemplo de respuesta#
operación editPreAuthorization - cambio de valor de preautorización#
Para el enrutamiento GetNetLac a través de SiTef es posible cambiar el valor de una preautorización no capturada. Para para usar esta funcionalidad, simplemente llame a la operación doPreAuthorization nuevamente con los datos de un transacción de preautorización con estado CON (confirmada) con la adición del campo monto. A continuación se muestran los detalles de esa llamada.
| Nombre del parámetro | Descripción | Tamaño | Obligatorio |
|---|---|---|---|
| nit | Identificador de transacción en el Portal Carat. Obtenido al devolver la llamada a beginTransaction. | = 64 A | Si |
| authorizer_id | Código de autorizador en el Portal Carat. Ver documento Anexo A - Autorizador de Portal Carat . | ≤ 3 N | Si |
| amount | Monto total de la compra (en centavos). | ≤ 12 N | Si |
| number | Número de tarjeta del comprador (PAN). | ≤ 19 N | Si |
| token | Se utiliza para casos de pagos recurrentes, donde la tarjeta ya debe estar almacenada en la base de datos de pagos online. Obligatorio utilizar uno de los campos (número, token o initial_wallet_transaction_id) | = 88 A | Condicional |
| expiry_date | Fecha de vencimiento en formato MMYY. | = 4 N | Si |
| security_code | Código de seguridad | ≤ 5 N | Si |
Los campos de respuesta son los mismos que para la operación doPreAuthorization, descrita en la Tabla 6.
En caso de éxito, se devolverá el responseCode '0'. El estado de la transacción no cambiará en hipótesis cualquiera (éxito o fracaso). Sin embargo, los campos sitef_usn, host_usn, Authorization_number, sitef_date, customer_receipt y comerciante_receipt cambiarán si se confirma el cambio.
Captura de operaciones: captura de autorización previa#
La captura de la Pre-Autorización tiene como objetivo realizar la Pre-Autorización, que puede ser por el monto total o menos que el monto total de la Autorización previa. Esto dependerá de la regla comercial de la aplicación Tienda virtual.
El flujo sería, realizar la operación doPreAuthorization y si se aprueba el resultado, la operación capture debería consumirse para completar el flujo. La captura se realizará en el momento definido por las reglas de negocio de la solicitud.
En la operación capture, el parámetro amountuede tener un valor igual o menor que el valor del parámetro amount del preautorización.
Para el enrutamiento GetNetLac via SiTef, el pago también se puede realizar en el paso de autorización previa y en este caso, la captura debe recibir un número de paquetes igual o superior al enviado anteriormente. Caso para pre La autorización se realiza en efectivo, la captura no se puede fraccionar.
En el caso de captura de transacciones de preautorización HTML, siguen las cuotas y el tipo de financiación obligatoriamente los valores definidos en la preautorización. Entonces en este caso no hay posibilidad de cambio de estos valores en el momento de la captura.
Detalles de la llamada#
Recurso: /v1/preauthorizations/capture/{nit}
Método HTTP: POST
Formato de la solicitud: JSON
Formato de la respuesta: JSON
Parámetros de encabezado:
| Nombre del parámetro | Descripción | Tamaño | Obligatorio |
|---|---|---|---|
| Content-Type | Valor fijo "application / json" | = 15 A | Si |
| merchant_id | Código de tienda en el Portal Carat. Los códigos de producción y certificación serán diferentes | ≤ 15 A | Si |
| merchant_key | Clave de autenticación para la tienda de pagos online. Las claves de producción y certificación serán diferentes. | <80 A | Si |
Parámetros de la solicitud de la operación capture#
| Nombre del parámetro | Descripción | Tamaño | Obligatorio |
|---|---|---|---|
| amount | Monto total de la compra (en centavos). | ≤ 12 N | Si |
| discount | Importe del descuento, en centavos. En caso de preautorizaciones con valores promocionales para el uso de Visa Checkout, VISA sugiere que este campo se envíe adicionalmente. | N | No |
| installments (\ *) | Número de cuotas, 1 = efectivo | ≤ 2 N | Si |
| installment_type | Junto con el campo de cuotas, indica cuotas. Los valores posibles para installment_type son: 3: Cuota con intereses de la compañía de tarjetas 4: Cuota realizada por la tienda y sin intereses (adoptar este valor por defecto / por defecto para transacciones en efectivo) | = 1 N | Si |
| promo_code | Código de promoción de Visa Checkout utilizado en la preautorización. En caso de preautorizaciones con valores promocionales para el uso de Visa Checkout, VISA sugiere que este campo se envíe adicionalmente. | A | No |
| subtotal | Importe subtotal, en centavos. En caso de preautorizaciones con valores promocionales para el uso de Visa Checkout, VISA sugiere que este campo se envíe adicionalmente. | N | No |
| number (**) | Número de tarjeta del comprador (PAN). | ≤ 19 N | Si |
| token (\ \ ) | Se utiliza para casos recurrentes de preautorización, en los que la tarjeta ya debe estar almacenada en la base de datos del Portal Carat. | = 88 A | Condicional |
| wallettransaction_id (\ \ _) | Código de identificación de transacción con billetera VisaCheckout. | <25 A | Requerido solo para Visa Checkout |
| initial_wallet_transaction_id | Informa si la ID de billetera (WALLET_TRANSACTION_ID) se está utilizando por primera vez. Si es la primera vez, envíe verdadero, de lo contrario, envíe falso. Valores posibles: verdadero / falso Valor predeterminado: verdadero | <5 A | Requerido solo para Visa Checkout |
| adquirer.submerchant_split [] | Consiste en una matriz para pagos divididos, exclusiva para enrutamiento BIN y Sipag, ambos a través de SiTef. Permite la división de partes del monto total del pago entre otras empresas. El número máximo de elementos permitidos en esta matriz es de 5 itens. Cada artículo está compuesto por los campos submechant_code y submerchant_amount. | No | |
| submerchant_code | Código de establecimiento BIN / Sipag | ≤ 15 AN | No |
| submerchant_amount | valor de transacción para el establecimiento | ≤ 12 N | No |
(*) installments: La cantidad máxima de cuotas configuradas en el portal de Portal Carat del comerciante no se verificará en este campo, que se publica solo para pagos HTML.
() Uso obligatorio sólo un \ \ entre los campos: número, token o initial_wallet_transaction_id
Captura de parámetros de respuesta de operación#
| Nombre del parámetro | Descripción | Tamaño |
|---|---|---|
| code | Código de respuesta de Portal Carat. Cualquier código que no sea "0" significa falla. Para obtener más información, consulte el documento adjunto A-2 - Códigos de respuesta. | <4 N |
| message | Mensaje de respuesta de Portal Carat. | <500 AN |
| adquirer_id | Adquiriente / código de enrutamiento utilizado en la transacción. | <4 N |
| acquirer_name | Nombre del adquirente / enrutamiento utilizado en la transacción. | <100 AN |
| amount | Importe de la compra especificado por la tienda (en centavos) al momento de la creación de la transacción. | <12 AN |
| authorization_number | Numero de autorización. | <6 AN |
| authorizer_code | Código de respuesta del autorizador. | <10 AN |
| authorizer_date | Fecha de vigencia de la preautorización devuelta por el autorizador en formato DD / MM / AAAA'T'HH: mm. Ejemplo: 07/13 / 2017T16: 03 | = 16 D |
| authorizer_id | Código de autorización utilizado en la transacción. | <4 N |
| authorizer_merchant_id | Código de afiliación del comerciante con la agencia autorizadora. | <100 AN |
| authorizer_message | Mensaje de respuesta del autorizador. | <500 AN |
| customer_receipt | Cupón (a través del cliente). | <4000 AN |
| eci | Indicador de comercio electrónico (indicador del nivel de seguridad de la transacción de preautorización a través de Cielo e-Commerce). | <3 AN |
| esitef_usn | Número secuencial único de la transacción de preautorización en Portal Carat. | = 15 N |
| host_usn | Autorizador NSU. | <15 AN |
| issuer Marca el código devuelto por el autorizador. | <5 AN | |
| merchant_receipt | Cupón (vía establecimiento). | <4000 AN |
| merchant_usn | Número secuencial único enviado por la tienda al crear la transacción. | <12 AN |
| nit | Identificador de la transacción de preautorización en Portal Carat. | = 64 AN |
| payment_type | Tipo de pago del autorizador elegido: B = comprobante bancario, C = crédito, D = débito, P = tarjeta de crédito Private Label , T = transferencia bancaria, G = tarjeta gift, O = otros métodos de pago, W = comprobante bancario NR vía Web Service | = 1 A |
| sitef_usn | Número secuencial único de la transacción de preautorización en SiTef. | = 6 N |
| status | Status de la transacción de preautorización en Portal Carat. | = 3 AN |
| tid | ID de transacción en adquirente / enrutamiento. Este campo solo se devuelve en transacciones con adquirentes que no son SiTef. | <40 AN |
| xid | Campo XID devuelto en autenticaciones 3DS o ciertos adquirientes / rutas. | <40 AN |
Ejemplo de solicitud#
Ejemplo de respuesta#
Operación doCardQuery - consulta de tarjeta#
Desde un NIT de preautorización con estado NOV (nuevo), es posible consultar el BIN de la tarjeta (primeros seis dígitos) en SiTef para obtener datos sobre sus capacidades (posibilidad de pago a plazos, cuotas máximas, requisito de código de seguridad, etc.), o incluso saber qué autorizador de la tienda es el más apto para realizar el pago.
En el caso de las transacciones de Visa Checkout, este servicio también devolverá los datos de la tarjeta y del usuario. devuelto por Visa.
Flujo#
Descripción del flujo:
- El comerciante crea una transacción en Portal Carat, pasando información como el código de la tienda, el número de cuotas y el código de pedido y obtiene un NIT (número de identificación de transacción) en respuesta.
- El comerciante envía el NIT obtenido en el paso anterior y los datos de la tarjeta a consultar. Con eso, el Portal Carat devuelve datos sobre las capacidades de la tarjeta enviada.
- La tienda virtual luego procede a consumir el servicio de procesamiento de pagos, pasando el NIT y el datos de la tarjeta del comprador. En caso de éxito, la transacción de pago cambiará su estado a CON (confirmado).
Detalles de la llamada#
Recursos: /v1/preauthorizations/{nit}/cards
Método HTTP: POST
Obs.: a pesar de ser una consulta, se eligió el método POST por razones de seguridad.
Formato de solicitud: JSON
Formato de respuesta: JSON
Parámetros de encabezado:
| Nombre del parámetro | Descripción | Tipo | Tamaño | Obligatorio |
|---|---|---|---|---|
| merchant_id | Código de tienda en el Portal Carat. Los códigos de producción y certificación serán diferentes. | AN | ≤ 15 | SI |
| merchant_key | Clave de autenticación para la tienda de Portal Carat. Las claves de producción y certificación serán diferentes. | AN | ≤ 80 | SI |
| Tipo de contenido | Debe enviarse con el valor “application / json” . | AN | = 15 | SI |
Ejemplo de consulta de tarjeta con envío del autorizador#
Solicitud:
Respuesta:
Ejemplo de consulta de tarjeta sin enviar autorizador#
Solicitud:
Respuesta:
Ejemplo de consulta de tarjeta Visa Checkout#
Solicitud:
Respuesta:
Ejemplo de consulta de tarjeta con datos adicionales para el enrutamiento de iCards a través de SiTef
Solicitud:
Respuesta:
Solicitar parámetros
En la siguiente tabla, hay una descripción de los parámetros de solicitud para el servicio de búsqueda de tarjetas:
| Nombre del parámetro | Descripción | Tipo | Tamaño | Obrigatorio |
|---|---|---|---|---|
| authorizer_id | Código del autorizador en el Portal Carat, como se indica en el documento “Anexo A - Autorizadores de Portal Carat”. Este campo solo es obligatorio si se envía el campo "wallet_transaction_id". | N | ≤ 3 | NO |
| numero | Número de tarjeta del comprador (PAN). | N | ≤ 19 | NO |
| token | HASH de una tarjeta almacenada en Portal Carat. No está permitido enviar un número de tarjeta abierto (campo ‘number’) y una tarjeta almacenada (campo ‘token’) en la misma solicitud. | AN | = 88 | NO |
| wallet_transaction_id | ID de una transacción de billetera digital. Por ahora, esta funcionalidad solo está disponible para el autorizador de Visa Checkout (authorizer_id: 406). No está permitido enviar un número de tarjeta abierto (campo ‘number’), una tarjeta almacenada (campo ‘token’) y un wallet_transaction_id en la misma solicitud. | AN | ≤ 25 | NO |
Obs.: Aunque no es obligatorio, se recomienda enviar el authorizer_id para la consulta de la tarjeta, principalmente para enrutamiento vía SiTef, con el fin de tener un comportamiento más efectivo en relación al enrutamiento registrado para el autorizador.
Parámetros de respuesta
En caso de éxito, el código de respuesta HTTP será 200. Cualquier otro código debe interpretarse como un error. En la siguiente tabla se muestra la descripción de los parámetros de respuesta del servicio de búsqueda de tarjetas:
| Nombre del parámetro | Descripción | Tipo | Tamaño |
|---|---|---|---|
| code | Código de respuesta de Portal Carat. Cualquier código que no sea '0' significa falla. Para obtener más información, consulte el documento “Anexo A-2 - Códigos de respuesta”. | N | ≤ 4 |
| message | Mensaje de respuesta de Portal Carat. | AN | ≤ 500 |
| status | Status de la transacción de preautorización en Portal Carat. Para obtener más información, consulte 11.1. | AN | = 3 |
| authorizer_code | Código de respuesta del autorizador. | AN | ≤ 10 |
| authorizer_message | Mensaje de respuesta del autorizador. | AN | ≤ 500 |
| acquirer_name | Nombre de enrutamiento. Por ejemplo: Cielo | AN | ≤ 256 |
| authorizer_id | Código de autorizador (utilice este ID al realizar el pago). | N | ≤ 3 |
| is_customer_id_required | Indica la recogida obligatoria del documento del cliente. | T / F | ≤ 5 |
| is_expiry_date_required | Indica la obligación de recolectar la fecha de vencimiento de la tarjeta del comprador. | T / F | ≤ 5 |
| is_installment_funding_enabled | Indica si el pago a plazos está habilitado. | T / F | ≤ 5 |
| is_security_code_required | Indica la recopilación de códigos de seguridad obligatorios. | T / F | ≤ 5 |
| is_spot_sale_enabled | Indica si el pago en efectivo está habilitado. | T / F | ≤ 5 |
| is_with_interest_sale_enabled | Indica si el pago de intereses está habilitado. | T / F | ≤ 5 |
| is_without_interest_sale_enabled | Indica si está habilitado el pago sin intereses. | T / F | ≤ 5 |
| max_installments_with_interest | Cuotas máximas con intereses. | N | ≤ 2 |
| min_installments_with_interest | Cuota mínima con intereses. | N | ≤ 2 |
| visa_checkout_date | Objeto con datos devueltos por Visa Checkout. | ||
| financing_plan_list | Objeto consistente en un conjunto de planes de financiamiento presentados en el enrutamiento de Via Certa Financiadora. Un plan de financiación consta de los siguientes campos: - cod_plano: código de identificación del plan de financiación, que debe enviarse en el momento del pago; - - tipo_plano: código del tipo de plan de financiación; - desc_plano: descripción del plan, que se puede presentar al comprador; - parc_plano: número máximo de cuotas posibles del plan. | ||
| is_customer_postal_code_required | Indica la recopilación obligatoria del código postal del usuario (CEP en Brasil). | T / F | <5 |
| Clave | Nombre de prefijo. | AN | ≤ 1024 |
| valor | Valor de prefijo | AN | ≤ 1024 |
Cancelación de preautorización y de captura#
Si la transacción de preautorización se realizó con éxito y la Tienda Virtual no quiere realizar la captura, puede cancelar la preautorización, liberando el monto reservado del límite de la tarjeta al cliente. Si la captura no se lleva a cabo, después de un cierto período de tiempo, la preautorización se cancela automáticamente, pero el cliente puede querer que la preautorización se cancele antes, para liberar el monto del límite de su tarjeta.
Es importante saber que solo una preautorización no capturada se puede cancelar en días posteriores. Una transacción de captura solo se puede cancelar el mismo día en que se realizó.
Para realizar la cancelación de preautorización o captura de preautorización, el flujo es ligeramente diferente, en el sentido de que la creación de la transacción de cancelación devuelve el nit en la URL de Autenticidad, es decir, la llamada a la operación beginCancelTransaction simplemente devolverá un "OK" y el nit será devuelto en la URL de autenticidad previamente registrada.
Tenga en cuenta que el Portal Carat solo enviará el mensaje "OK" si el envío de NIT fue exitoso, con el servidor de la tienda respondiendo "HTTP 200 OK" y solo después del retorno "HTTP 200 OK" se podrá utilizar el nit de la transacción de cancelación.
Información para el desarrollo de la transacción de cancelación, incluido el hash, consulte el manual Interfaz Web Service REST de Pago, Agendar y Cancelar . Si aún no ha recibido el documento, pregunte al e-mail autorizadores5317@softwareexpress.com.br ou pelo tel. (11)3170-5317.
operación getStatus - consulta de transacción#
En caso de falla de comunicación o demora excesiva en la respuesta (timeout) en alguna de las operaciones posteriores a beginTransaction, la tienda debe consumir obligatoriamente la operación getStatus. Esta operación permite verificar el estado de una solicitud a la que el comerciante no obtuvo respuesta, recuperando los parámetros que no pudo recibir en el flujo normal.
La tienda debe recuperar el estado de la transacción (con un plazo máximo de 15 días para consulta) siempre que tenga el nit, a través del webservice getStatus, pasando como parámetro la clave de autenticación de la tienda (merchantKey) y el nit.
Desarrollo / Certificación: en caso de que no haya recibido el merchantKey para desarrollo / certificación, solicítela a través del e-mail autorizadores5317@softwareexpress.com.br ou pelo telefone (11) 3170-5317.
Producción : el merchantKey para Producción será enviada por el equipo de Portal Carat de Producción; si no se ha recibido después de los procedimientos debidos para ingresar a Producción, solicítela al e-mail esitef.prod6773@softwareexpress.com.br.
Tenga en cuenta que, en casos excepcionales, la clave de autenticación (merchantKey) se puede cambiar por razones de seguridad, sin embargo, el equipo de producción se comunicará con la tienda antes del cambio.
Teniendo en cuenta que varios factores pueden causar un retraso en la respuesta, incluida la inestabilidad de Internet y el host de la red de autorización de la tarjeta. Recomendamos que el servidor de la tienda haya establecido un tiempo de espera igual o superior a 90 segundos.
Nota: Este servicio solo devolverá datos si la transacción se realizó a través de servicios web, no funcionará en caso de transacciones a través de la interfaz HTML.
Atención: La consulta de la transacción en el Portal Carat NO consulta el estado de la transacción en el adquirente / autorizador. Este servicio devuelve el status de la transacción en la base de datos de Portal Carat.
Ejemplo: Si se confirma una transacción de preautorización en Portal Carat, pero se revierte vía telefónica directamente al adquirente / autorizador, esta anulación no se reflejará necesariamente en el servicio de consulta de pago de Portal Carat.
Detalles de la llamada#
Recurso: /v1/transactions/{nit}
Método HTTP: GET
Formato de solicitud: JSON
Formato de respuesta: JSON
Parámetros de encabezado:
| Nombre del parámetro | Descripción | Tamaño | Obligatorio |
|---|---|---|---|
| Content-Type | Valor fijo "application / json" | = 15 A | Si |
| merchant_id | Código de tienda en el Portal Carat. Los códigos de producción y certificación serán diferentes | ||
| merchant_key | Clave de autenticación para la tienda de Pagos Online. Las claves de producción y certificación serán diferentes. | ≤ 80 A | Si |
| nit | Identificador de transacción en el Portal Carat. Recibí la devolución de llamada para comenzar la transacción. | = 64 A | Si |
Parámetros de la solicitud de operación getStatus En la URL del recurso debe enviarse el nit
| Nombre del parámetro | Descripción | Tamaño | Obligatorio |
|---|---|---|---|
| nit | Identificador de transacción en el Portal Carat. Recibido en la devolución de llamada para el beginTransaction. | = 64 A | Si |
Llamar a la operación de consulta de transacciones - getStatus - no requiere un cuerpo de solicitud.
Parámetros de la respuesta de la operación getStatus
| Nombre del parámetro | Descripción | Tamaño | |
|---|---|---|---|
| code | Código de respuesta de Portal Carat. Cualquier código que no sea "0" significa que la consulta falló. Para obtener más información, consulte el documento Anexo A-2 - Códigos de respuesta. | <4 N | |
| message | Mensaje de respuesta de Portal Carat de la consulta. | <500 AN | |
| adquirer_id | Adquiriente / código de enrutamiento utilizado en la transacción. | <4 N | |
| acquirer_name | Nombre del adquirente / enrutamiento utilizado en la transacción. | <100 AN | |
| amount | Importe de la compra especificado por la tienda (en centavos) al momento de la creación de la transacción. | <12 AN | |
| authorization_number | Número de autorização. | < 6 AN | |
| authorizer_code | Código de respuesta del autorizador. | <10 AN | |
| authorizer_date | Fecha de ejecución de la preautorización devuelta por el autorizador en formato DD / MM / AAAA'T'HH: mm. | ||
| Ejemplo: 07/13 / 2017T16: 03 | = 16 D | ||
| authorizer_id | Código de autorización utilizado en la transacción. | <4 N | |
| authorizer_merchant_id | Código de afiliación del comerciante con la agencia autorizadora. | <100 AN | |
| authorizer_message | Mensaje de respuesta del autorizador. | <500 AN | |
| customer_receipt | Cupón (a través del cliente). | <4000 AN | |
| eci | Eletronic Commerce Indicator (indicador del nivel de seguridad de la transacción de preautorización a través de Cielo e-Commerce). | <3 AN | |
| esitef_usn | Número secuencial único de la transacción de preautorización en Portal Carat. | = 15 N | |
| host_usn | NSU del autorizador | < 15 AN | |
| issuer | Código de la marca de la tarjeta devuelto por el autorizador. | <5 AN | |
| merchant_receipt | Cupón (vía establecimiento). | <4000 AN | |
| merchant_usn | Número secuencial único enviado por la tienda al crear la transacción. | <12 AN | |
| nit | Identificador de la transacción de preautorización en Portal Carat. | = 64 AN | |
| order_id | Código de pedido enviado por la tienda al crear la transacción. | <40 AN | |
| payment_type | Tipo de pago del autorizador elegido: B = comprobante bancario, C = crédito, D = débito, P = tarjeta de crédito Private Label puro, T = transferencia bancaria, G = tarjeta gift, O = otros métodos de pago, W = comprobante NR vía Web Service | = 1 A | |
| sitef_usn | Número secuencial único de la transacción de preautorización en SiTef. | = 6 N | |
| status | Status de la transacción de preautorización en Portal Carat. | = 3 AN | |
| tid | ID de transacción en adquirente / enrutamiento. Este campo solo se devuelve en transacciones con adquirentes que no son SiTef. | <40 AN | |
| xid | Campo XID devuelto en autenticaciones 3DS o ciertos adquirientes / enrutameientos. | <40 AN | |
| adquirer_id | Código adquirientede/enrutamiento utilizado en la transacción. | < 4 N | |
| acquirer_name | Nombre del adquirente / enrutamiento utilizado en la transacción. | <100 AN | |
| amount | Importe de la compra especificado por la tienda (en centavos) al momento de la creación de la transacción. | <12 AN | |
| authorization_number | Numero de autorización. | <6 AN | |
| authorizer_code | Código de respuesta del autorizador. | <10 AN | |
| authorizer_date | Fecha deejecución de la preautorización devuelta por el autorizador en formato DD / MM / AAAA'T'HH: mm. Ejemplo: 07/13 / 2017T16: 03 | = 16 D | |
| authorizer_id | Código de autorización utilizado en la transacción. | <4 N | |
| authorizer_merchant_id | Código de afiliación del comerciante con la agencia autorizadora. | <100 AN | |
| authorizer_message | Mensaje de respuesta del autorizador. | <500 AN | |
| customer_receipt | Cupón (a través del cliente). | <4000 AN | |
| eci | Eletronic Commerce Indicator (indicador del nivel de seguridad de la transacción de preautorización a través de Cielo e-Commerce). | <3 AN | |
| esitef_usn | Número secuencial único de la transacción de preautorización en Portal Carat | = 15 N | |
| host_usn | NSU del autorizador. | < 15 AN | |
| issuer | Código de la marca de la tarjeta devuelto por el autorizador. | <5 AN | |
| merchant_receipt | Cupón (vía establecimiento). | <4000 AN | |
| merchant_usn | Número secuencial único enviado por la tienda al crear la transacción. | <12 AN | |
| nit | Identificador de la transacción de preautorización en Portal Carat. | = 64 AN | |
| order_id | Código de pedido enviado por la tienda al crear la transacción. | <40 AN | |
| payment_type | Tipo de pago del autorizador elegido: B = comprobante bancario, C = crédito, D = débito, P = tarjeta de crédito Private Label puro, T = transferencia bancaria, G = tarjeta gift, O = otros métodos de pago, W = Comprobante NR vía Web Service | = 1 A | |
| sitef_usn | Número secuencial único de la transacción de preautorización en SiTef. | = 6 N | |
| estado | Estado de la transacción de preautorización en Portal Carat. | = 3 AN | |
| tid | ID de transacción en adquirente / enrutamiento. Este campo solo se devuelve en transacciones con adquirentes que no son SiTef. | <40 AN | |
| xid | Campo XID devuelto en autenticaciones 3DS o ciertos adquirientes / enrutamientos. | <40 AN |
Atención: Los campos de código y mensaje hacen referencia al código y mensaje que hace referencia a la solicitud de consulta. Estos no se refieren a las transacciones consultadas.
Ejemplo de solicitud
Ejemplo de solicitud
Tablas compartidas#
Estado de transacción de Portal Carat#
| Código | Nombre | Descripción |
|---|---|---|
| NOV | Nuevo | Transacción recién creada. |
| INV | Inválido | La transacción no se creó correctamente, la tienda probablemente envió algún parámetro incorrecto y la transacción no se pudo inicializar correctamente. |
| PPC | Pendiente de confirmación | Pago pendiente de confirmación. |
| PPN | Deshecho | Pago pendiente no confirmado (cancelado). |
| PEN | En espera de pago | Transacción pendiente de respuesta de la institución financiera. |
| CON | Hecho | Transacción confirmada por la entidad financiera. |
| NEG | Denegado | Transacción denegada por la institución financiera. |
| ERR | Error al realizar el pago | Error en la comunicación con el autorizador. Inténtalo de nuevo. |
| BLQ | Bloqueado | Transacción bloqueada después de varios intentos de búsqueda de tarjetas. |
| EXP | Expirado | La transacción expiró debido a la fecha de vencimiento del NIT. |
| EST | Extornado | Pago extornado. |