> ## Documentation Index > Fetch the complete documentation index at: https://devs.tapipay.la/llms.txt > Use this file to discover all available pages before exploring further. # Cancelar link de pago > Desactiva un link de pago. Operación idempotente. ## OpenAPI ````yaml /api-reference/openapi.yaml post /payment-links/{id}/cancel openapi: 3.0.0 info: title: TapiPay Facade API version: 1.0.0 description: > Facade API pública de la plataforma de cobranzas TapiPay. Ofrece un contrato limpio y desacoplado del modelo interno del OFU, permitiendo a los clientes crear y gestionar cobros (deudas puntuales, suscripciones recurrentes, links de pago, productos y contactos) sin conocer detalles internos de Company, Modalities o GenerationData. contact: name: TapiPay Team url: https://www.tapipay.com license: name: Proprietary servers: - url: https://tapipay-facade.dev.tapila.cloud description: Desarrollo security: - apiKeyAuth: [] tapiAuth: [] paths: /payment-links/{id}/cancel: post: tags: - Payment Links summary: Cancelar link de pago description: Desactiva un link de pago. Operación idempotente. operationId: cancelPaymentLink parameters: - name: id in: path required: true schema: type: string pattern: ^plk_[a-zA-Z0-9]+$ responses: '200': description: > Link de pago cancelado exitosamente o ya estaba CANCELLED (idempotente). - ACTIVE → CANCELLED: retorna 200 con estado actualizado. - CANCELLED → CANCELLED: retorna 200 sin cambios (idempotente). content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/PaymentLink' requestId: type: string '401': description: No autenticado content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Link de pago no encontrado content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: > Violación de regla de negocio. Causas: - Link está en estado PAID (no canceable, pago ya procesado). - Link está en estado EXPIRED (no canceable, expiró). content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: PaymentLink: type: object required: - paymentLinkId - status - amount - currency - description - singleUse - createdAt - paymentUrl properties: paymentLinkId: type: string pattern: ^plk_[a-zA-Z0-9]+$ description: ID interno del PaymentLink (prefijo plk_) externalPaymentLinkId: type: string description: Llave externa del link (única por organización) status: $ref: '#/components/schemas/PaymentLinkStatus' description: Estado del link (ACTIVE, PAID, EXPIRED, CANCELLED) amount: type: number description: Monto en pesos (hasta 2 decimales, inmutable tras creación) currency: $ref: '#/components/schemas/Currency' description: Moneda del link (inmutable tras creación) description: type: string description: Descripción visible en la página de pago (actualizable) singleUse: type: boolean description: Si true, se desactiva tras el primer pago (inmutable tras creación) expiresAt: type: string format: date-time nullable: true description: > Fecha/hora de expiración (ISO 8601, RFC3339). Null si no expira. Actualizable, pero solo a valores futuros válidos. successUrl: type: string format: uri nullable: true description: URL de redirección post-pago exitoso (inmutable tras creación) metadata: type: object description: Metadatos arbitrarios (actualizable) paymentUrl: type: string format: uri nullable: true description: > URL pública del portal de pago. Comportamiento HÍBRIDO según deudor conocido o no: **SIN DEUDOR CONOCIDO (anónimo/reutilizable):** - Si privateLinks=true (default): URL opaca con shortCode anti-enumeración: `https://app.tapipay.la/s/{slug}/portal/{shortCode}/` donde shortCode no expone identidad. Null si falla integración. - Si privateLinks=false (legacy): URL con identifierValue (PII si es externalClientId): `https://app.tapipay.la/s/{slug}/portal/{identifierValue}/` donde identifierValue = sanitized org name prefix + random (ej. acm-x3kM9pQr). Null si falla. **CON DEUDOR CONOCIDO (externalClientId o contactData):** - Si privateLinks=true: URL opaca con shortCode: `https://app.tapipay.la/s/{slug}/portal/{shortCode}/` (no expone PII del deudor). Null si falla. - Si privateLinks=false: URL legacy con identifierValue = externalClientId (PII): `https://app.tapipay.la/s/{slug}/portal/{externalClientId}/` Null si falla. identifierValue: type: string nullable: true description: > **SOLO PARA LINKS SIN DEUDOR CONOCIDO (anónimo/reutilizable).** Null/omitido para links con deudor conocido (PII-safe). Identificador sintético usado como último segmento de `paymentUrl` (cuando privateLinks=false). Patrón: {primeras 3 letras sanitizadas del nombre org}-{random alfanumérico ≥8} Ejemplo: acm-x3kM9pQr Generación: se normaliza org name (diacríticos→ASCII, no-alfanuméricos→eliminados, lowercase), se toman primeras 3 letras; si quedan <3, se usa fallback "lnk". Ver ADR-006 y BR-007 para edge cases. contact: $ref: '#/components/schemas/ContactWithInline' nullable: true description: > (no implementado en v1, reservado para v2) Contacto resuelto o creado inline (si fue proporcionado externalClientId o contactData). Null en v1. product: $ref: '#/components/schemas/ProductWithInline' nullable: true description: > Producto asociado si fue referenciado en creación (via productName). Se resuelve o crea inline igual que en Debt y Subscription. Null si no se especificó producto. createdAt: type: string format: date-time description: Timestamp de creación (ISO 8601, RFC3339) Error: type: object required: - error - requestId properties: error: type: object required: - code - message properties: code: type: string enum: - INVALID_REQUEST - AUTHENTICATION_FAILED - RESOURCE_NOT_FOUND - RESOURCE_CONFLICT - RESOLUTION_ERROR - BUSINESS_RULE_VIOLATION - RATE_LIMITED - INTERNAL_ERROR description: Código de error estándar message: type: string description: Mensaje legible del error details: type: array description: Array de detalles adicionales (validaciones por campo, etc.) items: type: object properties: field: type: string issue: type: string requestId: type: string pattern: ^req_[a-zA-Z0-9]+$ description: ID único del request para trazabilidad PaymentLinkStatus: type: string enum: - ACTIVE - PAID - EXPIRED - CANCELLED Currency: type: string enum: - MXN - ARS - PEN - COP - CLP - USD default: MXN description: > Código de moneda ISO 4217. Whitelist de monedas aceptadas por la Facade. Si no se envía, se usa el default de la organización (fallback: MXN). Si se envía un valor fuera de este whitelist, la Facade devuelve 400 INVALID_REQUEST. ContactWithInline: type: object required: - contactId - externalClientId - createdInline properties: contactId: type: string pattern: ^con_[a-zA-Z0-9]+$ description: ID interno del contacto (prefijo con_) externalClientId: type: string description: Llave natural del contacto createdInline: type: boolean description: > Indica si el contacto fue creado inline en esta operación. NOTA: Este es un embedded thin contact (no incluye name/email/phones/active/updatedAt del contacto completo). Para obtener datos completos del contacto, consultá GET /contacts/{id}. ProductWithInline: type: object required: - productId - name - active - createdInline properties: productId: type: string description: ID del producto en el OFU (sin prefijo prod_) name: type: string description: Nombre del producto active: type: boolean description: Estado del producto createdInline: type: boolean description: Indica si el producto fue creado inline en esta operación securitySchemes: apiKeyAuth: type: apiKey in: header name: x-api-key description: > API key del API Gateway de Tapi. Requerida en todas las operaciones. Distinta por ambiente (desarrollo, homologación, producción). tapiAuth: type: apiKey in: header name: x-authorization-token description: > Token TAPI JWT. Requerido en todas las operaciones. Se envía sin prefijo "Bearer". Ej: x-authorization-token: eyJhbGci... ````