Servicio de creación de transacciones
El consumo del servicio de creación de transacciones es obligatorio en los flujos de pago y programación. Como resultado de esta operación, el comerciante obtendrá un NIT (pago) y / o un SID (cronograma) que será necesario para los siguientes pasos del flujo, así como el uso del servicio de consulta de transacciones.
NIT y SID tienen un límite de tiempo para su uso. Este plazo se configura en Portal Carat, y si se excede, la transacción cambiará de NOV (nuevo) a EXP (vencido), lo que impide futuras operaciones con esta transacción, por lo que es necesario consumir el servicio de creación de transacciones. de nuevo.
Detalles de la llamada#
- Recurso:
/v1/transactions - Método HTTP:
POST - Formato de la solicitud:
JSON - Formato de la resposta:
JSON - Parámetros de encabezado:
| Parámetro | Descripción | Formato | Obligatorio |
|---|---|---|---|
merchant_id | Código de tienda en el Portal Carat. Los códigos de producción y certificación serán diferentes. | < 15 AN | 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 AN | SI |
Content-Type | Debe enviarse con el valor application / json. | = 15 AN | SI |
Ejemplos#
A continuación, se muestran algunos ejemplos de llamadas al servicio de creación de transacciones mediante la herramienta cURL.
Creación de pago con confirmación automática#
Solicitud:
Respuesta:
Creación de pagos con confirmación atrasada#
Solicitud:
Respuesta:
Creación de pagos mediante cronograma#
Solicitud:
Respuesta:
Creación de horarios sin pago#
Solicitud:
Respuesta:
Creación de pago con análisis de riesgo Cielo e-Commerce #
Solicitud:
Resposta:
Creación de pagos con análisis de riesgo (usando antifraude Konduto )#
Para más información consulte nuestra sección específica de Konduto
Solicitud:
Respuesta:
Códigos de respuesta
Ver referencia en Códigos API - Códigos de respuesta
Parámetros de solicitud#
En la siguiente tabla se muestra una descripción de los parámetros de solicitud del servicio de creación de transacciones:
| Parámetro | Descripción | Formato | Requerido |
|---|---|---|---|
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 e 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 adquirentes (Cielo, Redecard, etc) es con Portal Carat y SiTef, 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 AN | No |
installments | Número de plazos. Envíe ‘1’ para transacciones en efectivo. | < 2 N | Si |
installment_type | Tipo de financiación a plazos: valor 3 = cuotas con intereses de la compañía de tarjetas. valor 4 = cuotas realizadas por la tienda y sin intereses (adoptar este valor por patrón/ default para transacciones en efectivo). Valor 6 = pago a plazos con intereses del administrador (IATA). valor 7 = pago a plazos realizado por la tienda y sin intereses (IATA). El pago a plazos de IATA solo es utilizado por empresas en el segmento del transporte aéreo. | < 2 N | Si |
authorizer_id | Código de autorizador en el Portal Carat. Más información. En operaciones con tarjeta tokenizada, si no se informa al autorizador, se utilizará el código autorizador utilizado en el almacenamiento de la tarjeta. | < 3 N | No |
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. | < 12 N | Si |
soft_descriptor | Texto adicional que aparecerá con el nombre del establecimiento en el extracto de la tarjeta de crédito del comprador. Más información | < 30 AN | No |
authorizer_authentication | Este campo debe enviarse con un valor true si se desea un pago con autenticación. Esta funcionalidad solo está disponible para Cielo e-Commerce y e.Rede REST. | < 5 T / F | No |
encrypted_card | Este campo debe enviarse con un valor true si el número de tarjeta que se enviará en el siguiente paso del flujo utiliza cifrado SiTef. La opción de enviar la tarjeta cifrada solo será posible con enrutamiento a través de SiTef y es necesaria la preconfiguración del SiTef en cuestión | < 5 T / F | No |
| iata | Este elemento contiene campos específicos de transacciones IATA. | ||
departure_tax | Impuesto de salida en centavos. | < 12 N | SÍ solo para installment_type = 6 o 7 |
first_installment | Entrada en transacciones IATA en centavos. Esta funcionalidad sólo está disponible para el adquirente de Getnet. | < 12 N | No |
| schedule | El envío del elemento schedule implica el uso de la función de programación periódica. Ninguno de sus campos es obligatorio si solo desea realizar un pago simple. | ||
amount | Valor en centavos de pagos recurrentes. Si no se envía este campo, se utilizará el monto del pago. | < 12 N | Si |
initial_date | Fecha de ejecución del primer pago programado. Esta fecha debe ser al menos dos días antes del día actual y nunca se permiten los días 29, 30 y 31. El formato de fecha que se debe seguir es: DD / MM / YYYY Ejemplo: 20 / 04/2021 | = 10 D | Si |
number_of_times | Número de pagos programados a realizar. Si este campo no se envía, la programación estará activa infinitamente. | < 3 N | No |
interval | Intervalo en meses entre cada pago programado. Si este campo no se envía, se asume el valor 1 (ejecuciones mensuales). | < 2 N | No |
do_payment_now | Envíe este campo con un valor de false si desea concertar una cita sin pago inmediato. Si este campo está ausente o por cualquier valor que no sea "falso", se creará una cita CON pago inmediato. | < 5 T / F | No |
installments | Número de cuotas para cada pago programado. Si este campo no se envía, se asume el valor 1. | < 2 N | No |
installment_type | Tipo de financiamiento para el pago a plazos de cada pago programado: Valor 3 = pago a plazos con intereses de la compañía de la tarjeta. Valor 4 = pago a plazos realizado por la tienda y sin intereses. (Adopte este valor como predeterminado / predeterminado para transacciones al contado). Si este campo no se envía, se asume el valor 4. | < 2 N | No |
soft_descriptor | Texto adicional que aparecerá con el nombre del establecimiento en el extracto de la tarjeta de crédito del comprador. Más información | < 30 AN | No |
show_times_invoice | Para cronogramas de tiempo finitos, envíe este campo con un valor true si desea agregar el número de ejecuciones/ejecuciones totales al final del campo soft_descriptor (ejemplo: Suscripción 3/12). | < 5 T / F | No |
| additional_data | Elemento para enviar datos adicionales. | ||
postpone_confirmation | Este campo debe enviarse con un valor true si se desea un pago con confirmación tardía. | < 5 T / F | No |
financing_plan | Código del plan de financiación. Requerido solo para pagos a plazos que devengan intereses enrutados por Via Certa Financiadora a través de SiTef. | < 4 N | COND. |
ecomm_pos_ref | Este campo enviará una identificación que aparecerá en el campo PDV del informe SiTef Web para transacciones de comercio electrónico. | < 8 AF | No |
customer_email | Si se informa, debe ser un email para enviar el comprobante al consumidor, cuando se efectúe una transacción a través de REST. | < 50 AN | No |
| additional_data.payer | Elemento de envío de datos sobre el comprador. | ||
identification_number | Documento de identificación del comprador (CPF/RG). | < 20 AN | No |
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 AN | Sí para pagos programados |
name | Nombre del comprador. | < 100 AN | No |
surname | Apellido del comprador. | < 100 AN | No |
| additional_data.merchant | Elemento para el envío de datos relativos al comerciante. | ||
email | Dirección de correo electrónico del almacenista. | < 1024 AN | No |
| additional_data.extra_param.prefixes | Elemento para el envío de prefijos SiTef, como CICLOS, CPLANO y VLRADD. Si el prefijo enviado no es compatible con la tarjeta enviada, Carat invalidará la transacción, evitando la falsa impresión del uso de una determinada funcionalidad. Ejemplo: { "key" : "value" } -> { "CICLOS" : "01" } | ||
key | Nombre del prefijo. | < 1024 AN | No |
value | Valor del prefijo. | < 1024 AN | No |
En la siguiente tabla se muestra la descripción de los parámetros adicionales que se deben enviar en un pago con análisis de fraude (por ahora solo disponible para Cielo e-Commerce):
| Parámetro | Descripción | Formato | Requerido |
|---|---|---|---|
| additional_data | |||
anti_fraud_institution | Este campo se utiliza cuando no hay contrato con una institución de revisión antifraude y quiere que la revisión de antifraude sea realizada por una empresa autorizadora, en este caso debe ser enviada con el valor 'AUTHORIZER'. Si tiene un contrato con un institución de análisis antifraude como: Konduto, CyberSource y ClearSale este campo no debe utilizarse. | = 10 AN | COND. |
anti_fraud | Habilita el servicio de análisis de fraudes. Valores permitidos: enabled_before_auth – el análisis de fraude se realizará ANTES de la autorización del pago. Si se rechaza el análisis, el pago no comenzará.enabled_after_auth: el análisis de fraude se realizará DESPUÉS de la autorización del pago. Si se rechaza el análisis, se cancelará el pago que ya ha sido autorizado. | < 19 AN | SÍ para el análisis de fraude |
anti_fraud_criteria | Criterios para la realización del análisis de fraude. Valores permitidos: ON_SUCCESS – solo realiza el análisis si la transacción es exitosa.SIEMPRE – siempre realiza el análisis. | < 10 AN | No |
finger_print_id | Identificador utilizado para cruzar la información obtenida por el Browser del usuario de Internet con los datos enviados para su análisis. Más detalles aqui. | < 50 AN | No |
gift | Indica si el pedido es para regalo o no. | < 5 T / F | No |
returns_accepted | Define si se aceptan devoluciones del pedido. | < 5 T / F | No |
journey_type | Tipo de viaje. Valores permitidos:ROUND_TRIP – ida y vuelta.OUTWARD – ida.RETURN – vuelta. | < 10 AN | No |
| additional_data.payer | |||
name | Nombre del comprador. Nota: la concatenación de nombre y apellido no puede exceder los 255 caracteres. | < 200 AN | No |
surname | Apellido del comprador. Nota: la concatenación del nombre con el apellido no puede exceder los 255 caracteres. | < 200 AN | No |
email | Correo electrónico del comprador. | < 255 AN | No |
born_date | Fecha de nacimiento del comprador, con el formato AAAA-MM-DDTHH: MM: SS. Por ejemplo: 1991-01-02T08:30:00. | = 19 AN | No |
address_street_name | Dirección del comprador. | < 255 AN | No |
address_street_number | Número de dirección del comprador. | < 15 AN | No |
address_street_complement | Complemento de la dirección del comprador. | < 50 AN | No |
address_zip_code | Código postal de la dirección del comprador. Por ejemplo: 21241140. | < 9 AN | No |
city | Ciudad de la dirección del comprador. | < 50 AN | No |
state | Estado de la dirección del comprador. Por ejemplo: SP. | = 2 AN | No |
address_country | País de la dirección del comprador. Por ejemplo: BRA. | < 35 AN | No |
| additional_data.shipment.receiver_address | |||
street_name | Dirección de entrega. | < 255 AN | No |
street_number | Número de dirección de entrega. | < 15 AN | No |
complement | Complemento de dirección de entrega. | < 50 AN | No |
zip_code | Código postal de la dirección de entrega. Por ejemplo: 21241-140. | < 9 AN | No |
city | Ciudad de dirección de entrega. | < 50 AN | No |
state | Estado de la dirección de entrega. | = 2 AN | No |
country | País de dirección de entrega según AN 3166-1. Por ejemplo: BRA | = 3 AN | No |
| additional_data.browser | |||
cookies_accepted | Identifica si el navegador del cliente acepta cookies. Envíe true en caso afirmativo. | < 5 T / F | No |
email | E-mail registrado en el navegador del comprador. | < 100 AN | No |
host_name | Nombre de host donde se encontraba el comprador antes de ingresar al sitio web de la tienda. | < 60 AN | No |
ip_address | Dirección IP del comprador. Se recomienda encarecidamente que envíe este campo. | < 15 AN | No |
agent | Nombre del navegador utilizado por el comprador. Por ejemplo: Chrome. | < 40 AN | No |
| additional_data.items[] | |||
gift_category | Campo que evaluará las direcciones de facturación y entrega para diferentes ciudades, estados o países. Puede tomar los siguientes valores: OFF – Ignora el análisis de riesgo para direcciones divergentes.YES– En caso de divergencia entre las direcciones de facturación y entrega, marque con riesgo pequeño.NO – En caso de discrepancia entre las direcciones de facturación y entrega, marque con alto riesgo. | < 3 AN | No |
risk | Nivel de riesgo del producto. Puede asumir los siguientes valores: LOW – El producto tiene un historial de pocas devoluciones de cargo.NORMAL – El producto tiene un historial de contracargos considerado normal.HIGH– El producto tiene un historial de contracargos superiores al promedio. | < 6 AN | No |
title | Nombre del producto. | < 255 AN | No |
quantity | Cantidad de producto a comprar. | < 15 N | No |
id | Código de comerciante de identificador de producto. | < 255 AN | No |
unit_price | Precio unitario del producto en centavos. | < 15 N | No |
category_id | Tipo de producto. Puede adoptar los siguientes valores: art, baby, coupon, donation, computing, camera, video_game, television, car_electronic, electronic, automotive, entertainment, fashion, game, home, musical, phone, service, learning, ticket, travel, virtual_good, physical, other, adult_content, gift_certificate, handling, shipping, shipping_and_handling o subscription. | < 21 AN | No |
| additional_data.items[].hedge | |||
time | Nivel de importancia de la hora del día del pedido del cliente. Puede tomar los siguientes valores: LOW – Importancia baja en el momento del día en que se realizó la compra, para análisis de riesgo.NORMAL – Importancia media en el momento del día en que se realizó la compra, para análisis de riesgo.ALTA – Alta importancia en el momento del día en que se realizó la compra, para análisis de riesgo.OFF – El momento de compra no afecta el análisis de riesgo. | < 6 AN | No |
host | Nivel de importancia del correo electrónico y las direcciones IP de los clientes en riesgo de puntuación. Puede asumir los siguientes valores: LOW – Baja importancia del correo electrónico y la dirección IP en el análisis de riesgos.NORMAL – Importancia media del correo electrónico y la dirección IP en el análisis de riesgos.HIGH – Gran importancia del correo electrónico y la dirección IP en el análisis de riesgos.OFF – El correo electrónico y la dirección IP no afectan el análisis de riesgos. | < 6 AN | No |
non_sensical | Nivel de prueba realizado en los datos del comprador con pedidos recibidos sin sentido. Puede tomar los siguientes valores: LOW – Baja importancia de la verificación realizada sobre el pedido del comprador, en el análisis de riesgo.NORMAL – Media importancia de la verificación realizada sobre el comprador orden, en análisis de riesgo.HIGH – Gran importancia de la verificación realizada en el pedido del comprador, en el análisis de riesgo.OFF – La verificación del pedido del comprador no afecta el análisis de riesgo. | < 6 AN | No |
obscenities | Nivel de obscenidad de las órdenes recibidas. Puede tomar los siguientes valores: LOW – Baja importancia de la verificación de obscenidades del pedido del comprador, en el análisis de riesgo.NORMAL – Importancia media de la verificación de obscenidades del comprador orden, en el análisis de riesgo.HIGH - Gran importancia de verificar la orden del comprador en busca de obscenidades en el análisis de riesgo. OFF – Verificar la orden del comprador en busca de obscenidades no afecta el análisis de riesgo. | < 6 AN | No |
phone | Nivel de pruebas realizadas con números de teléfono. Puede tomar los siguientes valores: LOW – Importancia baja en pruebas realizadas con números de teléfono.NORMAL – Importancia media en pruebas realizadas con números de teléfono.HIGH – Gran importancia de las pruebas realizadas con números de teléfono.OFF – La prueba de números de teléfono no afecta el análisis de riesgos. | < 6 AN | No |
velocity | Nivel de importancia de la frecuencia de compra del cliente. Puede tomar los siguientes valores: LOW – Baja importancia sobre el número de compras realizadas por el cliente en los últimos 15 minutos.NORMAL – Media importancia sobre el número de compras realizadas por el cliente en los últimos 15 minutos.HIGH – Gran importancia en el número de compras realizadas por el cliente en los últimos 15 minutos.OFF – La frecuencia de las compras realizadas por el cliente no afectar el análisis de fraude. | < 6 AN | No |
| additional_data.items[].passenger | |||
email | Correo electrónico del pasajero. | < 255 AN | No |
legal_document | Id del pasajero a quien se le emitió el boleto. | < 32 AN | No |
name | Nombre del pasajero. | < 120 AN | No |
rating | Clasificación de pasajeros. Puede tomar los siguientes valores: ADULT – Pasajero adulto.CHILD – Pasajero infantil.INFANT – Pasajero infantil.YOUTH – Pasajero adolescente.ESTUDIANTE – Pasajero estudiante.SENIOR_CITIZEN – Pasajero mayor.MILITARY – Pasajero militar. | < 14 AN | No |
customer_class | Clasificación de aerolínea. Puede utilizar valores como Gold o Platinum. | < 32 AN | No |
| additional_data.items[].passenger.phone | |||
ddi | Código de país del teléfono del pasajero. Para pedidos fuera de E.U.A., se recomienda enviar este campo. | < 3 N | No |
ddd | Código de área del teléfono del pasajero. | < 3 N | No |
number | Número de teléfono del pasajero. | < 9 N | No |
| additional_data.extra_param.acquirer_params[] | |||
key | Id de la información adicional que se enviará. Puede encontrar más detalles sobre cómo enviar este campo en https://developercielo.github.io/Webservice-3.0/#merchant-defined-data. | < 1024 N | NO |
value | Valor de la información adicional a enviar. | < 1024 AN | No |
| additional_data.shipment | |||
name | Nombre del destinatario de la entrega. | < 255 AN | No |
method | Tipo de servicio de entrega de productos. Puede tomar los siguientes valores: SAME_DAY – Servicio de entrega el mismo día.ONE_DAY – Servicio de entrega nocturno o al día siguiente.TWO_DAY – Servicio de entrega en dos días.THREE_DAY – Servicio de entrega en tres días.LOW_COST – Servicio de entrega de bajo costo.PICKUP – Producto recogido en la tienda.OTHER – Otro método de entrega.NONE – No hay servicio de entrega ya que es un servicio o suscripción. | < 9 AN | NO |
| additional_data.shipment.phones[] | |||
ddi | Código de país del teléfono del destinatario de la entrega. Para pedidos fuera de E.U.A., se recomienda enviar este campo. | < 3 N | No |
ddd | Código de área del teléfono del destinatario de la entrega. | < 3 N | No |
number | Número de teléfono del destinatario de la entrega. | < 9 N | No |
| additional_data.connections[] | |||
flight_date | Fecha, hora y minuto de salida del vuelo en formato AAAA-MM-DDTHH:MM:SS. Por ejemplo: 1991-01-02T08:30:00. | = 19 AN | No |
from | Código de aeropuerto del punto de origen del viaje. Por ejemplo: CGH. | = 3 AN | NO |
to | Código de aeropuerto del punto de destino del viaje. Por ejemplo: GYN. | = 3 AN | NO |
Parámetros de respuesta#
Si tiene éxito, el código de respuesta HTTP será "201". 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 creación de transacciones:
| Parámetro | Descripción | Formato |
|---|---|---|
code | Código de respuesta de Portal Carat. Cualquier código que no sea "0" significa error. Más información. | < 4 N |
message | Mensaje de respuesta de Portal Carat. | < 500 AN |
| payment | ||
status | Estado de la transacción de pago en Portal Carat. Más información. | = 3 AN |
nit | Identificador de transacción en el Portal Carat (encriptado). | = 64 AN |
order_id | Código de pedido enviado por la tienda al crear la transacción. | < 40 AN |
merchant_usn | Número secuencial único enviado por la tienda al crear la transacción. | < 12 N |
amount | Monto total de la compra (en centavos). | < 12 N |
| schedule | ||
sid | Identificador de la transacción de reserva en Portal Carat. | = 64 AN |
amount | Monto programado especificado por la tienda (en centavos) para los pagos. | < 12 N |
status | Estado de la agenda en el Portal Carat. Más información. | = 3 AN |
order_id | Código de pedido enviado por la tienda al crear la transacción. | < 40 AN |
merchant_usn | Número secuencial único enviado por la tienda al crear la transacción. | < 12 N |