Saques

Use a API de saques para retirar valores da conta Raims por Pix e acompanhar o envio para a conta da empresa. As consultas ajudam a planejar a retirada e conferir o valor recebido no destino.

Consultar condições e limites

Use Consultar condições de saque, com GET /v1/withdrawals/limits, antes de solicitar uma retirada.

A resposta informa o saldo disponível, o valor mínimo por saque e a tarifa para valores abaixo do limite indicado. A tarifa é descontada do valor solicitado. Os valores monetários usam centavos de real.

Em Produção, destination_configured informa se existe um destino cadastrado. O objeto limits apresenta os limites diário e noturno, o limite do período atual, quanto já foi utilizado e quanto resta. O teto informado para uma solicitação considera os limites de saque; o valor solicitado também precisa caber no saldo disponível e respeitar a tarifa.

O período diário começa às 06:00 e termina às 06:00 do dia seguinte, pelo horário de São Paulo. Das 20:00 às 06:00, o saque também precisa caber no limite noturno, que faz parte do diário. period identifica o período atual e period_ends_at informa seu término em segundos Unix UTC. Saques em processamento comprometem o limite; uma falha confirmada libera o valor.

Essa consulta não reserva dinheiro ou limite nem garante que uma solicitação será aceita. Outros saques podem alterar as condições entre a consulta e o pedido. Os limites consideram os saques registrados na Raims; transferências feitas por outro canal na mesma conta também podem afetar o valor aceito.

No Sandbox, a resposta apresenta o saldo simulado e as regras de mínimo e tarifa. destination_configured retorna false e limits retorna null. Esses campos não informam o destino nem os limites da conta de Produção. Em Produção, limits também pode retornar null quando não houver limites disponíveis para consulta. Isso não significa que a conta pode sacar sem limite.

Consultar os destinos de saque

Use Listar destinos de saque para conferir as chaves Pix verificadas da própria empresa. Cada destino informa o nome do titular, o ISPB da instituição, o tipo e a chave mascarada. is_default identifica o destino padrão atual; verified_at informa a data da verificação em segundos Unix UTC.

A listagem exige uma chave de API de Produção. O Sandbox retorna 403 DATA_ENVIRONMENT_NOT_SUPPORTED, pois não tem destinos bancários. O console desta documentação aceita somente chaves Sandbox; faça a consulta pelo servidor da integração, sem inserir uma chave de Produção no navegador.

Comece sem cursor, processe list e copie page.next_after para after enquanto page.has_next for verdadeiro. Uma página pode ter menos itens que page_size ou estar vazia e ainda indicar outra página. Continue pelo cursor até has_next ser false; não use o tamanho de list para concluir a navegação. Para voltar, copie page.previous_before para before, sem enviar os dois cursores juntos. Consulte Listagem e paginação.

Para conferir um destino específico, use Recuperar um destino de saque e o id completo recebido, com prefixo wdst_. Esse identificador pertence ao destino, enquanto wd_ identifica uma solicitação de saque. Um destino removido ou que não esteja mais disponível para a empresa retorna a mesma resposta de recurso não encontrado.

Consultar um destino não o seleciona nem solicita uma transferência. Para cadastrar uma chave, removê-la ou trocar o padrão, use

Conta, Configurações, Chave Pix de saque.

A solicitação pela API usa o padrão disponível naquele momento, não um ID enviado por quem solicita. Confira também as condições e os limites antes de pedir o saque. O destino pode mudar depois da consulta, e sua presença na lista não garante que a retirada será aceita.

Solicitar um saque Pix

Use Solicitar saque, com POST /v1/withdrawals, e informe amount_cents com o valor total que deseja retirar, incluindo a tarifa. A requisição exige uma chave de API de Produção.

O destino é a chave Pix padrão cadastrada em

Conta, Configurações, Chave Pix de saque. A chave deve pertencer ao mesmo CNPJ da empresa. A Raims confere a titularidade ao cadastrar o destino e ao solicitar o saque. A API não recebe ou altera a chave Pix de destino. Para cadastrar ou trocar essa chave, use o Dashboard antes de solicitar.

A solicitação está sujeita à disponibilidade da conta para saques, ao saldo disponível, ao valor mínimo e aos limites aplicáveis. Ter uma chave de API válida não elimina essas condições.

A resposta 202 informa que o saque ainda precisa ser acompanhado. Guarde o id retornado e consulte GET /v1/withdrawals/{id}. Enquanto o saque estiver pendente, em processamento ou com resultado desconhecido, acompanhe esse mesmo identificador antes de solicitar outra retirada. A resposta 200 pode apresentar o resultado já encerrado de uma solicitação repetida.

Se a resposta informar PIX_WITHDRAWAL_RESULT_UNKNOWN, use o caminho retornado no header Location para consultar o saque antes de solicitar outra retirada. Para falta de saldo ou limite, consulte novamente as condições. Quando o erro indicar um destino ausente ou alterado, confira a chave Pix padrão no Dashboard.

Para conferir o fluxo pelo Dashboard, consulte Saques por Pix.

Saque automático

Use Consultar saque automático para ler a configuração e Atualizar saque automático para ativar, desativar ou ajustar a tentativa diária. Os dois endpoints exigem uma chave de API de Produção. A integração usa a autenticação normal da chave, sem código de confirmação (OTP) ou sessão do Dashboard.

O saque automático usa o destino próprio selecionado no Dashboard. Cadastre e verifique a chave Pix da empresa antes de ativar a configuração. A API não recebe outra chave Pix nem muda o destino da retirada.

Envie enabled: true para ativar e enabled: false para desativar. minimum_amount_cents é o saldo mínimo que permite a tentativa, em centavos de real. Esse campo não fixa o valor de cada saque: a tentativa considera o saldo disponível e o limite Pix restante. Se o limite permitir retirar apenas parte do saldo, o restante continua na conta.

time define o horário diário em HH:mm, pelo fuso de São Paulo. Por exemplo, 18:30 representa 18h30 em São Paulo. Omitir um campo preserva seu valor atual; null não é aceito. Enviar novamente os mesmos valores mantém a configuração e a próxima tentativa prevista.

Salvar a configuração não solicita um saque imediato. next_execution_at informa a próxima tentativa prevista em segundos Unix UTC, ou null quando não houver uma programada. Esse horário não confirma uma retirada. Desativar o saque automático impede novas tentativas; acompanhe no histórico os saques que já tiverem sido solicitados.

A tentativa depende de a conta estar apta para sacar e de o destino continuar válido. O saldo disponível precisa alcançar o mínimo configurado, e o limite restante precisa permitir pelo menos o valor mínimo de um saque. Se uma dessas condições não for atendida, não há retirada naquela tentativa. As mesmas regras de tarifa e limites dos saques manuais se aplicam.

Acompanhe os pedidos gerados em Listar saques e confira seu status. Configuração ativa ou próxima tentativa informada não comprovam transferência concluída. Para os passos no Dashboard, consulte Saques automáticos.

Consultar o histórico de saques

Use Listar saques, com GET /v1/withdrawals. Você pode filtrar pela situação e pelo intervalo da solicitação. As datas requested_gte e requested_lte usam segundos Unix UTC e incluem os instantes informados. Por padrão, os saques mais recentes aparecem primeiro.

A resposta usa list e page. Comece sem cursor, processe list e copie page.next_after para after enquanto page.has_next for verdadeiro. Mantenha os filtros, a ordenação e a mesma chave durante a navegação. Para mudar a consulta, comece novamente sem cursor.

Para voltar, use page.previous_before em before. Copie o cursor inteiro, sem interpretar ou alterar seu conteúdo, e não envie os dois cursores juntos. Veja Listagem e paginação.

Recuperar um saque pelo ID

Use Recuperar um saque, com GET /v1/withdrawals/{id}. Informe o id completo, com prefixo wd_, recebido na listagem.

No Extrato, um lançamento com reference_type: 3 pode informar esse identificador em reference_id. Use-o para consultar o saque relacionado e conferir seu resultado. O ID do saque é diferente do ID do lançamento, que usa o prefixo st_.

Valores e destino

Os valores usam centavos de real:

Por exemplo, um saque com amount_cents: 10000 e fee_amount_cents: 100 tem net_amount_cents: 9900, equivalentes a R$ 99,00 para o destino. Esses valores não confirmam a transferência. Considere o saque concluído somente quando status for COMPLETED; falha ou cancelamento não comprovam recebimento nem cobrança da tarifa.

pix_destination identifica o destino Pix disponível, com a chave mascarada. bank_account apresenta os dados disponíveis de uma conta bancária usada no saque, também com o número da conta mascarado. Esses campos ficam null quando não houver dados daquele tipo de destino. Consultar o histórico não permite mudar o destino cadastrado.

Acompanhar a situação do saque

Confira status antes de considerar o saque concluído:

requested_at informa quando o saque foi solicitado. As datas de conclusão, falha e cancelamento ficam null enquanto o respectivo resultado não estiver registrado. Todas usam segundos Unix UTC.

Quando houver falha, failure_reason informa um código público e uma mensagem em inglês. Use o código no tratamento da integração. A mensagem serve ao diagnóstico; não é necessário compará-la literalmente. Consulte Motivos de falha do saque para entender cada código e a conferência indicada antes de outra solicitação.

Consultas repetidas não iniciam nem aceleram o saque. Um registro pendente ou em processamento não comprova que o dinheiro chegou à conta de destino.

Empresa e ambiente

As requisições exigem uma chave de API e usam a empresa e o ambiente vinculados a ela. Uma chave Sandbox não acessa saques de Produção. Se não houver saques no ambiente consultado, a listagem retorna list vazia. A solicitação de saque está disponível somente em Produção; uma chave Sandbox permite consultar o histórico simulado e as condições de teste, mas não solicitar uma transferência.

O console desta documentação aceita somente chaves Sandbox. A consulta individual devolve a mesma resposta de recurso não encontrado quando o ID não existe ou não pertence à empresa e ao ambiente da chave.