Referencia de API

URL base: la que te entregamos con tu acceso (en los ejemplos, https://api.pagos.example.com).

Header	Cuándo
Authorization: Bearer <api key>	en todas las llamadas
Content-Type: application/json	en las que envían body
Idempotency-Key: <uuid>	obligatorio al crear intents, pedir checkout y devolver (Idempotencia)
X-Correlation-Id: <tu id>	opcional; se devuelve en la respuesta y como request_id en errores

Formato de las respuestas

• Pagos (/v1/payment-intents, /v1/payments): el recurso directamente.
• Administración (/v1/admin/…): envuelto en { "success": true, "data": … }.
• Errores: siempre { "error": { "code", "message", "request_id", "details" } } (Errores).

Los /v1/admin/… de esta referencia (API keys, conectores, webhooks, conciliación) son los que también puedes llamar directo desde tu backend. Alta de empresas, invitaciones, usuarios y sesión son administración de cuenta pensada para humanos: se usan desde la consola de administración, no por API key.

OpenAPI 3.0.0 · 16 operaciones

Payment intents

POST/v1/payment-intentsAPI key

Crea un payment intent

Body CreatePaymentIntentRequestDto

merchant_account_idrequerido	string ej. mrc_01JATENANT0000000000000001
external_referencerequerido	string ej. order-12345
amountrequerido	number Entero > 0 en la unidad mínima de la moneda ej. 25990
currencyrequerido	string ej. CLP
description	string ej. Compra 12345
providerrequerido	"auto" | "transbank_webpay_plus" | "mercadopago_checkout_pro" ej. auto
return_urlrequerido	string ej. https://consumer.example.com/payments/return
metadata	object

Respuestas

• 201CreatePaymentIntentResponseDto

POST/v1/payment-intents/{id}/checkoutAPI key

Inicia el checkout hospedado de un payment intent

Parámetros

idrequerido

path · string

Body StartCheckoutRequestDto

providerrequerido

"auto" | "transbank_webpay_plus" | "mercadopago_checkout_pro" ej. auto

Respuestas

• 200StartCheckoutResponseDto

GET/v1/payment-intents/{id}API key

Obtiene un payment intent

Parámetros

idrequerido

path · string

Respuestas

• 200PaymentIntentDetailDto

Pagos y refunds

GET/v1/paymentsAPI key

Lista pagos con paginación por cursor

Parámetros

status	query · string
from	query · string
to	query · string
cursor	query · string
limit	query · number Entre 1 y 100, por defecto 20

Respuestas

• 200ListPaymentsResponseDto

POST/v1/payments/{paymentId}/refundsAPI key

Reembolsa (parcial o total) un pago autorizado

Parámetros

paymentIdrequerido

path · string

Body RequestRefundRequestDto

amountrequerido	number Entero > 0 en la unidad mínima de la moneda ej. 10000
external_reference	string ej. refund-001

Respuestas

• 201RequestRefundResponseDto

Administración (API keys, conectores, webhooks, conciliación)

POST/v1/admin/api-credentialsAPI key

Crea una nueva API credential para la application autenticada

Respuestas

• 200object

POST/v1/admin/api-credentials/{id}/revokeAPI key

Revoca una API credential de la application autenticada

Parámetros

idrequerido

path · string

Respuestas

• 200object

GET/v1/admin/merchant-accounts/{merchantAccountId}/connectorsAPI key

Lista los conectores configurados para el merchant account

Parámetros

merchantAccountIdrequerido

path · string

Respuestas

• 200object

POST/v1/admin/merchant-accounts/{merchantAccountId}/connectorsAPI key

Configura un nuevo conector para el merchant account

Parámetros

merchantAccountIdrequerido

path · string

Body CreateConnectorConfigDto

providerrequerido	"transbank_webpay_plus" | "mercadopago_checkout_pro" ej. transbank_webpay_plus
moderequerido	"MOCK" | "SANDBOX" | "PRODUCTION" ej. SANDBOX
enabledrequerido	boolean ej. true
priorityrequerido	number ej. 10
public_config	object
credentials	object Se guardan cifradas; nunca se devuelven por ningún endpoint. Un objeto vacío ({}) limpia las credenciales existentes.

Respuestas

• 200object

PATCH/v1/admin/merchant-accounts/{merchantAccountId}/connectors/{connectorId}API key

Actualiza enabled/priority/public_config/credentials de un conector

Parámetros

merchantAccountIdrequerido	path · string
connectorIdrequerido	path · string

Body UpdateConnectorConfigDto

enabled	boolean ej. false
priority	number ej. 5
public_config	object
credentials	object Se guardan cifradas; nunca se devuelven por ningún endpoint. Un objeto vacío ({}) limpia las credenciales existentes.

Respuestas

• 200object

GET/v1/admin/payment-intents/{paymentIntentId}/reconciliation-entriesAPI key

Chequeos de conciliación con el proveedor de un payment intent

Parámetros

paymentIntentIdrequerido	path · string
limit	query · number Entre 1 y 100, por defecto 20

Respuestas

• 200object

GET/v1/admin/webhook-endpointsAPI key

Lista los webhook endpoints de la application autenticada

Respuestas

• 200object

POST/v1/admin/webhook-endpointsAPI key

Registra un webhook endpoint nuevo; el secreto se devuelve una sola vez

Body CreateWebhookEndpointRequestDto

urlrequerido	string ej. https://consumer.example.com/webhooks/payments
events	string[] Vacío o ausente = suscrito a todos los eventos de payments.events.v1.

Respuestas

• 200object

DELETE/v1/admin/webhook-endpoints/{id}API key

Borra un webhook endpoint y sus entregas registradas

Parámetros

idrequerido

path · string

Respuestas

• 200sin cuerpo

GET/v1/admin/webhook-endpoints/{endpointId}/deliveriesAPI key

Lista las entregas de un webhook endpoint

Parámetros

endpointIdrequerido

path · string

Respuestas

• 200object

POST/v1/admin/webhook-endpoints/{endpointId}/deliveries/{deliveryId}/retryAPI key

Reprograma un intento inmediato (calendario de reintentos fresco)

Parámetros

endpointIdrequerido	path · string
deliveryIdrequerido	path · string

Respuestas

• 200object