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_idymerchant_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:
Respuesta:
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:
Respuesta:
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.
Respuesta:
Cancelación: uso de la misma idempotency_key y carga útil con diferente cantidad#
Solicitud:
Respuesta:
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 |