Servicio de cancelación
Después de obtener un NIT de cancelación en el paso anterior, la tienda puede efectivamente realizar la reversión.
Después de una cancelación exitosa, la transacción de pago cambiará su estado a EST (extornado). Dependiendo de la adquirente, es posible realizar reversiones parciales, es decir, cancelar un importe inferior al pagado. En este caso, la transacción de pago mantendrá el satus CON.
Detalles de la llamada#
- Recurso:
/v1/cancellations/{nit} - Método HTTP:
PUT - 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 |
Ejemplos#
A continuación, se muestran algunos ejemplos de llamadas al servicio de cancelación con la herramienta cURL.
Cancelación de pago a través de SiTef#
Solicitud:
Para usar este ejemplo, no olvide definir la variable {{url}} con el valor
esitef-homologacao.softwareexpress.com.br
Respuesta:
Cancelación de pago a través de BIN#
Solicitud:
Para usar este ejemplo, no olvide definir la variable {{url}} con el valor
esitef-homologacao.softwareexpress.com.br
Respuesta:
Cancelación a través de host#
Solicitud
Para usar este ejemplo, no olvide definir la variable {{url}} con el valor
esitef-homologacao.softwareexpress.com.br
Respuesta:
Códigos de respuesta
Ver referencia en Códigos API - Códigos de respuesta
Cancelación origen externo#
Solicitud:
Para usar este ejemplo, no olvide definir la variable {{url}} con el valor
esitef-homologacao.softwareexpress.com.br
Respuesta:
Parámetros de solicitud#
En la siguiente tabla se muestra la descripción de los parámetros de solicitud de servicio de cancelación:
| Parámetro | Descripción | Formato | Requerido |
|---|---|---|---|
amount | Valor en centavos a cancelar. Es importante tener en cuenta que no todos los adquirentes admiten un extorno con un valor menor que el pago (cancelación parcial). Si este campo no se envía, Portal Carat utilizará el monto total del pago. | < 12 N | NO |
soft_descriptor | Texto adicional que aparecerá con el nombre del establecimiento en el extracto de la tarjeta de crédito del comprador. [Más información] (soft-descriptor.md) | < 30 AN | NO |
| card | |||
number | Número de tarjeta del comprador (PAN). Obligatorio al cancelar pagos a través de SiTef. | < 19 N | COND. |
expiry_date | Fecha de vencimiento de la tarjeta en formato "MMAY". Su obligación depende del comprador elegido. | = 4 N | COND. |
security_code | Código de seguridad. Obligatorio en función del contrato firmado con las redes adquirentes. | < 5 N | COND. |
token | HASH de una tarjeta almacenada en Pagamento Online. No está permitido enviar un número de tarjeta abierta (campo número) y una tarjeta almacenada (campo token) en la misma solicitud. | = 88 AN | NO |
wallet_transaction_id | ID de una transacción de billetera digital. Por ahora, esta funcionalidad solo está disponible para Visa Checkout y Autorizadores VEE (a través de CardSE a través de SiTef). No está permitido enviar un número de tarjeta abierta (campo número), una tarjeta almacenada (campo token ) y un wallet_transaction_id en la misma solicitud. | < 25 AN | NO |
| acquirer | Los campos de este elemento solo deben enviarse en casos de cancelaciones a través de host, cancelaciones de origen externo o cancelaciones de rutas a través de PayPal. | ||
routing_id | Información de enrutamiento utilizada para pagos realizados fuera de e-SiTef. Esta información, si se envía, se utiliza para identificar el enrutamiento en SiTef. Esta información solo tiene sentido en transacciones de origen externo. | < 5 N | NO |
host_usn | NSU del anfitrión / autorizador de la transacción que se cancelará. Obligatorio para cancelaciones a través de host y origen externo. | = 20 N | COND. |
sitef_usn | SiTef NSU de la transacción a cancelar. Obligatorio para cancelaciones a través de host y origen externo. | = 6 N | COND. |
authorizer_date | Fecha efectiva de pago de SiTef en formato "DD / MM / AAAA". Obligatorio para cancelaciones a través de host y origen externo. | = 6D | COND. |
authorizer_id | Código de autorizador en el Portal Carat. Debe ser la misma cantidad enviada en el pago. Obligatorio para cancelaciones a través de host y origen externo. | < 3 N | COND. |
tef_product_code | Código de producto TEF obtenido al realizar el pago. Este campo puede recibir los siguientes valores: 0001 - Visa 0080 - Mastercard Estos valores pueden ser cambiados por Cielo sin previo aviso. Obligatorio para cancelaciones vía host y origen externo para enrutamiento vía Cielo. | < 4 N | COND. |
tef_flow_code | Código del flujo de TEF obtenido en el pago. Actualmente, este campo solo puede recibir el valor "01" (flujo de crédito). Obligatorio para cancelaciones vía host y origen externo para enrutamiento vía Cielo. | < 2 N | COND. |
authorization_number | Número de autorización de transacción que se cancelará. Obligatorio para cancelaciones a través de host y origen externo. | < 60 N | COND. |
product_code | Código de producto. Es obligatorio y se usa solo cuando se enruta a través de Marisa. | < 6 N | COND. |
refund_type | Tipo de reversión que desea realizar en el pago. Es obligatorio y se usa solo para enrutar a través de Paypal. Valores permitidos: Full - Se desea la reversión total del pago. Partial - Se desea la reversión parcial del pago | < 7 AN | COND. |
currency_code | Código de moneda que se utilizará en la reversión de acuerdo con ISO 4217. Para Real, el código utilizado es BRL. Es obligatorio y se utiliza sólo para enrutar a través de Paypal. | < 3 AN | COND. |
invoice_id | Código de pedido para el reembolso del propio comerciante para consultas futuras o seguimiento. Se usa sólo para enrutar a través de Paypal. | < 127 AN | NO |
note | Mensaje personalizado para recordatorios de devolución de cargo. Solo se usa para enrutamiento a través de Paypal. | < 256 AN | NO |
retry_until | Fecha y hora límite hasta la que se intentará el extorno. Formato: AAAA-MM-DDTHH: MM: SS. Se usa solo para enrutar a través de Paypal. | < 20 AN | NO |
refund_source | Fuente de fondos del comerciante que se utilizará para realizar la reversión. Se usa solo para enrutar a través de Paypal. Valores permitidos: cualquier: el comerciante no tiene preferencia. Se utilizará cualquier fuente de fondos disponible. default: se utilizará la fuente de fondos configurada en la cuenta del comerciante. instant: el saldo del comerciante se utilizará como fuente de fondos. eCheck - La opción “eCheck” se utilizará como fuente de fondos. Si el saldo del comerciante puede cubrir el contracargo, se utilizará el saldo. | < 7 AN | NO |
merchant_store_details | Información sobre el establecimiento del comerciante. Se usa solo para enrutamiento a través de Paypal. | < 50 AN | NO |
refund_advice | Indicador para un cliente que ya ha recibido un reembolso por una transacción determinada. Se usa solo para enrutar a través de Paypal. | < 5 AN | NO |
refund_item_details | Detalles del artículo individual tratado en el extorno. Sólo se usa para enrutar a través de Paypal. | NO | |
msg_sub_id | Este ID identificará de forma única el mensaje y se puede utilizar para solicitar los últimos resultados de una solicitud anterior sin la necesidad de crear una nueva solicitud. Esto se puede hacer, por ejemplo, en llamadas que se cancelaron debido al tiempo de espera o errores durante el proceso. Sólo se utiliza para enrutamiento a través de Paypal. | < 38 AN | NO |
terminal_id | Se usa si es un punto de venta. Se usa solo para enrutamiento a través de Paypal. | < 50 AN | NO |
store_id | Se usa si es un punto de venta. Se usa solo para enrutamiento a través de Paypal. | < 50 AN | NO |
terminal | Terminal SiTef que desea utilizar. Si no se envía, PayPal generará una terminal aleatoria. | = 14 N | NO |
company_code | Código de la empresa SiTef que desea utilizar. Si no se envía, PayPal enviará el código de empresa registrado en la tienda. | = 8 N | NO |
| acquirer.submerchant_split[] | Consiste en una matriz para transacciones divididas, exclusivo para enrutamiento BIN y Sipag, ambos a través de SiTef . Permite la división de partes del monto total del pago entre otras empresas. El número máximo de elementos permitidos en esta matriz es de 5 elementos. Cada elemento se compone de los campos submechant_code y submerchant_amount. | ||
submerchant_code | Código de establecimiento BIN / Sipag | < 51 AN | NO |
submerchant_amout | Valor de transacción para el establecimiento | < 12 N | NO |
ecomm_pos_ref | Este campo enviará una identificación que aparecerá en el campo PDV del informe SiTef Web para transacciones de comercio electrónico. | < 8 AF | NO |
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 cancelació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 cancelació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 cancelación en el Portal 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 cancelación especificado en la tienda (en centavos). | < 12 N |
sitef_usn | Número secuencial único de la transacción de cancelación de SiTef. | = 6 N |
esitef_usn | Número secuencial único de la transacción de cancelació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 cancelació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 cancelació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 cancelación a través del host. | < 5 T / F |