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) que será necesario para los siguientes pasos del flujo, así como el uso del servicio de consulta de transacciones.
NIT tiene 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 pago con análisis de riesgo #
Solicitud:
Resposta:
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. | < 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 | < 25 AN | 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 |
customer_email | Para transacciones REST, envia el comprobante de cliente al e-mail informado. | < 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 |
Campos de MCC dinámicos#
Inicialización de preautorización o transacción de pago REST#
Parámetros de solicitud#
Además de los campos mencionados en Servicio de creación de transacciones REST, Los campos siguientes se utilizan en el escenario dinámico específico de MCC de integración con bin:
| Parámetro | Descripción | Formato | Obligatorio | |||
|---|---|---|---|---|---|---|
soft_descriptor | Frase personalizada que quedará impresa en la factura al portador. Para obtener información sobre el MCC dinámico, equivale al nombre del subinquilino. | < 25 AN | SÍ | |||
| additional_data | Elemento para enviar datos adicionales. | |||||
mcc | Substore MCC. | = 4 N | SÍ | |||
subacquirer_merchant_id | Código de substore. Campo legado!!! Dar preferencia a additional_data.subacquirer_merchant.id | < 15 N | NO | |||
| additional_data.subacquirer_merchant | Elemento de envío de datos referentes al comerciante de un subcomprador. | |||||
id | Código de substore. | < 15 N | SÍ | |||
phone_number | Número de teléfono del subinquilino. | < 14 AN | NO | |||
address | Dirección de substore. | < 48 AN | NO | |||
city | Ciudad del subarrendatario. | < 13 AN | NO | |||
state | Estado de subinquilino, en formato de acrónimo de dos dígitos (ex.: SP). | = 2 A | SÍ | |||
country | País del subarrendatario. seguir el modelo ISO 3166-1 alpha-2 (ex.: BR). | = 2 A | SÍ | |||
zip_code | Código postal del comerciante. | < 9 AN | SÍ | |||
identification_number | CNPJ del propietario de la sub-tienda. | < 18 N | SÍ | |||
payment_facilitator_id | Código de facilitador. | < 11 N | SÍ | |||
Ejemplo#
Solicitud:
Respuesta:
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 |