Pago con Idempotência
Interfaz de pagos que permite a la tienda solicitar autorizaciones de venta utilizando idempotência
#
Detalles de la llamada- Recurso:
/v2/payments/
- Método HTTP:
POST
- Formato da requisição:
JSON
- Formato da resposta:
JSON
- Parâmetros de cabeçalho:
Parâmetro | Descrição | Formato | Obrigatório |
---|---|---|---|
merchant_id | Código de tienda en el Portal Carat. Los códigos de producción y certificación serán diferentes. | < 15 AN | SIM |
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 | SIM |
Content-Type | Debe enviarse con el valor application/json . | = 15 AN | SIM |
idempotency_key | Es como un código aleatorio (identificador), de hasta 80 caracteres, creado por el integrador que utilizará la API Carat. | < 80 N | SIM |
#
EjemplosSolicitud:
Para usar este ejemplo y los demás, no olvide establecer la variable {{url}} en el valor
esitef-homologacao.softwareexpress.com.br
Respuesta:
#
Pago utilizando la misma idempotency_key con diferente order_idSolicitud:
Respuesta:
#
Realizar una preautorización si la idempotency_key es la misma que una transacción de pagoSolicitud:
Respuesta :
#
Parámetros de solicitudEn 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. Para las transacciones enrutadas a través del adquiriente Bin, hay un límite de 20 caracteres. | < 40 AN | SÍ | |||
installments | Número de plazos. Envíe ‘1’ para transacciones en efectivo. | < 2 N | SÍ | |||
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 | SÍ | |||
authorizer_id | Código de autorizador en el Portal Carat. Más información. | < 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 | SÍ | |||
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 | |||
card | Datos de la tarjeta. | |||||
number | Número de tarjeta del comprador (PAN). Token generado por la tarjeta (DPAN) para pago con token de marca de tarjeta. Más información | < 19 N | SÍ | |||
expiry_date | Fecha de vencimiento de la tarjeta en formato MMAA . Su obligación depende del comprador elegido. En la mayoría de los casos, este campo es obligatorio. | = 4 N | COND. | |||
security_code | Código de seguridad. Este campo puede no ser obligatorio si la empresa tiene un acuerdo en el contrato firmado con las redes adquirentes, solo para el pago de ciertos segmentos. Sin embargo, es posible configurar el campo obligatorio en la configuración de la tienda, consulte el soporte de Carat para obtener más información. Importante: un pago con horario agendado implica el almacenamiento de la tarjeta comprador de datos en el entorno de Portal Carat. Sin embargo, por razones de seguridad, el código de seguridad no se puede almacenar. Por tanto, los pagos programados siempre se ejecutarán sin enviar el código de seguridad. | < 5 N | COND. | |||
holder | Nombre del tarjetahabiente. Requerido solo para pagos con e-Rede, GetNet WS y VR (SmartNet). | < 30 AN | COND. | |||
token | HASH de una tarjeta almacenada en Portal Carat. No está permitido enviar un número de tarjeta abierta (campo número ) y una tarjeta almacenada (campo token ) en la misma solicitud. | = 88 AN | NO | |||
cryptogram | Criptograma generado por la marca de la tarjeta | = 28 AN | NO | |||
wallet_type | Campo que especifica si la transacción se procesa con PAN o DPAN. Si "tipo" está vacío, el valor predeterminado es PAN (número de tarjeta no tokenizado). Si hay una transacción tokenizada, debes enviar el valor “network_token”. | AN | NO | |||
external_authentication | Este elemento recibe campos de resultado de autenticación MPI. | |||||
eci | Indicador de comercio electrónico: indica el nivel de seguridad de la transacción con autenticación del titular de la tarjeta | < 3 N | NO | |||
xid | Identificador de la operación de autenticación del titular de la tarjeta, realizada en un servicio ajeno al Portal Carat | < 40 N | NO | |||
cavv | Valor de verificación de autenticación del titular de la tarjeta: código que indica el resultado de la autenticación del titular de la tarjeta. | < 40 N | NO | |||
acquirer | Se requieren datos específicos según el adquirente / enrutamiento. | |||||
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 | NO | |||
special_code | Código de uso general de Conductor / Renner. | < 6 N | NO | |||
mid | Código de comerciante adquirente: para las rutas BIN, el MID que utilizará el comerciante es único. Este campo debe usarse si es necesario seleccionar un MID diferente al predeterminado. | < 15 AN | COND. | |||
recurrency | Flag que define si se paga y el no. Aceptado para todos los enrutamientos a través de SiTef, Cielo e-Commerce, Stone WS, Global Payments WS, SafraPay, e.Rede REST y GetnetWS. En caso de recursividad a través de Stone WS, es obligatorio enviar solo un campo adicional a continuación, is_first_recurring The is_subsequent_recurring . | 5 T / F | NO | |||
recurrency_tid | TID de la primera transacción en repetición. Identificador que diferencia la primera recurrencia de las posteriores. Solo se usa cuando se trata de una recurrencia. Campo utilizado únicamente en el enrutamiento REST de e.Rede para las marcas Visa y Mastercard y en el enrutamiento GetnetWS. | 18 AN | NO | |||
is_first_recurring | Flag utilizada en solitario para el enrutamiento de StoneWS. Indica que la transacción es la primera de una serie de transacciones recurrentes. | 5 T / F | COND. | |||
is_subsequent_recurring | Flag utilizada en solitario para el enrutamiento de StoneWS. Indica que la transacción es la segunda o la enésima de una serie de transacciones recurrentes, donde n > 2. | 5 T / F | COND. | |||
recurrency_original_amount | Valor original de la transacción que inició la recurrencia. Este valor debe ser informado en todas las recurrencias posteriores. Se usa solo para la recurrencia. Campo utilizado solo en enrutamiento BIN, obligatorio cuando haya recurrencia | < 18 AN | NO | |||
product_code | Código de producto. Es obligatorio en el enrutamiento vía Marisa. | < 6 N | COND. | |||
terminal | Terminal SiTef que desea utilizar. Si no se envía, PayPal generará una terminal aleatoria. | = 14 N | NO | |||
company_code | Código de la empresa SiTef que desea utilizar. Si no se envía, PayPal enviará el código de empresa registrado en la tienda. | = 8 N | NO | |||
authorization_number | Código de Autorización. Obligatorio para el autorizador de Bradescard Voucher | < 6 AN | COND. | |||
acquirer.vouchers_filter[] | Filtro de Vouchers: elección de cupones que no se aceptarán. Opciones de "Vouchers": 01 - Alimentación, 02 - Comida 03 - Cultura, 04 - Combustible, 05 - Beneficio. Ejemplo: No se aceptan cupones: Cultura, Combustible, Beneficio. Debe enviar: "vouchers_filter": ["03", "04", "05"] | |||||
acquirer.prefixes | Elemento para enviar prefijos SiTef, como CYCLES, CPLANO y VLRADD. Si el prefijo enviado no es compatible con la tarjeta enviada, Portal Carat invalidará la transacción, evitando que se dé una falsa impresión del uso de una determinada funcionalidad. Ejemplo: { "key" : "value" } -> { "CICLOS" : "01" } | |||||
key | Nombre de prefijo. | < 1024 AN | NO | |||
value | Valor de prefijo. | < 1024 AN | NO | |||
acquirer.submerchant_split[] | Consiste en una matriz para pagos divididos, exclusiva para enrutamiento BIN y Sipag, ambos a través de SiTef. Permite dividir partes del monto total del pago entre otras empresas. El número máximo de elementos permitidos en esta matriz es de 5 elementos. Cada elemento se compone de los campos submechant_code y submerchant_amount . | |||||
submerchant_code | Código de establecimiento BIN / Sipag | < 51 AN | NO | |||
submerchant_amount | valor de transacción para el establecimiento | < 12 N | NO | |||
acquirer.card_on_file | Está destinado al envío de información específica como, por ejemplo, la autorización de almacenamiento de la tarjeta, confirmando que el titular de la tarjeta ha autorizado el almacenamiento de la misma. Más información. | |||||
usage | Indica el uso. Por ejemplo, en caso de autorización de almacenamiento: authorized | < 11 AN | NO | |||
reason | Indica el motivo. Por ejemplo, en caso de autorización de almacenamiento: card | < 11 AN | NO | |||
ATENCIÓN: Los parámetros | ||||||
additional_data | Elemento para el envío de datos adicionales. | |||||
postpone_confirmation | Este campo debe enviarse con el valor true si se desea un pago con confirmación tardía. | < 5 T/F | NO | |||
visitor_id | Identificador de visitante obtenido del JavaScript del Konduto | < 40 AN | NO | |||
description | Descripción del producto | < 100 AN | NO | |||
discount_amount | Importe de descuento del producto en centavos | < 10 N | NO | |||
discount_info | Información de descuento. | < 500 AN | NO | |||
sku | Artículo Código de producto | < 100 AN | NO | |||
creation_date | Indica la fecha de publicación del producto en el sitio web de la tienda (Formato: DD / MM / AAAA ) | = 10 AN | NO | |||
additional_data.payer | Elemento de envío de datos sobre el comprador. | |||||
name | Nombre del cliente | < 100 AN | SÍ | |||
surname | Apellido del cliente | < 100 AN | SÍ | |||
email | Dirección de correo electrónico del cliente | < 100 AN | SÍ | |||
born_date | Fecha de nacimiento del cliente (formato: AAAA-MM-DDTHH: MM: SS ) | = 19 AN | NO | |||
identification_number | Número de documento fiscal del cliente | < 100 AN | NO | |||
creation_date | Fecha de creación de la cuenta o registro del cliente en el sitio web (formato: DD / MM / AAAA ) | = 10 AN | NO | |||
is_new_client | Booleano que indica si el cliente está utilizando una cuenta recién creada para esta compra | < 5 T / F | NO | |||
is_vip_client | Booleano que indica si se trata de un cliente VIP o un comprador frecuente. | < 5 T / F | NO | |||
additional_data .passengers[] | Información del pasajero | |||||
name | Nombre del pasajero | < 100 AN | SÍ | |||
last_name | Apellido del pasajero | < 100 AN | SÍ | |||
legal_document | Número de documento | < 100 AN | SÍ | |||
legal_document_type | Tipo de documento (5 = pasaporte, cualquier otro número = id) | < 8 AN | SÍ | |||
birth_date | Fecha de nacimiento del pasajero (formato: AAAA-MM-DDTHH: MM: SS ) | < 17 AN | NO | |||
nationality | País de nacimiento del pasajero, según ISO 3166-1 alfa-3 | = 3 AN | NO | |||
is_frequent_traveler | Flag de viajero frecuente | < 5 T / F | NO | |||
is_with_special_needs | Flag de viajero con necesidades especiales | < 5 T / F | NO | |||
frequent_flyer_card | Tipo de programa de fidelización | < 255 AN | NO | |||
customer_class | Categoría del programa de fidelización | < 255 AN | NO | |||
additional_data .hotel_reservations[] | Información de reserva de hotel | |||||
hotel | Nombre del hotel | < 100 AN | SÍ | |||
categoría | Categoría de hotel | < 100 AN | NO | |||
additional_data .hotel_reservations [] .address | Información sobre la dirección del hotel | |||||
street_name | Calle del hotel | < 255 AN | NO | |||
street_number | Número de hotel | < 255 AN | NO | |||
complement | Complemento de la dirección del hotel. | < 100 AN | NO | |||
city | Hotel City | < 100 AN | NO | |||
state | Acrónimo de Hotel State | < 100 AN | NO | |||
zip_code | Código postal del hotel | < 100 AN | NO | |||
country | País del hotel, según ISO 3166-1 alfa-3. | = 3 AN | NO | |||
additional_data .hotel_reservations[] .rooms[] | Información de las habitaciones del hotel | |||||
number | Número de habitación | < 100 AN | NO | |||
code | Código de habitación | < 100 AN | NO | |||
type | Tipo de habitación | < 100 AN | NO | |||
check_in_date | Fecha y hora de entrada (formato: AAAA-MM-DDTHH: MM: SS ) | < 17 AN | NO | |||
check_out_date | Fecha y hora de salida (formato: AAAA-MM-DDTHH: MM: SS ) | < 17 AN | NO | |||
number_of_guests | Numero de personas | < 9999 N | NO | |||
board_basis | Régimen de alimentación | < 100 AN | NO | |||
additional_data .hotel_reservations[] .rooms[] .guests[] | Información de los huéspedes de la habitación | |||||
name | Nombre de invitado | < 100 AN | SÍ | |||
document | Número de documento de invitado | < 8 AN | NO | |||
document_type | Documento utilizado por el cliente:
| < 8 AN | NO | |||
birth_date | Fecha de nacimiento del cliente (formato: AAAA-MM-DDTHH: MM: SS ) | < 17 AN | NO | |||
nationality | Nacionalidad del invitado, según ISO 3166-1 alpha-3. | = 3 AN | NO | |||
additional_data .events[] | Información relacionada con los datos del evento | |||||
name | Nombre del evento | < 255 AN | SÍ | |||
date | Fecha y hora del evento en UTC (formato AAAA-MM-DDTHH: MM: SS ) | < 17 AN | SÍ | |||
type | Tipo de evento:
| < 9 AN | SÍ | |||
subtype | Detalle del tipo de evento | < 255 AN | NO | |||
additional_data .events[] .venue | Información sobre los datos de ubicación de un evento | |||||
name | Nombre de la ubicación | < 255 AN | NO | |||
street_name | Nombre de la calle | < 255 AN | NO | |||
street_number | Número de calle | < 255 AN | NO | |||
city | Ciudad del lugar | < 255 AN | NO | |||
state | Estado de la ubicación | < 255 AN | NO | |||
country | País de ubicación, siguiendo ISO 3166-1 alfa-3. | = 3 AN | NO | |||
cpacity | Capacidad de la ubicación | < 255 AN | NO | |||
additional_data .events[] .tickets[] | Información de entradas para eventos | |||||
id | Identificador único del ticket. | < 255 AN | NO | |||
category | Categoría de entrada:
| < 10 AN | SÍ | |||
section | Sección de entradas | < 255 AN | NO | |||
premium | Indicador de entrada premium | < 5 T / F | NO | |||
additional_data .events[] .tickets[] .attendee | Información de los participantes del evento | |||||
name | Nombre del participante | < 255 AN | NO | |||
document | Documento del participante | < 100 AN | SÍ | |||
document_type | Tipo de documento del participante:
| < 100 AN | NO | |||
birth_date | Fecha de nacimiento del participante (formato: AAAA-MM-DDTHH: MM: SS ) | < 17 AN | NO | |||
additional_data.merchant | Elemento para el envío de datos relativos al comerciante. | |||||
email | Dirección de correo electrónico del cliente | < 100 AN | SÍ | |||
additional_data .connections[] | Información sobre conexiones de viaje | |||||
journey_type |
| < 7 AN | SÍ | |||
origin_city | Ciudad de origen. | < 100 AN | SÍ, si transport_type = bus | |||
destination_city | Ciudad de destino. | < 100 AN | SÍ, si transport_type = bus | |||
from | Código de aeropuerto IATA para el aeropuerto de origen | = 3 AN | SÍ, si transport_type = flight | |||
to | Código de aeropuerto IATA para el aeropuerto de destino. | = 3 AN | SÍ, si transport_type = flight | |||
departure_date | Fecha y hora de envío (formato: AAAA-MM-DDTHH: MM: SS ) | < 17 AN | SI | |||
class | Nombre de la clase (Ex: economy , business e first ) | < 8 AN | NO | |||
class_code | Código de clase | < 20 AN | NO | |||
company | Nombre de la compañía aérea | < 20 AN | NO | |||
additional_data .billing_data .address | Información de la factura | |||||
street_name | Calle de la factura del cliente con el banco | < 255 AN | NO | |||
street_number | Número de calle de la factura del cliente con el banco | < 255 AN | NO | |||
complement | Complemento de dirección de factura. | < 100 AN | NO | |||
city | Ciudad de Holder | < 100 AN | NO | |||
state | Estado del titular | < 100 AN | NO | |||
zip_code | Código postal del propietario | < 100 AN | NO | |||
country | Código de país del titular, según ISO 3166-1 alfa-3 | = 3 AN | NO | |||
additional_data .travel | Información sobre tarifas aéreas | |||||
transport_type | Tipo de viaje (flight ou bus ) | < 6 AN | SÍ | |||
expiration_date | Fecha de caducidad (formato: DD / MM / AAAA ) | = 10 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 | 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 anulara el pago que ya ha sido autorizado. | < 19 AN | SÍ para el análisis de fraude |
journey_type | Tipo de viaje. Valores permitidos:ROUND_TRIP – ida y vuelta.OUTWARD – ida.RETURN – vuelta. | < 10 AN | No |
#
Parámetros de respuestaSi 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 realización de pagos:
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.] (Api-codes.md # response-codes) | < 4 N |
message | Mensaje de respuesta de Portal Carat. | < 500 AN |
payment | ||
authorizer_code | Código de respuesta del autorizador. | < 10 AN |
authorizer_message | Mensaje de respuesta del autorizador. | < 500 AN |
status | Estado de la transacción de pago en Portal Carat. Más información. | = 3 AN |
nit | Identificador de la transacción de pago en Carat. | = 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 | Importe de la compra especificado por la tienda (en centavos) al momento de la creación de la transacción. | < 12 N |
sitef_usn | Número secuencial único de la transacción de pago de SiTef. | = 6 N |
sitef_usn | Número secuencial único de la transacción de pago en Pagamento Online. | = 15 N |
customer_receipt | Cupón (a través del cliente). | < 4000 AN |
comerciante_receipt | Cupón (vía establecimiento). | < 4000 AN |
authorizer_id | Código de autorización utilizado en la transacción. | < 4 N |
acquirer_id | Código del adquirente utilizado en la transacción. | < 4 N |
acquirer_name | Nombre del adquirente utilizado en la transacción. | < 100 AN |
authorizer_date | Fecha de vigencia del pago devuelta por el autorizador en formato DD / MM / AAAA'T'HH: mm . Ejemplo: 07/13 / 2017T16: 03 | = 16 D |
authorization_number | Numero de autorización. | < 6 AN |
host_usn | Autorizador NSU. | < 15 AN |
tid | ID de transacción en el adquirente. Este campo solo se devuelve en transacciones con adquirentes que no son SiTef. | < 40 AN |
eci | Indicador de comercio electrónico (indicador del nivel de seguridad de las transacciones de pago). | < 3 AN |
payment_date | Fecha de vigencia del pago en Portal Carat en el formato DD / MM / AAAA'T'HH: mm . Ejemplo: 07/13 / 2017T16: 03 | = 16 D |
issuer | Marca el código devuelto por el autorizador. | < 5 AN |
authorizer_merchant_id | Código de afiliación del comerciante con la agencia autorizadora. | < 100 AN |
xid | Campo XID devuelto en autenticaciones 3DS o ciertos adquirentes. | < 40 AN |
cavv | Valor de verificación de autenticación del titular de la tarjeta: código que indica el resultado de la autenticación del titular de la tarjeta. | < 40 N |
recurrency_tid | Id. De transacción (TID) de la bandera, que se refiere a la primera transacción de la recurrencia. Solo se devuelve cuando es una recurrencia. Campo utilizado solo en el enrutamiento REST e.Rede para las marcas Visa y Mastercard. | < 16 AN |
terminal_id | Código de terminal utilizado en la transacción | < 8 AN |
payment_type | Tipo de pago del autorizador elegido: B = comprobante bancario, C = crédito, D = débito, P = tarjeta de crédito de Private Label pura, T = transferencia bancaria, G = tarjeta gift, O = otros métodos de pago, W = comprobante bancario NR vía Web Service | = 1 AN |
payment.analysis | ||
status | Estado de la transacción de pago en Portal Carat. Más información. | = 3 AN |
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 |