🚀 Informações Gerais

Nome da API: BullsPay Gateway API

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

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://api-gateway.bullspay.com.br/
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://api-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."
}

💰 Split de Pagamentos

O Split de Pagamentos permite dividir automaticamente o valor de uma transação entre múltiplos recebedores. É muito simples de usar - basta adicionar o parâmetro splits na criação da transação.

Como Integrar

Para usar o split, adicione o array splits no JSON da criação de transação:

{
  "amount": 10000,
  "buyer_infos": {
    "buyer_name": "João Silva",
    "buyer_document": "123.456.789-00",
    "buyer_email": "joao@exemplo.com"
  },
  "splits": [
    {
      "email": "percentage@example.com",
      "type": "percentage",
      "value": 10
    },
    {
      "email": "amount@example.com",
      "type": "amount",
      "value": 2580
    }
  ],
  "payment_method": "pix"
}

Tipos de Split

Tipo	Descrição	Exemplo
`percentage`	Porcentagem do valor total	10 = 10%
`amount`	Valor fixo em centavos	2580 = R$ 25,80

Parâmetros do Split

Parâmetro	Tipo	Descrição
email *	string	Email da conta que receberá o split
type *	string	`percentage` ou `amount`
value *	integer	Valor em % (1-100) ou centavos

💡 Dica: O valor restante após os splits sempre vai para a conta principal. No exemplo acima, de R$ 100,00 total: 10% (R$ 10,00) + R$ 25,80 = R$ 35,80 para os splits, restando R$ 64,20 para a conta principal.

📋 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