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

Home

Detalles de la llamada#

Ejemplos#

Cancelamento#

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

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

Parámetros de solicitud#

Parámetros de respuesta#