Localpayment para desarrolladores
Construye en torno a los detalles locales.
Encuentra las guías de la API, los requisitos por país, las herramientas de prueba y los ejemplos de implementación detrás de cada flujo de pago disponible.
- REST + JSON
- Webhooks firmados con HMAC
- Sandbox Stage
- Servidor MCP público
REST + JSONLo esencial para desarrolladores
Guías
Guías de integración paso a paso para cada producto y flujo de pago.
Guías —Referencia de la API
Endpoints, campos de solicitud, respuestas y códigos de estado.
Referencia de la API —Herramientas para desarrolladores
Servidor MCP, colección de Postman y herramientas de prueba.
Herramientas para desarrolladores —Página de estado
Disponibilidad en vivo de la API e historial de incidentes.
Página de estado —
Documentación
Ve directo a lo que necesitas
Accesos directos a docs.localpayment.com: guías, referencia de la API y herramientas.
Autenticación
Intercambia tu usuario y contraseña de API por un token de acceso de 5 minutos y un token de refresco de 24 horas.
Autenticación —Tu primer pago de prueba
Un recorrido guiado para crear y confirmar un cobro en Stage.
Tu primer pago de prueba —Pay-ins
Tarjetas, cuentas virtuales y medios de pago locales, todo con un único endpoint Create Payin.
Pay-ins —Payouts
Payouts por transferencia bancaria y a billeteras sobre rieles de compensación locales, con doble firma opcional.
Payouts —Cuentas virtuales
Emite números de cuenta locales por cliente y concilia cada transferencia entrante.
Cuentas virtuales —Webhooks
Notificaciones firmadas y en tiempo real para cada cambio de estado.
Webhooks —Estados y códigos de error
Todos los códigos por tipo de transacción, desde 100 INPROGRESS hasta 906 contracargo.
Estados y códigos de error —Colección de Postman
Solicitudes listas para usar y un archivo de entorno Stage.
Colección de Postman —Estado del sistema
Disponibilidad en vivo de los servicios de pay-in, payout y autenticación, con historial de incidentes.
Estado del sistema —
Tus primeras llamadas
Autentica, cobra, confirma
Tres pasos cubren el ciclo principal: obtener un token, crear un cobro y verificar el webhook firmado que lo confirma. El mismo modelo de solicitud, estados y webhooks se aplica en todos los países y medios de pago.
- Los tokens vencen a los 5 minutos: renuévalos con POST /api/token/refresh/
- Envía tu propio externalId único en cada transacción
- El estado final llega por webhook, firmado con HMAC-SHA256
# 1) Obtén un token de acceso (Stage · válido por 5 minutos)
ACCESS_TOKEN=$(curl -s -X POST https://api.stage.localpayment.com/api/token/ \
-H "Content-Type: application/json" \
-d "{\"username\": \"$LP_API_USER\", \"password\": \"$LP_API_PASSWORD\"}" \
| jq -r .access)
# 2) Crea un cobro Pix (ilustrativo, valores ficticios)
curl -X POST https://api.stage.localpayment.com/api/payin/ \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"paymentMethod": { "type": "BankTransfer", "code": "1314", "flow": "DIRECT" },
"externalId": "7c1e2f7a-0000-4000-8000-000000000001",
"country": "BRA",
"currency": "USD",
"amount": 100,
"accountNumber": "<your-account-number>",
"conceptCode": "0003",
"merchant": { "type": "COMPANY", "name": "Nortia Commerce Ltda" },
"payer": {
"type": "INDIVIDUAL",
"name": "Maria",
"lastname": "Silva",
"document": { "type": "CPF", "id": "000.000.000-00" }
}
}'Diseño de la API
Predecible por diseño
Convenciones que se mantienen iguales entre productos y países, para que tu código de integración también lo haga.
REST y JSON
URLs orientadas a recursos, verbos y códigos HTTP estándar y cuerpos JSON. Los países usan códigos ISO-3, como BRA o MEX.
Tokens Bearer de corta duración
POST /api/token/ devuelve un token de acceso válido por 5 minutos y uno de refresco válido por 24 horas, enviado como Authorization: Bearer.
Tu ID y el nuestro
Cada transacción lleva tu externalId y te devolvemos nuestro internalId. Usa cualquiera de los dos para consultar el estado o conciliar.
A prueba de duplicados
Reutilizar un externalId devuelve 409 Conflict en lugar de crear una segunda transacción, así puedes reintentar con seguridad una solicitud que agotó el tiempo de espera.
Códigos para decidir
Cada respuesta trae un objeto status con code, description y detail, más un arreglo errors. Las familias de códigos te dicen qué hacer.
Límites de solicitudes con backoff
El exceso de solicitudes devuelve 429. Reintenta con backoff exponencial y un patrón circuit breaker, igual que ante respuestas 5xx y el código 800.
Manejo de errores
Familias de códigos de estado
Cada respuesta incluye status.code. El primer dígito te dice si esperar, corregir, reintentar o revertir.
1xx
- Significado
- Pendiente
- Ejemplos
- 100 INPROGRESS
- Qué hacer
- Espera el webhook o consulta el estado
2xx
- Significado
- Éxito
- Ejemplos
- 200 COMPLETED
- Qué hacer
- Entrega el pedido y actualiza tu contabilidad
3xx
- Significado
- Validación
- Ejemplos
- 300 rechazado (parámetro inválido) · 301 no autorizado para el país
- Qué hacer
- Corrige la solicitud: no la reintentes sin cambios
7xx
- Significado
- Reglas de negocio
- Ejemplos
- 701 cuenta inválida · 702 fondos insuficientes
- Qué hacer
- Muestra un mensaje claro o alerta a tu equipo de operaciones
8xx
- Significado
- Proveedor o sistema
- Ejemplos
- 800 error reintentable
- Qué hacer
- Reintenta con backoff exponencial
9xx
- Significado
- Reversiones
- Ejemplos
- 902 reembolsado · 904 suscripción cancelada tras reintentos fallidos · 906 contracargo
- Qué hacer
- Revierte la entrega y actualiza tu contabilidad
Estados HTTP en uso: 200, 201, 400, 401, 403, 404, 409, 429, 500, 502 y 503. Las tablas de códigos por tipo de transacción están en la referencia de la documentación.
Recorrido de integración
De la primera llamada a producción
La mayor parte del trabajo ocurre en Stage. El acceso a producción llega tras una revisión de seguridad y la verificación de tu empresa.
- 01
Obtén credenciales de Stage
Las credenciales de Stage se emiten al iniciar la alianza. Registra las IP de tus servidores en el Business Portal.
Stage
- 02
Construye y prueba
Integra pay-ins, payouts o cuentas virtuales, procesa webhooks y prueba escenarios de error con datos de prueba.
Stage
- 03
Revisión de seguridad y KYB
Revisamos tu integración y completamos la verificación de tu empresa (KYB) antes de emitir las credenciales de producción.
Cumplimiento
- 04
Sal a producción y expande
Cambia a credenciales e IP de producción. Suma países y medios de pago por configuración, sin reintegrar.
Producción
Herramientas de IA
Deja que tu asistente de IA lea la documentación
La documentación de Localpayment está pensada para funcionar con herramientas de desarrollo asistido por IA: incluye un servidor MCP, prompts listos para usar y acceso estructurado diseñado para sistemas de IA.
- Servidor MCP en docs.localpayment.com/mcp, sin autenticación
- Un índice llms.txt y una versión Markdown de cada página
- Una biblioteca de prompts y agentes de integración y QA para los frameworks de agentes más usados
- “Ask AI” integrado en la documentación
{
"mcpServers": {
"localpayment-docs": {
"url": "https://docs.localpayment.com/mcp"
}
}
}Seguridad
Seguro por defecto, desde la primera solicitud
Controles integrados en la API y el Business Portal, no agregados después.
Cifrado en tránsito y en reposo
TLS 1.2+ en tránsito y AES-256 en reposo, con claves rotadas mediante AWS KMS.
Solo servidor a servidor
Las llamadas viajan por HTTPS desde tu backend. Nunca expongas credenciales ni tokens en un navegador o una app móvil.
Lista de IP permitidas
Solo las IP de servidor que registres en el Business Portal pueden llamar a la API, tanto en Stage como en producción.
Webhooks firmados
Cada notificación lleva una firma HMAC-SHA256, así puedes rechazar todo lo que no enviamos nosotros.
Payouts con doble firma
Exige un segundo aprobador antes de que un payout salga de tu cuenta, por API o en el portal.
MFA y acceso por roles
Los usuarios del Business Portal inician sesión con autenticación multifactor y solo tienen los permisos que su rol necesita.
Preguntas frecuentes de desarrolladores
¿Hay un SDK?
No hay SDK oficiales de servidor: la API es REST y JSON, así que sirve cualquier cliente HTTP. Para formularios de tarjeta, el SDK JavaScript Smart Fields tokeniza los datos en campos alojados y reduce tu alcance PCI.
¿Cómo obtengo credenciales del sandbox?
Las credenciales de Stage se emiten al comienzo de la alianza. Cuéntanos sobre tu proyecto en el formulario de contacto y nuestro equipo te acompañará durante la incorporación.
¿Qué URL base uso?
Stage: https://api.stage.localpayment.com. Producción: https://api.v3.localpayment.com. Cada entorno tiene sus propias credenciales.
¿Cuánto tarda una integración?
Los equipos suelen salir a producción en semanas. Una vez integrado, los nuevos mercados se suman por configuración, sin reintegrar.
¿Cómo se manejan los reintentos y duplicados?
Envía un externalId único por transacción. Si reintentas con el mismo externalId, recibes 409 Conflict en lugar de un duplicado. Reintenta 429, 5xx y el código 800 con backoff exponencial.
¿Dónde reviso el estado del servicio?
En status.localpayment.com, que cubre los servicios de pay-in, payout y autenticación, los rieles locales y el historial de incidentes. Si necesitas ayuda, escribe a support@localpayment.com: el soporte está disponible 24/7.
Guías para desarrolladores
Guía rápida
Tu primer pago de prueba en seis pasos.
Guía rápida —Sandbox
El entorno Stage, tarjetas de prueba y simuladores.
Sandbox —Webhooks
Configura, verifica y procesa notificaciones.
Webhooks —Herramientas de IA
Servidor MCP, llms.txt y biblioteca de prompts.
Herramientas de IA —Hoja de ruta
Sigue los próximos cambios de la API en la documentación.
Hoja de ruta —Business Portal
Opera pagos, usuarios y webhooks.
Business Portal —
¿Listo para construir?
Habla con nuestro equipo para iniciar la alianza y recibir credenciales de Stage, o explora la documentación ahora mismo.