Servicio de consulta de tarjetas (preautorización)

Esta sección explica en el contexto de la autorización previa. Consulte el flujo para obtener más detalles.

Desde un NIT de autorización previa con estado NOV (nuevo), es posible consultar el BIN de la tarjeta (primeros seis dígitos) en SiTef para obtener datos sobre sus capacidades (posibilidad de pago a plazos, cuotas máximas, requisito de código de seguridad, etc.), o incluso saber qué autorizador de la tienda es el más Apto para realizar el pago.

En el caso de transacciones de Visa Checkout, este servicio también devolverá datos de la tarjeta y del usuario devuelto por Visa.

Flujo

Descripción del flujo:

1. El comerciante crea una transacción en Portal Carat, pasando información como el código de la tienda, el número de cuotas y el código de pedido y obtiene un NIT (número de identificación de transacción) en respuesta.
2. El comerciante envía el NIT obtenido en el paso anterior y los datos de la tarjeta a consultar. Con eso, el Portal Carat devuelve datos sobre las capacidades de la tarjeta enviada.
3. La tienda virtual luego procede a consumir el servicio de procesamiento de pagos, pasando el NIT y los datos de la tarjeta del comprador. En caso de éxito, la transacción de pago cambiará su estado a CON (confirmado).

Detalles de la llamada

• Recursos: /v1/preauthorizations/{nit}/cards

• Método HTTP: POST

Obs .: a pesar de ser una consulta, se eligió el método POST por razones de seguridad.

• Formato de solicitud: JSON

• Formato de respuesta: JSON

• Parámetros de encabezado:

Nombre del parámetro	Descripción	Tipo	Tamaño	Obligatorio
merchant_id	Código de tienda en el Portal Carat. Los códigos de producción y certificación serán diferentes.	AN	≤ 15	SI
merchant_key	Clave de autenticación para la tienda de pagos online. Las claves de producción y certificación serán diferentes.	AN	≤ 80	SI
Content-Type	Debe enviarse con el valor "application / json" .	AN	= 15	SI

Ejemplo de consulta de tarjeta con envío de autorizador

Solicitud:

curl

--request POST "https://esitef-homologacao.softwareexpress.com.br/e-

sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz123456

7890abcdefghijklmnopqr /cards"

--header "Content-Type: application/json"

--header "merchant_id: xxxxxxxxxxx"

--header "merchant_key: xxxxxxxxxxx"

--data-binary

{

"card":{

"number":"5555555555555555"

},

"authorizer_id":"1"

}

--verbose

Respuesta:

{

"code": "0",

"message": "OK. Transaction successful.",

"preauthorization": {

"status": "NOV"

},

"card": {

"acquirer_name": "Redecard",

"authorizer_id": "1",

"authorizer_response_code": "000",

"is_customer_id_required": "false",

"is_expiry_date_required": "true",

"is_installment_funding_enabled": "true",

"is_security_code_required": "true",

"is_spot_sale_enabled": "true",

"is_with_interest_sale_enabled": "true",

"is_without_interest_sale_enabled": "true",

"max_installments_with_interest": "12",

"min_installments_with_interest": "01",

"prefixes": {

"TRAT": "2",

"PERIFERICO": "1",

"CSEG": "2"

}

}

}

Ejemplo de consulta de tarjeta sin envío de autorizador

Solicitud:

curl

--request POST "https://esitef-homologacao.softwareexpress.com.br/e-

sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz123456

7890abcdefghijklmnopqr/cards"

--header "Content-Type: application/json"

--header "merchant_id: xxxxxxxxxxx"

--header "merchant_key: xxxxxxxxxxx"

--data-binary

{

"card":{

"number":"6543210987654321"

}

}

--verbose

Respuesta:

{

"code": "0",

"message": "OK. Transaction successful.",

"preauthorization": {

"status": "NOV"

},

"card": {

"acquirer_name": "Redecard",

"authorizer_id": "1",

"authorizer_response_code": "000",

"is_customer_id_required": "false",

"is_expiry_date_required": "true",

"is_installment_funding_enabled": "true",

"is_security_code_required": "true",

"is_spot_sale_enabled": "true",

"is_with_interest_sale_enabled": "true",

"is_without_interest_sale_enabled": "true",

"max_installments_with_interest": "12",

"min_installments_with_interest": "01",

"prefixes": {

"TRAT": "2",

"PERIFERICO": "1",

"CSEG": "2"

}

}

}

Ejemplo de Consulta de tarjeta Visa Checkout

Solicitud:

curl

--request POST "https://esitef-homologacao.softwareexpress.com.br/e-

sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz123

4567890abcdefghijklmnopqr/cards"

--header "Content-Type: application/json"

--header "merchant_id: xxxxxxxxxxx"

--header "merchant_key: xxxxxxxxxxx"

--data-binary

{

"card":{

"wallet_transaction_id":"4444444444444444444"

},

"authorizer_id":"406"

}

--verbose

Respuesta:

{

"code": "0",

"message": "OK. Transaction successful.",

"preauthorization": {

"status": "NOV"

},

"card": {

"acquirer_name": "Redecard",

"authorizer_id": "406",

"authorizer_response_code": "000",

"is_customer_id_required": "false",

"is_expiry_date_required": "true",

"is_installment_funding_enabled": "true",

"is_security_code_required": "true",

"is_spot_sale_enabled": "true",

"is_with_interest_sale_enabled": "true",

"is_without_interest_sale_enabled": "true",

"max_installments_with_interest": "12",

"min_installments_with_interest": "01",

"prefixes": {

"TRAT": "2",

"PERIFERICO": "1"

},

"visa_checkout_data": {

"payment_request": {

"currency_code": "BRL",

"subtotal": "115.5",

"total": "115.5",

"order_id": "09387",

"source_id": "LOJAVISACHECK"

},

"user_data": {

"user_first_name": "Comprador",

"user_last_name": "Esitef",

"user_full_name": "Comprador Esitef",

"user_name": "esitef2@gmail.com",

"user_email": "esitef2@gmail.com",

"enc_user_id": "c5DmPXTXC3VwZywsFESEGAqiLM5PXSZG7hgyQgRv0j8=",

"user_personal_id": "12345678909"

},

"creation_time_stamp": 1502206049403,

"payment_instrument": {

"id": "AWUU0/rQrmKCMx+C740kBefZP2GNsdAMYUTXAzCPk+M=",

"last_four_digits": "1010",

"bin_six_digits": "406897",

"verification_status": "VERIFIED",

"issuer_bid": "10029901",

"nick_name": "Cartão PAN",

"name_on_card": "aaaaaaaaaa vvvvvvvvvv",

"card_first_name": "aaaaaaaaaa",

"card_last_name": "vvvvvvvvvv",

"payment_type": {

"card_brand": "VISA",

"card_type": "CREDIT"

},

"billing_address": {

"person_name": "aaaaaaaaaa vvvvvvvvvv",

"first_name": "aaaaaaaaaa",

"last_name": "vvvvvvvvvv",

"line1": "qqqqqqqqqq",

"line2": "eeeeee",

"line3": "wwwwwwwww",

"city": "cccccccc",

"state_province_code": "SP",

"postal_code": "01238010",

"country_code": "BR",

"phone": "987654321",

"default": "false"

},

"card_arts": {

"card_art": [

{

"base_image_file_name": "https://sandbox.secure.checkout.visa.com/VmeCardArts/lg_visa_card.png",

"height": 105,

"width": 164

}

]

},

"expiration_date": {

"month": "11",

"year": "2022"

}

},

"risk_data": {

"advice": "UNAVAILABLE",

"score": 0,

"avs_response_code": "0",

"cvv_response_code": "0",

"age_of_account": "704"

},

"visa_checkout_guest": "false"

}

}

}

Ejemplo de consulta de tarjeta con datos adicionales para el enrutamiento de iCards a través de SiTef

Solicitud:

curl

--request POST "https://esitef-homologacao.softwareexpress.com.br/e-

sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz123456

7890abcdefghijklmnopqr/cards"

--header "Content-Type: application/json"

--header "merchant_id: xxxxxxxxxxx"

--header "merchant_key: xxxxxxxxxxx"

--data-binary

{

"card":{

"number":"6543210987654321"

},

"authorizer_id":"38"

}

--verbose

Respuesta:

{

"code": "0",

"message": "OK. Transaction successful.",

"card": {

"acquirer_name": "iCards",

"authorizer_id": "38",

"authorizer_response_code": "000",

"is_customer_id_required": "true",

"is_expiry_date_required": "true",

"is_installment_funding_enabled": "true",

"is_security_code_required": "true",

"is_spot_sale_enabled": "true",

"is_with_interest_sale_enabled": "true",

"is_without_interest_sale_enabled": "true",

"max_installments_with_interest": "12",

"min_installments_with_interest": "01",

"prefixes": {

"NPSAQ": "0299",

"CAPTPPRE": "1",

"XCAPPREAUT": "11"

},

"is_customer_postal_code_required": "true",

"is_card_holder_required": "true"

},

"preauthorization": {

"status": "NOV"

}

}

Códigos de respuesta

Ver referencia en Códigos API - Códigos de respuesta

Parámetros de solicitud

En la siguiente tabla, hay una descripción de los parámetros de solicitud para el servicio de búsqueda de tarjetas:

Nombre del parámetro	Descripción	Tipo	Tamaño	Obligatorio
authorizer_id	Código del autorizador en Portal Carat, que figura en la [lista de autorizadores] (autorizadores). Este campo solo es obligatorio si se envía el campo "wallet_transaction_id".	N	≤ 3	NO
number	Número de tarjeta del comprador (PAN).	N	≤ 19	NO
token	HASH de una tarjeta almacenada en Portal Carat. No está permitido enviar un número de tarjeta abierto (campo ‘number’) y una tarjeta almacenada (campo ‘token’) en la misma solicitud.	AN	= 88	NO
wallet_transaction_id	ID de una transacción de billetera digital. Por ahora, esta funcionalidad solo está disponible para el autorizador de Visa Checkout (authorizer_id: 406). No está permitido enviar un número de tarjeta abierto (campo ‘number’), una tarjeta almacenada (campo ‘token’) y un wallet_transaction_id en la misma solicitud.	AN	≤ 25	NO

Nota: Aunque no es obligatorio, se recomienda enviar el authorizer_id para la consulta de la tarjeta, principalmente para enrutamiento vía SiTef, con el fin de tener un comportamiento más efectivo en relación al enrutamiento registrado a la empresa autorizante.

Parámetros de respuesta

En caso de éxito, el código de respuesta HTTP será 200. 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 búsqueda de tarjetas:

Nombre del parámetro	Descripción	Tipo	Tamaño
code	Código de respuesta de Portal Carat. Cualquier código que no sea '0' significa falla. Para obtener más información, consulte el documento "Anexo A-2 - Códigos de respuesta".	N	≤ 4
message	Mensaje de respuesta de Portal Carat.	AN	≤ 500
status	Statusvde la transacción de autorización previa en Portal Carat.	AN	= 3
authorizer_code	Código de respuesta del autorizador.	AN	≤ 10
authorizer_message	Mensaje de respuesta del autorizador.	AN	≤ 500
acquirer_name	Nombre de enrutamiento. Por ejemplo: Cielo	AN	≤ 256
authorizer_id	Código de autorizador.	N	≤ 3
is_customer_id_required	Indica la recogida obligatoria del documento del cliente.	T / F	≤ 5
is_expiry_date_required	Indica la obligación de cobrar la fecha de vencimiento de la tarjeta del comprador.	T / F	≤ 5
is_installment_funding_enabled	Indica si el pago a plazos está habilitado.	T / F	≤ 5
is_security_code_required	Indica la recopilación de códigos de seguridad obligatorios.	T / F	≤ 5
is_spot_sale_enabled	Indica si el pago en efectivo está habilitado.	T / F	≤ 5
is_with_interest_sale_enabled	Indica si el pago de intereses está habilitado.	T / F	≤ 5
is_without_interest_sale_enabled	Indica si está habilitado el pago sin intereses.	T / F	≤ 5
max_installments_with_interest	Cuotas máximas con intereses.	N	≤ 2
min_installments_with_interest	Cuota mínima con intereses.	N	≤ 2
visa_checkout_data	Objeto con datos devueltos por Visa Checkout.
financing_plan_list	Objeto consistente en un array de planos de financiamiento presentados en el enrutamiento de Via Certa Financiadora. Un plan de financiación consta de los siguientes campos: - cod_plano: código de identificación del plan de financiación, que debe enviarse en el momento de ejecución del pago; - tipo_plano: código del tipo de plan de financiación; - desc_plan: descripción del plan, que se puede presentar al comprador; - parc_plano: número máximo de cuotas posibles del plan.
is_customer_postal_code_required	Indica la recopilación obligatoria del código postal del usuario (CEP en Brasil).	T / F	<5
key	Nombre de prefijo.	AN	≤ 1024
value	Valor de prefijo	AN	≤ 1024