Saltar al contenido
ApiPay Hub · Docs

ApiPay Hub · API de pagos /v1

Documentación para integrar pagos

Un solo contrato para Webpay Plus y MercadoPago: creas un payment intent, el comprador paga en el componente alojado de la pasarela y tu backend recibe un webhook firmado con el resultado.

Objetivo verificable: la integración típica (crear el intent desde tu servidor, montar el widget y recibir el webhook de resultado) debe lograrse en menos de una hora siguiendo el quickstart. Si te toma más, el que falla es este portal.

Ir al quickstartReferencia de API

Puntos de entrada

QuickstartAcepta tu primer pago en 10 minutos: crea el payment intent desde tu backend, monta el widget de checkout y recibe el webhook de resultado. Todo en modo test, sin tocar una tarjeta real.Empieza aquíReferencia de APITodos los endpoints de /v1 con sus payloads, esquemas y errores, generados desde el contrato OpenAPI. Autenticación con X-API-Key y client_secret en el header X-Client-Secret.Ver la referenciaSDKsNode.js, PHP, Python y Java para tu backend, más @apipay/checkout-js para el navegador. Misma superficie en los cuatro, idempotencia automática y errores tipados por code.Elegir SDK

Lo esencial, antes de escribir código

Montos en unidad mínima
amount_minor es un entero y currency es ISO 4217. CLP tiene exponente 0: 1499000 son $1.499.000. Nunca un float.
Una clave secreta, un header
La API pública se autentica con el header X-API-Key y una clave sk_live_ o sk_test_. Nunca Authorization: Bearer.
Reintentar un cobro es tu decisión
Los SDKs reintentan GET, y jamás un POST del que hubo respuesta. Ese reintento lo haces tú con la Idempotency-Key que el SDK te expone.
Los datos de tarjeta no pasan por aquí
Alcance PCI DSS SAQ A: la tarjeta se captura siempre en el componente alojado de la pasarela. ApiPay recibe un token, nunca un número.

Guías

  • Payment intents

    Ciclo de vida del intent y los siete estados canónicos, con la matriz de transiciones permitidas.

  • Confirmación

    Las dos formas de confirmar un cobro: hosted fields con token y flujo de redirección.

  • Checkout alojado

    El botón «Pagar con ApiPay»: intent sin gateway_id, redirección a checkout_url y el comprador eligiendo entre las pasarelas del comercio.

  • Medios de pago guardados

    Inscripción Oneclick por POST de formulario, el pm_ resultante y el cobro posterior sin el titular delante.

  • Webhooks

    Verificación de la firma ApiPay-Signature paso a paso, tolerancia de 300 s, reintentos y deduplicación por evt_.

  • Reembolsos

    Reembolsos totales y parciales, el monto reembolsable disponible y los eventos refund.succeeded y refund.failed.

  • Modo test y modo live

    Claves sk_test_ y sk_live_ sobre la misma API, partición por livemode y la tabla de escenarios de gateway-sandbox.

  • Manejo de errores

    Los 17 códigos de error de application/problem+json y cómo escribir la lógica de negocio contra code.

Recetas por framework

Proyectos mínimos y completos, con el mismo recorrido de extremo a extremo en cada lenguaje.

  • Express

    Proyecto mínimo en Express con @apipay/node: crear el intent, servir el widget y verificar el webhook.

  • Laravel

    Proyecto mínimo en Laravel con apipay/apipay-php, incluida la verificación estática de webhooks.

  • FastAPI

    Proyecto mínimo en FastAPI con el SDK apipay de Python y el cuerpo crudo del webhook intacto.

  • Spring Boot

    Proyecto mínimo en Spring Boot con com.apipay:apipay-java sobre el baseline Java 17 del SDK.