> ## 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 por transferência bancária

Envie fundos por transferência bancária 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 por transferência bancária permitem que você envie fundos diretamente para as contas bancárias dos beneficiários. 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 por transferência bancária, 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 `"BankTransfer"`.

### 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 (Argentina)

```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 '[
 {
  "externalId": "212407f5-0c86-4687-91e4-df3ab8a513ab",
  "country": "ARG",
  "currency": "ARS",
  "amount": 500.18,
  "paymentMethod": {
    "type": "BankTransfer",
    "code": "0010",
    "flow": "DIRECT"
  },
  "beneficiary": {
    "name": "John",
    "lastName": "Doe",
    "type": "INDIVIDUAL",
    "document": {
      "type": "CUIT",
      "id": "20907920276"
    },
    "userReference": "Test",
    "email": "john.doe@email.com",
    "phone": {
      "countryCode": "54",
      "areaCode": "11",
      "number": "12345678"
    },
    "birthDate": "2021-11-08",
    "nationality": "Argentine",
    "address": {
      "street": "Avenida Principal",
      "number": "234",
      "city": "La Plata",
      "state": "Buenos Aires",
      "country": "Argentina",
      "zipCode": "C1420",
      "comment": "TEST"
    },
    "bank": {
      "name": "BANCO DE GALICIA Y BUENOS AIRES S.A.U.",
      "code": "007",
      "account": {
        "number": "0070145330004020870169",
        "type": "S"
      }
    }
  },
  "sender": {
    "type": "INDIVIDUAL",
    "name": "David",
    "lastName": "Doe",
    "document": {
      "type": "CUIT",
      "id": "20907920276"
    },
    "userReference": "Test",
    "email": "david.doe@email.com",
    "phone": {
      "countryCode": "54",
      "areaCode": "11",
      "number": "12345678"
    },
    "birthDate": "2021-11-08",
    "nationality": "Argentine",
    "address": {
      "street": "Avenida Principal",
      "number": "234",
      "city": "La Plata",
      "state": "Buenos Aires",
      "country": "Argentina",
      "zipCode": "C1420",
      "comment": "TEST"
    }
  },
  "merchant": {
    "type": "COMPANY",
    "name": "Company Name",
    "document": {
      "type": "CUIT",
      "id": "20907920276"
    },
    "userReference": "Test",
    "email": "company@email.com",
    "phone": {
      "countryCode": "54",
      "areaCode": "11",
      "number": "12345678"
    },
    "birthDate": "2021-11-08",
    "nationality": "Argentine",
    "address": {
      "street": "Avenida Principal",
      "number": "234",
      "city": "La Plata",
      "state": "Buenos Aires",
      "country": "Argentina",
      "zipCode": "C1420",
      "comment": "TEST"
    }
  },
  "accountNumber": "{{accountNumber}}",
  "conceptCode": "0039",
  "comment": "ARG TEST",
  "requireAuth": true
}
]'
```

***

## 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": "212407f5-0c86-4687-91e4-df3ab8a513ab",
    "internalId": "095a5d8d-53ff-4a8d-9665-7ceb6eaa94df",
    "paymentMethod": {
        "code": "0010",
        "name": "INTERBANKING",
        "description": "string",
        "paymentMethodType": "BankTransfer"
    },
    "country": "ARG",
    "currency": "ARS",
    "amount": 500.18,
    "accountNumber": "{{accountNumber}}",
    "clientCode": "0001",
    "clientName": "Acme",
    "status": {
        "code": "104",
        "description": "PendingAuth",
        "detail": "The payout is pending of authorization by client"
    },
    "beneficiary": {
        "bank": {
            "name": "BANCO DE GALICIA Y BUENOS AIRES S.A.U.",
            "code": "007",
            "countryISOCode3": null,
            "branch": null,
            "account": {
                "number": "0070145330004020870169",
                "type": "S",
                "alias": null,
                "pixKey": null,
                "phone": null
            }
        },
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "CUIT",
            "id": "20907920276"
        },
        "userReference": "Test",
        "email": "john.doe@email.com",
        "phone": {
            "countryCode": "54",
            "areaCode": "11",
            "number": "12345678"
        },
        "birthdate": "2021-11-08T00:00:00Z",
        "nationality": "Argentine",
        "address": {
            "street": "Avenida Principal",
            "number": "234",
            "city": "La Plata",
            "state": "Buenos Aires",
            "country": "Argentina",
            "zipCode": "C1420",
            "comment": "TEST"
        }
    },
    "merchant": {
        "type": "COMPANY",
        "name": "Company Name",
        "lastname": null,
        "document": {
            "type": "CUIT",
            "id": "20907920276"
        },
        "userReference": "Test",
        "email": "company@email.com",
        "phone": {
            "countryCode": "54",
            "areaCode": "11",
            "number": "12345678"
        },
        "birthdate": "2021-11-08T00:00:00Z",
        "nationality": "Argentine",
        "address": {
            "street": "Avenida Principal",
            "number": "234",
            "city": "La Plata",
            "state": "Buenos Aires",
            "country": "Argentina",
            "zipCode": "C1420",
            "comment": "TEST"
        }
    },
    "sender": {
        "type": "INDIVIDUAL",
        "name": "David",
        "lastname": "Doe",
        "document": {
            "type": "CUIT",
            "id": "20907920276"
        },
        "userReference": "Test",
        "email": "david.doe@email.com",
        "phone": {
            "countryCode": "54",
            "areaCode": "11",
            "number": "12345678"
        },
        "birthdate": "2021-11-08T00:00:00Z",
        "nationality": "Argentine",
        "address": {
            "street": "Avenida Principal",
            "number": "234",
            "city": "La Plata",
            "state": "Buenos Aires",
            "country": "Argentina",
            "zipCode": "C1420",
            "comment": "TEST"
        }
    },
    "comment": "ARG TEST",
    "exchangeRateToken": null,
    "date": {
        "creationDate": "2025-10-10T21:04:44.2729228Z",
        "processedDate": "2025-10-10T21:04:44.2731812Z"
    },
    "errors": null,
    "internalLoteID": "151840"
}
```

### 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] Brasil
>
> **Requisitos especiais:**
>
> * `beneficiary.bank.branch` é **obrigatório** quando você envia o payout com um número de conta (`beneficiary.bank.account.number`). Isso se aplica tanto a transferências TED quanto Pix feitas para uma conta. Se você o omitir, o payout é rejeitado com o erro 300 (`beneficiary.bank.branch` must not be null) e o erro 701 (Invalid bank branch code).
>   * `code`: **Obrigatório.** O código da agência no formato exigido pelo banco.
>   * `name`: **Opcional.** O nome completo da agência bancária.
> * Quando você envia o payout com uma chave Pix (`beneficiary.bank.account.alias`), `beneficiary.bank.branch` é opcional.
> * `merchant.address` é **obrigatório** e deve incluir `country`.
>   * `country`: **Obrigatório.** O código de país ISO de 3 letras do endereço do comerciante (por exemplo, `BRA`).
>   * Os demais campos de `merchant.address` são opcionais.
>
> **Envio de fundos com Chave Pix:**
>
> Como alternativa aos dados bancários tradicionais, você pode enviar fundos usando uma chave Pix. O Pix é o sistema de pagamentos instantâneos do Brasil, que permite transferências 24 horas por dia, 7 dias por semana, incluindo fins de semana e feriados.
>
> Para usar este método:
>
> 1. O destinatário deve possuir uma chave Pix registrada.
> 2. Você deve informar essa chave na propriedade `beneficiary.bank.account.alias`.
>
>    **Observação:** as propriedades beneficiary.bank.account.type e beneficiary.bank.account.number devem ser excluídas da solicitação.
>
> **Tipos de chave Pix suportados:**
>
> Você pode usar qualquer um dos cinco tipos de chave a seguir:
>
> * CPF (Registro de Contribuinte Individual)
> * CNPJ (Cadastro Nacional de Pessoa Jurídica)
> * Número de celular
> * Endereço de email
> * Chave aleatória: um código único de 32 caracteres gerado pelo Banco Central. Essa opção permite que os destinatários recebam pagamentos sem compartilhar informações pessoais.

> [tab] Chile
>
> **Requisitos especiais:**
>
> * Quando a moeda estiver definida como **CLP**, o valor deve ser especificado como um número inteiro. Casas decimais não são permitidas.

> [tab] Colômbia
>
> Os bancos disponíveis dependem do método de pagamento escolhido. A Colômbia oferece suporte a três trilhos de pagamento: ACH (`0060`), Transfiya (`0061`) e Bre-B (`0062`).
>
> **Transfiya (`0061`)**
>
> > [!NOTE]
> >
> > A Transfiya identifica os beneficiários pelo **número de celular**. Isso é diferente do ACH (`0060`), que exige um número de conta bancária e o código do banco.
>
> A Transfiya processa pagamentos usando o número de celular cadastrado do beneficiário. Após o início da transação, o beneficiário recebe uma notificação por SMS e pode aceitar ou rejeitar a transferência pelo aplicativo do banco.
>
> | Campo | Valor |
> | - | - |
> | `beneficiary.bank.account.type` | `"P"` |
> | `beneficiary.bank.account.number` | Sequência de 12 dígitos começando com `+573` |
>
> **Instituições apoiadas:**
>
> * BANCO AGRARIO DE COLOMBIA
> * BANCO COOPERATIVO COOPCENTRAL DIGITAL
> * BANCO CREZCAMOS
> * BANCO DE LAS MICROFINANZAS BANCAMIA SA
> * BANCO FALABELLA
> * BANCO FINANDINA
> * BANCO ITAÚ
> * BANCO POWWI
> * BANCO SERFINANZA
> * BANCOCOOPCENTRAL
> * BANCOLOMBIA
> * CFA COOPERATIVA FINANCIERA
> * CONFIAR COOPERATIVA FINANCIERA
> * DAVIVIENDA
> * MOVII
> * NEQUI
>
> **Atualmente não é suportado:**
>
> * Banco AV Villas (serviço intermitente)
> * Banco de Bogotá
> * Banco de Occidente SA
> * Dale
> * Davibank
>
> ***
>
> **Bre-B (`0062`)**
>
> Bre-B é o sistema de pagamento instantâneo da Colômbia para transferências em tempo real entre instituições financeiras. Ele utiliza identificadores simples, como números de telefone ou números de identificação, em vez de dados bancários completos.
>
> Antes de começar, consulte a [lista de bancos disponíveis](https://docs.localpayment.com/pt-br/docs/colombia.md) para verificar quais instituições oferecem suporte ao Bre-B.
>
> Para usar este método:
>
> 1. O destinatário deve ter uma chave Bre-B registrada em seu banco.
>
> 2. Forneça a chave em `beneficiary.bank.account.alias`.
>
> > [!NOTE]
> >
> > Ao usar o Bre-B, exclua `beneficiary.bank.account.type` e `beneficiary.bank.account.number` da solicitação.
>
> Tipos de chaves Bre-B suportados:
>
> * **Documento de identidade**: Carteira de identidade, Cartão de imigração, Cartão de cidadania ou Passaporte
> * **Código do comerciante**
> * **Número de celular**
> * **Endereço de email**
> * **Chave alfanumérica** — um código único gerado pelo banco (por exemplo, `@alphamunKey01`) que permite pagamentos sem compartilhar informações pessoais
>
> Antes de enviar o pagamento, você pode, opcionalmente, verificar se a chave Bre-B está ativa e visualizar os detalhes do proprietário (ocultos). Consulte [Verificar um Alias de Pagamento](https://docs.localpayment.com/pt-br/docs/verify-a-payout-alias.md).

> [tab] República Dominicana
>
> **Requisitos especiais:**
>
> * O `beneficiary.bank.account.number` pode ser fornecido em formato nacional ou IBAN. Ambos representam a mesma conta subjacente.
>   * **Formato nacional:** O número de conta doméstico padrão.
>     Exemplo: 830640009
>   * **Formato IBAN:** O padrão internacional de 28 caracteres. Um IBAN dominicano começa com "DO".
>     Exemplo: DO42BPDO00000000000830640009

> [tab] México
>
> **Requisitos especiais:**
>
> * O `beneficiary.document.type` é opcional.
> * Especificações para pagamentos por número de celular:
>   * `beneficiary.bank.account.type`: Deve ser definido como "P".
>   * `beneficiary.bank.account.number`: Deve ser um número de 10 dígitos.

> [tab] Peru
>
> **Requisitos especiais:**
>
> * Para validar um **CCI**, recomendamos usar o recurso oficial fornecido pelos bancos peruanos:
>   [https://www.transferenciasinterbancarias.pe/](https://www.transferenciasinterbancarias.pe/)

***

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