PIX Out (Envio)

Realiza uma transferência PIX para uma chave PIX de destino.

Endpoint

POST /hub/transactions/out

URL base (homologação)

https://staging.sharktecnologia.com/api/v1

Headers obrigatórios

accept: application/json
Content-Type: application/json
Authorization: Basic {token}

Request Body

Campos

Campo	Tipo	Obrigatório	Descrição
`amount`	integer	Sim	Valor em centavos (deve ser maior que `0`). Ex.: `1000` = R$ 10,00
`pix_key`	string	Sim	Chave PIX de destino de acordo com o `pix_type` informado
`pix_type`	string	Sim	Tipo da chave PIX: `CPF`, `CNPJ`, `EMAIL`, `PHONE`
`description`	string	Não	Descrição da transação

Tipos de chave PIX (`pix_type`)

Valor	Descrição	Exemplo de `pix_key`
`CPF`	Cadastro de Pessoa Física	`12345678901`
`CNPJ`	Cadastro Nacional da Pessoa Jurídica	`12345678000199`
`EMAIL`	Endereço de e-mail	`usuario@exemplo.com`
`PHONE`	Número de telefone	`+5511999999999`

Exemplo de payload

{
  "amount": 5000,
  "pix_key": "usuario@exemplo.com",
  "pix_type": "EMAIL",
  "description": "Transferência para fornecedor"
}

Exemplos

cURL

curl --location 'https://staging.sharktecnologia.com/api/v1/hub/transactions/out' \
  --header 'accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic <SEU_TOKEN_BASE64>' \
  --data '{
    "amount": 5000,
    "pix_key": "usuario@exemplo.com",
    "pix_type": "EMAIL",
    "description": "Transferência para fornecedor"
  }'

Python

import requests

url = "https://staging.sharktecnologia.com/api/v1/hub/transactions/out"
headers = {
    "accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Basic <SEU_TOKEN_BASE64>"
}
payload = {
    "amount": 5000,
    "pix_key": "usuario@exemplo.com",
    "pix_type": "EMAIL",
    "description": "Transferência para fornecedor"
}

response = requests.post(url, json=payload, headers=headers, timeout=30)
print(response.status_code)
print(response.json())

TypeScript

const response = await fetch(
  "https://staging.sharktecnologia.com/api/v1/hub/transactions/out",
  {
    method: "POST",
    headers: {
      accept: "application/json",
      "Content-Type": "application/json",
      Authorization: "Basic <SEU_TOKEN_BASE64>",
    },
    body: JSON.stringify({
      amount: 5000,
      pix_key: "usuario@exemplo.com",
      pix_type: "EMAIL",
      description: "Transferência para fornecedor",
    }),
  },
);

const data = await response.json();
console.log(response.status, data);

Respostas

200 OK

Transferência PIX realizada com sucesso.

{
  "status": "success",
  "transaction_id": "xyz789-abc123-def456",
  "message": "Transferência realizada com sucesso"
}

Campos da resposta

Campo	Tipo	Descrição
`status`	string	Status da transação (`success`, `pending`, `failed`)
`transaction_id`	string	ID único da transação no provedor
`message`	string	Mensagem descritiva sobre o resultado da operação

401 Unauthorized

Credenciais inválidas, token mal formatado ou uso de chaves em ambiente incorreto.

{
  "detail": "Not authenticated"
}

422 Unprocessable Content

Dados de entrada inválidos ou usuário sem Provider configurado.

{
  "detail": "User does not have a Provider configured. Please contact SharkHub support."
}

Caso esse erro aconteça, entre em contato com o suporte da SharkHub para que um Provider seja definido para o seu usuário. Clientes não têm acesso à tela de usuários e não conseguem configurar Providers diretamente.

500 Internal Server Error

Erro interno do servidor.

{
  "detail": "Internal server error"
}

501 Not Implemented

Funcionalidade não implementada para o provedor.

{
  "detail": "Provider does not support this operation"
}

Observações importantes

O usuário deve ter saldo suficiente para realizar a transferência.
O usuário deve ter um Provider de saída configurado para utilizar este endpoint. Se a API retornar erro de Provider, entre em contato com o suporte da SharkHub.
A chave PIX de destino deve ser válida e ativa.
O tipo de chave (pix_type) deve corresponder ao formato da chave informada.

Códigos de status HTTP

Código	Descrição
`200`	OK - Requisição processada com sucesso
`401`	Unauthorized - Credenciais inválidas ou não fornecidas
`403`	Forbidden - Usuário sem permissão para a operação
`422`	Unprocessable Content - Dados de entrada inválidos
`500`	Internal Server Error - Erro interno do servidor
`501`	Not Implemented - Funcionalidade não disponível para o provedor

On this page