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

# Testes em ambiente de sandbox para pagamentos

Use as contas de teste do Stage para acionar cenários específicos de rejeição de Payout antes de entrar em produção com Payouts por Transferência Bancária.

Antes de enviar Payouts a beneficiários reais em Produção, use o ambiente Stage para confirmar que a sua integração lida tanto com Payouts bem-sucedidos quanto com os cenários de rejeição que os bancos dos beneficiários retornam na prática. Este guia cobre o fluxo de sandbox de Payouts por Transferência Bancária e fornece contas de teste dedicadas, uma por país, que acionam de forma determinística cada cenário de rejeição.

## Antes de começar

* [Credenciais de API](https://docs.localpayment.com/pt-br/docs/api-keys-and-environments.md) válidas (token de acesso) para o Stage.
* Familiaridade com [Enviar fundos por transferência bancária](https://docs.localpayment.com/pt-br/docs/send-funds-via-bank-transfer.md) e com a estrutura da requisição [Create a Payout](https://docs.localpayment.com/pt-br/reference/create-a-payout.md).
* Um endpoint de webhook configurado para receber notificações de status de Payout.

***

## Como o sandbox simula rejeições

O Stage não movimenta dinheiro real, mas segue o mesmo fluxo da Produção: a Localpayment recebe a sua requisição, valida a estrutura dela e, se estiver formatada corretamente, define o status como `In Progress` e a encaminha para uma resposta bancária simulada com base nos dados da conta que você enviar. Essa resposta decide se o Payout será aprovado ou rejeitado. Você descobre o resultado da forma habitual: por webhook ou consultando o status da transação.

Qualquer Payout com uma requisição corretamente estruturada é aprovado automaticamente. As contas de teste deste guia são a exceção: cada uma está associada a um motivo de rejeição específico, para que você possa reproduzir essa condição de erro sob demanda, em vez de esperar que ela ocorra naturalmente.

```mermaid theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#31467c', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0c1a29', 'actorBkg': '#31467c', 'actorBorder': '#0c1a29', 'actorTextColor': '#ffffff', 'actorLineColor': '#0c1a29', 'signalColor': '#0c1a29', 'signalTextColor': '#0c1a29', 'labelBoxBkgColor': '#31467c', 'labelBoxBorderColor': '#0c1a29', 'labelTextColor': '#ffffff', 'loopTextColor': '#0c1a29', 'noteBkgColor': '#ffffff', 'noteBorderColor': '#31467c', 'noteTextColor': '#0c1a29'}}}%%
sequenceDiagram
  autonumber
  participant Dev as Seu backend
  participant LP as Localpayment (Stage)
  participant Bank as Resposta simulada do banco

  Dev->>LP: POST /api/payout/ (dados de teste de beneficiary.bank)
  LP->>LP: Valida os campos da requisição
  LP-->>Dev: Resposta: status In Progress
  LP->>Bank: Encaminha o payout
  Bank-->>LP: Aprova, ou rejeita com o código de teste mapeado
  alt Rejeitado
    LP-->>Dev: Webhook: status REJECTED (code / description)
  else Aprovado
    LP-->>Dev: Webhook: status COMPLETED
  end
  Dev->>LP: (ou) GET status do payout
  LP-->>Dev: Status atual
```

1. Você envia um Payout no Stage usando uma das contas de teste das tabelas abaixo.
2. A Localpayment valida a estrutura da requisição e, se ela for válida, define o Payout como `In Progress` enquanto o encaminha para uma resposta bancária simulada.
3. A resposta bancária simulada avalia os dados da conta do beneficiário. Uma conta corretamente estruturada que não corresponda a uma das contas de teste abaixo é aprovada automaticamente. Uma conta de teste é rejeitada com o código associado a ela.
4. A Localpayment notifica você sobre o status final por meio do seu endpoint de webhook, ou você o obtém consultando a transação. Use isso para confirmar que a sua integração reage corretamente a Payouts `REJECTED` sem precisar esperar por uma rejeição bancária real.

> [!NOTE]
>
> Estas contas de teste são exclusivas do Stage. Enviar um Payout para uma dessas contas em Produção não produzirá o mesmo resultado, pois a Produção encaminha para bancos reais.

***

## Códigos de rejeição

Cada conta de teste abaixo retorna um destes cinco resultados. Todos resultam em um Payout `REJECTED` com os `status.code` e `status.description` correspondentes.

| Código | Descrição | Cenário |
| - | - | - |
| `701` | `InvalidAccountNumber` | O número da conta falha na validação de formato ou de dígito verificador. |
| `702` | InvalidAccountNumber - Account Closed | A conta existe em formato, mas está encerrada ou inativa. |
| `703` | InvalidAccountNumber - Account Blocked | A conta existe em formato, mas está bloqueada. |
| `640` | Transaction rejected by AML | A transação é rejeitada pelos controles de AML. |
| `833` | Error account does not accept transfers | A conta ou instituição de destino não aceita transferências recebidas. |

***

## Contas de teste por país

Cada aba lista os dados bancários do beneficiário de um país. Todos os cenários compartilham o mesmo `paymentMethod.code` e, salvo indicação em contrário, o mesmo `beneficiary.bank.code` e `beneficiary.bank.name` desse país. `account.details` é o valor a ser enviado em `beneficiary.bank.account.number` (ou em `beneficiary.bank.account.alias`, quando indicado) para acionar o código de rejeição correspondente. `Description` é o `status.description` que você verá na resposta e no webhook para esse código.

> [tab] Argentina
>
> **Método de pagamento:** COELSA, código `0010` · **Banco:** BANCO DE GALICIA (`007`) · `account.type`: `S` · `account.details` é o CBU
>
> | Código | `account.details` | Descrição |
> | - | - | - |
> | `701` | `0070001600000000000017` | `InvalidAccountNumber` |
> | `702` | `0070001600000000000024` | InvalidAccountNumber - Account Closed |
> | `703` | `0070001600000000000031` | InvalidAccountNumber - Account Blocked |
> | `640` | `0070001600000000000048` | Transaction rejected by AML |
> | `833` | `0070001600000000000055` | Error account does not accept transfers |
>
> `account.type` `C` (conta corrente) também funciona nesses cenários.

> [tab] Bolívia
>
> **Método de pagamento:** código `0020` · Qualquer instituição · `account.type`: `S` · `beneficiary.bank.code` ainda não foi publicado; confirme o valor correto com o seu gerente de conta antes de entrar em produção.
>
> | Código | `account.details` | Descrição |
> | - | - | - |
> | `701` | `00000001` | `InvalidAccountNumber` |
> | `702` | `00000002` | InvalidAccountNumber - Account Closed |
> | `703` | `00000003` | InvalidAccountNumber - Account Blocked |
> | `640` | `00000004` | Transaction rejected by AML |
> | `833` | `00000005` | Error account does not accept transfers |

> [tab] Brasil
>
> **Método de pagamento:** PIX, código `0031`
>
> Os Payouts via PIX identificam o beneficiário por meio de `beneficiary.bank.account.alias` (a chave PIX) em vez de um número de conta bancária. Alguns cenários abaixo usam uma conta bancária padrão, para cobrir também beneficiários de Transferência Bancária.
>
> | Código | `account.details` | Descrição |
> | - | - | - |
> | `701` | `account.alias`: `00100000001` | `InvalidAccountNumber` |
> | `702` | Bank `001` BCO DO BRASIL S.A. · `account.number`: `00001235-0` | InvalidAccountNumber - Account Closed |
> | `703` | Bank `001` BCO DO BRASIL S.A. · `account.number`: `00001234-1`, `account.type`: `S` | InvalidAccountNumber - Account Blocked |
> | `640` | `account.alias`: `rejected.aml@sandbox.br` | Transaction rejected by AML |
> | `833` | `account.alias`: `00100000005` | Error account does not accept transfers |

> [tab] Chile
>
> **Método de pagamento:** código `0050` · **Banco:** BANCO DE CHILE (`001`) · `account.type`: `S`
>
> | Código | `account.details` | Descrição |
> | - | - | - |
> | `701` | `001000000001` | `InvalidAccountNumber` |
> | `702` | `001000000002` | InvalidAccountNumber - Account Closed |
> | `703` | `001000000003` | InvalidAccountNumber - Account Blocked |
> | `640` | `001000000004` | Transaction rejected by AML |
> | `833` | `001000000005` | Error account does not accept transfers |
>
> `account.type` aceita `S` (poupança), `C` (conta corrente) ou `V` (vista).

> [tab] Colômbia
>
> Estes cenários de teste usam a rede ACH (código `0060`). Qualquer instituição aceita estes valores de teste. `account.type`: `S`.
>
> | Código | `account.details` | Descrição |
> | - | - | - |
> | `701` | `000000001` | `InvalidAccountNumber` |
> | `702` | `000000002` | InvalidAccountNumber - Account Closed |
> | `703` | `000000003` | InvalidAccountNumber - Account Blocked |
> | `640` | `000000004` | Transaction rejected by AML |
>
> Este cenário usa o Bre-B (código `0062`). `account.type`: `P`.
>
> | Código | `account.details` | Descrição |
> | - | - | - |
> | `833` | `+573000000005` | Error account does not accept transfers |

> [tab] Costa Rica
>
> **Método de pagamento:** código `0070` · **Banco:** BANCO DE COSTA RICA (`0152`) · `account.type`: `S` · `account.details` é o IBAN (22 caracteres)
>
> | Código | `account.details` | Descrição |
> | - | - | - |
> | `701` | `CR38015200000000000001` | `InvalidAccountNumber` |
> | `702` | `CR11015200000000000002` | InvalidAccountNumber - Account Closed |
> | `703` | `CR81015200000000000003` | InvalidAccountNumber - Account Blocked |
> | `640` | `CR54015200000000000004` | Transaction rejected by AML |
> | `833` | `CR27015200000000000005` | Error account does not accept transfers |

> [tab] República Dominicana
>
> **Método de pagamento:** código `0080` · **Banco:** BANCO BHD (`101012308`) · `account.details` é o IBAN (28 caracteres)
>
> | Código | `account.details` | Descrição |
> | - | - | - |
> | `701` | `DO13BAGR00000000000000000001` | `InvalidAccountNumber` |
> | `702` | `DO83BAGR00000000000000000002` | InvalidAccountNumber - Account Closed |
> | `703` | `DO56BAGR00000000000000000003` | InvalidAccountNumber - Account Blocked |
> | `640` | `DO29BAGR00000000000000000004` | Transaction rejected by AML |
> | `833` | `DO02BAGR00000000000000000005` | Error account does not accept transfers |

> [tab] El Salvador
>
> **Método de pagamento:** código `0100` · Qualquer instituição · `account.type`: `S` · `account.details` é o IBAN (28 caracteres)
>
> | Código | `account.details` | Descrição |
> | - | - | - |
> | `701` | `SV50ACAT00000000000000000001` | `InvalidAccountNumber` |
> | `702` | `SV23ACAT00000000000000000002` | InvalidAccountNumber - Account Closed |
> | `703` | `SV93ACAT00000000000000000003` | InvalidAccountNumber - Account Blocked |
> | `640` | `SV66ACAT00000000000000000004` | Transaction rejected by AML |
> | `833` | `SV39ACAT00000000000000000005` | Error account does not accept transfers |

> [tab] Guatemala
>
> **Método de pagamento:** código `0110` · Qualquer instituição · `account.type`: `S` · `beneficiary.bank.code` ainda não foi publicado; confirme o valor correto com o seu gerente de conta antes de entrar em produção.
>
> | Código | `account.details` | Descrição |
> | - | - | - |
> | `701` | `0000000001` | `InvalidAccountNumber` |
> | `702` | `0000000002` | InvalidAccountNumber - Account Closed |
> | `703` | `0000000003` | InvalidAccountNumber - Account Blocked |
> | `640` | `0000000004` | Transaction rejected by AML |
> | `833` | `0000000005` | Error account does not accept transfers |

> [tab] Honduras
>
> **Método de pagamento:** código `0120` · Qualquer instituição · `account.type`: `S` · `beneficiary.bank.code` ainda não foi publicado; confirme o valor correto com o seu gerente de conta antes de entrar em produção.
>
> | Código | `account.details` | Descrição |
> | - | - | - |
> | `701` | `00000000001` | `InvalidAccountNumber` |
> | `702` | `00000000002` | InvalidAccountNumber - Account Closed |
> | `703` | `00000000003` | InvalidAccountNumber - Account Blocked |
> | `640` | `00000000004` | Transaction rejected by AML |
> | `833` | `00000000005` | Error account does not accept transfers |

> [tab] México
>
> **Método de pagamento:** SPEI, código `0130` · **Banco:** BANAMEX (`002`) · `account.details` é o CLABE (18 dígitos)
>
> | Código | `account.details` | Descrição |
> | - | - | - |
> | `701` | `002180000000000012` | `InvalidAccountNumber` |
> | `702` | `002180000000000025` | InvalidAccountNumber - Account Closed |
> | `703` | `002180000000000030` | InvalidAccountNumber - Account Blocked |
> | `640` | `002180000000000041` | Transaction rejected by AML |
> | `833` | `002180000000000054` | Error account does not accept transfers |

> [tab] Panamá
>
> **Método de pagamento:** código `0150` · Qualquer instituição · `account.type`: `S` · `beneficiary.bank.code` ainda não foi publicado; confirme o valor correto com o seu gerente de conta antes de entrar em produção.
>
> | Código | `account.details` | Descrição |
> | - | - | - |
> | `701` | `000000000001` | `InvalidAccountNumber` |
> | `702` | `000000000002` | InvalidAccountNumber - Account Closed |
> | `703` | `000000000003` | InvalidAccountNumber - Account Blocked |
> | `640` | `000000000004` | Transaction rejected by AML |
> | `833` | `000000000005` | Error account does not accept transfers |

> [tab] Paraguai
>
> **Método de pagamento:** código `0160` · Qualquer instituição · `account.type`: `S` · `beneficiary.bank.code` ainda não foi publicado; confirme o valor correto com o seu gerente de conta antes de entrar em produção.
>
> | Código | `account.details` | Descrição |
> | - | - | - |
> | `701` | `000000000001` | `InvalidAccountNumber` |
> | `702` | `000000000002` | InvalidAccountNumber - Account Closed |
> | `703` | `000000000003` | InvalidAccountNumber - Account Blocked |
> | `640` | `000000000004` | Transaction rejected by AML |
> | `833` | `000000000005` | Error account does not accept transfers |

> [tab] Peru
>
> **Método de pagamento:** código `0170` · **Banco:** Interbank (`003`) · `account.type`: `S` · `account.details` é o CCI (20 dígitos)
>
> | Código | `account.details` | Descrição |
> | - | - | - |
> | `701` | `00300029183746555075` | `InvalidAccountNumber` |
> | `702` | `00300047392810555078` | InvalidAccountNumber - Account Closed |
> | `703` | `00300091827364777776` | InvalidAccountNumber - Account Blocked |
> | `640` | `00300053748291777777` | Transaction rejected by AML |
> | `833` | `00300062839471777776` | Error account does not accept transfers |

***

## Referência de mapeamento de campos

As contas de teste acima preenchem o objeto padrão `beneficiary.bank` de [Create a Payout](https://docs.localpayment.com/pt-br/reference/create-a-payout.md):

| Campo | Notas |
| - | - |
| `beneficiary.bank.code` | Obrigatório para Argentina, Chile, Colômbia (ACH) e Peru. Não obrigatório para o México (a CLABE já codifica o banco) nem para o PIX do Brasil. |
| `beneficiary.bank.account.number` | Obrigatório na maioria dos países. Omita-o quando você enviar em `account.alias` uma chave PIX (Brasil), Peru (Yape), Bolívia (Yape) ou Colômbia (Bre-B). |
| `beneficiary.bank.account.type` | `S` (poupança), `C` (conta corrente) ou `V` (vista, somente Chile). Obrigatório para Argentina, Chile, Colômbia e Peru. Não é usado com uma chave PIX (Brasil), Peru (Yape), Bolívia (Yape) ou Colômbia (Bre-B). |
| `beneficiary.bank.account.alias` | Usado para uma chave PIX (Brasil), Peru (Yape), Bolívia (Yape) e Colômbia (Bre-B). |

Números de conta que passam na validação de dígito verificador (CLABE do México, CBU da Argentina e os formatos de IBAN usados por Costa Rica, República Dominicana e El Salvador) são valores de teste estruturalmente válidos, não contas reais. Eles existem apenas para alcançar o cenário de rejeição associado.

***

## Próximos passos

> [card] [Enviar fundos por transferência bancária](https://docs.localpayment.com/pt-br/docs/send-funds-via-bank-transfer.md)
>
> Referência completa da API para criar Payouts por Transferência Bancária, incluindo requisitos específicos de cada país.

> [card] [Devoluções e Recalls](https://docs.localpayment.com/pt-br/docs/returns-and-recalls.md)
>
> Entenda o que acontece quando um Payout é rejeitado ou devolvido após a conclusão em Produção.


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