Criar depósito

POST /api/v1/valepix/deposits

Gera uma cobrança PIX ou BOLETO para adicionar saldo à integração autorizada.

Autenticação

Envie um API token ativo no header Authorization.

Authorization: Bearer <VALEPIX_API_TOKEN>
Accept: application/json
Content-Type: application/json

Path params

Esta rota não possui path params.

Body

Campo	Tipo	Obrigatório	Descrição
amount	integer	Sim	Valor do depósito em centavos, maior que zero
method	string	Sim	PIX ou BOLETO
name	string	Não	Nome do pagador; quando omitido, a API usa os dados cadastrados da empresa
document	string	Não	Documento do pagador; quando omitido, a API usa os dados cadastrados da empresa
due_date	string	Não	Data e hora de vencimento no formato ISO 8601
transaction_id	string	Não	UUID definido previamente pela integração para identificar a transação

Exemplo curl

curl --request POST \
  --url "https://routes.valepix.com.br/api/v1/valepix/deposits" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "amount": 100000,
    "method": "PIX",
    "name": "Empresa Exemplo",
    "document": "12345678000190",
    "transaction_id": "00000000-0000-4000-8000-000000000501"
  }'

Response

HTTP 201 Created.

{
  "success": "success",
  "data": {
    "transaction_id": "00000000-0000-4000-8000-000000000501",
    "status": "PENDING",
    "amount": 100000,
    "description": "Depósito",
    "fee_amount": 250,
    "payment_info": {
      "amount": 100250,
      "pix_copy_paste": "codigo_pix_retornado",
      "pix_qr_code_url": "https://exemplo.test/qr-code",
      "expiration_date": "2026-07-24T23:59:59Z"
    }
  }
}

Guarde o transaction_id e consulte o pagamento em Consultar depósito.

amount é o valor líquido que será adicionado ao saldo, fee_amount é a taxa da operação e payment_info.amount é o total da cobrança.

Validações importantes

• amount deve ser um número inteiro em centavos maior que zero.
• method aceita PIX ou BOLETO.
• Quando informado, transaction_id deve estar no formato UUID. O campo define previamente o identificador da transação.
• Quando due_date é omitido, a API define a expiração da cobrança.
• O status inicial costuma ser PENDING; o estado muda conforme o processamento do pagamento.
• Para BOLETO, o cadastro da empresa precisa conter os dados necessários para emissão.

Erros comuns

HTTP	Quando acontece	Ação recomendada
400	Body ou formato de campo inválido	Corrigir os dados enviados
401	Token ausente, inválido, expirado ou revogado	Conferir o header Authorization
403	Token sem acesso ao recurso solicitado	Confirmar token com a ValePix
422	Valor não positivo, UUID inválido ou configuração necessária indisponível	Corrigir os dados ou a configuração da empresa
429	Limite de chamadas excedido	Reduzir a taxa de chamadas e aplicar backoff
500, 502, 503, 504	Falha temporária ao processar a cobrança	Tentar novamente com backoff e acionar suporte se persistir