Criar Transferência

Solicita um saque (cashout) do seu saldo disponível para uma chave PIX.

Autenticação

Este endpoint requer autenticação via API Keys:

X-Api-Public-Key

string

required

Sua chave pública da API

X-Api-Private-Key

string

required

Sua chave privada da API

Parâmetros do Body

amount

number

required

Valor do cashout em reais (ex: 100.50 = R

100,50). **Mínimo: R

100,00**. Máximo: R$ 100.000,00

pixKey

string

required

Chave PIX para recebimento (entre 8 e 77 caracteres)

pixKeyType

string

Tipo da chave PIX. Valores possíveis: CPF, CNPJ, EMAIL, PHONE, RANDOM. Padrão: CPF

O valor mínimo para transferência é R$ 100,00. Valores abaixo deste mínimo retornarão erro TRANSFER_NOT_ALLOWED.

Exemplo de Requisição

curl -X POST https://api.nextpagamentos.io/api/public/cashout \
  -H "X-Api-Public-Key: sua_chave_publica_aqui" \
  -H "X-Api-Private-Key: sua_chave_privada_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "pixKey": "11999999999",
    "pixKeyType": "PHONE"
  }'

Resposta de Sucesso

integer

ID do cashout

amount

string

Valor em reais

pixKey

string

Chave PIX

status

string

Status do cashout (PENDING, PROCESSING, etc.)

createdAt

string

Data de criação (ISO 8601)

Exemplo de Resposta

{
  "id": 12345,
  "amount": "100.00",
  "netAmount": "95.00",
  "pixKey": "11999999999",
  "pixKeyType": "PHONE",
  "status": "PENDING",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "fees": {
    "fixed": "2.00",
    "variable": "3.00",
    "total": "5.00"
  }
}

netAmount

string

Valor líquido após taxas em reais

pixKeyType

string

Tipo da chave PIX utilizada

fees

object

Detalhamento das taxas cobradas

fees.fixed

string

Taxa fixa em reais

fees.variable

string

Taxa variável em reais

fees.total

string

Total de taxas em reais

Configuração de Webhooks

Para receber notificações automáticas sobre mudanças de status dos saques, você precisa configurar um webhook no painel do usuário.

Como Configurar

Acesse o painel do NextPay Gateway
Vá em Menu lateral > Integrações > Adicionar Webhook
Configure a URL do seu webhook (ex: https://seusite.com/webhook/cashout)
Em “Tipos de Notificação”, marque “Notificar Saques”
Salve a configuração

Sem webhook configurado, você NÃO receberá notificações automáticas de mudança de status dos saques (PROCESSING → COMPLETED/REJECTED).

Quando o Webhook é Enviado

O webhook é enviado quando o status do saque muda, após o processamento do postback do provedor BaaS (Sqala, Witetec, Transfeera, etc.). As notificações são enviadas para os seguintes status:

PROCESSING - Saque em processamento
COMPLETED - Saque concluído com sucesso
REJECTED - Saque rejeitado
CANCELLED - Saque cancelado

Formato do Payload

{
  "id": 123,
  "userId": 1,
  "amount": "100.00",
  "pixKey": "11999999999",
  "pixKeyType": "PHONE",
  "status": "COMPLETED",
  "externalId": "GATEWAY-123",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:35:00.000Z",
  "processedAt": "2025-01-15T10:35:00.000Z",
  "user": {
    "id": 1,
    "name": "João Silva",
    "email": "joao@exemplo.com"
  },
  "type": "WITHDRAWAL"
}

Campos do Payload

Campo	Tipo	Descrição
`id`	integer	ID interno do saque no NextPay Gateway
`userId`	integer	ID do usuário que solicitou o saque
`amount`	string	Valor do saque em reais (formato string, ex: “100.00”)
`pixKey`	string \| null	Chave PIX utilizada para o saque
`pixKeyType`	string \| null	Tipo da chave PIX (CPF, CNPJ, EMAIL, PHONE, RANDOM)
`status`	string	Status atual do saque (PENDING, PROCESSING, COMPLETED, CANCELLED, REJECTED)
`externalId`	string \| null	ID externo do saque no provedor BaaS
`createdAt`	string	Data de criação do saque (ISO 8601)
`updatedAt`	string	Data da última atualização (ISO 8601)
`processedAt`	string \| null	Data de processamento do saque (ISO 8601)
`user`	object	Dados do usuário (id, name, email)
`type`	string	Sempre “WITHDRAWAL” para identificar o tipo de notificação

Segurança

Webhooks permanentes de saques não incluem assinatura HMAC. Diferente dos postbacks por transação (que usam X-Signature), os webhooks permanentes são enviados sem assinatura.

Recomendações de segurança:

Validar a origem usando a URL configurada
Usar HTTPS
Validar o userId para garantir que o saque pertence à sua conta
Implementar idempotência para evitar processamento duplicado

Exemplo de Implementação

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook/cashout', (req, res) => {
  const payload = req.body;
  
  // Validar tipo de notificação
  if (payload.type !== 'WITHDRAWAL') {
    return res.status(400).json({ error: 'Tipo de notificação inválido' });
  }
  
  // Validar userId (garantir que é da sua conta)
  const expectedUserId = process.env.YOUR_USER_ID;
  if (payload.userId !== parseInt(expectedUserId)) {
    return res.status(403).json({ error: 'Usuário não autorizado' });
  }
  
  // Processar notificação
  console.log('Saque atualizado:', {
    id: payload.id,
    status: payload.status,
    amount: payload.amount,
    pixKey: payload.pixKey
  });
  
  // Implementar lógica de negócio aqui
  // Ex: atualizar status no seu sistema, enviar email, etc.
  
  // Sempre retornar 200 para confirmar recebimento
  res.status(200).json({ success: true });
});

app.listen(3000);

Boas Práticas

Sempre retorne HTTP 200 para confirmar recebimento
Implemente idempotência usando o campo id do saque
Valide o userId para garantir segurança
Use HTTPS para proteger os dados em trânsito
Implemente retry logic no seu servidor caso a notificação falhe
Log todas as notificações recebidas para auditoria

Diferenças entre Webhook Permanente e Postback

Característica	Webhook Permanente	Postback por Transação
Configuração	Painel do usuário	Campo `postbackUrl` na criação
Assinatura HMAC	Não	Sim (`X-Signature` header)
Escopo	Todas as transações/saques do usuário	Apenas transação/saque específica
Campo `type`	Sim (“WITHDRAWAL”)	Não
Campo `user`	Sim (dados do usuário)	Não

Códigos de Erro

400 Bad Request

Dados inválidos. Exemplo: valor deve ser um número válido maior que zero.

{
  "message": "Dados inválidos",
  "error": "O valor deve ser um número válido maior que zero"
}

401 Unauthorized

Não autorizado - API Key ou API Secret inválidos.

{
  "message": "Não autorizado",
  "error": "Chaves de API inválidas ou ausentes"
}

403 Forbidden

Cashout via API desabilitado ou usuário sem permissão. Pode retornar:

API_WITHDRAWAL_DISABLED_GLOBALLY - Cashout via API está desabilitado para este usuário
TRANSFER_NOT_ALLOWED - Transferência não permitida

{
  "message": "Transferência não permitida",
  "errorType": "TRANSFER_NOT_ALLOWED"
}

422 Unprocessable Entity

Saldo insuficiente ou regras de negócio. Pode retornar:

INSUFFICIENT_BALANCE - Saldo insuficiente para realizar o cashout
MINIMUM_VALUE - Valor abaixo do mínimo permitido (R$ 100,00)
MAXIMUM_VALUE - Valor acima do máximo permitido (R$ 100.000,00)

{
  "message": "Saldo insuficiente para realizar o cashout",
  "errorType": "INSUFFICIENT_BALANCE"
}

500 Internal Server Error

Erro interno do servidor.

{
  "message": "Erro interno do servidor",
  "error": "Falha ao processar cashout. Tente novamente mais tarde."
}

Começando

MCP (Model Context Protocol)

Transações

Transferências

Saldo

Autenticação

Parâmetros do Body

Exemplo de Requisição

Resposta de Sucesso

Exemplo de Resposta

Configuração de Webhooks

Como Configurar

Quando o Webhook é Enviado

Formato do Payload

Campos do Payload

Segurança

Exemplo de Implementação

Boas Práticas

Diferenças entre Webhook Permanente e Postback

Códigos de Erro

400 Bad Request

401 Unauthorized

403 Forbidden

422 Unprocessable Entity

500 Internal Server Error

Começando

MCP (Model Context Protocol)

Transações

Transferências

Saldo

​Autenticação

​Parâmetros do Body

​Exemplo de Requisição

​Resposta de Sucesso

​Exemplo de Resposta

​Configuração de Webhooks

​Como Configurar

​Quando o Webhook é Enviado

​Formato do Payload

​Campos do Payload

​Segurança

​Exemplo de Implementação

​Boas Práticas

​Diferenças entre Webhook Permanente e Postback

​Códigos de Erro

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​422 Unprocessable Entity

​500 Internal Server Error

Autenticação

Parâmetros do Body

Exemplo de Requisição

Resposta de Sucesso

Exemplo de Resposta

Configuração de Webhooks

Como Configurar

Quando o Webhook é Enviado

Formato do Payload

Campos do Payload

Segurança

Exemplo de Implementação

Boas Práticas

Diferenças entre Webhook Permanente e Postback

Códigos de Erro

400 Bad Request

401 Unauthorized

403 Forbidden

422 Unprocessable Entity

500 Internal Server Error