Cancelación con Idempotencia

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 requisição: JSON
• Formato da resposta: JSON
• Parâmetros de cabeçalho:

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.
idempotency_key	Es como si fuera un código aleatorio (identificador), de 80 caracteres, creado como un integrador que usaré en la API do Carat.	< 80 N	SIM

Ejemplos

Cancelamento

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

Solicitud:

curl --location --request POST 'https://{{url}}/e-sitef/api/v2/cancellations/0a5e7dc9ef8ed24819c06a9bc1ed71f653671c931bd33fa49413477352de40d1' \

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

--header 'merchant_id: xxxxxxxxxxxxxxx' \

--header 'merchant_key: xxxxxxxxxxxxxxx' \

--header 'idempotency_key: ************' \

--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://{{url}}/e-sitef/api/v2/cancellations/1bfff28297349381d8fc66fd0162c711ea5a61d932077d0109fe5642e7188e74' \

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

--header 'merchant_id: xxxxxxxxxxxxxxx' \

--header 'merchant_key: xxxxxxxxxxxxxxx' \

--header 'idempotency_key: ************' \

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

--data-raw '{

"amount": "1100",

"card": {

"expiry_date": "1223",

"security_code": "123",

"number": "5555555555555555"

}

}'

Respuesta:

{

"code": "0",

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

"cancellation": {

"authorizer_code": "000",

"authorizer_message": "Transacao Aprov.",

"status": "CON",

"nit": "70d70a62062d01deaf49a96c98e2c4f7306975c93164c01b5fa639fe8cb9ba05",

"order_id": "1679514603756",

"customer_receipt": ".....S.O.F.T.W.A.R.E.E.X.P.R.E.S.S.... \nSI Rede 5 \nMU Codigo transacao: 400 \nLA Codigo operacao: 200030 \nDO Valor: 111,00 \n.....S...I...M...U...L...A...D...O.... \nSI NSU SiTef: 136447 \nMU 13/09/23 16:16 \nLA ID PDV: ES000053 \nDO Estab.: 000000000000005 \n.....S...I...M...U...L...A...D...O.... \nSI Host: 999136447 \nMU Transacao Simulada Aprovada \nLA \n (SiTef) \n",

"merchant_receipt": ".....S.O.F.T.W.A.R.E.E.X.P.R.E.S.S.... \nSI Rede 5 \nMU Codigo transacao: 400 \nLA Codigo operacao: 200030 \nDO Valor: 111,00 \n.....S...I...M...U...L...A...D...O.... \nSI NSU SiTef: 136447 \nMU 13/09/23 16:16 \nLA ID PDV: ES000053 \nDO Estab.: 000000000000005 \n.....S...I...M...U...L...A...D...O.... \nSI Host: 999136447 \nMU Transacao Simulada Aprovada \n (SiTef) \n",

"authorizer_id": "2",

"acquirer_id": "1005",

"acquirer_name": "Redecard",

"authorizer_date": "13/09/2023T16:16",

"authorization_number": "136446",

"merchant_usn": "12050620649",

"esitef_usn": "230913025455891",

"sitef_usn": "136447",

"host_usn": "999136447 ",

"amount": "1100",

"payment_type": "C",

"issuer": "2",

"authorizer_merchant_id": "000000000000005",

"acquirer_cnpj": "67844256000156",

"esitef_date": "13/09/2023T16:16",

"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.

Cancelación: utilizando la misma idempotency_key y lo mismo payload

Solicitud:

Puede suceder que se devuelvan campos adicionales en la respuesta de la segunda llamada, pero se devolverán todos los campos de la primera solicitud.

curl --location --request POST 'https://{{url}}/e-sitef/api/v2/cancellations/1bfff28297349381d8fc66fd0162c711ea5a61d932077d0109fe5642e7188e74' \

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

--header 'merchant_id: xxxxxxxxxxxxxxx' \

--header 'merchant_key: xxxxxxxxxxxxxxx' \

--header 'idempotency_key: ************' \

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

--data-raw '{

"amount": "1100",

"card": {

"expiry_date": "1223",

"security_code": "123",

"number": "5555555555555555"

}

}'

Respuesta:

{

"code": "0",

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

"cancellation": {

"authorizer_code": "000",

"authorizer_message": "Transacao Aprov.",

"status": "CON",

"nit": "70d70a62062d01deaf49a96c98e2c4f7306975c93164c01b5fa639fe8cb9ba05",

"order_id": "1679514603756",

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

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

"authorizer_id": "2",

"acquirer_id": "1005",

"acquirer_name": "Redecard",

"authorizer_date": "13/09/2023T16:16",

"authorization_number": "136446",

"merchant_usn": "12050620649",

"esitef_usn": "230913025455891",

"sitef_usn": "136447",

"host_usn": "999136447 ",

"amount": "1100",

"payment_type": "C",

"issuer": "2",

"authorizer_merchant_id": "000000000000005",

"terminal_id": "ES000053",

"acquirer_cnpj": "67844256000156",

"esitef_date": "13/09/2023T16:16",

"is_host_cancel": "false"

}

}

Cancelación: uso de la misma idempotency_key y carga útil con diferente cantidad

Solicitud:

curl --location --request POST 'https://{{url}}/e-sitef/api/v2/cancellations/1bfff28297349381d8fc66fd0162c711ea5a61d932077d0109fe5642e7188e74' \

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

--header 'merchant_id: xxxxxxxxxxxxxxx' \

--header 'merchant_key: xxxxxxxxxxxxxxx' \

--header 'idempotency_key: ************' \

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

--data-raw '{

"amount": "11100",

"card": {

"expiry_date": "1223",

"security_code": "123",

"number": "5555555555555555"

}

}'

Respuesta:

{

"code": "1270",

"message": "Idempotent transaction body does not match the original",

"cancellation": {

"status": "INV"

}

}

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