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

# Enviar fundos via carteira

Envie fundos via carteira usando a API da Localpayment. Este guia abrange tudo o que você precisa saber sobre como criar payouts, lidar com respostas, gerenciar o status da transação e atender aos requisitos específicos de cada país.

Os payouts para carteira permitem que você envie fundos diretamente para a carteira digital do beneficiário. Você pode iniciar essas transferências por meio de:

* **Business Portal Localpayment**: Interface amigável para [gerenciamento manual de transações.](https://docs.localpayment.com/pt-br/docs/internal-transfers)
* **Integração de API**: Acesso programático para processamento automatizado de payouts.

Este guia se concentra na implementação da API, abrangendo todo o fluxo, da inicialização à conclusão.

## Antes de começar

Certifique-se de ter:

* [Credenciais de API ](https://docs.localpayment.com/pt-br/docs/api-keys-and-environments.md)válidas (token de acesso).
* Informações completas sobre o beneficiário.
* [Configuração](https://docs.localpayment.com/pt-br/docs/setup-guide.md) adequada da conta para o país de destino.
* Compreensão dos requisitos específicos de cada país (consulte [Requisitos por País](#country-specific-requirements) abaixo).

***

## Etapa 1: Inicializar a transação de payout

Para criar um payout para carteira, envie uma solicitação `POST` ao endpoint **[Create a Payout](https://docs.localpayment.com/pt-br/reference/create-a-payout.md)** com `paymentMethod.type` definido como `Wallet`.

### Endpoint

```
POST https://api.stage.localpayment.com/api/payout/
```

### Cabeçalhos obrigatórios

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
Authorization: Bearer <your_access_token>
```

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

A solicitação requer vários objetos-chave:

| Objeto | Descrição | Obrigatório |
| - | - | - |
| `beneficiary` | Dados do destinatário, incluindo informações bancárias | ✅ |
| `sender` | Informações do remetente para fins de conformidade | ✅ |
| `merchant` | Detalhes do comerciante/empresa | ✅ |
| `paymentMethod` | Configuração do método de pagamento | ✅ |
| `amount` | Valor da transação | ✅ |
| `currency` | Código da moeda da transação | ✅ |
| `country` | Código do país de destino | ✅ |

### Exemplo de solicitação (Bolívia)

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/payout/ \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "value": {
    "externalId": "07e80cf6-b11b-479c-ad9a-b952ec256cdb",
    "country": "BOL",
    "currency": "BOB",
    "amount": 1000,
    "paymentMethod": {
      "type": "Wallet",
      "code": "0021",
      "flow": "direct"
    },
    "beneficiary": {
      "name": "John",
      "lastName": "Doe",
      "type": "INDIVIDUAL",
      "document": {
        "type": "CI",
        "id": "7794986"
      },
      "bank": {
        "name": "Yape",
        "code": "990",
        "account": {
          "alias": "+59112345678"
        }
      }
    },
    "sender": {
      "type": "INDIVIDUAL",
      "name": "David",
      "lastName": "Doe",
      "document": {
        "type": "CI",
        "id": "4812012-1B"
      }
    },
    "merchant": {
      "type": "COMPANY",
      "name": "Company Name"
    },
    "accountNumber": "{{accountNumber}}",
    "conceptCode": "0039"
  }
}
'
```

***

## Etapa 2: Lidar com a resposta

### Resposta bem-sucedida

Uma resposta bem-sucedida inclui informações detalhadas sobre a transação e identificadores de rastreamento:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "07e80cf6-b11b-479c-ad9a-b952ec256cdb3",
  "internalId": "9cbdb959-acb0-49e5-a52a-a8f9dddcde15",
  "paymentMethod": {
    "code": "0021",
    "name": "BCP",
    "description": "Yape",
    "paymentMethodType": "Wallet"
  },
  "country": "BOL",
  "currency": "BOB",
  "amount": 1000,
  "accountNumber": "{{accountNumber}}",
  "clientCode": "0001",
  "clientName": "Acme",
  "status": {
    "code": "100",
    "description": "Received",
    "detail": "The payout was received"
  },
  "beneficiary": {
    "bank": {
      "name": "Yape",
      "code": "990",
      "countryISOCode3": null,
      "branch": null,
      "account": {
        "number": null,
        "type": null,
        "alias": "+59112345678",
        "pixKey": null,
        "phone": null
      }
    },
    "type": "INDIVIDUAL",
    "name": "John",
    "lastname": "Doe",
    "document": {
      "type": "CI",
      "id": "7794986"
    },
    "userReference": null,
    "email": null,
    "phone": null,
    "birthdate": "0001-01-01T00:00:00Z",
    "nationality": null,
    "address": null
  },
  "merchant": {
    "type": "COMPANY",
    "name": "Company Name",
    "lastname": null,
    "document": null,
    "userReference": null,
    "email": null,
    "phone": null,
    "birthdate": "0001-01-01T00:00:00Z",
    "nationality": null,
    "address": null
  },
  "sender": {
    "type": "INDIVIDUAL",
    "name": "David",
    "lastname": "Doe",
    "document": {
      "type": "CI",
      "id": "4812012-1B"
    },
    "userReference": null,
    "email": null,
    "phone": null,
    "birthdate": "0001-01-01T00:00:00Z",
    "nationality": null,
    "address": null
  },
  "comment": null,
  "exchangeRateToken": null,
  "date": {
    "creationDate": "2025-10-10T22:03:25.5138845Z",
    "processedDate": "2025-10-10T22:03:25.5140817Z"
  },
  "errors": null,
  "internalLoteID": "151880"
}
```

### Campos de resposta principais

| Campo | Descrição | Caso de uso |
| - | - | - |
| `internalId` | Identificador de transação exclusivo da Localpayment | Rastreamento e suporte de transações |
| `externalId` | Seu número de referência | Reconciliação interna |
| `status.code` | Código de status da transação atual | Monitoramento de status |
| `date.creationDate` | Quando a transação foi criada | Registro de auditoria |
| `date.processedDate` | Quando a transação começou a ser processada | Cálculo do tempo de processamento |

### Resposta de erro

Quando uma solicitação falhar, você receberá informações detalhadas sobre o erro:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
[
  {
    "externalId": "1736488884",
    "internalId": "cd052d8c-8406-45f8-98aa-aff9876c3285",
    "status": {
      "code": "801",
      "description": "Rejected",
      "detail": "Params error"
    },
    "errors": [
      {
        "code": "300",
        "description": "Invalid param + [paymentMethod.code] + doesn't exist for PAYMENT_METHOD_TYPE BankTransf"
      },
      {
        "code": "300",
        "description": "Invalid param + [beneficiary.document.id] + doesn´t match regex ^(20|23|24|25|26|27|30|33|34)-?\\d{2}[.]?\\d{3}[.]?\\d{3}-?\\d$"
      }
    ],
    "comment": "Addicional informetion"
  }
]
```

***

## Etapa 3: Rastrear o status da transação

Após efetuar um payout, acompanhe o 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

| Código | Status | Descrição |
| :- | :- | :- |
| `100` | `Received` | O payout foi recebido. |
| `101` | `Locked` | O payout foi confirmado e passou pelas validações de AML (Anti-Money Laundering, ou Prevenção à Lavagem de Dinheiro). |
| `102` | Em andamento | O payout foi enviado ao banco. |
| `104` | `PendingAuth` | O payout está pendente de autorização por parte do cliente. |
| `200` | `Completed` | O payout foi debitado. |
| `300` | `Rejected` | Parâmetro inválido + \[nome do parâmetro] + \[motivo]. |

> [!NOTE]
>
> **Referência completa**
>
> Consulte todos os códigos de status em nossa [Documentação de Status da Transação](https://docs.localpayment.com/pt-br/reference/transaction-status-error-codes).

***

## Etapa 4: Aprovação da transação

Para maior segurança, certas transações exigem a [aprovação de duas pessoas](https://docs.localpayment.com/pt-br/docs/approvals-and-double-signature.md):

1. **Iniciador**: Envia o pedido de payout.
2. **Aprovador**: Analisa e confirma a transação.

Este processo pode ser gerenciado através do [Business Portal](https://docs.localpayment.com/pt-br/docs/dashboard-review-payout.md) ou dos [endpoints da API](https://docs.localpayment.com/pt-br/reference/authorize-payout.md).

> [!NOTE]
>
> **Nota de segurança**
>
> Os requisitos de aprovação ajudam a prevenir transações não autorizadas e a garantir a conformidade com as regulamentações locais.

***

## Requisitos específicos de cada país

Os detalhes de implementação variam de país para país. Qualquer país não mencionado explicitamente segue o procedimento padrão sem requisitos especiais. Consulte esses requisitos antes da integração:

> [tab] Bolívia
>
> **Pagamentos YAPE:**
>
> * `paymentMethod.code`: Defina como 0021.
> * `beneficiary.bank.code`: Defina como 990.
> * `beneficiary.bank.account.alias`: Deve conter o número de telefone do beneficiário no formato +591XXXXXXXX (formato internacional completo).
> * Omita os seguintes campos: `beneficiary.bank.account.type` e `beneficiary.bank.account.number`.

> [tab] Peru
>
> **Requisitos especiais:**
>
> * `paymentMethod.code`: Defina como 0171.
> * `beneficiary.bank.account.alias`: Defina como um número de celular de 9 dígitos começando com 9 (por exemplo, 987654321).
> * Omita os seguintes campos: `beneficiary.bank.account.type` e `beneficiary.bank.account.number`.
> * `beneficiary.bank.code`:
>   * YAPE: Defina como 901.
>   * PLIN: Defina como 902.
>   * LIGO: Defina como 921.
>   * DALE: Defina como 922.

> [tab] Costa Rica
>
> **Pagamentos SINPE Móvil:**
>
> * `paymentMethod.code`: Defina como 0071.
> * `beneficiary.bank.account.alias`: Defina como o número de telefone do beneficiário no formato +506XXXXXXXX (formato internacional completo).
> * `beneficiary.bank.name` e `beneficiary.bank.code`: Defina como o nome e o código do banco do beneficiário (o banco ao qual o número de telefone está vinculado), conforme a [tabela de códigos de bancos](https://docs.localpayment.com/pt-br/docs/costa-rica.md#bank-codes).
> * Omita os seguintes campos: `beneficiary.bank.account.type` e `beneficiary.bank.account.number`.
>
> Disponível 24 horas por dia, 7 dias por semana, incluindo fins de semana e feriados.

***

## Testando sua integração

### Ambiente de Sandbox

Utilize o ambiente de teste para realizar os procedimentos:

```
https://api.stage.localpayment.com/api/payout/
```

### Cenários de teste

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

1. **Transação bem-sucedida**: Fluxo de payout padrão
2. **Erros de validação**: conta bancária inválida, campos ausentes
3. **Atrasos no processamento**: transações que levam tempo para serem processadas.
4. **Transações com falha**: Fundos insuficientes, beneficiários bloqueados
5. **Atualizações de status**: gerenciamento de webhooks e consulta de status.

***

## Recursos e próximos passos

Maximize o sucesso da sua integração com estes recursos essenciais.

> [card] [Integração de Webhook](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Configure notificações em tempo real para atualizações do status das transações.

> [card] [Relatórios do Business Portal](https://docs.localpayment.com/pt-br/docs/balance-report.md)
>
> Acesse análises detalhadas, ferramentas de geração de relatórios e recursos de conciliação.

> [card] [Monitoramento de transações](https://docs.localpayment.com/pt-br/reference/transaction-status-error-codes)
>
> Aprenda a consultar o status das transações e a implementar um rastreamento abrangente.

> [card] [Referência da API](https://docs.localpayment.com/pt-br/reference/exchange-bulk.md)
>
> Documentação completa dos endpoints com exemplos interativos.

> [!NOTE]
>
> **Dica profissional**
>
> Sempre teste seu fluxo de trabalho em nosso ambiente de sandbox antes de implantá-lo em produção. Isso garante que o tratamento de erros, o processamento de webhooks e o rastreamento de status funcionem corretamente em todos os cenários.

***

> [!NOTE]
>
> **Precisar de ajuda?**
>
> Entre em contato com nossa [equipe de suporte](mailto:support@localpayment.com) caso encontre algum problema ou precise de ajuda com a integração.


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