Saltar al contenido
ApiPay Hub · Docs

Referencia de API

Esta referencia se genera desde contracts/openapi/payment-api.v1.yaml, el contrato del servicio payment-api. Es la única fuente: si algo de esta página y el contrato discrepan, manda el contrato. Puedes descargar el YAML y usarlo para generar clientes o cargarlo en tu cliente HTTP.

Autenticación

Toda llamada autenticada lleva la clave del tenant en el header X-API-Key. Nunca se usa Authorization: Bearer.

  • Las claves secretas sk_live_ / sk_test_ son solo server-to-server y abren la API completa. No pueden salir de tu backend.
  • Las publicables pk_live_ / pk_test_ solo pueden leer y confirmar su payment intent, y para ello es obligatorio el header X-Client-Secret con el client_secret del intent. Ese valor viaja siempre en el header, jamás como query param.
  • El prefijo decide el modo: una clave *_test_ opera contra la misma api.apipay.io con livemode: false. Ver modo test vs live.

Base URL y versionado

Hay un solo servidor, https://api.apipay.io, y la versión mayor va en la ruta: /v1. Mientras exista solo /v1 el portal documenta una única versión; un cambio incompatible nacería como /v2 con su propio YAML y su propio periodo de soporte. La política está en el changelog y política de deprecación.

Convenciones que aplican a todo

  • Dinero: amount_minor entero en unidades menores más currency ISO 4217. CLP tiene exponente 0, así que 1499000 son $1.499.000. Nunca hay decimales flotantes en el cable.
  • Identificadores opacos y prefijados: pi_ payment intent, re_ refund, txn_ transaction, evt_ evento. Prefijo más 24 caracteres base62; nunca se exponen claves internas.
  • Campos JSON en snake_case y enums de estado en MAYÚSCULAS.
  • Errores RFC 9457 (application/problem+json) con el miembro de extensión code, que es el identificador estable contra el que se escribe la lógica de negocio —nunca contra detail, que es texto para humanos. Catálogo completo en manejo de errores.
  • Idempotencia: los dos POST de creación (/v1/payment-intents y /v1/refunds) exigen el header Idempotency-Key. Se persiste 24 h; repetirla con el mismo cuerpo devuelve la respuesta original con Idempotency-Replayed: true, y con un cuerpo distinto responde 409 idempotency_key_reuse.
  • Paginación solo por cursor: { object: "list", data: [...], next_cursor, has_more }. Nunca por offset.
  • Correlación: toda respuesta trae X-Request-Id. Guárdalo en tus logs: es lo primero que pide soporte.

Mapa de endpoints

Los ocho endpoints del contrato. El detalle de cada uno —parámetros, cuerpos, ejemplos y respuestas de error— está en la referencia interactiva de más abajo.

MétodoRutaAutenticaciónNota
POST/v1/payment-intentssk_Idempotency-Key obligatoria. Devuelve 201 con el intent en CREATED y su client_secret.
GET/v1/payment-intents/{id}sk_ · pk_ + X-Client-SecretCon pk_ la respuesta omite campos server-only y añade el bloque checkout del widget.
POST/v1/payment-intents/{id}/confirmsk_ · pk_ + X-Client-SecretInicia el cobro. Puede devolver REQUIRES_ACTION con redirect_url, PROCESSING o SUCCEEDED.
POST/v1/payment-intents/{id}/cancelsk_Solo desde CREATED o REQUIRES_ACTION; sobre un estado terminal responde 409 invalid_state_transition.
POST/v1/refundssk_Idempotency-Key obligatoria. Total sin amount_minor, parcial con amount_minor, sobre un intent SUCCEEDED.
GET/v1/refunds/{id}sk_Visible solo para el tenant propietario: cross-tenant responde 404, nunca 403.
GET/v1/transactionssk_Cursor + limit (máx. 100, default 20) y filtros status, type, from, to. Orden created_at DESC.
POST/v1/gateways/{gatewayId}/webhookssin API keyEntrada de las pasarelas (webpay, mercadopago). La autenticidad la da la firma de cada pasarela.

Los webhooks que ApiPay envía a tu comercio son otra cosa y no viven en este contrato: los firma ApiPay-Signature y se documentan en webhooks paso a paso.

Una llamada completa

Crear un intent de $1.499.000 en CLP con Webpay, en modo test. Recuerda que CLP tiene exponente 0: amount_minor es el monto tal cual. La clave del ejemplo es ficticia:

curl -sS https://api.apipay.io/v1/payment-intents \
  -H "X-API-Key: sk_test_ejemploFICTICIAnoFuncionaJamas1" \
  -H "Idempotency-Key: 8f14e45f-ceea-467a-9f2b-1c0d7f0a3b91" \
  -H "Content-Type: application/json" \
  -d '{"amount_minor":1499000,"currency":"CLP","gateway_id":"webpay"}'

En producción no se llama a la API con curl a mano: los cuatro SDKs server-side ponen la autenticación, la Idempotency-Key, los reintentos y los errores tipados por ti.

Referencia interactiva

Renderizada directamente desde el contrato. Colección de Postman: se genera en CI con openapi-to-postmanv2 desde este mismo YAML; el workflow todavía no existe, así que hoy no hay enlace de descarga —importa el YAML de arriba, que produce la misma colección.

Cargando la referencia interactiva…