PORTUGUÊS

🚀 Informações Gerais

Nome da API: BullsPay Gateway API

URL Base: https://gateway.bullspay.com.br/api

Versão: 1.0

Descrição: API para processamento de pagamentos, saques e gerenciamento de transações.

Endpoints

Abaixo estão listadas as URLs que serão utilizadas para acessar a nossa API. No ambiente de produção e sandbox.

Ambiente URL
Produção https://gateway.bullspay.com.br/api
Sandbox https://api-staging.bullspay.com.br

🔐 Autenticação

A autenticação na API da BullsPay é feita através de chaves API (API Keys). Você precisa incluir suas chaves nos headers de todas as requisições.

Tipos de Autenticação

Credenciais (API Key)

  • Tipo: API Key
  • Header: X-Public-Key: {client_id}, X-Private-Key: {secret_key}
  • Como: Via dashboard
⚠️ Importante: Mantenha suas chaves privadas seguras e nunca as exponha em código client-side ou repositórios públicos.

🎯 Como Começar

1. Gerar Token de Acesso

2. Configurar no Postman

  • Environment Variable: base_url = https://gateway.bullspay.com.br/api
  • Environment Variable: auth_token = {seu_token_aqui}

📊 Endpoints Principais

GET

Listar Transações

Ambiente URL
Produção https://api-gateway.bullspay.com.br/api/transactions/list
Sandbox https://api-staging.bullspay.com.br/api/transactions/list

Query Parameters

Parameter Type Description
page integer Número identificador da página
Default: 1
limit integer Quantidade de registros por página
Default: 10, Máximo: 100
status string Status das transações a serem filtradas
Valores: paid, pending, failed, refunded, chargeback, all
id string Filtrar por unic_id (LIKE)
curl --location 'https://api-gateway.bullspay.com.br/api/transactions/list?status=paid&page=1&limit=10' \ --header 'Accept: application/json' \ --header 'X-Public-Key: {{client_Id}}' \ --header 'X-Private-Key: {{secret_key}}'

Exemplo de Resposta

{ "success": true, "message": "Transações listadas com sucesso", "data": { "transactions": [ { "unic_id": "uuid-da-transacao", "total_value": 10000, "total_to_receiver": 9500, "buyerData": { "buyer_name": "João Silva", "buyer_document": "123.456.789-00", "buyer_email": "joao@exemplo.com" }, "status": "paid", "created_at": "2024-01-15T10:30:00Z" } ], "pagination": { "current_page": 1, "total": 50, "per_page": 10, "last_page": 5 } } }
POST

Criar Transação

Ambiente URL
Produção https://api-gateway.bullspay.com.br/api/transactions/create
Sandbox https://api-staging.bullspay.com.br/api/transactions/create

Body Parameters

Parameter Type Description
amount * integer Valor da transação em centavos
Mínimo: 600 (R$ 6,00)
buyer_infos * object Informações do comprador
external_id string ID externo para identificação
payment_method * string Método de pagamento (ex: pix)
curl --location 'https://api-gateway.bullspay.com.br/api/transactions/create' \ --header 'Accept: application/json' \ --header 'X-Public-Key: {{client_Id}}' \ --header 'X-Private-Key: {{secret_key}}' \ --header 'Content-Type: application/json' \ --data '{ "amount": 12990, "buyer_infos": { "buyer_name": "João da Silva", "buyer_email": "joao.silva@example.com", "buyer_document": "73164731000", "buyer_phone": "27999999999" }, "external_id": "pedido_123", "payment_method": "pix" }'

Exemplo de Resposta

{ "success": true, "data": { "unic_id": "uuid-da-transacao", "status": "pending", "total_value": 12990, "payment_url": "https://bullspay.com.br/pay/uuid-da-transacao", "qr_code_base64": "base64-do-qr-code", "qr_code_text": "texto-do-qr-code-pix", "created_at": "2024-01-15T10:30:00Z" } }
PUT

Reembolsar Transação

Ambiente URL
Produção https://api-gateway.bullspay.com.br/api/transactions/refund/{unic_id}
Sandbox https://api-staging.bullspay.com.br/api/transactions/refund/{unic_id}

Path Parameters

Parameter Type Description
unic_id * string ID único da transação a ser reembolsada
curl --location 'https://api-gateway.bullspay.com.br/api/transactions/refund/334dc41f-3980-459b-a182-859c5d2ae72a' \ --header 'Accept: application/json' \ --header 'X-Public-Key: bp_client_kpxNgSrcsPO7mw9C4ymv9RlgmJy1fcun' \ --header 'X-Private-Key: bp_secret_Twf0HMMBWJd6RX1F6PoFVd2bxvpFhlRLjv2nuoCfWLHxWlladqkrFJ6yHiRpQ7KO'

Exemplo de Resposta

{ "success": true, "message": "Transação reembolsada com sucesso." }
GET

Consultar Saldo

Ambiente URL
Produção https://api-gateway.bullspay.com.br/api/withdrawals/balance
Sandbox https://api-staging.bullspay.com.br/api/withdrawals/balance

Headers

Header Valor
Accept application/json
X-Public-Key bp_client_kpxNgSrcsPO7mw9C4ymv9RlgmJy1fcun
X-Private-Key bp_secret_Twf0HMMBWJd6RX1F6PoFVd2bxvpFhlRLjv2nuoCfWLHxWlladqkrFJ6yHiRpQ7KO
curl --location 'https://api-gateway.bullspay.com.br/api/withdrawals/balance' \ --header 'Accept: application/json' \ --header 'X-Public-Key: bp_client_kpxNgSrcsPO7mw9C4ymv9RlgmJy1fcun' \ --header 'X-Private-Key: bp_secret_Twf0HMMBWJd6RX1F6PoFVd2bxvpFhlRLjv2nuoCfWLHxWlladqkrFJ6yHiRpQ7KO'

Exemplo de Resposta

{ "success": true, "data": { "balance": 123456, "available_balance": 120000, "blocked_balance": 3456 } }
GET

Listar Saques

Ambiente URL
Produção https://api-gateway.bullspay.com.br/api/withdrawals/list
Sandbox https://api-staging.bullspay.com.br/api/withdrawals/list

Query Parameters

Parameter Type Description
page integer Número identificador da página
Default: 1
limit integer Quantidade de registros por página
Default: 10, Máximo: 100
status string Status dos saques a serem filtrados
Valores: paid, pending, failed, canceled, refunded, all
id string Filtrar por unic_id (LIKE)
curl --location 'https://api-gateway.bullspay.com.br/api/withdrawals/list?status=all&page=1&limit=10' \ --header 'Accept: application/json' \ --header 'X-Public-Key: bp_client_kpxNgSrcsPO7mw9C4ymv9RlgmJy1fcun' \ --header 'X-Private-Key: bp_secret_Twf0HMMBWJd6RX1F6PoFVd2bxvpFhlRLjv2nuoCfWLHxWlladqkrFJ6yHiRpQ7KO'

Exemplo de Resposta

{ "success": true, "message": "Saques listados com sucesso", "data": { "withdrawals": [ { "unic_id": "uuid-do-saque", "amount": 10000, "pix_key_type": "cpf", "pix_key": "123.456.789-00", "status": "paid", "created_at": "2024-01-15T10:30:00Z" } ], "pagination": { "current_page": 1, "total": 50, "per_page": 10, "last_page": 5 } } }
POST

Solicitar Saque

Ambiente URL
Produção https://api-gateway.bullspay.com.br/api/withdrawals/request
Sandbox https://api-staging.bullspay.com.br/api/withdrawals/request

Body Parameters

Parameter Type Description
amount * integer Valor do saque em centavos
Mínimo: 1000 (R$ 10,00)
pix_key_type * string Tipo da chave PIX
Valores: cpf, cnpj, email, phone, random
pix_key * string Chave PIX para recebimento
curl --location 'https://api-gateway.bullspay.com.br/api/withdrawals/request' \ --header 'Accept: application/json' \ --header 'X-Public-Key: bp_client_kpxNgSrcsPO7mw9C4ymv9RlgmJy1fcun' \ --header 'X-Private-Key: bp_secret_Twf0HMMBWJd6RX1F6PoFVd2bxvpFhlRLjv2nuoCfWLHxWlladqkrFJ6yHiRpQ7KO' \ --header 'Content-Type: application/json' \ --data '{ "amount": 500, "pix_key_type": "cpf", "pix_key": "18066392702" }'

Exemplo de Resposta

{ "success": true, "data": { "unic_id": "uuid-do-saque", "status": "pending", "amount": 500, "pix_key_type": "cpf", "pix_key": "18066392702", "created_at": "2024-01-15T10:30:00Z" } }
GET

Listar Webhooks

Ambiente URL
Produção https://api-gateway.bullspay.com.br/api/webhooks/list
Sandbox https://api-staging.bullspay.com.br/api/webhooks/list

Query Parameters

Parameter Type Description
page integer Número identificador da página
Default: 1
limit integer Quantidade de registros por página
Default: 10, Máximo: 100
curl --location 'https://api-gateway.bullspay.com.br/api/webhooks/list?page=1&limit=10' \ --header 'Accept: application/json' \ --header 'X-Public-Key: bp_client_kpxNgSrcsPO7mw9C4ymv9RlgmJy1fcun' \ --header 'X-Private-Key: bp_secret_Twf0HMMBWJd6RX1F6PoFVd2bxvpFhlRLjv2nuoCfWLHxWlladqkrFJ6yHiRpQ7KO'

Exemplo de Resposta

{ "success": true, "message": "Webhooks listados com sucesso", "data": { "webhooks": [ { "webhook_id": "uuid-do-webhook", "url": "https://webhook.site/a2b27729-c9db-4419-aa38-7c17274afbae", "send_transaction_event": true, "send_withdraw_event": false, "created_at": "2024-01-15T10:30:00Z" } ], "pagination": { "current_page": 1, "total": 50, "per_page": 10, "last_page": 5 } } }
POST

Criar Webhook

Ambiente URL
Produção https://api-gateway.bullspay.com.br/api/webhooks/create
Sandbox https://api-staging.bullspay.com.br/api/webhooks/create

Body Parameters

Parameter Type Description
url * string URL que receberá as notificações
send_transaction_event boolean Receber eventos de transação
Default: true
send_withdraw_event boolean Receber eventos de saque
Default: false
curl --location 'https://api-gateway.bullspay.com.br/api/webhooks/create' \ --header 'Accept: application/json' \ --header 'X-Public-Key: bp_client_kpxNgSrcsPO7mw9C4ymv9RlgmJy1fcun' \ --header 'X-Private-Key: bp_secret_Twf0HMMBWJd6RX1F6PoFVd2bxvpFhlRLjv2nuoCfWLHxWlladqkrFJ6yHiRpQ7KO' \ --header 'Content-Type: application/json' \ --data '{ "url": "https://webhook.site/a2b27729-c9db-4419-aa38-7c17274afbae", "send_withdraw_event": false, "send_transaction_event": true }'

Exemplo de Resposta

{ "success": true, "data": { "webhook_id": "uuid-do-webhook", "url": "https://webhook.site/a2b27729-c9db-4419-aa38-7c17274afbae", "send_transaction_event": true, "send_withdraw_event": false, "created_at": "2024-01-15T10:30:00Z" } }
DEL

Deletar Webhook

Ambiente URL
Produção https://api-gateway.bullspay.com.br/api/webhooks/{unic_id}
Sandbox https://api-staging.bullspay.com.br/api/webhooks/{unic_id}

Path Parameters

Parameter Type Description
unic_id * string ID único do webhook a ser deletado
curl --location --request DELETE 'https://api-gateway.bullspay.com.br/api/webhooks/delete/766458dc-5017-4e1f-8b71-427e9af3462f' \ --header 'Accept: application/json' \ --header 'X-Public-Key: bp_client_kpxNgSrcsPO7mw9C4ymv9RlgmJy1fcun' \ --header 'X-Private-Key: bp_secret_Twf0HMMBWJd6RX1F6PoFVd2bxvpFhlRLjv2nuoCfWLHxWlladqkrFJ6yHiRpQ7KO'

Exemplo de Resposta

{ "success": true, "message": "Webhook deletado com sucesso." }

📋 Parâmetros de Query

Paginação

Parâmetro Tipo Descrição
page integer Página atual (padrão: 1)
limit integer Itens por página (padrão: 10, máximo: 100)

Filtros de Transação

Parâmetro Tipo Descrição
status string Status das transações a serem filtradas
Valores: paid, pending, failed, refunded, chargeback, all
id string Filtrar por unic_id (LIKE)

Filtros de Saques

Parâmetro Tipo Descrição
status string Status dos saques a serem filtrados
Valores: paid, pending, failed, canceled, refunded, all
id string Filtrar por unic_id (LIKE)

💰 Valores Mínimos

Transações

Valor mínimo: R$ 6,00

Saques

Valor mínimo: R$ 10,00

🔗 Webhooks

Os webhooks permitem que você receba notificações em tempo real sobre eventos que ocorrem em sua conta BullsPay.

Configuração

  • Via Dashboard: Acesse https://gateway.bullspay.com.br
  • Via API: Use o endpoint de criação de webhooks
  • Selecione Eventos: Escolha entre eventos de transação e saque

Eventos Disponíveis

Tipo Eventos
Transações paid, pending, failed, refunded, chargeback
Saques paid, pending, failed, canceled, refunded

Formato do Payload

{ "event_type": "transaction", "data": { "unic_id": "uuid-da-transacao", "external_id": "id-externo-adquirente", "status": "paid", "total_value": 10000, "total_to_receiver": 9500, "created_at": "2024-01-15T10:30:00Z" } }

🚨 Códigos de Status

Sucesso

Código Status Descrição
200 OK Requisição bem-sucedida
201 Created Recurso criado

Erro do Cliente

Código Status Descrição
400 Bad Request Requisição inválida / Usuário não aprovado
401 Unauthorized Não autenticado
422 Unprocessable Entity Dados inválidos

Erro do Servidor

Código Status Descrição
500 Internal Server Error Erro interno do servidor

Exemplo de Resposta de Erro

{ "success": false, "message": "Você não está autorizado a executar essa ação. Sua conta ainda está em análise." }

📝 Exemplos de Resposta

Lista de Transações

{ "success": true, "message": "Transações listadas com sucesso", "data": { "transactions": [ { "unic_id": "uuid-da-transacao", "total_value": 10000, "total_to_receiver": 9500, "buyerData": { "buyer_name": "João Silva", "buyer_document": "123.456.789-00", "buyer_email": "joao@exemplo.com" }, "status": "paid", "created_at": "2024-01-15T10:30:00Z" } ], "pagination": { "current_page": 1, "total": 50, "per_page": 10, "last_page": 5 } } }

🔧 Configuração do Postman

Environment Variables

{ "base_url": "https://gateway.bullspay.com.br/api", "auth_token": "seu_token_aqui", "api_key": "sua_api_key_aqui" }

Headers Globais

Content-Type: application/json Accept: application/json

📞 Suporte

Para dúvidas ou problemas: