> ## 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 prompts

Uma coleção selecionada de instruções prontas para uso na criação, depuração e teste de integrações do Localpayment. Organizadas por caso de uso e país. Copie, cole e acelere o processo.

Copie qualquer um dos prompts abaixo e cole-o em seu assistente de IA, com ou sem o [servidor MCP](https://docs.localpayment.com/pt-br/docs/mcp-server.md) conectado. Os prompts marcados com 🔌 obtêm resultados significativamente melhores quando o servidor MCP está ativo, pois a IA consulta as especificações em tempo real, em vez de depender de dados de treinamento potencialmente desatualizados.

> [!NOTE]
>
> **Configuração recomendada para obter os melhores resultados:**
>
> 1. **Servidor MCP** (primário): Configure o [servidor MCP do Localpayment](https://docs.localpayment.com/pt-br/docs/mcp-server.md) em sua ferramenta de IA. A IA chamará automaticamente `list-endpoints`, `get-endpoint`, `search` e `fetch` para responder com dados verificados e em tempo real.
> 2. **LLMs.txt** (alternativa): Se você estiver usando uma interface de chat sem MCP, cole `https://docs.localpayment.com/llms.txt` no início da sessão para dar à IA um mapa completo da documentação antes de fazer perguntas.
> 3. **Artigos em texto simples**: Para tópicos específicos, acrescente `.md` a qualquer URL de documentação (por exemplo, `https://docs.localpayment.com/docs/virtual-accounts-overview.md`) e cole o conteúdo diretamente no seu prompt.
>
> A utilização desses recursos evita alucinações e garante que a IA gere código com base na API Localpayment atual e correta.

***

## Autenticação e gerenciamento de tokens

A autenticação é necessária antes de cada chamada à API Localpayment. Esses prompts abrangem todo o ciclo de vida do token.

> [!NOTE]
>
> Se você está começando do zero, o guia [Faça seu primeiro pagamento de teste](https://docs.localpayment.com/pt-br/docs/make-your-first-test-payment.md) descreve todo o fluxo passo a passo (token → descoberta de métodos de pagamento → criação de pagamento → webhook → verificação de status), com exemplos reais de curl para cada chamada.

```
🔌 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.
```

***

## Virtual Accounts

> [!WARNING]
>
> **A autenticação é sempre necessária primeiro.** Cada chamada à API Localpayment precisa de um token Bearer válido. Antes de executar qualquer um dos prompts abaixo, certifique-se de que sua integração lide com a geração de token (`POST /api/token/`) e solicite um novo token quando o atual expirar. Consulte o [guia de autenticação](https://docs.localpayment.com/pt-br/docs/authentication.md) para obter detalhes.
>
> Os prompts do "caminho feliz completo" abaixo incluem a autenticação como etapa 1.

### Integração completa: Caminho feliz

Utilize essas instruções para criar uma integração completa de Virtual Account, desde a criação até a conciliação.

> [tab] Argentina (CVU)
>
> **Criar uma Virtual Account:**
>
> ```
> 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 um pagamento (Stage):**
>
> ```
> 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.
> ```
>
> **Receber e analisar o 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]
> ```
>
> **Caminho feliz completo, de ponta a ponta:**
>
> ```
> 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)
>
> **Criar uma Virtual Account:**
>
> ```
> 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, entenda a diferença:**
>
> ```
> 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?
> ```
>
> **Caminho feliz completo, de ponta a ponta:**
>
> ```
> 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] Colômbia (Bre-B)
>
> **Criar uma Virtual Account:**
>
> ```
> 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.
> ```
>
> **Caminho feliz completo, de ponta a ponta:**
>
> ```
> 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)
>
> **Criar uma Virtual Account:**
>
> ```
> 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.
> ```
>
> **Caminho feliz completo, de ponta a ponta:**
>
> ```
> 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] Peru (CCI)
>
> **Criar uma Virtual Account:**
>
> ```
> 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.
> ```
>
> **Caminho feliz completo, de ponta a ponta:**
>
> ```
> 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.
> ```

***

### Operações de Virtual Account

```
🔌 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.
```

***

## Criando integrações por país

### Iniciar uma integração para um novo 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?
```

### Cartões

```
🔌 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 Alternativos de Pagamento (APMs)

```
🔌 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.
```

***

## Depuração de códigos de erro

```
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?
```

**Mensagens comuns de depuração de erros:**

```
🔌 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 e reconciliação

```
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.
```

***

## Testes e Garantia de Qualidade

```
🔌 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.
```

***

## Explore a API com as ferramentas MCP

Essas instruções foram projetadas para funcionar diretamente com as ferramentas MCP disponíveis no servidor Localpayment. Use-as quando quiser navegar pela API programaticamente, em vez de fazer perguntas específicas de integração.

**Mapa completo da 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.
```

**Descubra os endpoints para uma funcionalidade:**

```
🔌 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.
```

**Leia atentamente o guia de documentação:**

```
🔌 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 verificação pré-integração:**

```
🔌 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.
```

**Valide a solicitação antes de enviá-la:**

```
🔌 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.