Cancelar Pago con Tarjeta

Cancela un Pago con Tarjeta que está actualmente activo. El enlace se desactivará permanentemente en el sistema.

Endpoint

DELETE /v1/cards/payment-links/{id}

Autenticación

Requiere API Key con el ability card_payment_links:cancel.

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
id	string (UUID)	Sí	ID del Pago con Tarjeta a cancelar

Ejemplo de Solicitud

cURL

curl -X DELETE "https://api.aloha.co/api/external/v1/cards/payment-links/9d8f7a6b-5c4d-3e2f-1a0b-9c8d7e6f5a4b" \
  -H "X-API-KEY: tu_api_key_aqui"

JavaScript

const paymentLinkId = '9d8f7a6b-5c4d-3e2f-1a0b-9c8d7e6f5a4b';

const response = await fetch(
  `https://api.aloha.co/api/external/v1/cards/payment-links/${paymentLinkId}`,
  {
    method: 'DELETE',
    headers: {
      'X-API-KEY': 'tu_api_key_aqui'
    }
  }
);
const data = await response.json();

if (data.success) {
  console.log('Pago con tarjeta cancelado exitosamente');
}

Python

import requests

payment_link_id = '9d8f7a6b-5c4d-3e2f-1a0b-9c8d7e6f5a4b'

headers = {
    'X-API-KEY': 'tu_api_key_aqui'
}

response = requests.delete(
    f'https://api.aloha.co/api/external/v1/cards/payment-links/{payment_link_id}',
    headers=headers
)
data = response.json()

if data['success']:
    print('Pago con tarjeta cancelado exitosamente')

PHP

<?php
$paymentLinkId = '9d8f7a6b-5c4d-3e2f-1a0b-9c8d7e6f5a4b';

$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => "https://api.aloha.co/api/external/v1/cards/payment-links/{$paymentLinkId}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_HTTPHEADER => [
        'X-API-KEY: tu_api_key_aqui'
    ]
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

if ($data['success']) {
    echo 'Pago con tarjeta cancelado exitosamente';
}

Respuesta Exitosa (200 OK)

{
  "success": true,
  "message": "Card payment link cancelled successfully"
}

Errores Posibles

Pago con Tarjeta No Encontrado (404)

{
  "success": false,
  "code": "CARD_PAYMENT_LINK_NOT_FOUND",
  "message": "Card payment link not found"
}

Pago con Tarjeta No Activo (422)

{
  "success": false,
  "code": "CARD_PAYMENT_LINK_NOT_ACTIVE",
  "message": "Card payment link is not active",
  "errors": {
    "status": "Current status is 'cancelled'"
  }
}

Pago con Tarjeta Ya Pagado (422)

{
  "success": false,
  "code": "CARD_PAYMENT_LINK_ALREADY_PAID",
  "message": "Card payment link has already been paid",
  "errors": {
    "status": "Current status is 'completed'"
  }
}

Distínguelo de CARD_PAYMENT_LINK_NOT_ACTIVE: los dos son 422 y los dos significan “no se puede cancelar”, pero piden lo contrario. Ya pagado quiere decir que liquides el pedido; ya cancelado, que emitas un enlace nuevo si todavía quieres cobrar.

Error Interno (500)

{
  "success": false,
  "code": "CARD_PAYMENT_ERROR",
  "message": "Failed to cancel card payment link"
}

Tabla de Errores

Código HTTP	Código de Error	Descripción
401	INVALID_API_KEY	API Key inválida o expirada
403	insufficient_scope	La API Key no tiene el ability card_payment_links:cancel
404	CARD_PAYMENT_LINK_NOT_FOUND	Pago con Tarjeta no encontrado o no pertenece al usuario
422	CARD_PAYMENT_LINK_ALREADY_PAID	El Pago con Tarjeta ya fue pagado: liquida el pedido
422	CARD_PAYMENT_LINK_NOT_ACTIVE	El Pago con Tarjeta ya estaba cancelado
500	CARD_PAYMENT_ERROR	Error interno al desactivar el enlace

Condiciones para Cancelar

Para cancelar un Pago con Tarjeta se debe cumplir la siguiente condición:

1. El estado debe ser active

Cancelar también se reconcilia

Antes de decidir, esta llamada comprueba contra el proveedor si el enlace fue pagado. Un pago que nunca llegó por webhook se liquida aquí y la cancelación se rechaza con CARD_PAYMENT_LINK_ALREADY_PAID, en vez de desactivar un enlace ya cobrado y dejar el pedido sin registro.

Irreversible

Una vez cancelado, un Pago con Tarjeta no puede ser reactivado. El enlace se desactivará permanentemente y deberás crear uno nuevo si necesitas recibir el pago.

Webhook de notificación

Si tienes webhooks configurados, recibirás una notificación con el evento card_payment_link.cancelled cuando el enlace sea cancelado.

Cuándo Cancelar un Pago con Tarjeta

Considera cancelar un Pago con Tarjeta cuando:

• El cliente ya no necesita realizar el pago
• Se creó por error con datos incorrectos
• Deseas actualizar el monto (cancela y crea uno nuevo)
• El enlace ya no es relevante para la transacción