Saltar al contenido principal

Una API de pagos, cualquier proveedor

La API de pagos te permite cobrar en Chile con Transbank Webpay Plus y Mercado Pago Checkout Pro integrándote una sola vez. Tu sistema crea una intención de pago, recibe una URL de checkout hospedado y se entera del resultado por un webhook firmado. Qué proveedor procesa el cobro lo decide la configuración de tu comercio, no tu código.

Cómo viaja un pago: tu sistema, la API de pagos, el registro transaccional, el procesador de eventos y los proveedoresTUS SISTEMASSistema ASistema BApp XREST /v1API de pagosAPI key · rate limitIdempotency-Keycrear · consultarconectoresWebpay PlusTransbank · redirect POSTCheckout ProMercado Pago · Orders APIsimulador · sandboxaprobar · rechazarwebhook + consultauna transacciónRegistro transaccionalestadoconsultaseventosdedupProcesador de eventospublica cada eventoactualiza consultasavisos del proveedorwebhooks a tu sistemaBUS DE EVENTOSpagosconectores · webhooksconciliaciónentregas agotadas
pedido del consumidorevento guardado con el cambioaplicado una sola vezwebhook saliente

Qué resuelve​

Sin la APICon la API
Una integración distinta por proveedor, con sus estados, retornos y reintentosUn contrato único: los mismos endpoints, estados y eventos para todos los proveedores
Tu sistema guarda credenciales de Transbank o Mercado PagoLas credenciales viven en la plataforma y nunca se devuelven
Confiar en el retorno del navegador para saber si se pagóEl resultado se confirma con el proveedor y te llega por webhook firmado
Reintentos manuales que pueden cobrar dos vecesIdempotencia en cada operación que mueve dinero
Cambiar de proveedor implica cambiar códigoSe cambia la prioridad del proveedor en la configuración del comercio

Cómo se ve una integración​

  1. Creas un payment intent con el monto, la moneda, tu referencia y a dónde volver (POST /v1/payment-intents).
  2. Pides el checkout (POST /v1/payment-intents/{id}/checkout) y redirige al comprador a la URL que te devolvemos.
  3. El comprador paga en la página del proveedor. Nunca ves datos de tarjeta.
  4. Recibes un webhook payment.authorized (o payment.failed) firmado con HMAC-SHA256, y puedes consultar el estado y sus eventos cuando quieras (GET /v1/payment-intents/{id}).
  5. Si hace falta, devuelves total o parcialmente (POST /v1/payments/{paymentId}/refunds).

Principios del contrato​

  • Agnóstico del proveedor. Tu código no conoce commerce_code, access_token ni los estados propios de Webpay o Mercado Pago.
  • El navegador no es la fuente de verdad. Un pago queda autorizado solo cuando el proveedor lo confirma.
  • Sin datos de tarjeta. El pago ocurre en el checkout del proveedor: por la API solo viajan referencias, montos y estados.
  • Idempotente y trazable. Cada operación acepta Idempotency-Key y cada respuesta de error trae un request_id para soporte.

Siguientes pasos​

  • Conceptos: payment intent, payment, refund, aplicación y comercio.
  • Primeros pasos: tu primer cobro en sandbox, con curl, Node, Python y Go.
  • Webhooks: eventos, firma y verificación.