BsPag API

Introdução

Essa documentação tem como objetivo fornecer todas as informações necessárias para integração com a API do BsPag.

Autenticação

A autenticação na API do BsPag é feita através do método Basic Auth.

Para autenticar as requisições, inclua um cabeçalho Authorization no formato "Basic {credentials}". O valor de {credentials} é composto pelo seu usuário/id e uma senha, unidos com dois pontos (:), e então codificados em base64. No caso dessa integração, a identificação do usuário é o API_TOKEN, e a senha deverá ficar vazia.

Atenção
Para montar a requisição Basic Auth, você deve utilizar o API_TOKEN da seguinte maneira:

User: API_TOKEN
Password: Vazio

Todos os endpoints autenticados estão marcados com o selo requer autenticação na documentação abaixo.

Você pode obter seu token acessando o painel administrativo do BsPag na seção de Configurações.

Recebimentos

Listar recebimentos por periodo

GET
https://api.bspag.com.br
/api/v1/receivables
requires authentication

Este endpoint retorna os recebimentos (extratos de depositos) de um determinado periodo. Os dados sao buscados diretamente da API do gateway de pagamentos e salvos localmente.

Importante: Este endpoint possui rate limit de 10 requisicoes por minuto por conta da dependencia de APIs externas. Recomenda-se fazer no maximo uma requisicao por mes de referencia.

  • month e year: Mes e ano de referencia dos recebimentos (obrigatorios).
  • day: Dia especifico para consulta. Se informado, retorna apenas os recebimentos daquele dia.
  • limit e offset: Paginacao dos resultados.

Headers

Authorization
Example:
Basic {API_TOKEN}
Content-Type
Example:
application/json
Accept
Example:
application/json

Query Parameters

month
integer
required

Mes de referencia (1-12). Exemplo: 3

Example:
3
year
integer
required

Ano de referencia. Exemplo: 2026

Example:
2026
day
integer

Dia especifico para consulta (1-31). Opcional. Exemplo: 15

Example:
15
limit
integer

Quantidade de registros por pagina. Padrao: 50. Exemplo: 50

Example:
50
offset
integer

Deslocamento para paginacao. Padrao: 0. Exemplo: 0

Example:
0

Response Fields

Example request: 
curl --request GET \
    --get "https://api.bspag.com.br/api/v1/receivables?month=3&year=2026&day=15&limit=50&offset=0" \
    --header "Authorization: Basic {API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "data": [
        {
            "deposit_date": "2026-03-10",
            "sale_date": "2026-03-08T14:30:00.000000Z",
            "order_id": 1234,
            "external_code": "EXT-001",
            "transaction_id": "98765432",
            "description": "Cliente Exemplo (00000000000)",
            "payment_method": "Cartao de Credito",
            "amount": "150.00",
            "tax": "4.50",
            "net_amount": "145.50",
            "installment_current": "2",
            "installment_quantity": "6"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 50,
        "total_pages": 1,
        "total_records": 1,
        "total_page_amount": 150,
        "total_page_tax": 4.5,
        "month": 3,
        "year": 2026
    }
}
{
    "error": true,
    "message": "Os campos month e year sao obrigatorios."
}
{
    "message": "Too Many Attempts."
}

Vendas

Consultar detalhes de venda

GET
https://api.bspag.com.br
/api/v1/orders/get-payments/{type}/{id}
requires authentication

Este endpoint retorna informações de pagamento associadas a um "transactionId", "orderId" ou "externalCode".

  • externalCode: Código externo associado à transação, normalmente o Id da venda no sistema que originou a transação.
  • transactionId: Identificador da transação BsPag
  • orderId: Identificador do pedido dentro da plataforma BsPag

Headers

Authorization
Example:
Basic {API_TOKEN}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

type
string
required

Tipo de identificador para a busca. Valores permitidos: "transactionId", "orderId", "externalCode". Exemplo: transactionId

Example:
transactionId
id
integer
required

O identificador da transação, pedido ou código externo, de acordo com o tipo. Exemplo: 12345678

Example:
12345678

Response Fields

Example request: 
curl --request GET \
    --get "https://api.bspag.com.br/api/v1/orders/get-payments/transactionId/12345678" \
    --header "Authorization: Basic {API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "idTransaction": 12345678,
    "Vendor": "Loja Exemplo",
    "PaymentDate": "2024-11-01",
    "PaymentDateTime": "2024-11-01T00:59:48Z",
    "CreatedDate": "2024-11-01",
    "CreatedDateTime": "2024-11-01T00:59:44Z",
    "Amount": 264.75,
    "NetValue": 252.57,
    "TaxValue": 12.18,
    "Customer": {
        "Name": "Cliente Teste",
        "Identity": "00000000000",
        "Email": "cliente.exemplo@teste.com",
        "Phone": "41999999999",
        "Address": {
            "ZipCode": "00000000",
            "Street": "Rua Exemplo",
            "Number": "123",
            "District": "Bairro Exemplo",
            "Complement": "Apto 101",
            "State": "SP",
            "City": "Cidade Exemplo"
        }
    },
    "PaymentObject": {
        "Token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "CardNumber": "111122****3333",
        "Brand": "2",
        "Installments": 6,
        "ReturnCode": "00",
        "Message": "Transação autorizada",
        "Is3DSAuthenticated": false
    },
    "PaymentSchedule": [
        {
            "Description": "Cliente Teste (00000000000)",
            "Amount": 42.1,
            "Tax": 0,
            "IsTransferred": false,
            "ReleaseDate": "2024-12-02",
            "InstallmentNumber": 1
        },
        {
            "Description": "Cliente Teste (00000000000)",
            "Amount": 42.1,
            "Tax": 0,
            "IsTransferred": false,
            "ReleaseDate": "2025-01-02",
            "InstallmentNumber": 2
        }
    ]
}
{
   "error": true,
   "responseDetail": "Invalid request. [Type not found | BsPagOrder id not found | External Code not found]",
   "ErrorCode": [9001 | 9002 | 9003]
}

Listar pedidos com filtros e paginação

GET
https://api.bspag.com.br
/api/v1/orders/index
requires authentication

Este endpoint retorna uma lista de pedidos baseados em critérios específicos fornecidos como parâmetros na URL.

  • consumerDocument: Documento do consumidor (CPF ou CNPJ).
  • dateStart e dateEnd: Período de criação do pedido para filtrar os resultados.
  • environment: Especifica o ambiente das transações. Valores permitidos: "production", "sandbox". Exemplo: production
  • mainStatus: Nome do status principal do pedido.
  • specificStatus: Nome do status específico do pedido.

A resposta inclui dados sobre os pedidos, documento do consumidor e status das transações, além de metadados para paginação.

Headers

Authorization
Example:
Basic {API_TOKEN}
Content-Type
Example:
application/json
Accept
Example:
application/json

Query Parameters

limit
integer

Tamanho da página (quantidade de registros por página). Padrão: 10. Exemplo: 10

Example:
10
offset
integer

Deslocamento para começar a listagem (útil para paginação). Padrão: 0. Exemplo: 10

Example:
10
consumerDocument
integer

Documento do consumidor para filtrar pedidos (CPF ou CNPJ). Opcional. Exemplo: 12345678900

Example:
12345678900
dateStart
string

date Data inicial no formato AAAA-MM-DD. Opcional. Exemplo: 2024-01-01

Example:
2024-01-01
dateEnd
string

date Data final no formato AAAA-MM-DD. Opcional. Exemplo: 2024-12-31

Example:
2024-12-31
environment
string

Ambiente das transações: Valores possíveis: "production" ou "sandbox". Padrão: production. Exemplo: production

Example:
production
mainStatus
string

Nome do status principal do pedido. Opcional. Valores Possíveis: "Aguardando Pagamento", "Em Processamento", "Pago", "Cancelado", "Falha" Exemplo: Pago

Example:
Pago
specificStatus
string

Nome do status específico do pedido. Opcional. Valores Possíveis: "Pendente", "Processamento", "Autorizado", "Em disputa", "Devolvido", "Baixado", "Recusado", "Liberado", "Em cancelamento", "Chargeback", "Pré-Autorizado". Exemplo: Autorizado

Example:
Autorizado

Response Fields

Example request: 
curl --request GET \
    --get "https://api.bspag.com.br/api/v1/orders/index?limit=10&offset=10&consumerDocument=12345678900&dateStart=2024-01-01&dateEnd=2024-12-31&environment=production&mainStatus=Pago&specificStatus=Autorizado" \
    --header "Authorization: Basic {API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "data": [
        {
            "order_id": 1626,
            "transaction_id": "101176594",
            "external_code": "206",
            "environment": "production",
            "amount": "50.00",
            "created_at": "2024-12-16T13:10:46.000000Z",
            "consumer_document": "98931008015",
            "main_status": "Falha",
            "specific_status": "Recusado"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 1,
        "total_pages": 3,
        "total_records": 3,
        "total_page_amount": 50,
        "total_filter_amount": 594.05
    }
}
{
   "error": true,
   "responseDetail": "Parâmetros inválidos. [Data inválida | Documento do consumidor não encontrado | Ambiente inválido]",
   "ErrorCode": [1001 | 1002 | 1003]
}