# Documentación para desarrolladores de Andorpay

Fuente de verdad: https://andorpay.com/developers/docs

Usa este resumen para integrar Andorpay sin inventar nada fuera de la documentación pública. Si un endpoint, evento, cabecera, campo o SDK no aparece aquí ni en la página de documentación, pregunta antes de inventarlo.

## Base de la API

https://api.andorpay.com/v1

## Cabeceras de servidor

- Authorization: Bearer <ANDORPAY_API_KEY>
- Content-Type: application/json
- Andorpay-Version: fija el contrato de API
- Idempotency-Key: usado para reintentar de forma segura checkouts y reembolsos

Nunca expongas una clave de API de Andorpay en paquetes de navegador o aplicaciones cliente.
La clave de API identifica al comercio. No envíes merchantId en llamadas normales a la API.

## Checkout alojado

Crea un checkout alojado:

POST /v1/checkouts

Campos de entrada habituales:

- productId
- externalCustomerId
- customer.email
- customer.name
- customer.billingDetails
- customer.tax.value
- customer.tax.type
- successUrl
- failUrl

Usa hostedUrl para redirigir al comprador a la UI alojada de Andorpay. Andorpay encapsula internamente cualquier paso firmado que Redsys pueda requerir. Trata las páginas de redirección solo como experiencia de usuario; entrega el producto desde eventos webhook verificados.

## Endpoints útiles

- POST /v1/checkouts
- POST /v1/payment-methods/change
- POST /v1/subscriptions/{id}/cancel
- GET /v1/products
- GET /v1/orders
- GET /v1/subscriptions
- GET /v1/invoices
- GET /v1/payments
- GET /v1/billing/dashboard
- POST /v1/refunds
- POST /v1/manual-charges

## Eventos webhook

Usa exactamente estos nombres de evento:

- payment.succeeded
- payment.failed
- subscription.created
- subscription.updated
- subscription.cancelled
- invoice.created
- invoice.payment_failed
- refund.created
- payment_method.updated
- payment_method.updated_required
- billing.operational_alert

Uso de cada evento:

- payment.succeeded: un pago ha sido autorizado y confirmado por el rail. Marca el pedido o pago como cobrado, entrega el producto y activa el acceso si no depende de una suscripción.
- payment.failed: el intento de pago ha fallado o ha sido rechazado. No entregues el producto; libera reservas, muestra recuperación de pago y conserva el motivo operativo en logs.
- subscription.created: se ha creado una suscripción desde un checkout recurrente. Crea o enlaza la suscripción local y concede acceso según el estado recibido.
- subscription.updated: la suscripción ha cambiado de estado, periodo, plan o datos relevantes. Sincroniza permisos, fechas de renovación, estado past_due/active y cambios de plan.
- subscription.cancelled: la suscripción ha sido cancelada o finalizada. Revoca o programa la retirada de acceso según la fecha efectiva y actualiza el estado local.
- invoice.created: se ha generado una factura o periodo de cobro. Registra la factura, muéstrala en el panel del cliente y espera eventos de pago para entrega o renovación.
- invoice.payment_failed: el cobro asociado a una factura no ha podido completarse. Activa gracia, reintentos, aviso al cliente o flujo de actualización de método de pago.
- refund.created: se ha creado un reembolso total o parcial. Actualiza el saldo del pedido, estado de pago y soporte/contabilidad interna.
- payment_method.updated: el método de pago del cliente se ha actualizado correctamente. Confirma la recuperación de cobro o marca el método como válido para futuros cargos.
- payment_method.updated_required: el cliente debe actualizar o autenticar su método de pago. Envía al cliente al flujo alojado de actualización y no canceles la suscripción automáticamente.
- billing.operational_alert: hay una incidencia operativa de billing, rail, credenciales, webhook o reintento. Alerta a operadores internos; no muestres el detalle técnico al cliente final.

Nota operativa: payment.failed, payment_method.updated_required y billing.operational_alert son eventos distintos. No trates todos los fallos del rail como una cancelación del usuario.

## Tratamiento de webhooks

- Verifica el cuerpo sin procesar con la cabecera Andorpay-Signature y el secreto de firma del webhook antes de interpretar JSON.
- Rechaza firmas cuya marca temporal esté fuera de una tolerancia de 5 minutos.
- Evita duplicados con event.id.
- Trata la entrega como al menos una vez y posiblemente desordenada.
- Devuelve 2xx solo después de persistir de forma duradera.
- Entrega pedidos en payment.succeeded.
- Actualiza accesos de suscripción desde subscription.created, subscription.updated y subscription.cancelled.
- Pide al cliente que actualice o autentique el método de pago en payment_method.updated_required.
- Alerta a operadores, no a clientes, en billing.operational_alert.

## Idempotencia y reintentos

- Genera un Idempotency-Key por cada checkout o reembolso lógico.
- Reutiliza la misma clave al reintentar la misma petición después de un tiempo de espera agotado, un 429 o un 5xx.
- No reutilices una clave para otro cuerpo, carrito, producto o reembolso.
- Registra el request_id de Andorpay y el código de error para operadores.

## Cancelación de suscripciones

Cancela con:

POST /v1/subscriptions/{subscriptionId}/cancel

Espera a eventos webhook de suscripción verificados antes de aplicar cambios finales de acceso.