Anulación

ADVERTENCIA: Esta página es un documento en construcción, sujeto a cambios sin previo aviso, y aún desvinculado de nuestra documentación completa. Si desea acceder a toda nuestra documentación, chequea aquí.

Para realizar operaciones de anulacíon, es necesario llamar al endpoint de anulación utilizando el NIT obtenido en la autorización de la venta. Si el autorizador aprueba la solicitud, el estado de esta transacción se cambiará a EST (invertido).

Nota: El proceso de anulación requiere autenticación con firma. La tienda debe tener una clave pública de cifrado RSA registrada en Carat y debe ensamblar una firma JWT (JSON Web Tokens) para enviar en el encabezado de autorización. En este caso, la información de la transacción de anulación se devolverá directamente en la respuesta del servicio. Más información.

Sin embargo, en escenarios donde la autenticación mutua (mTLS) está habilitada para la tienda, la autenticación con firma ya no es obligatoria, simplemente se envían las credenciales merchant_id y merchant_key.

Detalles de la llamada

• Recurso: /v2/cancellations/{nit}
• Método HTTP: POST
• Formato da solicitud: JSON
• Formato da respuesta: 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
Authorization	La firma de autenticación de la tienda debe enviarse en el formato Bearer {firma}". Ejemplo: Bearer JHVGytfdgauygdauiw78264284527852897hagdg`. Este campo es obligatorio, a menos que la tienda esté configurada para comunicarse con autenticación mutua (mTLS) con Carat.	< 2000 AN	COND.

Ejemplos

A continuación, se muestran algunos ejemplos de llamadas al servicio de anulación con la herramienta cURL.

Anulación

Solicitud:

curl --location --request POST 'https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v2/cancellations/0a5e7dc9ef8ed24819c06a9bc1ed71f653671c931bd33fa49413477352de40d1' \

--header 'Content-Type: application/json' \

--header 'merchant_id: xxxxxxxxxxxxxxx' \

--header 'merchant_key: xxxxxxxxxxxxxxx' \

--header 'Authorization: Bearer {{assinatura}}'

Respuesta:

{

"code": "0",

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

"cancellation": {

"authorizer_code": "200",

"authorizer_message": "Refund successful. [Cód.: 359]",

"status": "CON",

"nit": "1c1caed9c650b298e52e8b1acd7d9eb6b6e85bf029dc285f682b86e6283479ac",

"order_id": "1665693831749",

"customer_receipt":"=== COMPROVANTE ===",

"merchant_receipt":"=== COMPROVANTE ===",

"authorizer_id": "2",

"acquirer_id": "202",

"acquirer_name": "e.Rede REST",

"authorizer_date": "08/09/2022T17:43",

"merchant_usn": "12050620649",

"esitef_usn": "221013109643171",

"host_usn": "828420940",

"tid": "221013109643160",

"amount": "1300",

"payment_type": "C",

"esitef_date": "08/09/2022T17:43",

"is_host_cancel": "false"

}

}

IMPORTANTE: Algunos adquirentes pueden exigir el envio de los datos de tarjeta en la solicitud. En estos casos, el siguiente ejemplo muestra como debe realizarse esa solicitud.

Solicitud:

curl --location --request POST 'https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v2/cancellations/1bfff28297349381d8fc66fd0162c711ea5a61d932077d0109fe5642e7188e74' \

--header 'Content-Type: application/json' \

--header 'merchant_id: xxxxxxxxxxxxxxx' \

--header 'merchant_key: xxxxxxxxxxxxxxx' \

--header 'Authorization: Bearer {{firma}}' \

--data-raw '{

"amount": "1100",

"card": {

"expiry_date": "1222",

"security_code": "123",

"number": "5555555555555555"

}

}'

Respuesta:

{

"code": "0",

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

"cancellation": {

"authorizer_code": "000",

"authorizer_message": "Transacao Aprov.",

"status": "CON",

"nit": "ece6580e54c4bbef28a2f0267ab385a9c87740479acf717a26e60e8f068c6606",

"order_id": "1662748697539",

"customer_receipt":"=== COMPROVANTE ===",

"merchant_receipt":"=== COMPROVANTE ===",

"authorizer_id": "2",

"acquirer_id": "1005",

"acquirer_name": "Redecard",

"authorizer_date": "09/09/2022T15:39",

"authorization_number": "093557",

"merchant_usn": "12050620649",

"esitef_usn": "220909107099221",

"sitef_usn": "093558",

"host_usn": "999093558 ",

"amount": "1100",

"payment_type": "C",

"issuer": "2",

"authorizer_merchant_id": "000000000000005",

"esitef_date": "09/09/2022T15:39",

"is_host_cancel": "false"

}

}

En la respuesta a la solicitud de anulación, obtenemos también un nit. Este nit es el identificador de la transacción de anulación en Carat. Por lo tanto, puede usarse en la API de consulta para consultar los datos de la anulación.

Anulación - Token de marca de tarjeta

Algunas marcas de tarjetas poseen una solución de tokenización que ofrece el almacenamiento de tarjetas en cajas fuertes en la propia marca, de forma encriptada. Esta tokenización de marca tiene como objetivo mejorar la seguridad y la calidad de la información de la tarjeta transmitida, lo que conduce a posibles aumentos en la conversión de la aprobación por parte de los bancos emisores.

Parámetro	Descripción	Formato	Requerido
card
number	Token generado por la tarjeta (DPAN).	≤ 19 N	Sí
cryptogram	Criptograma generado por la tarjeta.	= 28 A	No

Solicitud:

curl --location --request POST 'https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v2/cancellations/e7403160cca530cadb9567222dc3abed55a1db47de2229453e08244dd97bb33b' \

--header 'Content-Type: application/json' \

--header 'merchant_id: xxxxxxxxxxxxxxx' \

--header 'merchant_key: xxxxxxxxxxxxxxx' \

--header 'Authorization: Bearer {{assinatura}}'

--data-raw '{

"amount": "1100",

"card": {

"expiry_date": "1222",

"security_code": "123",

"number": "5555555555555555",

"cryptogram": "ALRzlt6NKQtPAAZAkOuIAAADFA=="

}

}'

Respuesta:

{

"code": "0",

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

"cancellation": {

"authorizer_code": "000",

"authorizer_message": "Transacao Aprov.",

"status": "CON",

"nit": "0e6afaa006d85e259bcc776c8694277b4bc8afb8971295325fe1142aa922220c",

"order_id": "1676900808881",

"customer_receipt":"=== COMPROVANTE ===",

"merchant_receipt":"=== COMPROVANTE ===",

"authorizer_id": "2",

"acquirer_id": "1005",

"acquirer_name": "Redecard",

"authorizer_date": "20/02/2023T10:46",

"authorization_number": "203932",

"merchant_usn": "12050620649",

"esitef_usn": "230220004506181",

"sitef_usn": "203939",

"host_usn": "999203939 ",

"amount": "1100",

"payment_type": "C",

"issuer": "2",

"authorizer_merchant_id": "000000000000005",

"esitef_date": "20/02/2023T10:46",

"is_host_cancel": "false"

}

}

Parámetros de solicitud

En la siguiente tabla se muestra la descripción de los parámetros de solicitud de servicio de anulación:

Parámetro	Descripción	Formato	Requerido
amount	Valor en centavos a anular. Es importante tener en cuenta que no todos los adquirentes admiten un extorno con un valor menor que el pago (anulación parcial). Si este campo no se envía, Portal Carat utilizará el monto total del pago.	< 12 N	NO
card	La obligación de este objeto depende única y exclusivamente del adquirente utilizado en la transacción.
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Í
cryptogram	Criptograma generado por la marca de la tarjeta	= 28 AN	NO
expiry_date	Fecha de vencimiento de la tarjeta en formato "MMAY".	= 4 N	COND.
security_code	Código de seguridad.	< 5 N	COND.

Parámetros de respuesta

Si tiene é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 anulación:

Parámetro	Descripción	Formato
code	Código de respuesta de Portal Carat. Cualquier código que no sea "0" (cero) significa falla. [Más información.] (codigos-da-api.md#codigos-de-resposta)	< 4 N
message	Mensaje de respuesta de Portal Carat.	< 500 AN
cancellation
authorizer_code	Código de respuesta del autorizador.	< 10 AN
authorizer_message	Mensaje de respuesta del autorizador.	< 500 AN
status	Status de la transacción de anulación de Portal Carat. [Más información.] (codigos-da-api.md#status-de-transacões-do-e-sitef)	= 3 AN
nit	Número de identificación de la transacción de anulación en el 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 momento de la creación de la transacción.	< 12 N
amount	Monto de anulación especificado en la tienda (en centavos).	< 12 N
sitef_usn	Número secuencial único de la transacción de anulación de SiTef.	= 6 N
esitef_usn	Número secuencial único de la transacción de anulación en el Portal Carat.	= 15 N
customer_receipt	Cupón (a través del cliente).	< 4000 AN
merchant_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 efectiva de anulación devuelta por el autorizador en formato DD / MM / YYYY'T'HH: mm. Ejemplo: 07/13 / 2017T16: 03	= 16 D
authorization_number	Numero de autorización.	< 6 AN
host_usn	NSU Autorizador.	< 20 AN
tid	ID de transacción en el adquirente. Este campo solo se devuelve en transacciones con adquirentes externos al SiTef.	< 40 AN
esitef_date	Fecha efectiva de anulación en el Portal Carat en el formato DD / MM / AAAA'T'HH: mm. Ejemplo: 07/13 / 2017T16: 03	= 16 D
issuer	Código de la marca de la tarjeta devuelto por el autorizador.	< 5 AN
authorizer_merchant_id	Código de afiliación del comerciante con la agencia autorizadora.	< 100 AN
is_host_cancel	Este campo devolverá el valor "verdadero" en caso de anulación a través del host.	< 5 T / F
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