Pagamentos via arquivo (PayOut)

Bem-vindo ao guia de Pagamentos via Arquivo da Orkestral.

Siga as instruções abaixo para preparar, validar e enviar arquivos contendo múltiplos pagamentos de saída (PayOuts) por PIX ou transferência bancária.

Objetivo

Orientar os clientes sobre como realizar pagamentos em lote por meio do portal da Orkestral, incluindo:

• preparação do arquivo;
• utilização dos modelos disponibilizados;
• envio pelo portal;
• correção dos erros de validação;
• acompanhamento das transações processadas.

Visão geral

A funcionalidade Pagamentos via Arquivo permite enviar vários PayOuts em uma única operação.

Cada linha do arquivo representa um pagamento independente. Após o envio:

• a Orkestral valida a estrutura e o conteúdo de todas as linhas;
• o arquivo válido é aceito para processamento;
• cada linha é transformada em uma transação PayOut;
• o pagamento é enviado ao PSP informado na linha;
• o resultado pode ser acompanhado no Relatório de Transações.

Estão disponíveis dois modelos:

• PIX;
• Transferência Bancária.

:::warning Importante

A mensagem “Arquivo enviado com sucesso!” confirma que o arquivo foi validado e aceito. Ela não significa que todos os pagamentos já foram concluídos.

:::

Antes de começar

Para utilizar a funcionalidade, é necessário:

• possuir uma conta ativa na Orkestral;
• estar vinculado ao merchant responsável pelos pagamentos;
• ter acesso ao menu Relatórios > Upload de payout;
• possuir um PSP de PayOut contratado, ativo e com credenciais válidas;
• possuir saldo e limites disponíveis no PSP;
• ter os dados corretos dos beneficiários;
• utilizar o modelo correspondente ao tipo de pagamento.

O PSP e a moeda informados no arquivo devem estar habilitados para o merchant.

Formatos e limites

Característica	Regra
Formatos aceitos	.csv, .xls e .xlsx
Tamanho	Menor que 15 MB
Arquivos por envio	Um arquivo
Tipos de pagamento	PIX ou transferência bancária
Cabeçalho	Deve estar na primeira linha
Conteúdo mínimo	Cabeçalho e pelo menos uma linha de pagamento
Arquivos Excel	Somente a primeira planilha é processada
Arquivos CSV	Devem utilizar vírgula como separador

Para arquivos CSV, recomenda-se utilizar a codificação UTF-8.

A plataforma não apresenta um limite público de linhas. Para cargas muito grandes, consulte a Orkestral sobre o volume recomendado.

Regras importantes

• Utilize o modelo disponível na própria tela.
• Não renomeie, remova, acrescente ou reordene as colunas.
• Não misture pagamentos PIX e transferências bancárias no mesmo arquivo.
• Não deixe linhas vazias entre os pagamentos.
• Não utilize células mescladas.
• Não utilize fórmulas nas células.
• Não envie arquivos protegidos por senha ou criptografados.
• Preencha os valores como números inteiros, sem símbolos monetários ou separadores.
• Mantenha documentos, contas e chaves sem formatação quando o modelo exigir somente números.
• Não inclua senhas, tokens ou outras credenciais no arquivo.

Baixar o modelo

1. Acesse a plataforma da Orkestral.
2. No menu lateral, abra Relatórios.
3. Clique em Upload de payout.
4. Localize a orientação exibida no início da página.
5. Clique em:
   • modelo de PIX; ou
   • modelo de transferência bancária.
6. Salve uma cópia do modelo.
7. Preencha somente as linhas destinadas aos pagamentos.

O modelo disponibilizado pela plataforma deve ser utilizado como referência principal para o layout.

Arquivo de PIX

O arquivo de PIX deve possuir exatamente o seguinte cabeçalho:

AMOUNT,CURRENCY,NAME,LAST NAME,DOCUMENT,DOCUMENT TYPE,PIX KEY,PSP

Colunas do arquivo de PIX

Coluna	Obrigatória	Descrição
AMOUNT	Sim	Valor do pagamento em centavos, como número inteiro e maior que zero. Por exemplo, 1000 representa R$ 10,00
CURRENCY	Sim	Código da moeda em letras maiúsculas. No fluxo PIX atual, utilize BRL
NAME	Sim	Nome do beneficiário
LAST NAME	Sim	Sobrenome do beneficiário
DOCUMENT	Sim	Documento do beneficiário contendo somente números
DOCUMENT TYPE	Sim	Tipo de documento habilitado para a integração. O fluxo atualmente confirmado utiliza CPF
PIX KEY	Sim	Chave PIX do beneficiário
PSP	Sim	PSP responsável pelo pagamento. No fluxo PIX atual, utilize WEPAYMENTS

A chave PIX deve estar ativa e ser reconhecida pelo PSP. O formato da chave pode variar entre documento, telefone, email ou chave aleatória.

Exemplo de PIX

AMOUNT,CURRENCY,NAME,LAST NAME,DOCUMENT,DOCUMENT TYPE,PIX KEY,PSP
1000,BRL,Joao,Silva,51584112808,CPF,42362893855,WEPAYMENTS

O exemplo é apenas ilustrativo. Utilize dados válidos do beneficiário e as configurações disponibilizadas para seu merchant.

Arquivo de Transferência Bancária

O arquivo de transferência bancária deve possuir exatamente o seguinte cabeçalho:

AMOUNT,CURRENCY,NAME,LAST NAME,EMAIL,DATE OF BIRTH,DOCUMENT,DOCUMENT TYPE,BANK NAME,BANK CODE,AGENCY CODE,AGENCY DIGIT,ACCOUNT NUMBER,ACCOUNT DIGIT,ACCOUNT TYPE,PSP

Colunas do arquivo de transferência

Coluna	Obrigatória	Descrição
AMOUNT	Sim	Valor do pagamento em centavos, como número inteiro e maior que zero
CURRENCY	Sim	Código da moeda habilitada para o PSP, em letras maiúsculas. Exemplo: COP
NAME	Sim	Nome do beneficiário
LAST NAME	Sim	Sobrenome do beneficiário
EMAIL	Sim	Email válido do beneficiário
DATE OF BIRTH	Sim	Data de nascimento do beneficiário
DOCUMENT	Sim	Número do documento do beneficiário
DOCUMENT TYPE	Sim	Tipo de documento aceito pelo PSP e pelo país da operação. Exemplos atualmente confirmados: CC, TI, DNI e CI
BANK NAME	Sim	Nome do banco conforme o catálogo aceito pela Orkestral
BANK CODE	Sim	Código numérico do banco
AGENCY CODE	Sim	Código numérico da agência
AGENCY DIGIT	Sim	Dígito numérico da agência
ACCOUNT NUMBER	Sim	Número da conta do beneficiário
ACCOUNT DIGIT	Sim	Dígito numérico da conta
ACCOUNT TYPE	Sim	Tipo da conta de acordo com o PSP
PSP	Sim	PSP responsável pelo pagamento. Utilize o PSP configurado para o merchant, como KUSHKI ou PAYVALIDA

Formatos de data aceitos

O campo DATE OF BIRTH aceita:

• dd/MM/yyyy, por exemplo 25/10/1990;
• yyyy-MM-dd, por exemplo 1990-10-25;
• yyyyMMdd, por exemplo 19901025;
• data nativa do Excel.

Tipos de conta

Os valores variam de acordo com o PSP.

Para Kushki, podem ser utilizados:

• CC;
• CA;
• CB;
• TD;
• NC;
• CV;
• DE;
• CM.

Para Payvalida, podem ser utilizados:

• AHORRO;
• CORRIENTE;
• MONETARIA.

Utilize somente um tipo de conta compatível com o PSP, o país e o banco do beneficiário.

Exemplo de transferência bancária

AMOUNT,CURRENCY,NAME,LAST NAME,EMAIL,DATE OF BIRTH,DOCUMENT,DOCUMENT TYPE,BANK NAME,BANK CODE,AGENCY CODE,AGENCY DIGIT,ACCOUNT NUMBER,ACCOUNT DIGIT,ACCOUNT TYPE,PSP
1000,COP,Ana,Souza,ana.souza@example.com,1990-10-25,43750860,CC,BANCO DE OCCIDENTE,1,1,7,987654321,0,CORRIENTE,PAYVALIDA

O exemplo é apenas ilustrativo. Os dados bancários, o tipo de conta, a moeda e o PSP devem corresponder à configuração do merchant.

Enviar o arquivo

1. Acesse a plataforma da Orkestral.
2. No menu lateral, abra Relatórios.
3. Clique em Upload de payout.
4. Em Selecione o tipo de transação, escolha:
   • PIX; ou
   • Transferência Bancária.
5. Arraste o arquivo para a área indicada ou clique para selecioná-lo.
6. Confirme se o nome do arquivo foi apresentado.
7. Clique em Importar.
8. Aguarde a validação.

observação

A plataforma identifica o tipo de pagamento pelo cabeçalho do arquivo. Portanto, selecionar uma aba não corrige um arquivo preenchido com o modelo incorreto.

Validação do arquivo

Antes de aceitar o arquivo, a Orkestral valida todas as linhas.

Se houver qualquer erro de estrutura ou preenchimento:

• o arquivo inteiro será rejeitado;
• nenhum pagamento será colocado na fila;
• os erros serão agrupados por categoria;
• a tela mostrará as células que precisam ser corrigidas.

Uma referência como A2 indica:

• coluna A;
• linha 2.

Após corrigir o arquivo, clique em Voltar, selecione-o novamente e realize um novo envio.

Erros estruturais

Mensagem	Possível causa	Como corrigir
Escolha um arquivo para fazer o upload	Nenhum arquivo foi selecionado	Selecione um arquivo antes de clicar em Importar
O arquivo deve ser menor que 15 MB	Arquivo acima do limite	Divida o conteúdo em arquivos menores
Este arquivo não possui conteúdo	Arquivo vazio ou sem pagamentos	Inclua o cabeçalho e pelo menos uma linha
Arquivo inválido. Use o arquivo de modelo como base	Cabeçalho incorreto ou estrutura incompatível	Crie uma nova cópia a partir do modelo
Colunas obrigatórias estão faltando	Uma ou mais colunas foram removidas	Restaure todas as colunas do modelo
Formato não suportado	Extensão diferente de CSV, XLS ou XLSX	Salve o arquivo em um formato permitido

Erros de preenchimento

Código técnico	Mensagem apresentada	Como corrigir
INVALID_NUMBER	Número inválido	Informe somente um valor numérico válido
BLANK_STRING	Célula vazia	Preencha o campo obrigatório
INVALID_CURRENCY	Moeda incorreta	Utilize a moeda habilitada para o PSP
INVALID_NUMBER_OR_BLANK_STRING	Número inválido ou célula vazia	Preencha o campo sem caracteres incompatíveis
INVALID_PSP	PSP errado	Utilize o nome do PSP configurado
INVALID_EMAIL	Email inválido	Corrija o formato do email
INVALID_DATE_OF_BIRTH	Data de nascimento inválida	Utilize um dos formatos aceitos
INVALID_ACCOUNT_TYPE	Tipo de conta inválido	Utilize um tipo compatível com o PSP
INVALID_BANK	Banco inválido	Utilize o nome do banco reconhecido pela plataforma
INVALID_DOCUMENT_TYPE	Tipo de documento inválido	Utilize um tipo compatível com o país e o PSP
FILE_ERROR	Erro no arquivo enviado	Verifique a quantidade, a ordem e o conteúdo das colunas

Processamento dos pagamentos

Depois que o arquivo é aceito, o processamento ocorre de forma assíncrona:

Arquivo enviado
      ↓
Validação completa
      ↓
Arquivo aceito para processamento
      ↓
Criação de um PayOut por linha
      ↓
Envio ao PSP indicado
      ↓
Atualização no Relatório de Transações

Cada linha recebe um identificador de transação próprio.

O PSP informado na coluna PSP é utilizado diretamente. Esse fluxo não utiliza o Fluxo de Pagamento para escolher outro provedor e não possui fallback automático entre PSPs.

Uma falha em uma linha não impede necessariamente o processamento das demais. Por isso, um arquivo pode produzir pagamentos concluídos e pagamentos com erro.

Acompanhar os pagamentos

Após a aceitação do arquivo, a plataforma redireciona o usuário para o Relatório de Transações.

Para acompanhar os pagamentos:

1. Acesse Relatórios > Transações.
2. No filtro Tipo da transação, selecione PayOut.
3. Utilize data, PSP, moeda ou status para localizar as transações.
4. Abra os detalhes de cada pagamento.

Status de PayOut

Situação	Significado
Processando	O PSP recebeu a solicitação, mas o resultado final ainda está pendente
Completo	O pagamento foi liquidado. O estado detalhado pode ser apresentado como Sacado
Falhado	O pagamento foi negado ou ocorreu um erro durante o processamento

O status pode ser atualizado posteriormente pelo PSP.

informação

Atualmente, o portal não apresenta um identificador de lote nem uma tela pública com o status geral do arquivo. O acompanhamento é realizado pelas transações individuais.

Correção e reenvio

Arquivo rejeitado durante a validação

Se o arquivo não apresentar a mensagem de envio bem-sucedido:

1. Corrija todas as células indicadas.
2. Salve o arquivo.
3. Volte à tela de upload.
4. Envie novamente o arquivo completo.

Como o arquivo foi rejeitado, nenhum PayOut foi colocado na fila.

Arquivo já aceito

perigo

Não envie novamente o arquivo completo sem antes consultar o Relatório de Transações. Um novo envio gera novos identificadores e pode duplicar pagamentos que já foram executados.

Se apenas algumas linhas falharem:

1. Identifique as transações já criadas.
2. Confirme quais pagamentos não foram concluídos.
3. Crie um novo arquivo contendo somente os pagamentos que realmente precisam de uma nova tentativa.
4. Em caso de dúvida, acione o suporte da Orkestral antes do reenvio.

Boas práticas de segurança

Os arquivos podem conter documentos e dados bancários dos beneficiários.

• Restrinja o acesso aos arquivos.
• Não envie os arquivos por canais públicos ou não autorizados.
• Não inclua dados bancários em logs.
• Não inclua senhas, tokens ou credenciais do PSP.
• Armazene os arquivos somente pelo período necessário.
• Exclua cópias locais quando não forem mais necessárias.
• Confirme a origem e a integridade dos dados antes do envio.
• Utilize apenas dispositivos e redes confiáveis.
• Mantenha os procedimentos alinhados às regras de proteção de dados aplicáveis.

Perguntas frequentes

A mensagem “Arquivo enviado com sucesso” significa que todos os pagamentos foram concluídos?

Não. Ela confirma que o arquivo foi validado e aceito. Os pagamentos são processados posteriormente.

Posso misturar PIX e transferência bancária no mesmo arquivo?

Não. Utilize um arquivo e um modelo para cada tipo de pagamento.

Posso alterar a ordem ou o nome das colunas?

Não. O cabeçalho deve permanecer exatamente igual ao modelo.

Posso reenviar um arquivo aceito?

Somente depois de confirmar quais transações já foram criadas. O reenvio integral pode gerar pagamentos duplicados.

Onde acompanho o resultado?

Em Relatórios > Transações, utilizando o filtro PayOut.