Skip to main content

​
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 = R100,50).∗∗Mıˊnimo: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: nxpay_f33e03c5c526bd65e0f1c8eddbc9d576" \
  -H "X-Api-Private-Key: nxpay_dc3295ab805921e4b6ece2462f65267e9e9e087bfd66c94e9762008dd45df006" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "pixKey": "11999999999",
    "pixKeyType": "PHONE"
  }'

​
Resposta de Sucesso

​
id
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

​
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."
}