> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Biblioteca de indicaciones

Una cuidada selección de sugerencias listas para usar para crear, depurar y probar integraciones de Localpayment. Organizadas por caso de uso y país. Copia, pega y acelera.

Copia cualquiera de las indicaciones que aparecen a continuación y pégalas en tu asistente de IA, con o sin el [servidor MCP](https://docs.localpayment.com/es/docs/mcp-server.md) conectado. Las indicaciones marcadas con 🔌 ofrecen resultados significativamente mejores cuando el servidor MCP está activo, ya que la IA consulta las especificaciones en tiempo real en lugar de basarse en datos de entrenamiento potencialmente desactualizados.

> [!NOTE]
>
> **Configuración recomendada para obtener los mejores resultados:**
>
> 1. **Servidor MCP** (principal): Configura el [servidor MCP de Localpayment](https://docs.localpayment.com/es/docs/mcp-server.md) en tu herramienta de IA. La IA llamará automáticamente a `list-endpoints`, `get-endpoint`, `search` y `fetch` para responder con datos verificados y en tiempo real.
> 2. **LLMs.txt** (alternativa): Si utilizas una interfaz de chat sin MCP, pega `https://docs.localpayment.com/llms.txt` al inicio de tu sesión para que la IA tenga un mapa completo de la documentación antes de hacer preguntas.
> 3. **Artículos de texto plano**: Para temas específicos, agrega `.md` a cualquier URL de documento (por ejemplo, `https://docs.localpayment.com/docs/virtual-accounts-overview.md`) y pega el contenido directamente en tu solicitud.
>
> El uso de estos recursos evita las alucinaciones y garantiza que la IA genere código en función de la API de Localpayment actual.

***

## Autenticación y gestión de tokens

Se requiere autenticación antes de cada llamada a la API de Localpayment. Estas indicaciones abarcan todo el ciclo de vida del token.

> [!NOTE]
>
> Si empiezas desde cero, la guía [Realiza tu primer pago de prueba](https://docs.localpayment.com/es/docs/make-your-first-test-payment.md) te guía paso a paso por todo el proceso: token → descubrimiento de métodos de pago → creación de pago → webhook → comprobación de estado, con ejemplos reales de curl para cada llamada.

```
🔌 Show me the complete authentication flow for the Localpayment API. How do I generate an access token (POST /api/token/), how long do the access and refresh tokens last, and how do I reuse the access token until it expires? Also explain the optional refresh endpoint (POST /api/token/refresh/) and how its token rotation works. Include curl examples for both calls and show me the correct way to store and use the token in subsequent requests using environment variables.
```

```
🔌 My Localpayment API requests are returning 401 Unauthorized. Walk me through diagnosing the issue: is my token expired, was it generated incorrectly, or is there something wrong with how I'm passing it in the Authorization header? Show me how to request a new token and retry the failed request. If the refresh endpoint returns 401 "Invalid or expired token", explain the possible causes (expired, already used, or invalidated by a newer token request) and what to do instead.
```

```
🔌 I'm building a long-running service that makes Localpayment API calls continuously. Show me the correct pattern for managing the token lifecycle: how to share a single token pair across all my processes and workers, how to request a new token when the access token expires or I get a 401 mid-operation, and how to avoid parallel token requests that invalidate earlier refresh tokens.
```

***

## Cuentas virtuales

> [!WARNING]
>
> **La autenticación siempre es necesaria primero.** Cada llamada a la API de Localpayment necesita un token Bearer válido. Antes de ejecutar cualquiera de las indicaciones siguientes, asegúrate de que tu integración gestione la generación de tokens (`POST /api/token/`) y solicite un nuevo token cuando el actual venza. Consulta la [guía de autenticación](https://docs.localpayment.com/es/docs/authentication.md) para obtener más detalles.
>
> Las indicaciones de "Ruta completa y feliz" que aparecen a continuación incluyen la autenticación como paso 1.

### Integración completa: un camino feliz

Utiliza estas indicaciones para crear una integración completa de la cuenta virtual, desde su creación hasta la conciliación.

> [tab] Argentina (CVU)
>
> **Crear una cuenta virtual:**
>
> ```
> Using the Localpayment API, help me create a CVU virtual account for an individual beneficiary in Argentina. Show me the full request with all required fields, a complete curl example, and the expected successful response. Also explain what the account number returned represents and how to share it with the payer.
> ```
>
> **Simular un pago (Etapa):**
>
> ```
> I have an active CVU virtual account in Localpayment's Stage environment with externalId [YOUR_EXTERNAL_ID]. Show me how to simulate an incoming payment to this account using the simulate endpoint. Include the curl request and explain what webhook payload I should expect to receive.
> ```
>
> **Recibir y analizar el webhook:**
>
> ```
> I received the following webhook payload from Localpayment after a payment to a CVU virtual account in Argentina. Explain each field, identify which fields I should use to reconcile this payment with my internal records, and tell me what the beneficiary.bank.account.number field represents:
>
> [PASTE YOUR WEBHOOK PAYLOAD HERE]
> ```
>
> **Camino feliz completo — de principio a fin:**
>
> ```
> Walk me through the COMPLETE integration flow for CVU virtual accounts in Argentina using the Localpayment API. Cover ALL necessary steps:
>
> 1. Authentication: generate an access token (POST /api/token/), reuse it while it is valid, and request a new one when it expires or returns 401
> 2. (Optional) Discover available payment methods for Argentina (GET /api/resources/payment-methods)
> 3. Create a CVU virtual account (POST /api/virtual-account) for an individual beneficiary — show all required fields and the expected response
> 4. Verify the account is active: check status (GET /api/virtual-account/{externalId})
> 5. Share the CVU with the payer and explain what they need to do
> 6. Simulate an incoming payment in Stage (POST /api/simulate/va)
> 7. Receive and parse the webhook: identify the key reconciliation fields (especially beneficiary.bank.account.number and tracking object)
>
> Include curl examples for each step. Use Stage environment. Use environment variables for all credentials.
> ```

> [tab] México (SPEI / TEF)
>
> **Crear una cuenta virtual:**
>
> ```
> Using the Localpayment API, help me create a CLABE virtual account for Mexico (SPEI). Show me the full request with all required fields for a company beneficiary, a complete curl example, and the expected successful response.
> ```
>
> **SPEI vs TEF: comprende la diferencia:**
>
> ```
> Explain the difference between SPEI (payment method code 1630) and TEF (payment method code 1680) in the context of Localpayment virtual accounts in Mexico. When would I receive a webhook with each code? Are there differences in the webhook payload structure?
> ```
>
> **Camino feliz completo — de principio a fin:**
>
> ```
> Walk me through the COMPLETE integration flow for SPEI virtual accounts in Mexico using the Localpayment API. Cover ALL necessary steps:
>
> 1. Authentication: generate an access token (POST /api/token/), reuse it while it is valid, and request a new one when it expires or returns 401
> 2. Create a CLABE virtual account for SPEI (POST /api/virtual-account) — show required fields for Mexico and the expected response
> 3. Verify the account is active (GET /api/virtual-account/{externalId})
> 4. Share the CLABE with the payer
> 5. Simulate an incoming SPEI payment in Stage (POST /api/simulate/va)
> 6. Receive and parse the webhook: explain paymentMethod.code 1630 (SPEI) vs 1680 (TEF), and the key reconciliation fields including tracking.id
>
> Include curl examples. Use Stage environment. Use environment variables for all credentials.
> ```

> [tab] Colombia (Bre-B)
>
> **Crear una cuenta virtual:**
>
> ```
> Using the Localpayment API, help me create a Bre-B virtual account in Colombia. Show me the full request, required fields, and the expected response including the Bre-B key that will be assigned.
> ```
>
> **Camino feliz completo — de principio a fin:**
>
> ```
> Walk me through the COMPLETE integration flow for Bre-B virtual accounts in Colombia using the Localpayment API. Cover ALL necessary steps:
>
> 1. Authentication: generate an access token (POST /api/token/)
> 2. Create a Bre-B virtual account (POST /api/virtual-account) — show required fields for Colombia and the Bre-B key returned in the response
> 3. Verify the account is active (GET /api/virtual-account/{externalId})
> 4. Share the Bre-B key with the payer
> 5. Simulate a payment in Stage (POST /api/simulate/va)
> 6. Receive and parse the webhook: explain why Bre-B always returns status 200 COMPLETED with no intermediate states, and identify the key reconciliation fields (tracking.id, beneficiary.bank.account.number)
>
> Include curl examples. Use Stage environment.
> ```

> [tab] Brasil (Pix)
>
> **Crear una cuenta virtual:**
>
> ```
> Using the Localpayment API, help me create a Pix virtual account in Brazil for an individual beneficiary. Show me the full request with all required fields and the expected response including the Pix key (alias) returned.
> ```
>
> **Camino feliz completo — de principio a fin:**
>
> ```
> Walk me through the COMPLETE integration flow for Pix virtual accounts in Brazil using the Localpayment API. Cover ALL necessary steps:
>
> 1. Authentication: generate an access token (POST /api/token/)
> 2. Create a Pix virtual account (POST /api/virtual-account) for an individual beneficiary — show required fields for Brazil and the Pix key (alias) returned in the response
> 3. Verify the account is active (GET /api/virtual-account/{externalId})
> 4. Share the Pix key with the payer and explain the different key types (random, email, phone)
> 5. Simulate an incoming Pix payment in Stage (POST /api/simulate/va)
> 6. Receive and parse the webhook: identify key reconciliation fields including beneficiary.bank.account.number and the alias fields
>
> Include curl examples. Use Stage environment.
> ```

> [tab] Perú (CCI)
>
> **Crear una cuenta virtual:**
>
> ```
> Using the Localpayment API, help me create a CCI virtual account in Peru for an individual beneficiary. Include the required document field (mandatory for Peru) and show a complete curl example with the expected response.
> ```
>
> **Camino feliz completo — de principio a fin:**
>
> ```
> Walk me through the COMPLETE integration flow for CCI virtual accounts in Peru using the Localpayment API. Cover ALL necessary steps:
>
> 1. Authentication: generate an access token (POST /api/token/)
> 2. Create a CCI virtual account (POST /api/virtual-account) for an individual beneficiary in Peru — note that the document field is mandatory for Peru, include it in the example
> 3. Verify the account is active (GET /api/virtual-account/{externalId})
> 4. Share the CCI (20-digit account number) with the payer
> 5. Simulate an incoming payment in Stage (POST /api/simulate/va)
> 6. Receive and parse the webhook: explain the reconciliation flow and how to handle cases where certain Peruvian banks do not return the payer's full name
>
> Include curl examples. Use Stage environment.
> ```

***

### Operaciones de cuentas virtuales

```
🔌 I need to temporarily disable a virtual account in Localpayment and re-enable it later. Show me the API calls for both operations, the required parameters, and what status changes I should expect in the webhook.
```

```
🔌 I want to delete a virtual account in Localpayment. Explain the consequences (is it reversible?), the API call required, and what happens to future payments sent to that account after deletion.
```

```
🔌 Show me how to create a CVU alias for a virtual account in Argentina. Include the format rules, the API request, the asynchronous activation flow (INPROGRESS status), and how to verify that the alias is active.
```

```
🔌 I need to check the current status of a virtual account including its assigned aliases. Show me the Get Virtual Account Status endpoint, the full response structure, and how to interpret each status code.
```

***

## Creación de integraciones por país

### Iniciar una nueva integración del país

```
🔌 I want to start accepting payments in [COUNTRY] using the Localpayment API. What payment methods are available there? Walk me through the recommended integration path, required beneficiary fields, currency, and any country-specific considerations I should be aware of.
```

```
🔌 I already have a Localpayment integration working for Mexico (SPEI). I need to add support for Colombia (Bre-B). What changes do I need to make to my existing integration? Are the request structures different? What are the key differences in the webhook payload?
```

### Tarjetas

```
🔌 Help me implement a one-time card payment using the Localpayment API. Show me the full request structure, required fields, how to handle the response, and what webhook I should expect when the payment is confirmed.
```

```
🔌 I want to implement 3D Secure authentication for card payments in Localpayment. Explain the flow, the additional fields required in the request, and how to handle the redirect and the final webhook notification.
```

```
🔌 Show me how to implement card tokenization in Localpayment. I want to save a customer's card for future payments without storing the raw card data. Include the tokenization request, how to use the token in a subsequent payment, and any expiration considerations.
```

### Métodos de pago alternativos (MPA)

```
🔌 I want to implement Pix payments (not virtual accounts) in Brazil using the Localpayment APM endpoint. Show me the request structure, required fields, and the webhook flow when the payment is completed.
```

```
🔌 I want to implement PSE payments in Colombia using the Localpayment API. Explain the flow, required fields, and how the redirect to the bank portal works. Include the webhook payload for a successful payment.
```

***

## Depuración de códigos de error

```
I received the following error response from the Localpayment API. Explain what it means, what caused it, and how to fix it:

[PASTE YOUR ERROR RESPONSE HERE]
```

```
🔌 What does error code [ERROR_CODE] mean in the Localpayment API? When does it occur, and what is the recommended fix?
```

**Mensajes comunes para la depuración de errores:**

```
🔌 I'm getting error 500 "External ID already used - Duplication" from the Localpayment API. Explain why this happens and the correct strategy for handling external IDs to avoid duplication in my integration.
```

```
🔌 I'm getting error 771 "Your Client Payin Settings have not been configured". What does this mean and what steps should I take to resolve it?
```

```
🔌 I'm getting error 776 "The alias is already in use" when trying to create a CVU alias in Argentina. Explain the alias uniqueness rule and how to choose a valid, unique alias.
```

```
🔌 I'm getting error 778 "The alias cannot be changed now; you must wait 24 hours after the last update." Explain the alias change restriction and what my options are.
```

```
🔌 I'm receiving status 101 OnHold on a payin. What does this status mean, when does it occur, and what action (if any) should I take?
```

***

## Webhooks y conciliación

```
Explain the complete webhook notification flow for Localpayment virtual account payments. What fields should I use to match an incoming webhook to a specific virtual account and transaction in my system?
```

```
I received the following webhook payload and I'm not sure how to reconcile it with my internal records. Which fields are the authoritative identifiers, and what does each key field mean?

[PASTE YOUR WEBHOOK PAYLOAD HERE]
```

```
🔌 What is the difference between externalId and internalId in Localpayment webhook payloads? Which one should I use for idempotency checks, and which one for support queries?
```

```
🔌 Explain the tracking object in Localpayment webhook payloads. What are tracking.id, tracking.reference, and tracking.concept? In which countries or payment methods is each field most useful for reconciliation?
```

```
🔌 My server is receiving duplicate webhook notifications from Localpayment. Explain Localpayment's retry mechanism and the correct way to implement idempotency in my webhook handler to avoid processing the same payment twice.
```

***

## Pruebas y control de calidad

```
🔌 Generate a comprehensive test suite for my Localpayment virtual account integration in [COUNTRY]. Include test cases for: successful payment, insufficient funds, invalid beneficiary, duplicate external ID, webhook delivery failure, and account status transitions.
```

```
🔌 I want to validate that my Localpayment integration covers all required fields for [COUNTRY]. Review the API spec and tell me if my request payload is missing any required parameters or contains any invalid values:

[PASTE YOUR REQUEST PAYLOAD HERE]
```

```
🔌 What are the Stage environment limitations I should be aware of when testing my Localpayment integration? Are there features that only work in Production?
```

```
🔌 Generate a Postman collection for the main Localpayment virtual account endpoints: create, get status, enable/disable, delete, and simulate payment. Use Stage as the base URL and include example request bodies for Argentina.
```

***

## Explora la API con las herramientas de MCP.

Estas indicaciones están diseñadas para funcionar directamente con las herramientas MCP disponibles en el servidor de Localpayment. Úsalas cuando desees navegar por la API mediante programación, en lugar de realizar preguntas específicas de integración.

**Mapa completo de la API:**

```
🔌 Using the Localpayment MCP tools, list all available API endpoints organized by product area. For each group, briefly explain what it does and give me the most important endpoint in that group. I want a complete map of the API.
```

**Descubre los endpoints de una función:**

```
🔌 Using search-endpoints, find all API operations related to [TOPIC — e.g. "refunds", "subscriptions", "FX", "webhooks"]. For each result, show me the HTTP method, path, and a one-line description.
```

**Lee detenidamente la guía de documentación:**

```
🔌 Search the Localpayment documentation for "[TOPIC]" and fetch the most relevant article. Read the full content and summarize: what the feature does, the key parameters, and any important caveats or country-specific notes.
```

**Comparar esquemas de endpoints:**

```
🔌 Use get-endpoint to retrieve the full schema for [ENDPOINT 1] and [ENDPOINT 2]. Compare their request structures, required fields, and response formats. Highlight the key differences between the two.
```

**Lista de verificación previa a la integración:**

```
🔌 I'm about to integrate [FEATURE] for [COUNTRY] using the Localpayment API. Before I start coding, use the MCP tools to: 1) find the relevant endpoints, 2) identify all required fields and validation rules, 3) check for any country-specific requirements or restrictions, and 4) list what webhook events I should expect. Give me a pre-integration checklist.
```

**Validar la solicitud antes de enviarla:**

```
🔌 Before I send this API request to Localpayment, use get-endpoint to read the live schema and validate my payload. Tell me if any required fields are missing, if any values are in the wrong format, and if there are any restrictions I might be violating:

[PASTE YOUR REQUEST PAYLOAD HERE]
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.