Preautorización con Idempotencia

Interfaz de preautorización que permite a la tienda realizar solicitudes de preautorización en una sola llamada.

Detalles de la llamada#

  • Recurso: /v2/preauthorizations/
  • Método HTTP: POST
  • Formato de solicitud: JSON
  • Formato de respuesta: JSON
  • Parámetros de encabezado:
ParámetroDescripciónFormatoObrigatorio
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-TypeValor fijo application / json= 15 ANSIM
idempotency_keyEs como si fuera un código aleatorio (identificador), de 80 caracteres, creado como un integrador que usaré en la API do Carat.< 80 NSIM

Ejemplos#

Solicitud:

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

Respuesta:

{
"code": "0",
"message": "OK. Transaction successful.",
"pre_authorization": {
"authorizer_code": "000",
"authorizer_message": "Transacao Aprov.",
"status": "CON",
"nit": "2623a02dcdb6c30c8a243a993c16e983ec270d7dbaf66833e78cb54e610b4e39",
"order_id": "3232333",
"customer_receipt":"=== CUSTOMER RECEIPT ===",
"merchant_receipt":"=== MERCHANT RECEIPT ===",
"authorizer_id": "2",
"acquirer_id": "1005",
"acquirer_name": "Redecard",
"authorizer_date": "13/09/2023T11:42",
"authorization_number": "135858",
"merchant_usn": "12050620649",
"esitef_usn": "230913025438034",
"sitef_usn": "135858",
"host_usn": "999135858 ",
"amount": "2220",
"payment_type": "C",
"issuer": "2",
"authorizer_merchant_id": "000000000000005",
"terminal_id": "ES000038",
"acquirer_cnpj": "67844256000156"
}
}

Preautorización previa utilizando la misma idempotency_key con diferente order_id#

Cuando una solicitud determinada se envía con la misma idempotency_key, pero con un payload diferente.

Solicitud:

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

Respuesta:

{
"code": "1270",
"message": "Idempotent transaction body does not match the original",
"pre_authorization": {
"status": "INV",
"nit": "a9c6e0c275bf6eecb7deca20ab96dfd4733ae1a2f4eb6fd8139df1af876598da",
"order_id": "13232333",
"merchant_usn": "12050620649",
"esitef_usn": "230913025438024",
"amount": "2220"
}
}

Parâmetros de requisição#

ParámetroDescripciónFormatoObligatorio
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<12NSI
encrypted_cardEste 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 encriptada solo será posible con enrutamiento vía SiTef y es necesaria la configuración previa del SiTef en cuestión.
Opciones:
1. "true"
2. "false" (valor defaut)
<5 ANNO
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 es una posible clave 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 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
authorizer_idCódigo de autorizador en el Portal Carat. Ver documento [Autorizadores.] (Authorizadoras.md) < 3 NSI
customer_idDocumento de identidad del comprador. Utilice solo caracteres alfanuméricos (sin puntos, guiones u otros caracteres especiales). < 20 ANNO
discountImporte 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. < 12 NNO
installmentsJunto con el campo installment_type, indica cuotas*, utilizado ÚNICAMENTE con autorizadores enrutados por e-Rede, GetNetLac vía SiTef, Rede vía SiTef, Cetelem vía SiTef e iCards vía SiTef. Envie 1 para transacciones en efectivo. < 2 NCOND.
installment_typeJunto con el campo installments, indica cuotas*, utilizados ÚNICAMENTE con autorizadores enrutados por e-Rede, GetNetLac vía SiTef, Rede vía SiTef, Cetelem vía SiTef e iCards vía SiTef. Para las otras rutas, las cuotas solo son posibles durante la captura. Los valores posibles para tipo_cuota son:
3.: Cuota con interés de la compañía de tarjeta
4.: Cuota realizada por la tienda y sin interés (adoptar este valor como estándar/por defecto para transacciones en effectivo)
= 1 NCOND.
mccMerchant Category Code - Indica el código de categoría de la tienda. Requerido cuando se usasubadquirência Stone WS y es posible enviarlo en subadquirência via SiTef. < 4 N Obligatorio solo para sub adquisición Stone WS
merchant_emailE-mail de la tienda. Este parámetro, cuando se envía, sobrescribe el e-mail de registro de la tienda. < 40 ANNO
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 < 22 ANNO
subtotalImporte 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. < 12 NNO
subacquirer_merchant_idIdentificación de la tienda en el sub adquirente. < 22 NNO
cardDebe se utilizar apenas una entre los campos: number, token o wallet_transaction_id
numberNúmero de tarjeta del comprador (PAN).

Token generado por la tarjeta (DPAN) para pago con token de bandera de tarjeta.
< 19 N
cryptogramCriptograma generado por la tarjeta.= 28 ASí para pagos con token de marca de tarjeta
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”.ANSí para pagos con token de marca de tarjeta
tokenSe 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 ANCOND.
wallet_transaction_idCódigo de identificación de transacción con wallet VisaCheckout. Requerido solo para Visa Checkout < 25 ANCOND.
initial_wallet_transaction_idInforma si el Wallet ID(wallet_transaction_id) se está utilizando por primera vez. Si es la primera vez, envíe true; de lo contrario, envíe false. Requerido solo para Visa Checkout.

Valor predeterminado: true
< 5 ANCOND.
holderNombre del portador de la tarjeta. Requerido solo para enrutamientos e-Rede, GetNet WS y VR (SmartNet). < 30 ANCOND.
expiry_dateFecha de vencimiento de la tarjeta en formato "MMAY".= 4 NCOND.
security_codeCódigo de seguridad. < 5 NCOND.
external_authentication Este elemento recibe campos de autenticación MPI.
versionVersión de 3DS utilizada en el proceso de autenticación (actualmente solo se acepta la versión 2)< 1 ANNO
eciIndicador de comercio electrónico: indica el nivel de seguridad de la transacción con autenticación del titular de la tarjeta < 3 NNO
reference_idIdentificador 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
acquirerDados específicos necessários dependendo da adquirente/roteamento.
terminalTerminal SiTef que desea utilizar. Si no se envía, el Portal Carat generará una terminal aleatoria. = 14 NNO
company_codeCódigo de la empresa SiTef que desea utilizar. Si no se envía, el Portal Carat enviará el código de empresa registrado en la tienda. = 8 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
additional_dataElemento para el envío de datos adicionales.
ecomm_pos_refEste campo enviará una identificación que aparecerá en el campo POS del reporte SiTef Web para transacciones de comercio electrónico.< 8 AFNO

* Parcelamento roteado por GetNetLac via SiTef : Neste caso, a loja será responsável pelo controle do parcelamento, logo não entrarão em vigor as regras de parcelamento configuradas para a interface de pagamento HTML do Carat, somente as regras de parcelamento da autorizadora serão verificadas e aplicadas. Para estas redes mencionadas, caso a pré-autorização seja feita à vista, a captura não pode ser parcelada. Ainda, pré- autorizações roteadas por GetNetLac via SiTef, quando parceladas, apenas são aceitas sem juros, isto é, com o parâmetro installment_type = 4. Parcelamentos com juros não são aceitos para este roteamento.

ATENÇÃO:

Além dos parâmetros de retorno dos serviços descritos nesta especificação o Carat poderá devolver outros parâmetros sem aviso prévio.

É importante que o aplicativo esteja preparado para receber os parâmetros desconhecidos além dos parâmetros já especificados e simplesmente desprezá-los.

Os parâmetros terminal e company_code deverão ser usados somente para roteamentos via SiTef e devem ser enviados simultaneamente.
É necessário também solicitar à equipe de atendimento do Carat a permissão Permite envio de Empresa e Terminal Sitef via REST.

Parâmetros de resposta#

La siguiente tabla contiene los parámetros de respuesta del servicio de promulgación de autorización previa. La aplicación debe almacenar los parámetros que considere necesarios. Sugerimos almacenar los parámetros: order_id, autorización_number, merchant_usn, esitef_usn, sitef_usn, host_usn, status, code, amount, message (el parámetromessage se puede mostrar al cliente).authorization_number

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
pre_authorization
acquirer_idCódigo del adquirente utilizado en la transacción. < 4 N
acquirer_nameNOmbre del adquirente utilizado en la transacción. < 100 AN
amountImporte de la compra especificado por la tienda (en centavos) al momento de la creación de la transacción. < 12 N
authorization_numberNumero de autorización. < 6 AN
authorizer_codeCódigo de resposta do autorizador.< 10 AN
authorizer_dateFecha de ejecución de la autorización previa devuelta por el autorizador en formato DD / MM / AAAA'T'HH: mm. Ejemplo: 13/07 / 2017T16: 03= 16 D
authorizer_idCódigo de autorización utilizado en la transacción. < 4 N
authorizer_merchant_idCódigo de afiliación del comerciante con la agencia autorizadora. < 100 AN
authorizer_messageMensaje de respuesta del autorizador. < 500 AN
customer_receiptCupón (a través del cliente). < 4000 AN
eciIndicador de comercio electrónico (indicador del nivel de seguridad de la transacción de autorización previa). < 3 AN
sitef_usnNúmero secuencial único de la transacción de autorización previa en Portal Carat.= 6 N
host_usnNSU del autorizador. < 15 AN
emisorCódigo de la bandera de la tarjeta devuelto por el autorizador. < 5 AN
merchant_receiptCupón (vía establecimiento).< 4000 AN
merchant_usnNúmero secuencial único enviado por la tienda al crear la transacción. < 12 AN
nitIdentificador de la transacción de autorización previa en Portal Carat.= 64 AN
order_idCódigo de pedido enviado por la tienda al crear la transacción. < 40 AN
payment_typeTipo de pago del autorizador elegido: B = boleto, 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= 1 AN
esitef_usnNúmero secuencial único de la transacción de autorización previa en SiTef.= 15 N
statusStatus de la transacción de autorización previa en Portal Carat.= 3 AN
tidID de transacción en adquirente / enrutamiento. Este campo solo se devuelve en transacciones con adquirentes externos SiTef. < 40 AN
xidCampo XID devuelto en autenticaciones 3DS o ciertos adquirientes / enrutamintos. < 40 AN
retryable_codeIndicador de reversibilidad de una transacción cuya autorización fue denegada por el autorizador. Este campo será devuelto en la respuesta a la solicitud de pago con tarjeta y deberá ser tomado en cuenta en el mecanismo de reintento de transacciones de la tienda en línea. Códigos válidos:
01 – Transacción denegada reversible, retener más tarde.
02 – Transacción denegada irreversible, no retentiva.
= 2 N