PIX In (Recebimento)

Cria uma cobrança PIX para recebimento. O sistema gera um QR Code que pode ser escaneado para realizar o pagamento.

Endpoint

POST /hub/transactions/in

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
`description`	string	Não	Descrição da transação
`payload`	string	Não	String EMV ou QR Code existente para reutilização

Exemplo de payload

{
  "amount": 1000,
  "description": "Pagamento de serviço"
}

Exemplos

cURL

curl --location 'https://staging.sharktecnologia.com/api/v1/hub/transactions/in' \
  --header 'accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic <SEU_TOKEN_BASE64>' \
  --data '{
    "amount": 1000,
    "description": "Pagamento de serviço"
  }'

Python

import requests

url = "https://staging.sharktecnologia.com/api/v1/hub/transactions/in"
headers = {
    "accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Basic <SEU_TOKEN_BASE64>"
}
payload = {
    "amount": 1000,
    "description": "Pagamento de serviço"
}

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/in",
  {
    method: "POST",
    headers: {
      accept: "application/json",
      "Content-Type": "application/json",
      Authorization: "Basic <SEU_TOKEN_BASE64>",
    },
    body: JSON.stringify({
      amount: 1000,
      description: "Pagamento de serviço",
    }),
  },
);

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

Respostas

200 OK

Transação PIX criada com sucesso.

{
  "status": "pending",
  "transaction_id": "abc123-def456-ghi789",
  "qr_code": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890520400005303986540510005802BR5913NOME EMPRESA6009SAO PAULO62070503***6304ABCD",
  "qr_code_name": "qr_empresa_123",
  "expiration_date": "2026-03-18T23:59:59"
}

Campos da resposta

Campo	Tipo	Descrição
`status`	string	Status da transação (`pending`, `paid`, `cancelled`)
`transaction_id`	string	ID único da transação no provedor
`qr_code`	string	Código EMV do QR Code para pagamento (PIX copia e cola)
`qr_code_name`	string	Nome identificador do QR Code
`expiration_date`	string	Data e hora de expiração do QR Code

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 QR Code gerado possui um prazo de expiração definido no campo expiration_date.
O status inicial será pending até o pagamento ser confirmado via webhook.
O sistema credita o saldo automaticamente quando o pagamento é confirmado.
O usuário deve ter um Provider de entrada configurado para utilizar este endpoint. Se a API retornar erro de Provider, entre em contato com o suporte da SharkHub.

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