🚀 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
- Acesse https://gateway.bullspay.com.br
- Faça login na sua conta
- Navegue para a aba "API"
- Clique em "Gerar um novo Token"
- Copie o token gerado
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:
- Dashboard: https://gateway.bullspay.com.br
- Documentação: Disponível na plataforma
- Suporte Técnico: Via dashboard