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âmetroDescriçãoFormatoObrigatório
merchant_idCódigo de tienda en el Portal Carat. Los códigos de producción y certificación serán diferentes.< 15 ANSIM
merchant_keyClave de autenticación para la tienda de pagos online. Las claves de producción y certificación serán diferentes.< 80 ANSIM
Content-TypeDebe enviarse con el valor application/json.= 15 ANSIM
idempotency_keyEs como un código aleatorio (identificador), de hasta 80 caracteres, creado por el integrador que utilizará la API Carat.< 80 NSIM

Ejemplos#

Solicitud:

Para usar este ejemplo y los demás, no olvide establecer la variable {{url}} en el valor
esitef-homologacao.softwareexpress.com.br

curl --location --request POST 'https://{{url}}/e-sitef/api/v2/payments/' \
--header 'Content-Type: application/json' \
--header 'merchant_id: ************' \
--header 'merchant_key: ************' \
--header 'idempotency_key: ************' \
--data-raw '{
"merchant_usn": "12050620649",
"order_id": "121314",
"installments": "10",
"installment_type": "4",
"authorizer_id": "2",
"amount": "10000",
"card": {
"expiry_date": "1222",
"security_code": "123",
"number": "5555555555555555"
}
}'
--verbose

Respuesta:

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "000",
"authorizer_message": "Transacao Aprov.",
"status": "CON",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "121314",
"customer_receipt": "====CUPOM COMPRADOR====",
"merchant_receipt": "====CUPOM ESTABELECIMENTO====",
"authorizer_id": "2",
"acquirer_id": "229",
"acquirer_name": "Bin",
"authorizer_date": "14/07/2022T11:54",
"authorization_number": "145778",
"merchant_usn": "12050620649",
"esitef_usn": "220714103502410",
"sitef_usn": "145778",
"host_usn": "999145778 ",
"amount": "10000",
"payment_type": "C",
"issuer": "2",
"authorizer_merchant_id": "000000000000005",
"terminal_id": "ES000032",
"payment_date": "14/07/2022T11:54"
}
}

Pago utilizando la misma idempotency_key con diferente order_id#

Solicitud:

curl --location --request POST 'https://{{url}}/e-sitef/api/v2/payments/' \
--header 'Content-Type: application/json' \
--header 'merchant_id: **********' \
--header 'merchant_key: **********' \
--header 'idempotency_key: ************' \
--data-raw '{
"merchant_usn": "12050620649",
"order_id": "1213140",
"installments": "10",
"installment_type": "4",
"authorizer_id": "2",
"amount": "10000",
"card": {
"expiry_date": "1222",
"security_code": "123",
"number": "5555555555555555"
}
}

Respuesta:

{
"code": "1270",
"message": "Idempotent transaction body does not match the original",
"payment": {
"status": "INV",
"nit": "6ffad47ea1446d76160f1241f0fdca39342521df4f3f577920d9c855047fb9a2",
"order_id": "1213140",
"merchant_usn": "12050620649",
"esitef_usn": "230912025329730",
"amount": "10000"
}
}

Realizar una preautorización si la idempotency_key es la misma que una transacción de pago#

Solicitud:

curl --location --request POST 'https://{{url}}/e-sitef/api/v2/preauthorizations/' \
--header 'Content-Type: application/json' \
--header 'merchant_id: **********' \
--header 'merchant_key: **********' \
--header 'idempotency_key: ************' \
--data-raw '{
"merchant_usn": "12050620649",
"order_id": "3232333",
"installments": "1",
"installment_type": "4",
"authorizer_id": "2",
"amount": "2221",
"card": {
"expiry_date": "1223",
"security_code": "123",
"number": "5555555555555555"
}
}'

Respuesta :

{
"code": "1272",
"message": "Idempotent transaction is not of the same type",
"pre_authorization": {
"status": "INV",
"nit": "307020e59b04907c0781124f55db49b0af934274433defa0c85890fe47de2f68",
"order_id": "3232333",
"merchant_usn": "12050620649",
"esitef_usn": "230914025614594",
"amount": "2221"
}
}

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:

ATENCIÓN: Los parámetros terminal y company_code solo deben usarse para enrutamiento a través de SiTef y deben enviarse simultáneamente.
También es necesario solicitar permiso al equipo de servicio de Portal Carat Permite el envío de Company y Sitef Terminal vía REST . Información del pasajero Información de reserva de hotel Información sobre la dirección del hotel Información de las habitaciones del hotel Información de los huéspedes de la habitación Información relacionada con los datos del evento Información sobre los datos de ubicación de un evento Información de entradas para eventos Información de los participantes del evento Información sobre conexiones de viaje Información de la factura Información sobre tarifas aéreas
ParámetroDescripciónFormatoRequerido
merchant_usnNú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 NNO
order_idCó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
installmentsNúmero de plazos. Envíe ‘1’ para transacciones en efectivo.< 2 N
installment_typeTipo 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
authorizer_idCódigo de autorizador en el Portal Carat. Más información.< 3 NNO
amountMonto 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
soft_descriptorTexto adicional que aparecerá con el nombre del establecimiento en el extracto de la tarjeta de crédito del comprador. Más información< 30 ANNO
cardDatos de la tarjeta.
numberNú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
expiry_dateFecha 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 NCOND.
security_codeCó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 NCOND.
holderNombre del tarjetahabiente. Requerido solo para pagos con e-Rede, GetNet WS y VR (SmartNet). < 30 ANCOND.
tokenHASH 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 ANNO
cryptogramCriptograma generado por la marca de la tarjeta= 28 ANNO
wallet_typeCampo 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”.ANNO
external_authenticationEste elemento recibe campos de resultado de autenticación MPI.
eciIndicador de comercio electrónico: indica el nivel de seguridad de la transacción con autenticación del titular de la tarjeta < 3 NNO
xidIdentificador de la operación de autenticación del titular de la tarjeta, realizada en un servicio ajeno al Portal Carat < 40 NNO
cavvValor 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 NNO
acquirerSe requieren datos específicos según el adquirente / enrutamiento.
financing_planCó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 NNO
special_codeCódigo de uso general de Conductor / Renner. < 6 NNO
midCó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 ANCOND.
recurrencyFlag 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 / FNO
recurrency_tidTID 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 ANNO
is_first_recurringFlag utilizada en solitario para el enrutamiento de StoneWS. Indica que la transacción es la primera de una serie de transacciones recurrentes. 5 T / FCOND.
is_subsequent_recurringFlag 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 / FCOND.
recurrency_original_amountValor 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 ANNO
product_codeCódigo de producto.
Es obligatorio en el enrutamiento vía Marisa.
< 6 NCOND.
terminalTerminal SiTef que desea utilizar. Si no se envía, PayPal generará una terminal aleatoria.= 14 NNO
company_codeCó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 NNO
authorization_numberCódigo de Autorización. Obligatorio para el autorizador de Bradescard Voucher < 6 ANCOND.
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.prefixesElemento 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" }
keyNombre de prefijo. < 1024 ANNO
valueValor de prefijo. < 1024 ANNO
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_codeCódigo de establecimiento BIN / Sipag < 51 ANNO
submerchant_amountvalor de transacción para el establecimiento < 12 NNO
acquirer.card_on_fileEstá 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.
usageIndica el uso.
Por ejemplo, en caso de autorización de almacenamiento: authorized
< 11 ANNO
reasonIndica el motivo.
Por ejemplo, en caso de autorización de almacenamiento: card
< 11 ANNO
additional_dataElemento para el envío de datos adicionales.
postpone_confirmationEste campo debe enviarse con el valor true si se desea un pago con confirmación tardía.< 5 T/FNO
visitor_idIdentificador de visitante obtenido del JavaScript del Konduto < 40 ANNO
descriptionDescripción del producto < 100 ANNO
discount_amountImporte de descuento del producto en centavos < 10 NNO
discount_infoInformación de descuento.< 500 ANNO
skuArtículo Código de producto < 100 ANNO
creation_dateIndica la fecha de publicación del producto en el sitio web de la tienda (Formato: DD / MM / AAAA)= 10 ANNO
additional_data.payerElemento de envío de datos sobre el comprador.
nameNombre del cliente < 100 AN
surnameApellido del cliente < 100 AN
emailDirección de correo electrónico del cliente < 100 AN
born_dateFecha de nacimiento del cliente (formato: AAAA-MM-DDTHH: MM: SS)= 19 ANNO
identification_numberNúmero de documento fiscal del cliente < 100 ANNO
creation_dateFecha de creación de la cuenta o registro del cliente en el sitio web (formato: DD / MM / AAAA)= 10 ANNO
is_new_clientBooleano que indica si el cliente está utilizando una cuenta recién creada para esta compra < 5 T / FNO
is_vip_clientBooleano que indica si se trata de un cliente VIP o un comprador frecuente. < 5 T / FNO
additional_data
.passengers[]
nameNombre del pasajero < 100 AN
last_nameApellido del pasajero < 100 AN
legal_documentNúmero de documento < 100 AN
legal_document_typeTipo de documento (5 = pasaporte, cualquier otro número = id) < 8 AN
birth_dateFecha de nacimiento del pasajero (formato: AAAA-MM-DDTHH: MM: SS) < 17 ANNO
nationalityPaís de nacimiento del pasajero, según ISO 3166-1 alfa-3= 3 ANNO
is_frequent_travelerFlag de viajero frecuente < 5 T / FNO
is_with_special_needsFlag de viajero con necesidades especiales < 5 T / FNO
frequent_flyer_cardTipo de programa de fidelización < 255 ANNO
customer_classCategoría del programa de fidelización < 255 ANNO
additional_data
.hotel_reservations[]
hotelNombre del hotel < 100 AN
categoríaCategoría de hotel < 100 ANNO
additional_data
.hotel_reservations []
.address
street_nameCalle del hotel < 255 ANNO
street_numberNúmero de hotel < 255 ANNO
complementComplemento de la dirección del hotel. < 100 ANNO
cityHotel City < 100 ANNO
stateAcrónimo de Hotel State < 100 ANNO
zip_codeCódigo postal del hotel < 100 ANNO
countryPaís del hotel, según ISO 3166-1 alfa-3.= 3 ANNO
additional_data
.hotel_reservations[]
.rooms[]
numberNúmero de habitación < 100 ANNO
codeCódigo de habitación < 100 ANNO
typeTipo de habitación < 100 ANNO
check_in_dateFecha y hora de entrada (formato: AAAA-MM-DDTHH: MM: SS) < 17 ANNO
check_out_dateFecha y hora de salida (formato: AAAA-MM-DDTHH: MM: SS) < 17 ANNO
number_of_guestsNumero de personas < 9999 NNO
board_basisRégimen de alimentación < 100 ANNO
additional_data
.hotel_reservations[]
.rooms[]
.guests[]
nameNombre de invitado < 100 AN
documentNúmero de documento de invitado < 8 ANNO
document_typeDocumento utilizado por el cliente:
  • cpf
  • rg
  • pasaporte
  • id
  • otro
< 8 ANNO
birth_dateFecha de nacimiento del cliente (formato: AAAA-MM-DDTHH: MM: SS) < 17 ANNO
nationalityNacionalidad del invitado, según ISO 3166-1 alpha-3.= 3 ANNO
additional_data
.events[]
nameNombre del evento < 255 AN
dateFecha y hora del evento en UTC (formato AAAA-MM-DDTHH: MM: SS) < 17 AN
typeTipo de evento:
  • espectáculo
  • teatro
  • películas
  • fiesta
  • festival
  • curso
  • deportes
  • corporativo
< 9 AN
subtypeDetalle del tipo de evento < 255 ANNO
additional_data
.events[]
.venue
nameNombre de la ubicación < 255 ANNO
street_nameNombre de la calle < 255 ANNO
street_numberNúmero de calle < 255 ANNO
cityCiudad del lugar < 255 ANNO
stateEstado de la ubicación < 255 ANNO
countryPaís de ubicación, siguiendo ISO 3166-1 alfa-3.= 3 ANNO
cpacityCapacidad de la ubicación < 255 ANNO
additional_data
.events[]
.tickets[]
idIdentificador único del ticket. < 255 ANNO
categoryCategoría de entrada:
  • estudiante
  • senior
  • gobierno
  • social
  • regular
< 10 AN
sectionSección de entradas < 255 ANNO
premiumIndicador de entrada premium < 5 T / FNO
additional_data
.events[]
.tickets[]
.attendee
nameNombre del participante < 255 ANNO
documentDocumento del participante < 100 AN
document_typeTipo de documento del participante:
  • cpf
  • cnpj
  • rg
  • pasaporte
  • otro
< 100 ANNO
birth_dateFecha de nacimiento del participante (formato: AAAA-MM-DDTHH: MM: SS) < 17 ANNO
additional_data.merchantElemento para el envío de datos relativos al comerciante.
emailDirección de correo electrónico del cliente < 100 AN
additional_data
.connections[]
journey_type
  • OUTWARD - para el exterior
  • RETURN - para el retorno
< 7 AN
origin_cityCiudad de origen. < 100 ANSÍ, si transport_type = bus
destination_cityCiudad de destino. < 100 ANSÍ, si transport_type = bus
fromCódigo de aeropuerto IATA para el aeropuerto de origen= 3 ANSÍ, si transport_type = flight
toCódigo de aeropuerto IATA para el aeropuerto de destino.= 3 ANSÍ, si transport_type = flight
departure_dateFecha y hora de envío (formato: AAAA-MM-DDTHH: MM: SS) < 17 ANSI
classNombre de la clase (Ex: economy, business e first) < 8 ANNO
class_codeCódigo de clase < 20 ANNO
companyNombre de la compañía aérea < 20 ANNO
additional_data
.billing_data
.address
street_nameCalle de la factura del cliente con el banco < 255 ANNO
street_numberNúmero de calle de la factura del cliente con el banco < 255 ANNO
complementComplemento de dirección de factura. < 100 ANNO
cityCiudad de Holder < 100 ANNO
stateEstado del titular < 100 ANNO
zip_codeCódigo postal del propietario < 100 ANNO
countryCódigo de país del titular, según ISO 3166-1 alfa-3= 3 ANNO
additional_data
.travel
transport_typeTipo de viaje (flight ou bus) < 6 AN
expiration_dateFecha de caducidad (formato: DD / MM / AAAA)= 10 ANNO

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ámetroDescripciónFormatoRequerido
additional_data
anti_fraudHabilita 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 ANSÍ para el análisis de fraude
journey_typeTipo de viaje. Valores permitidos:
ROUND_TRIP – ida y vuelta.
OUTWARD – ida.
RETURN – vuelta.
< 10 ANNo

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 realización de pagos:

ParámetroDescripciónFormato
codeCó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
messageMensaje de respuesta de Portal Carat. < 500 AN
payment
authorizer_codeCódigo de respuesta del autorizador. < 10 AN
authorizer_messageMensaje de respuesta del autorizador. < 500 AN
statusEstado de la transacción de pago en Portal Carat. Más información.= 3 AN
nitIdentificador de la transacción de pago en Carat.= 64 AN
order_idCódigo de pedido enviado por la tienda al crear la transacción. < 40 AN
merchant_usnNúmero secuencial único enviado por la tienda al crear la transacción. < 12 N
amountImporte de la compra especificado por la tienda (en centavos) al momento de la creación de la transacción. < 12 N
sitef_usnNúmero secuencial único de la transacción de pago de SiTef.= 6 N
sitef_usnNúmero secuencial único de la transacción de pago en Pagamento Online.= 15 N
customer_receiptCupón (a través del cliente). < 4000 AN
comerciante_receiptCupón (vía establecimiento). < 4000 AN
authorizer_idCódigo de autorización utilizado en la transacción. < 4 N
acquirer_idCódigo del adquirente utilizado en la transacción. < 4 N
acquirer_nameNombre del adquirente utilizado en la transacción. < 100 AN
authorizer_dateFecha de vigencia del pago devuelta por el autorizador en formato DD / MM / AAAA'T'HH: mm. Ejemplo: 07/13 / 2017T16: 03= 16 D
authorization_numberNumero de autorización. < 6 AN
host_usnAutorizador NSU. < 15 AN
tidID de transacción en el adquirente. Este campo solo se devuelve en transacciones con adquirentes que no son SiTef. < 40 AN
eciIndicador de comercio electrónico (indicador del nivel de seguridad de las transacciones de pago). < 3 AN
payment_dateFecha de vigencia del pago en Portal Carat en el formato DD / MM / AAAA'T'HH: mm. Ejemplo: 07/13 / 2017T16: 03= 16 D
issuerMarca el código devuelto por el autorizador. < 5 AN
authorizer_merchant_idCódigo de afiliación del comerciante con la agencia autorizadora. < 100 AN
xidCampo XID devuelto en autenticaciones 3DS o ciertos adquirentes. < 40 AN
cavvValor 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_tidId. 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_idCódigo de terminal utilizado en la transacción < 8 AN
payment_typeTipo 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
statusEstado de la transacción de pago en Portal Carat. Más información.= 3 AN
codeCódigo de respuesta de Portal Carat. Cualquier código que no sea "0" significa error. Más información. < 4 N
messageMensaje de respuesta de Portal Carat. < 500 AN