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

# Wire Out

O Localpayment permite que você retire fundos da sua conta Localpayment e os deposite em sua própria conta bancária externa por meio da integração da API e da interface do Business Portal. Este guia abrange todo o fluxo de trabalho de transferência eletrônica para liquidação de fundos, detalhando o fluxo de autorização, a implementação da API e o acompanhamento do status.

> [!NOTE]
>
> **Wire Out vs. Payout**
>
> Uma **Wire Out** é uma **liquidação/saque**: os fundos são transferidos da sua conta Localpayment para a **sua própria conta bancária externa**, nunca para terceiros.
>
> Um **Payout** é um **desembolso para um destinatário final** (normalmente seu cliente). Se você precisar enviar fundos para um terceiro, use o endpoint [Create Payout](https://docs.localpayment.com/pt-br/reference/create-a-payout.md).

## Antes de começar

Certifique-se de ter:

> [card] [Credenciais da API](https://docs.localpayment.com/pt-br/docs/api-keys-and-environments.md)
>
> Credenciais de API e token de acesso válidos para autenticação.

> [card] [Configuração da conta](https://docs.localpayment.com/pt-br/docs/make-your-first-test-payment.md)
>
> Configuração adequada da conta para o país de destino e verificação da empresa.

> [card] [Lista branca de IPs](https://docs.localpayment.com/pt-br/docs/dashboard-whitelist-your-ips.md)
>
> Adicione os endereços IP do seu servidor à lista de permissões para acesso à API.

> [card] [Endpoint do webhook](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Configure um URL de webhook para receber notificações de pagamento.

### Requisitos adicionais de Wire Out:

* **Saldo disponível** suficiente em sua conta Localpayment. Consulte-o no [Relatório de Balanço](https://docs.localpayment.com/pt-br/docs/balance-report.md) ou estime os fundos futuros com o [Relatório de Saldo Projetado](https://docs.localpayment.com/pt-br/docs/projected-balance-report.md).
* Função de usuário com **permissões suficientes** para autorização de Wire Out (consulte a documentação sobre funções e permissões).
* **Dados bancários externos** (código SWIFT, número da conta, informações do beneficiário).

***

## Guia de Implementação

A Localpayment oferece dois métodos para processar transferências bancárias: integração via API para processamento automatizado e Business Portal para operações manuais.

> [card] [Processamento de Wire Out via API](#process-wire-out-via-api)
>
> Inicie transações de Wire Out programaticamente por meio da API REST para
> fluxos de liquidação automatizados e integração de sistemas.

> [card] [Processamento de Transferências Bancárias no Business Portal](https://docs.localpayment.com/pt-br/docs/dashboard-wire-out.md)
>
> Processe manualmente instruções de Wire Out por meio do Business Portal da Localpayment,
> com uma interface visual e orientação passo a passo.

***

## Etapa 1: Processar Wire Out via API

Para iniciar uma transação de Wire Out via API, envie uma solicitação `POST` para o endpoint [Wire Out](https://docs.localpayment.com/pt-br/reference/wire-out.md).

### Parâmetros-chave da solicitação

A solicitação requer vários parâmetros-chave:

| Parâmetro | Descrição | Obrigatório |
| - | - | - |
| `transactionType` | Deve ser configurado para "WireOut" | ✅ |
| `externalId` | Seu ID de referência exclusivo para a transação. | ✅ |
| `country` | Código do país em formato ISO onde o pagamento será processado. | ✅ |
| `currency` | Moeda utilizada para o valor da transação | ✅ |
| `amount` | Valor a ser debitado da sua conta | ✅ |
| `accountNumber` | Seu número de conta Localpayment | ✅ |
| `to` | Objeto da conta bancária de destino. **O beneficiário deve ser você**, o mesmo titular da conta de origem, e não um terceiro. | ✅ |
| `to.name` | Nome do banco de destino | ✅ |
| `to.swift` | Código SWIFT/BIC do banco de destino | ✅ |
| `to.address` | Endereço do banco de destino | ✅ |
| `to.accountName` | Nome do titular da conta no banco de destino. | ✅ |
| `to.accountNumber` | Número da conta no banco de destino. | ✅ |
| `to.routingNumber` | Número de roteamento/código de classificação (varia conforme o país; por exemplo, transferências nos US) | ❌ |
| `to.beneficiaryAddress` | Seu endereço como beneficiário no banco de destino. | ✅ |
| `comment` | Nota opcional sobre a transação | ❌ |

### Exemplo de solicitação

> [tab] Padrão (fiat)
>
> ```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> curl --request POST \
>   --url https://api.stage.localpayment.com/api/account/wire-out \
>   --header 'Authorization: Bearer <your_access_token>' \
>   --header 'accept: application/json' \
>   --header 'content-type: application/json' \
>   --data '{
>     "transactionType": "WireOut",
>     "externalId": "c048aaea-5916-4dfe-add9-e3a720c42a08",
>     "country": "ARG",
>     "currency": "ARS",
>     "amount": 1000,
>     "accountNumber": "{{accountNumber}}",
>     "to": {
>       "name": "BBVA Arg.",
>       "swift": "BCSARG",
>       "address": "Centro 123",
>       "accountName": "John Doe",
>       "accountNumber": "3220001805117354710015",
>       "beneficiaryAddress": "Av. Corrientes 1234"
>     },
>     "comment": "Settlement"
>   }'
> ```

> [tab] Stablecoin (USDC / USDT)
>
> ```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> curl --request POST \
>   --url https://api.stage.localpayment.com/api/account/wire-out \
>   --header 'Authorization: Bearer <your_access_token>' \
>   --header 'accept: application/json' \
>   --header 'content-type: application/json' \
>   --data '{
>     "transactionType": "WireOut",
>     "externalId": "a3f7c912-4e85-4b2d-9c0f-6d1e8a2b5f47",
>     "country": "GLO",
>     "currency": "USDC",
>     "amount": 100,
>     "accountNumber": "{{accountNumber}}",
>     "to": {
>       "name": "Banco Galicia",
>       "swift": "GALVARAR",
>       "address": "123 Blockchain Ave",
>       "accountName": "Jane Doe",
>       "accountNumber": "{{walletAddress}}",
>       "routingNumber": "routingNumber",
>       "beneficiaryAddress": "123 Blockchain Ave"
>     },
>     "comment": "Stablecoin settlement"
>   }'
> ```
>
> > [!NOTE]
> >
> > Para Wire Outs em stablecoins, defina `currency` como `"USDC"` ou `"USDT"`. Para `country`, use `"GLO"` ou o código de país ISO alfa-3 que corresponde à carteira de destino. O campo `to.accountNumber` deve conter o endereço da carteira de destino.

Veja todos os [parâmetros disponíveis](https://docs.localpayment.com/pt-br/reference/wire-out.md) na solicitação.

***

## Etapa 2: Lidar com a resposta

### Resposta bem-sucedida

Uma transferência eletrônica (Wire Out) iniciada com sucesso retorna os detalhes da transação com o status inicial:

> [tab] Padrão (fiat)
>
> ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> {
>     "transactionType": "WireOut",
>     "externalId": "c048aaea-5916-4dfe-add9-e3a720c42a08",
>     "internalId": "c0e5ec40-b5b6-49aa-8c2d-b1ba01080100",
>     "country": "ARG",
>     "currency": "ARS",
>     "clientCode": "0001",
>     "creationDate": "2025-09-29T18:41:49.940+00:00",
>     "errors": [],
>     "status": {
>         "code": "100",
>         "description": "RECEIVED",
>         "detail": "WIRE OUT"
>     },
>     "accountNumber": "{{accountNumber}}",
>     "amount": 1000.0,
>     "fees": {
>         "description": "Fee",
>         "currency": "ARS",
>         "amount": 30.0,
>         "account": "{{accountNumber}}"
>     },
>     "localTaxes": [],
>     "withHoldings": [],
>     "comment": "Settlement"
> }
> ```

> [tab] Stablecoin (USDC / USDT)
>
> ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> {
>     "internalId": "53f2fcb7-0cf0-40f4-8416-2d00e91786a1",
>     "externalId": "a3f7c912-4e85-4b2d-9c0f-6d1e8a2b5f47",
>     "clientCode": "0001",
>     "country": "GLO",
>     "errors": [],
>     "accountNumber": "{{accountNumber}}",
>     "code": "102",
>     "comment": "Stablecoin settlement",
>     "creationDate": "2026-01-15T15:18:43.121+00:00",
>     "localTaxes": [],
>     "status": {
>         "code": "102",
>         "description": "Received",
>         "detail": "Authorized"
>     },
>     "transactionType": "WireOut",
>     "currency": "USDC",
>     "fees": {
>         "account": "{{accountNumber}}",
>         "amount": 0,
>         "currency": "USDC",
>         "description": "Fee"
>     },
>     "withHoldings": [],
>     "amount": 100,
>     "transactionFlow": "wireInAutomatic"
> }
> ```

### Campos de resposta principais

| Parâmetro | Descrição | Caso de uso |
| - | - | - |
| `externalId` | Sua referência para a transação original. | Conciliação e rastreamento. |
| `internalId` | Identificador de reembolso exclusivo da Localpayment. | Para fins de suporte e auditoria. |
| `status.code` | Código de status da transação atual. | Monitoramento de status. |
| `creationDate` | Quando a transação foi criada. | Rastreamento de auditoria e geração de relatórios. |

### Resposta de erro

Quando uma solicitação Wire Out falha, você recebe informações detalhadas sobre o erro:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "status": {
        "code": "300",
        "description": "REJECTED",
        "detail": "[to.address must not be empty]"
    },
    "timestamp": "2025-09-29 18:52:05.640378596",
    "errors": [
        {
            "code": "300",
            "detail": "to.address must not be empty"
        }
    ]
}
```

***

## Etapa 3: Rastrear o Status do Wire Out

Após iniciar uma operação de Wire Out, monitore seu progresso através destes métodos:

> [card] [Webhooks (Recomendado)](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Receba notificações em tempo real quando o status da transação mudar. Ideal para ambientes de produção.

> [card] [Endpoint da API de Status](https://docs.localpayment.com/pt-br/reference/get-transaction-status.md)
>
> Consultar o status da transação programaticamente. Útil para consultar ou recuperar notificações de webhook perdidas.

> [card] [Visualização do Business Portal](https://docs.localpayment.com/pt-br/docs/dashboard-overview.md)
>
> Interface visual para monitoramento de transações. Ideal para supervisão manual e análise detalhada de transações.

### Códigos de Status Comuns do Wire Out

| Código | Status | Descrição |
| - | - | - |
| `100` | `PendingAuth` | Transação criada, aguardando autorização. |
| `101` | `PendingDebit` | Transação em andamento após validação do Localpayment. |
| `102` | `Received` | Transação autorizada |
| `200` | `Completed` | Os fundos foram transferidos com sucesso para o banco de destino. |
| `404` | `Rejected` | O código do provedor não corresponde ao número da conta. |
| `511` | `Rejected` | Valor zero especificado na solicitação |
| `716` | `Rejected` | Rejeitado pelo administrador durante a autorização. |
| `717` | `RejectedByBank` | Transação rejeitada pelo banco de destino |

> [!NOTE]
>
> **Notificações de Conclusão**
>
> Você receberá notificações por e-mail quando as transações atingirem os status `Completed` ou `Rejected`, independentemente de terem sido iniciadas via API ou Business Portal. Para transações de Wire Out em cripto (USDC/USDT), o callback de webhook `Completed` também inclui o hash da transação na blockchain (campo `hash`) para que você possa verificar o pagamento de forma independente em um explorador de blocos. Este campo não se aplica a Wire Out em moeda fiduciária — consulte [Webhooks](https://docs.localpayment.com/pt-br/docs/webhooks.md) para obter um exemplo completo da carga útil.

***

## Processamento de Transferências Bancárias no Business Portal

As transferências eletrônicas também podem ser processadas através da interface do Business Portal da Localpayment. Este método oferece um fluxo de trabalho visual para gerenciar transferências de fundos e é particularmente útil para:

* Liquidações pontuais\*\* que não exigem automação de API.
* Supervisão administrativa\*\* com fluxos de trabalho de autorização visual.
* **Transferências rápidas de fundos** sem recursos para o desenvolvimento.

Para obter instruções detalhadas sobre como processar transações de Transferência Eletrônica de Fundos (Wire Out) através do Business Portal, incluindo orientações passo a passo e tutoriais da interface, consulte o [Guia de Transferência Eletrônica de Fundos do Business Portal](https://docs.localpayment.com/pt-br/docs/dashboard-wire-out.md) .

***

## Testando sua integração

### Cenários de teste

Verifique se sua integração lida com esses cenários:

1. **Wire Out bem-sucedido**: Processo de transferência com parâmetros válidos e saldo suficiente.
2. **Fundos insuficientes**: Tentativa de transferência que excede o saldo da conta.
3. **Dados bancários inválidos**: teste com códigos SWIFT ou números de conta incorretos.
4. **Fluxo de trabalho de autorização**: Verificar o status de autorização pendente e o processo de aprovação.

***

## Próximos passos

> [card] [Ver o estado da transação](https://docs.localpayment.com/pt-br/reference/get-transaction-status.md)
>
> Verifique o status atual das transações de Wire Out usando a API de Status
> da Transação.

> [card] [Configurar webhooks](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Configure webhooks para receber notificações em tempo real sobre o status
> do Wire Out.


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