Documentação REST API

BANCO PHOENIX
API de Pagamentos

API completa de processamento de pagamentos com suporte a PIX e cartão de crédito. Gerencie transações, saques via PIX e saldo a partir de uma única integração.

Autenticação por Header

Respostas JSON

PIX & Cartão de Crédito

Webhooks de Postback

Introdução

Visão Geral da API

A API do PHOENIX é uma REST API que permite integrar funcionalidades completas de pagamento à sua plataforma: desde a criação de transações até saques e consulta de saldo. Todas as comunicações utilizam JSON e autenticação via headers HTTP.

	Endpoint	Descrição
GET	/ping	Testa a conexão e valida as credenciais antes de operar
POST	/createTransaction	Cria uma nova transação via PIX (retorna QR Code) ou cartão de crédito (aprovação síncrona)
POST	/pixOut	Solicita um saque via PIX para uma chave pix especificada: processado de forma assíncrona
GET	/transactions	Lista as transações do usuário autenticado com paginação por cursor
GET	/transaction/:id	Retorna todos os dados de uma transação específica pelo seu ID
GET	/balance	Verifica o saldo disponível da conta PHOENIX

Fluxo PIX

Chame /createTransaction com paymentMethod: "pix"
Exiba o qrCode retornado ao cliente
Aguarde o webhook com status: "PAID"
Confirme o pagamento na sua base de dados

Fluxo Cartão de Crédito

Chame /createTransaction com paymentMethod: "credit_card"
Inclua os dados do cartão no campo card e installments
O retorno já traz CONFIRMED ou REFUSED de forma síncrona
Consulte /transaction/:id para conferir os detalhes

Fluxo Saque (Pix-Out)

Verifique o saldo disponível com /balance
Chame /pixOut com a chave PIX e o valor desejado
Aguarde o webhook com status: "PAID" ou "FAILED"
Confira balanceUpdated para garantir que o saldo foi atualizado

Webhooks

Informe postbackUrl na criação da transação
A PHOENIX enviará um POST de confirmação quando o pagamento for concluído
Responda com HTTP 200 em até 5 segundos
Valide o transactionId recebido na sua base antes de processar

Ambiente	URL Base	Uso
Produção · Ativo	`https://api.bpx.solutions`	Domínio oficial PHOENIX: use com credenciais de produção
Sandbox · Testes	`https://api.bpx.solutions/sandbox`	Ambiente de testes com credenciais próprias: nenhum valor real é movimentado

Autenticação

Autenticação por Headers

Todos os endpoints, incluindo /ping, requerem autenticação via headers HTTP. Inclua userId e apiKey em todas as requisições.

Header	Tipo	Obrigatoriedade	Descrição
userId	string	Obrigatório	Identificador único do usuário na plataforma PHOENIX.
apiKey	string	Obrigatório	Chave secreta de API. Mantenha em sigilo: nunca exponha em código client-side.
Content-Type	string	POST	Obrigatório em requisições POST. Use `application/json`.

Exemplo de Headers

Content-Type: application/json
userId: SEU_USER_ID_AQUI
apiKey: sua-api-key-secreta

Referência

Status da Transação

As transações percorrem estes estados ao longo do ciclo de vida. Use o campo postbackUrl para receber atualizações em tempo real via webhook.

PENDING

Aguardando pagamento (PIX)

PROCESSING

Pix-out aceito pelo parceiro: aguardando confirmação

CONFIRMED

Cartão aprovado com sucesso

REFUSED

Pagamento recusado

RECEIVED

PIX pago: status final na consulta

REFUNDED

Transação estornada

PAID

Pagamento concluído: status enviado no webhook

FAILED

Falha no processamento (pix-out)

Webhooks

Notificações via Webhook (Postback)

Quando um pagamento é concluído (ou um pix-out é processado), a PHOENIX envia automaticamente uma requisição POST para cada URL configurada em postbackUrl e/ou postbackUrls (aceitos em ambos os fluxos). O corpo da requisição é um payload compacto de confirmação: para obter os dados completos da transação, consulte GET /transaction/:id com o transactionId recebido.

Evento	Status no payload	Quando ocorre
Pagamento PIX recebido	PAID	PIX confirmado pelo banco: o webhook envia `status: "PAID"`; na consulta (`GET /transaction/:id`) a transação aparece como `RECEIVED`
Pix-out aceito	PENDING	Saque aceito pelo provedor de liquidação: status intermediário, aguarde `PAID` ou `FAILED`
Pix-out concluído	PAID	Saque via PIX processado com sucesso
Pix-out falhou	FAILED	Saque via PIX não pôde ser processado

Seu endpoint de postback deve responder com HTTP 2xx rapidamente: no pix-out o disparo expira em 8 segundos. Recomendamos usar 1 URL de postback por integração sempre que possível. Verifique a autenticidade da requisição comparando o transactionId com sua base de dados antes de processar o evento.

Campo	Tipo	Descrição
webhookId	string	Identificador do disparo do webhook: no pagamento PIX, tem o mesmo valor de `transactionId`
transactionId	string	ID único da transação no PHOENIX: use em `GET /transaction/:id` para obter os dados completos
status	"PAID" \| "FAILED" \| "PENDING" \| "REFUNDED"	`PAID`: pagamento confirmado e creditado · `FAILED`: pix-out que não pôde ser processado (valor devolvido) · `PENDING`: pix-out aceito, aguardando confirmação · `REFUNDED`: pix-out estornado após concluído (valor devolvido)
balanceUpdated	boolean	Indica se o saldo da conta já foi atualizado quando o webhook foi disparado
endToEndId	string	ID end-to-end do PIX no Banco Central: pode ser vazio (`""`) dependendo do adquirente

Payload recebido pelo seu servidor · POST application/json

{
  "webhookId": "DFFHYXDZFYGNBCXW",
  "transactionId": "DFFHYXDZFYGNBCXW",
  "status": "PAID",
  "balanceUpdated": true,
  "endToEndId": "E00416968202510122026AkMT0C8eVEP"
}

O webhook confirma o pagamento: ele não carrega os dados completos da transação. Ao receber status: "PAID", consulte GET /transaction/:id com o transactionId para obter cliente, itens, valores e demais metadados. Transações de cartão de crédito não geram webhook: o resultado (CONFIRMED/REFUSED) é retornado de forma síncrona na própria resposta de /createTransaction.

Webhook do Pix-Out

Mesmo formato compacto: enviado para cada URL em postbackUrls (até 5 URLs) quando o saque via PIX for aceito, processado ou falhar. Apenas URLs https com host público são aceitas. Endereços internos ou privados (localhost, 127.0.0.1, faixas 10.x, 192.168.x, 172.16-31.x, 169.254.x) são recusados por segurança, tanto na validação quanto no momento do envio. Para testar na sua máquina, exponha o servidor com um túnel (ngrok, Cloudflare Tunnel ou similar).

Campo	Tipo	Descrição
webhookId	string	Identificador do disparo do webhook: pode ser um ID aleatório ou repetir o `transactionId`, dependendo da etapa do saque
transactionId	string	ID da solicitação de pix-out nos sistemas PHOENIX
status	"PAID" \| "FAILED" \| "PENDING" \| "REFUNDED"	`PAID`: saque processado com sucesso (`balanceUpdated: true`) · `FAILED`: saque não pôde ser processado, valor devolvido ao saldo (`balanceUpdated: false`, líquido zero pra você) · `PENDING`: saque aceito pelo provedor, aguardando confirmação (`balanceUpdated: false`) · `REFUNDED`: saque estornado após concluído, valor devolvido ao saldo (`balanceUpdated: true`)
balanceUpdated	boolean	Indica se o saldo da conta foi atualizado após o processamento
endToEndId	string	ID end-to-end do PIX no Banco Central, campo opcional: dependendo do provedor de liquidação, o webhook `PAID` pode vir sem este campo ou com string vazia. Trate como opcional na sua integração

Payload · Pix-Out POST

{
  "webhookId": "QJZKPLMWXRTYBNAD",
  "transactionId": "PIXOUTID12345XYZ",
  "status": "PAID",
  "balanceUpdated": true,
  "endToEndId": "E00416968202510122026AkMT0C8eVEP"
}

GET /ping

Testa conexão de api com o servidor

Teste de credenciais. Use este endpoint para verificar se suas credenciais estão corretas e a API está acessível antes de realizar transações reais.

200	Credenciais válidas: conexão estabelecida com sucesso
401	Credenciais ausentes ou inválidas

Resposta · texto puro 200

pong - api valid

Resposta 401

{ "error": "userId e apiKey são obrigatórios nos headers" }

POST /createTransaction

Cria uma transação

Esse endpoint permite que você crie uma transação. Suporta pagamento por PIX ou cartão de crédito. Para PIX, o QR Code é retornado imediatamente. Para cartão de crédito, o status é retornado de forma síncrona (CONFIRMED ou REFUSED). O webhook enviará status: "PAID" quando o PIX for pago (na consulta via GET /transaction/:id, a transação aparece como RECEIVED).

Campo	Tipo	Obrigatoriedade	Descrição
paymentMethod	string	Obrigatório	`pix` ou `credit_card`
amount	number	Obrigatório	Valor total da transação em REAIS (incluindo todos os itens)
customer	object	Obrigatório	Nome completo, documento (CPF/CNPJ), e-mail válido e telefone do cliente (apenas números com DDD, ex.: 67989999519)
items	array	Obrigatório	Array de itens com `title`, `unitPrice`, `quantity`, `tangible` e `externalRef`
card	object	Condicional	Obrigatório quando `paymentMethod` for `credit_card`. Número sem espaços (16 chars), holderName, expirationMonth (2 dígitos), expirationYear (4 dígitos), cvv
installments	number	Condicional	Obrigatório caso `paymentMethod` for igual a `credit_card`
shipping	object	Opcional	Taxa de envio e endereço completo: obrigatório para produtos físicos (`tangible: true`)
externalId	string	Opcional	Seu ID interno do pedido para rastreamento
subsellerCnpj	string	Opcional*	CNPJ do subseller, sem pontuações ou espaços. ex.: `44339024000144` (Obrigatório em alguns casos)
subsellerName	string	Opcional*	Nome do subseller, ex.: `Casa de Bolos LTDA` (Obrigatório em alguns casos)
subsellerId	string	Opcional*	ID do subseller na sua base (Obrigatório em alguns casos)
subsellerCep	string	Opcional*	CEP do CNPJ do subseller, sem pontuações ou espaços. ex.: `66200577` (Obrigatório em alguns casos)
postbackUrl	string	Opcional	URL única que receberá o postback de confirmação da transação
postbackUrls	array	Opcional	(array de strings): Endpoints adicionais que receberão o postback. Use quando precisar de mais de um destino; recomendamos 1 URL se possível
checkoutId	string	Opcional	ID do checkout caso não queira utilizar o próprio ID da PHOENIX
shopUrl	string	Opcional	URL antes do checkout do usuário
checkoutUrl	string	Opcional	URL do checkout do usuário
metadata	string	Opcional	Metadado adicional em formato string para seus registros
ip	string	Opcional	IP do cliente no checkout, ex.: `155.53.5.173`
userAgent	string	Opcional	User agent do cliente no checkout

Body da Requisição · PIX

{
  "paymentMethod": "pix",
  "amount": 400,
  "customer": {
    "name": "José da Silva",
    "document": {
      "number": "12345678909",
      "type": "cpf"
    },
    "email": "jose.silva@example.com",
    "phone": "67989999519"
  },
  "items": [{
    "title": "Camisa Polo Premium",
    "unitPrice": 200.25,
    "quantity": 2,
    "tangible": true,
    "externalRef": "SKU12345"
  }],
  "externalId": "ORD-987654321",
  "shipping": {
    "fee": 20,
    "address": {
      "street": "Rua das Flores",
      "streetNumber": "123",
      "complement": "Apto 45",
      "zipCode": "79002100",
      "neighborhood": "Centro",
      "city": "Campo Grande",
      "state": "MS"
    }
  },
  "postbackUrl": "https://minhaloja.com.br/webhook",
  "checkoutId": "CHK123",
  "metadata": "pedido-test-001",
  "ip": "155.53.5.173",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0)"
}

Resposta 200

{
  "id": "XMANBXBUWHBFYRFQ",
  "status": "PENDING",
  "liquid": 394.50,
  "qrCode": "00020126360014br.gov.bcb.brcode...",
  "retention": 0
}

Campo	Tipo	Descrição
id	string	ID da transação criada no PHOENIX. Guarde para consultas futuras.
status	string	Status da transação: `CONFIRMED`/`REFUSED` (cartão) ou `PENDING` (pix). O webhook enviará `status: "PAID"` quando o pix for pago.
liquid	number	Valor líquido em REAIS a receber pela transação: o valor total menos as taxas da plataforma
qrCode	string	Código copia-e-cola do PIX. Retornado em todas as transações, inclusive cartão de crédito: ignore-o quando `paymentMethod` for `credit_card`
retention	number	Valor retido no SALDO PROTEGIDO da plataforma. Atualmente sempre `0`.

POST /pixOut

Solicita um pix-out

Esse endpoint permite que você solicite um pix-out. A requisição é processada de forma assíncrona. Utilize postbackUrls para receber atualizações de status quando o saque for concluído ou falhar.

Campo	Tipo	Obrigatoriedade	Descrição
pixKey	string	Obrigatório	Chave pix para solicitar o pix out
pixKeyType	string	Opcional	Tipo da chave pix: `email` \| `phone` \| `evp` \| `cpf` \| `cnpj`. Detectado automaticamente a partir da chave quando omitido
amount	number	Obrigatório	Valor em reais do pix out
postbackUrls	array	Opcional	(array de strings): Endpoints que irão receber postback das transações. Recomendamos usar 1 postback se possível
description	string	Opcional	Descrição do pix-out
externalId	string	Opcional	ID externo para acompanhamento

Body da Requisição

{
  "pixKey": "manoelsouza@gmail.com",
  "pixKeyType": "email",
  "amount": 150.50,
  "description": "Saque de fundo",
  "externalId": "PIX-OUT-001",
  "postbackUrls": [
    "https://minhaloja.com.br/pix-webhook"
  ]
}

Resposta 200

{
  "status": "processing",
  "id": "Id da solicitação de pix-out nos sistemas PHOENIX"
}

200	`{"status": "processing", "id": "..."}`: saque aceito e enviado para processamento
200	`{"status": "awaiting_approval", "id": "...", "requiresApproval": true}`: contas com aprovação manual habilitada: o saque fica pendente até aprovação de um administrador
401	Credenciais inválidas ou saque bloqueado para a conta
402	`{"error": "Saldo insuficiente"}`: o saldo disponível não cobre o valor do saque mais as taxas
403	Valor excede o limite diário de PIX-OUT, ou conta sem API habilitada / KYC pendente: o corpo `{"error": "..."}` detalha o motivo

Webhook do Pix-Out Enviado para cada URL em postbackUrls (até 5 URLs) quando o status mudar

Campo	Tipo	Descrição
webhookId	string	Identificador do disparo do webhook: pode ser um ID aleatório ou repetir o `transactionId`, dependendo da etapa do saque
transactionId	string	ID da solicitação de pix-out nos sistemas PHOENIX
status	"PAID" \| "FAILED" \| "PENDING" \| "REFUNDED"	`PAID`: saque processado com sucesso (`balanceUpdated: true`) · `FAILED`: saque não pôde ser processado, valor devolvido ao saldo (`balanceUpdated: false`, líquido zero pra você) · `PENDING`: saque aceito pelo provedor, aguardando confirmação (`balanceUpdated: false`) · `REFUNDED`: saque estornado após concluído, valor devolvido ao saldo (`balanceUpdated: true`)
balanceUpdated	boolean	Indica se o saldo da conta foi atualizado após o processamento do pix-out
endToEndId	string	ID end-to-end do PIX no Banco Central, campo opcional: dependendo do provedor de liquidação, o webhook `PAID` pode vir sem este campo ou com string vazia. Trate como opcional na sua integração

Payload do Webhook · Pix-Out POST

{
  "webhookId": "QJZKPLMWXRTYBNAD",
  "transactionId": "PIXOUTID12345XYZ",
  "status": "PAID",
  "balanceUpdated": true,
  "endToEndId": "E00416968202510122026AkMT0C8eVEP"
}

GET /transactions

Retorna transações do usuário

Retorna as transações do usuário autenticado ordenadas por transactionDate desc e __name__ desc. Use lastDocId para avançar a paginação (cursor-based). A API busca limit+1 itens internamente para determinar se há próxima página (hasNextPage). Somente transações de recebimento (PIX e cartão) são listadas: solicitações de pix-out não aparecem neste endpoint.

Parâmetro	Tipo	Obrigatoriedade	Descrição
limit	number	Opcional	Número máximo de itens retornados. Padrão: `20`
lastDocId	string	Opcional	Cursor (ID do último documento da página anterior) para continuar a paginação

Requisição

GET /transactions?limit=20&lastDocId=

Content-Type: application/json
userId: SEU_USER_ID_AQUI
apiKey: sua-api-key

Resposta 401

{
  "error": "string"
}

Resposta 500

{
  "status": "string",
  "error": "string",
  "message": "string"
}

Resposta 200

{
  "status": "success",
  "data": {
    "transactions": [
      {
        "id": "ID do documento (Firestore)",
        "amount": 400,
          "transactionId": "ID único da transação no PHOENIX",
          "paymentMethod": "pix | credit_card",
          "transactionDate": "2025-10-12T20:26:03.423Z",
          "transactionTime": 1760300763423,
          "status": "PENDING | CONFIRMED | REFUSED | RECEIVED | REFUNDED",
          "externalId": "ID externo do cliente",
          "paidWebhookSent": true,
          "errorPaidWebhookSent": false,
          "pixQrCode": "Código QR do PIX (quando aplicável)",
          "repass": 2.46,
          "customerCpf": "string",
          "customerEmail": "string",
          "customerPhone": "string",
          "customer": {
            "name": "string",
            "email": "email format",
            "phone": "string",
            "document": { "number": "string", "type": "cpf | cnpj" }
          },
          "shipping": {
            "fee": 20,
            "address": {
              "street": "string", "streetNumber": "string",
              "complement": "string", "zipCode": "string",
              "neighborhood": "string", "city": "string",
              "state": "string"
            }
          },
          "subsellerCnpj": "string",
          "subsellerId": "string",
          "subsellerName": "string"
        }
      ],
      "pagination": {
        "limit": 20,
        "count": "Quantidade de itens na página atual",
        "hasNextPage": false,
        "hasPrevPage": false,
        "nextCursor": "ID do último doc desta página (use como lastDocId)"
      }
    }
  }

GET /transaction/{transactionId}

Retorna os dados de uma transação

Esse endpoint permite que você recupere os dados de uma transação específica pelo ID. Retorna todos os metadados da transação incluindo cliente, itens, envio, dados de pagamento e status dos webhooks. A resposta vem embrulhada em {"status": "success", "data": {...}}: campos nulos ou ausentes são omitidos.

Parâmetro	Tipo	Obrigatoriedade	Descrição
transactionId	string	Obrigatório	ID da transação a ser consultada

Resposta 200

{
    "status": "success",
    "data": {
      "transactionId": "XMANBXBUWHBFYRFQ",
      "externalId": "ORD-987654321",
      "checkoutId": "CHK123",
      "status": "RECEIVED",
      "amount": 400,
    "paymentMethod": "pix",
    "transactionDate": "2025-10-12T20:26:03.423Z",
    "transactionTime": 1760300763423,
    "customer": {
      "name": "José da Silva",
      "email": "jose.silva@example.com",
      "phone": "67989999519",
      "document": { "number": "12345678909", "type": "cpf" }
    },
    "items": [{
      "title": "Camisa Polo Premium",
      "unitPrice": 200.25,
      "quantity": 2,
      "tangible": true,
      "externalRef": "SKU12345"
    }],
    "shipping": {
      "fee": 20,
      "address": {
        "street": "Rua das Flores",  "streetNumber": "123",
        "complement": "Apto 45",       "zipCode": "79002100",
        "neighborhood": "Centro",      "city": "Campo Grande",
        "state": "MS"
      }
    },
    "pixQrCode": "Código QR do PIX (quando aplicável)",
    "repass": 2.46,
    "endToEndId": "E00416968202510122026AkMT0C8eVEP",
    "pixAcquirer": "Adquirente PIX da transação (quando aplicável)",
    "partnerTransactionId": "ID da transação no parceiro (quando aplicável)",
    "userId": "SEU_USER_ID_AQUI",
    "userName": "Manoel Souza",
    "userEmail": "manoelsouza@gmail.com",
    "userPhone": "67981112559",
    "userCpfCnpj": "01299986660",
    "userAgency": "0001",
    "userAccount": "54466325-0",
    "subsellerCnpj": "44339024000144",
    "subsellerName": "Casa de Bolos LTDA",
    "subsellerId": "subseller123",
    "subsellerCep": "66200577",
    "shopUrl": "https://minhaloja.com.br",
    "checkoutUrl": "https://minhaloja.com.br/checkout/987654",
    "postbackUrls": ["https://minhaloja.com.br/webhook"],
    "metadata": "pedido-test-001",
    "ip": "155.53.5.173",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
    "paidWebhookSent": true,
    "errorPaidWebhookSent": false,
    "refundWebhookSent": false
  }
}

Resposta 401

{ "status": "error", "error": "Unauthorized" }

Resposta 404

{ "status": "error", "error": "Transaction not found" }

GET /balance

Verifica o saldo de uma conta PHOENIX

Ver saldo de conta PHOENIX. Utilize antes de solicitar um pix-out para confirmar saldo disponível.

Requisição

GET /balance

Content-Type: application/json
userId: SEU_USER_ID_AQUI
apiKey: sua-api-key

Resposta 200

{
  "status": "success",
  "amount": 5000.75
}

BaaS

BaaS: Subcontas e Transferências Internas

O módulo BaaS permite que a sua conta master crie e gerencie subcontas via API e movimente valores entre contas do banco com transferências internas. Cada subconta recebe o próprio userId e apiKey na criação e opera 100% via API: todas as demais rotas desta documentação (/createTransaction, /pixOut, /transactions, /transaction/:id, /balance) funcionam normalmente para subcontas, autenticadas com as credenciais da própria subconta.

Pré-requisito: as rotas BaaS só funcionam para contas master com a flag baasEnabled ativa. A habilitação é feita com o time PHOENIX: solicite pelo seu canal de atendimento. Sem a flag, qualquer rota BaaS responde 403 com {"error": "BaaS não habilitado para esta conta"}. Todas as rotas BaaS exigem os headers userId e apiKey da conta master, a mesma autenticação das demais rotas.

	Endpoint	Descrição
POST	/accounts	Cria uma subconta vinculada à conta master: retorna `userId` e `apiKey` próprios
GET	/accounts	Lista as subcontas da conta master com paginação por cursor
GET	/accounts/:accountId	Consulta uma subconta específica, incluindo o saldo atual
POST	/internalTransfer	Transfere valores entre contas do banco: master, subcontas ou qualquer conta ativa
POST	/pixKeys	Cadastra uma chave PIX na conta autenticada (master ou subconta)
GET	/pixKeys	Lista as chaves PIX da conta autenticada, com a contagem e o teto da conta
POST	/accounts/:accountId/pixKeys	Cadastra uma chave PIX em uma subconta do master, com as credenciais do master
GET	/accounts/:accountId/pixKeys	Lista as chaves PIX de uma subconta do master

Guarde o apiKey da subconta com segurança. Ele é retornado na criação (POST /accounts) e na listagem (GET /accounts). Trate-o como segredo: nunca exponha em código client-side nem em repositórios públicos. A subconta não possui login no painel: ela opera exclusivamente via API com essas credenciais.

POST /accounts

Criar subconta

Cria uma subconta vinculada à conta master autenticada. A subconta nasce ativa, com KYC aprovado via master, e opera exclusivamente via API com o userId e o apiKey retornados nesta resposta. Requer os headers userId e apiKey da conta master com baasEnabled habilitado. O cpfCnpj é único no banco: se já existir uma conta com o mesmo documento, a API responde 409.

Campo	Tipo	Obrigatoriedade	Descrição
name	string	Obrigatório	Nome completo ou razão social do titular da subconta
cpfCnpj	string	Obrigatório	CPF (11 dígitos) ou CNPJ (14 dígitos), apenas números. Deve ser único: documento já cadastrado retorna `409`
email	string	Obrigatório	E-mail do titular da subconta
phone	string	Obrigatório	Telefone com DDD, apenas números. ex.: `67989999519`
address	object	Obrigatório	Endereço do titular com `street`, `city`, `state` e `zipCode`
description	string	Opcional	Descrição livre da subconta para os seus registros

Requisição · cURL

curl -X POST https://api.bpx.solutions/accounts \
  -H "Content-Type: application/json" \
  -H "userId: SEU_USER_ID_MASTER" \
  -H "apiKey: sua-api-key-master" \
  -d '{
    "name": "Maria Oliveira ME",
    "cpfCnpj": "44339024000144",
    "email": "financeiro@mariaoliveira.com.br",
    "phone": "67989999519",
    "address": {
      "street": "Rua das Flores, 123",
      "city": "Campo Grande",
      "state": "MS",
      "zipCode": "79002100"
    },
    "description": "Subconta do lojista Maria Oliveira"
  }'

Resposta 201

{
  "status": "success",
  "account": {
    "userId": "A1B2C3D4E5F6G7H8I9J0K1L2M3N4",
    "apiKey": "kf93jd8shd72hf94jg82ldpa03mcbz",
    "name": "Maria Oliveira ME",
    "cpfCnpj": "44339024000144",
    "email": "financeiro@mariaoliveira.com.br",
    "agency": "0001",
    "accountNumber": "54466325",
    "validatorDigit": "0",
    "active": true,
    "createdAt": "2026-08-04T14:22:07.113Z"
  }
}

Campo	Tipo	Descrição
userId	string	Identificador da subconta na PHOENIX. Use nos headers para operar a subconta em qualquer rota da API
apiKey	string	Chave secreta de API da subconta. Retornada na criação e na listagem: guarde com segurança
agency	string	Agência da subconta: `0001`
accountNumber	string	Número da conta da subconta (8 dígitos)
validatorDigit	string	Dígito verificador do número da conta
active	boolean	`true`: a subconta nasce ativa e pronta para operar via API
createdAt	string	Data e hora de criação da subconta

400	Validação do corpo: campo obrigatório ausente ou inválido (ex.: `cpfCnpj` fora de 11 ou 14 dígitos). O corpo `{"error": "..."}` detalha o motivo
401	Credenciais do master ausentes ou inválidas
403	`{"error": "BaaS não habilitado para esta conta"}`: conta master sem a flag `baasEnabled`
409	`cpfCnpj` já cadastrado em outra conta do banco: o documento da subconta deve ser único

GET /accounts

Listar subcontas

Lista as subcontas vinculadas à conta master autenticada, com paginação por cursor (mesmo padrão de /transactions). Requer os headers userId e apiKey da conta master com baasEnabled habilitado. Cada item da lista inclui o apiKey da subconta: guarde-o com segurança.

Parâmetro	Tipo	Obrigatoriedade	Descrição
limit	number	Opcional	Número máximo de itens retornados. Padrão: `20`. Máximo: `100`
lastDocId	string	Opcional	Cursor (ID do último documento da página anterior) para continuar a paginação

Requisição · cURL

curl "https://api.bpx.solutions/accounts?limit=20&lastDocId=" \
  -H "userId: SEU_USER_ID_MASTER" \
  -H "apiKey: sua-api-key-master"

Resposta 200

{
  "status": "success",
  "data": {
    "accounts": [
      {
        "userId": "A1B2C3D4E5F6G7H8I9J0K1L2M3N4",
        "apiKey": "kf93jd8shd72hf94jg82ldpa03mcbz",
        "name": "Maria Oliveira ME",
        "cpfCnpj": "44339024000144",
        "email": "financeiro@mariaoliveira.com.br",
        "phone": "67989999519",
        "agency": "0001",
        "accountNumber": "54466325",
        "active": true,
        "createdAt": "2026-08-04T14:22:07.113Z"
      }
    ],
    "pagination": {
      "limit": 20,
      "count": 1,
      "hasNextPage": false,
      "nextCursor": "A1B2C3D4E5F6G7H8I9J0K1L2M3N4"
    }
  }
}

401	Credenciais do master ausentes ou inválidas
403	`{"error": "BaaS não habilitado para esta conta"}`: conta master sem a flag `baasEnabled`

GET /accounts/{accountId}

Consultar subconta

Retorna os dados de uma subconta específica, incluindo o saldo atual (balance). Requer os headers userId e apiKey da conta master com baasEnabled habilitado. A subconta precisa pertencer à conta master autenticada: subconta de outro master responde 404.

Parâmetro	Tipo	Obrigatoriedade	Descrição
accountId	string	Obrigatório	`userId` da subconta a ser consultada (retornado na criação e na listagem)

Requisição · cURL

curl https://api.bpx.solutions/accounts/A1B2C3D4E5F6G7H8I9J0K1L2M3N4 \
  -H "userId: SEU_USER_ID_MASTER" \
  -H "apiKey: sua-api-key-master"

Resposta 200

{
  "status": "success",
  "account": {
    "userId": "A1B2C3D4E5F6G7H8I9J0K1L2M3N4",
    "apiKey": "kf93jd8shd72hf94jg82ldpa03mcbz",
    "name": "Maria Oliveira ME",
    "cpfCnpj": "44339024000144",
    "email": "financeiro@mariaoliveira.com.br",
    "phone": "67989999519",
    "agency": "0001",
    "accountNumber": "54466325",
    "active": true,
    "createdAt": "2026-08-04T14:22:07.113Z",
    "balance": 1250.75
  }
}

401	Credenciais do master ausentes ou inválidas
403	`{"error": "BaaS não habilitado para esta conta"}`: conta master sem a flag `baasEnabled`
404	`{"error": "Subaccount not found"}`: a subconta não existe ou não pertence à conta master autenticada

POST /internalTransfer

Transferência interna entre contas

Transfere valores entre contas do banco. A conta de origem é sempre a conta autenticada: use os headers userId e apiKey da conta que envia o dinheiro (conta principal ou subconta, cada uma com as próprias credenciais). Qualquer conta do banco pode transferir para qualquer outra conta do banco: o destino (account_Id) é o userId de qualquer conta ativa. Não exige a flag baasEnabled. A execução é síncrona: a resposta já retorna COMPLETED. Se o crédito no destino falhar depois do débito na origem, o valor é devolvido automaticamente à origem e a API responde 502.

Campo	Tipo	Obrigatoriedade	Descrição
account_Id	string	Obrigatório	`userId` da conta de destino: qualquer conta ativa do banco. Não pode ser igual à origem
amount	number	Obrigatório	Valor em reais, maior que zero, com 2 casas decimais
description	string	Opcional	Descrição da transferência para os seus registros
webhookUrls	array	Opcional	(array de strings) Até 5 URLs `https` que receberão o webhook de confirmação da transferência

Requisição · cURL

curl -X POST https://api.bpx.solutions/internalTransfer \
  -H "Content-Type: application/json" \
  -H "userId: USERID_DA_CONTA_DE_ORIGEM" \
  -H "apiKey: apikey-da-conta-de-origem" \
  -d '{
    "account_Id": "USERID_DA_CONTA_DESTINO",
    "amount": 150.50,
    "description": "Repasse semanal",
    "webhookUrls": ["https://minhaloja.com.br/transfer-webhook"]
  }'

Resposta 200

{
  "status": "COMPLETED",
  "id": "AQZKPLMWXRTYBNAD",
  "fromAccountId": "USERID_DA_CONTA_DE_ORIGEM",
  "toAccountId": "USERID_DA_CONTA_DESTINO",
  "amount": 150.50
}

400	Validação do corpo: campo obrigatório ausente, `amount` inválido ou conta de origem igual à conta de destino
401	Credenciais da conta de origem ausentes ou inválidas
402	`{"error": "Saldo insuficiente"}`: o saldo da conta de origem não cobre o valor da transferência
403	Conta de origem sem a API habilitada ou conta de destino inativa
404	Conta de destino não encontrada
502	`{"error": "Falha na transferência, valor devolvido"}`: o crédito no destino falhou depois do débito na origem; o valor foi devolvido automaticamente à conta de origem

BaaS

Webhook de Transferência Interna

Quando a transferência interna é concluída, a PHOENIX envia uma requisição POST para cada URL informada em webhookUrls no POST /internalTransfer. A entrega é não-bloqueante: os disparos acontecem sem atrasar a resposta da API. Cada disparo expira em 8 segundos. Apenas URLs https são aceitas, com no máximo 5 URLs por transferência.

Campo	Tipo	Descrição
webhookId	string	Identificador aleatório do disparo do webhook (16 caracteres A-Z)
transactionId	string	ID da transferência: o mesmo `id` retornado pelo `POST /internalTransfer`
status	"PAID"	Enviado quando a transferência foi concluída com sucesso
type	"internalTransfer"	Identifica o tipo do evento
amount	number	Valor transferido em reais
fromAccountId	string	`userId` da conta de origem do débito
toAccountId	string	`userId` da conta de destino do crédito
balanceUpdated	boolean	`true`: os saldos já estão atualizados quando o webhook é disparado

Payload recebido pelo seu servidor · POST application/json

{
  "webhookId": "KQZRPLMWXBTYCNAD",
  "transactionId": "AQZKPLMWXRTYBNAD",
  "status": "PAID",
  "type": "internalTransfer",
  "amount": 150.50,
  "fromAccountId": "USERID_DA_SUBCONTA_ORIGEM",
  "toAccountId": "USERID_DA_CONTA_DESTINO",
  "balanceUpdated": true
}

Responda com HTTP 2xx rapidamente: o disparo expira em 8 segundos. Antes de processar o evento, valide o transactionId comparando com o id retornado pelo POST /internalTransfer na sua base de dados.

Chaves PIX

Cadastro de chaves PIX da conta autenticada e das subcontas do master. As duas rotas de conta própria (POST /pixKeys e GET /pixKeys) funcionam para qualquer conta ativa e não exigem a flag baasEnabled: só as rotas /accounts/:accountId/pixKeys, que agem sobre uma subconta, exigem uma conta master com BaaS habilitado.

Ainda não existe exclusão de chave. O contrato atual tem apenas criação e listagem, então cada chave cadastrada ocupa uma vaga em definitivo: 5 chaves para conta PF e 20 para PJ. Não gaste vaga com teste em produção: para experimentar, use o /sandbox, onde POST /sandbox/reset devolve todas as vagas.

POST /pixKeys

Criar chave PIX

Cadastra uma chave PIX na conta autenticada. Funciona tanto para a conta master quanto para uma subconta BaaS: use os headers userId e apiKey da própria conta que vai receber a chave. Não exige a flag baasEnabled. Os tipos aceitos são evp (aleatória), cpf, cnpj, email e phone. Cada chave é única no banco: uma chave já cadastrada responde 409.

Titularidade obrigatória: a chave só pode ser um dado do próprio titular, já cadastrado na conta. cpf e cnpj conferem contra o cpfCnpj da conta, email contra o email e phone contra o phone. Dado de terceiro, ou diferente do cadastro, é recusado com 400. Conta PF (11 dígitos) não cadastra chave cnpj e conta PJ (14 dígitos) não cadastra chave cpf. Para usar um e-mail ou telefone diferente do cadastral, atualize o cadastro da conta antes.

Limite de chaves por conta: 5 chaves para conta PF e 20 chaves para conta PJ. Ao estourar o limite, a API responde 429. Não existe exclusão de chave hoje, então vaga usada é vaga perdida: não gaste vaga com teste em produção. No /sandbox a chave nasce REGISTERED com dictRegistered: true, o envelope traz sandbox: true e a unicidade é escopada ao seu próprio sandbox (a mesma chave pode existir no sandbox de outro integrador, o que em produção seria 409). Use o sandbox para exercitar o fluxo e POST /sandbox/reset para devolver todas as vagas.

Campo	Tipo	Obrigatoriedade	Descrição
keyType	string	Obrigatório	Tipo da chave: `evp`, `cpf`, `cnpj`, `email` ou `phone`. Qualquer outro valor retorna `400`
key	string	Condicional	Valor da chave. A obrigatoriedade depende do `keyType`: veja a tabela de regras abaixo

keyType	Campo key	Regra de validação
evp	Não enviar	Chave aleatória: o servidor gera um UUID. Enviar `key` junto retorna `400`
cpf	Opcional	Se enviado, precisa ser exatamente o `cpfCnpj` da conta. Se omitido, a API usa o documento da própria conta. Exige conta PF (11 dígitos)
cnpj	Opcional	Mesma regra do `cpf`, exigindo conta PJ (14 dígitos)
email	Obrigatório	E-mail válido, com no máximo 77 caracteres, normalizado para minúsculo. Precisa ser o mesmo e-mail cadastrado na conta: e-mail diferente do cadastro é `400`
phone	Obrigatório	Celular no formato E.164: `+55` + DDD + número (10 ou 11 dígitos após o `+55`). Você pode enviar só os dígitos (ex.: `67989999519`) que a API normaliza para `+5567989999519`. Precisa ser o mesmo telefone cadastrado na conta: telefone diferente do cadastro é `400`

Requisição · cURL

curl -X POST https://api.bpx.solutions/pixKeys \
  -H "Content-Type: application/json" \
  -H "userId: SEU_USER_ID" \
  -H "apiKey: sua-api-key" \
  -d '{
    "keyType": "evp"
  }'

# Chave de e-mail
curl -X POST https://api.bpx.solutions/pixKeys \
  -H "Content-Type: application/json" \
  -H "userId: SEU_USER_ID" \
  -H "apiKey: sua-api-key" \
  -d '{
    "keyType": "email",
    "key": "financeiro@mariaoliveira.com.br"
  }'

Resposta 201

{
  "status": "success",
  "pixKey": {
    "id": "3F9AC12B7E4D08A6F51C93B27DE640A8C1F5B93D",
    "accountId": "A1B2C3D4E5F6G7H8I9J0K1L2M3N4",
    "keyType": "evp",
    "key": "e7c1f0a2-5b44-4c9e-9a31-2f6d8b0c7d15",
    "status": "PENDING",
    "dictRegistered": false,
    "createdAt": "2026-08-13T12:00:00.000Z"
  }
}

Campo	Tipo	Descrição
id	string	Identificador único da chave PIX na PHOENIX. Não existe consulta por id: para reler a chave, use `GET /pixKeys`
accountId	string	`userId` da conta dona da chave
keyType	string	Tipo cadastrado: `evp`, `cpf`, `cnpj`, `email` ou `phone`
key	string	Valor final da chave, já normalizado. Em `evp` é o UUID gerado pelo servidor
status	string	Situação do registro da chave
dictRegistered	boolean	Indica se o registro da chave já foi confirmado
createdAt	string	Data e hora do cadastro da chave

400	Validação do corpo: `keyType` ausente ou inválido, `key` faltando ou malformada, `key` enviada junto com `evp`, ou documento diferente do titular da conta. O corpo `{"error": "..."}` detalha o motivo
401	Credenciais ausentes ou inválidas nos headers `userId` e `apiKey`
403	Conta sem API liberada (`apiEnabled`) ou inativa (KYC pendente). Para subconta BaaS, também vale o bloqueio herdado da conta master
409	Chave já cadastrada: cada chave PIX é única no banco, em qualquer conta
429	Limite de chaves da conta atingido: 5 chaves para conta PF e 20 chaves para conta PJ

GET /pixKeys

Listar chaves PIX

Lista todas as chaves PIX cadastradas na conta autenticada, junto com o total (count) e o limite de chaves da conta (limit). Use os headers userId e apiKey da própria conta (master ou subconta). Não exige a flag baasEnabled e não tem paginação: o retorno já traz todas as chaves da conta.

Parâmetro	Tipo	Obrigatoriedade	Descrição
userId	header	Obrigatório	Identificador da conta que quer listar as próprias chaves
apiKey	header	Obrigatório	Chave secreta de API da mesma conta. Esta rota não recebe query string nem corpo

Requisição · cURL

curl https://api.bpx.solutions/pixKeys \
  -H "userId: SEU_USER_ID" \
  -H "apiKey: sua-api-key"

Resposta 200

{
  "status": "success",
  "data": {
    "pixKeys": [
      {
        "id": "3F9AC12B7E4D08A6F51C93B27DE640A8C1F5B93D",
        "accountId": "A1B2C3D4E5F6G7H8I9J0K1L2M3N4",
        "keyType": "evp",
        "key": "e7c1f0a2-5b44-4c9e-9a31-2f6d8b0c7d15",
        "status": "PENDING",
        "dictRegistered": false,
        "createdAt": "2026-08-13T12:00:00.000Z"
      },
      {
        "id": "B71D4E0C9A26F385C0417BDE92F6A5083C1D7E44",
        "accountId": "A1B2C3D4E5F6G7H8I9J0K1L2M3N4",
        "keyType": "email",
        "key": "financeiro@mariaoliveira.com.br",
        "status": "PENDING",
        "dictRegistered": false,
        "createdAt": "2026-08-13T12:04:31.882Z"
      }
    ],
    "count": 2,
    "limit": 20
  }
}

Campo	Tipo	Descrição
data.pixKeys	array	Lista das chaves da conta. Cada item tem os mesmos campos da resposta de criação: `id`, `accountId`, `keyType`, `key`, `status`, `dictRegistered` e `createdAt`
data.count	number	Quantidade de chaves já cadastradas na conta
data.limit	number	Limite de chaves da conta: `5` para conta PF e `20` para conta PJ. Com `count` igual ao `limit`, novos cadastros retornam `429`

401	Credenciais ausentes ou inválidas nos headers `userId` e `apiKey`
403	Conta sem API liberada (`apiEnabled`) ou inativa (KYC pendente). Para subconta BaaS, também vale o bloqueio herdado da conta master

POST /accounts/{accountId}/pixKeys

Criar chave PIX em subconta

Cadastra uma chave PIX em uma subconta, autenticando com as credenciais da conta master. Requer os headers userId e apiKey do master com baasEnabled habilitado, e a subconta indicada em accountId precisa pertencer a esse master: subconta de outro master responde 404. As regras de tipo, titularidade, unicidade e limite são exatamente as mesmas do POST /pixKeys, aplicadas sobre os dados da subconta.

A chave é sempre do titular da subconta. Chave cpf ou cnpj precisa ser o documento cadastrado na própria subconta, nunca o documento do master nem de terceiro. Se omitir o campo key nesses tipos, a API usa o cpfCnpj da subconta. O limite continua sendo 5 chaves para subconta PF e 20 para subconta PJ, contado por subconta.

Campo	Tipo	Obrigatoriedade	Descrição
accountId	string	Obrigatório	(path) `userId` da subconta que vai receber a chave. Precisa ser subconta da master autenticada
keyType	string	Obrigatório	Tipo da chave: `evp`, `cpf`, `cnpj`, `email` ou `phone`
key	string	Condicional	Valor da chave, seguindo a mesma tabela de regras do `POST /pixKeys`: ausente em `evp`, opcional em `cpf` e `cnpj`, obrigatório em `email` e `phone`

Requisição · cURL

curl -X POST https://api.bpx.solutions/accounts/A1B2C3D4E5F6G7H8I9J0K1L2M3N4/pixKeys \
  -H "Content-Type: application/json" \
  -H "userId: SEU_USER_ID_MASTER" \
  -H "apiKey: sua-api-key-master" \
  -d '{
    "keyType": "cnpj"
  }'

# Chave de celular da subconta
curl -X POST https://api.bpx.solutions/accounts/A1B2C3D4E5F6G7H8I9J0K1L2M3N4/pixKeys \
  -H "Content-Type: application/json" \
  -H "userId: SEU_USER_ID_MASTER" \
  -H "apiKey: sua-api-key-master" \
  -d '{
    "keyType": "phone",
    "key": "67989999519"
  }'

Resposta 201

{
  "status": "success",
  "pixKey": {
    "id": "9C40E7B21D5A83F60B94C7E1052DA6F38B7C4901",
    "accountId": "A1B2C3D4E5F6G7H8I9J0K1L2M3N4",
    "keyType": "cnpj",
    "key": "44339024000144",
    "status": "PENDING",
    "dictRegistered": false,
    "createdAt": "2026-08-13T12:10:44.507Z"
  }
}

Campo	Tipo	Descrição
id	string	Identificador único da chave PIX na PHOENIX
accountId	string	`userId` da subconta dona da chave: o mesmo enviado no path
keyType	string	Tipo cadastrado: `evp`, `cpf`, `cnpj`, `email` ou `phone`
key	string	Valor final da chave, já normalizado. Em `cpf` e `cnpj` é o documento da própria subconta
status	string	Situação do registro da chave
dictRegistered	boolean	Indica se o registro da chave já foi confirmado
createdAt	string	Data e hora do cadastro da chave

400	Validação do corpo: `keyType` ausente ou inválido, `key` faltando ou malformada, `key` enviada junto com `evp`, ou documento diferente do titular da subconta
401	Credenciais do master ausentes ou inválidas
403	`{"error": "BaaS não habilitado para esta conta"}`: conta master sem a flag `baasEnabled`. Também responde `403` se a master estiver inativa ou sem API liberada
404	`{"error": "Subaccount not found"}`: a subconta não existe ou não pertence à conta master autenticada
409	Chave já cadastrada: cada chave PIX é única no banco, em qualquer conta
429	Limite de chaves da subconta atingido: 5 chaves para PF e 20 chaves para PJ

GET /accounts/{accountId}/pixKeys

Listar chaves PIX de subconta

Lista as chaves PIX de uma subconta, autenticando com as credenciais da conta master. Requer os headers userId e apiKey do master com baasEnabled habilitado, e a subconta precisa pertencer a esse master: subconta de outro master responde 404. O retorno é o mesmo do GET /pixKeys, com count e limit calculados sobre a subconta.

Parâmetro	Tipo	Obrigatoriedade	Descrição
accountId	string	Obrigatório	(path) `userId` da subconta a ser consultada. Precisa ser subconta da master autenticada

Requisição · cURL

curl https://api.bpx.solutions/accounts/A1B2C3D4E5F6G7H8I9J0K1L2M3N4/pixKeys \
  -H "userId: SEU_USER_ID_MASTER" \
  -H "apiKey: sua-api-key-master"

Resposta 200

{
  "status": "success",
  "data": {
    "pixKeys": [
      {
        "id": "9C40E7B21D5A83F60B94C7E1052DA6F38B7C4901",
        "accountId": "A1B2C3D4E5F6G7H8I9J0K1L2M3N4",
        "keyType": "cnpj",
        "key": "44339024000144",
        "status": "PENDING",
        "dictRegistered": false,
        "createdAt": "2026-08-13T12:10:44.507Z"
      }
    ],
    "count": 1,
    "limit": 20
  }
}

Campo	Tipo	Descrição
data.pixKeys	array	Lista das chaves da subconta, com os mesmos campos da resposta de criação
data.count	number	Quantidade de chaves já cadastradas na subconta
data.limit	number	Limite de chaves da subconta: `5` para PF e `20` para PJ

401	Credenciais do master ausentes ou inválidas
403	`{"error": "BaaS não habilitado para esta conta"}`: conta master sem a flag `baasEnabled`. Também responde `403` se a master estiver inativa ou sem API liberada
404	`{"error": "Subaccount not found"}`: a subconta não existe ou não pertence à conta master autenticada

Sandbox

Sandbox: Ambiente de Testes

O Sandbox é um ambiente 100% simulado para você desenvolver e testar a integração completa sem depender da liberação de produção e sem movimentar dinheiro real. As credenciais do sandbox são totalmente isoladas das credenciais de produção, as transações ficam em uma collection separada e o saldo é fictício: cada conta sandbox nasce com R$ 10.000,00 de saldo simulado. Todas as rotas usam o prefixo /sandbox na mesma URL base: https://api.bpx.solutions/sandbox.

Auto-confirmação: as transações simuladas se confirmam sozinhas. Um pix-in vira PAID em aproximadamente 15 segundos e um pix-out em aproximadamente 10 segundos: ambos disparam o postback normalmente, com o campo sandbox: true. Para testes instantâneos, use POST /sandbox/simulate/pay/:id.

O QR Code do sandbox não é pagável. O código EMV retornado é sintético, gerado apenas para você testar a exibição no seu checkout: nenhum app de banco consegue pagá-lo. O pagamento é simulado pelo próprio ambiente (auto-confirmação ou simulate/pay).

Funciona mesmo com a produção bloqueada. O POST /sandbox/provision usa as suas credenciais de produção só para identificar a conta: ele não exige API liberada nem KYC aprovado. Ou seja, você integra e testa tudo no sandbox enquanto a sua conta de produção ainda está em análise, e nenhuma chamada aqui movimenta valor real.

Webhook só chega em endereço público. O postback do sandbox segue as mesmas regras de segurança da produção: a URL precisa ser http(s) com host público. localhost, 127.0.0.1 e faixas privadas (10.x, 192.168.x, 172.16-31.x, 169.254.x) são bloqueadas. Para receber na sua máquina durante o desenvolvimento, use um túnel como ngrok ou Cloudflare Tunnel.

	Endpoint	Descrição
POST	/sandbox/provision	Gera (ou retorna) as credenciais sandbox da sua conta. Idempotente: sempre devolve as mesmas credenciais
GET	/sandbox/balance	Consulta o saldo simulado da conta sandbox
POST	/sandbox/createTransaction	Cria uma transação PIX simulada: QR sintético, auto-`PAID` em ~15s com postback
POST	/sandbox/pixOut	Solicita um pix-out simulado: auto-`PAID` em ~10s com postback
GET	/sandbox/pixOutTransactions	Lista os pix-outs simulados da conta sandbox
POST	/sandbox/pixKeys	Cadastra uma chave PIX simulada. DICT simulado: nasce `REGISTERED` na hora
GET	/sandbox/pixKeys	Lista as chaves PIX simuladas da conta sandbox
POST	/sandbox/accounts/:accountId/pixKeys	Cadastra uma chave PIX de uma subconta simulada, com as credenciais do master
GET	/sandbox/accounts/:accountId/pixKeys	Lista as chaves PIX de uma subconta simulada
GET	/sandbox/transaction/:id	Consulta uma transação simulada pelo ID
POST	/sandbox/simulate/pay/:id	Força o `PAID` imediato de uma transação `PENDING`, sem esperar a auto-confirmação
POST	/sandbox/reset	Apaga todos os mocks da sua conta sandbox e re-seeda o saldo em R$ 10.000,00

Credenciais 100% isoladas. As rotas /sandbox/* aceitam apenas sandboxUserId e sandboxApiKey nos headers userId e apiKey. As credenciais de produção não funcionam nelas (a única exceção é POST /sandbox/provision, que usa as credenciais de produção para gerar as do sandbox), e as credenciais sandbox nunca funcionam nas rotas de produção. O sandbox usa as mesmas taxas configuradas na sua conta: o pix-in credita o valor líquido e o pix-out debita valor mais taxa, igual à produção.

POST /sandbox/provision

Obter credenciais do sandbox

Cria (ou retorna) as credenciais sandbox vinculadas à sua conta. É a única rota do sandbox autenticada com as credenciais de produção: envie o userId e o apiKey de produção nos headers. A chamada é idempotente: chamar de novo sempre retorna as mesmas credenciais, então você pode usá-la também para recuperar um sandboxApiKey perdido.

Header	Tipo	Obrigatoriedade	Descrição
userId	string	Obrigatório	Seu `userId` de produção na PHOENIX.
apiKey	string	Obrigatório	Seu `apiKey` de produção na PHOENIX.

Requisição · cURL

curl -X POST https://api.bpx.solutions/sandbox/provision \
  -H "userId: SEU_USER_ID_DE_PRODUCAO" \
  -H "apiKey: sua-api-key-de-producao"

Resposta 200

{
  "status": "success",
  "sandbox": true,
  "baseUrl": "/sandbox",
  "sandboxUserId": "SANDBOX:KQZJXWMRPLTBAYVGNCHDUFSE",
  "sandboxApiKey": "SBQKWJRTPLMENXAYVGCH",
  "seedBalance": 10000,
  "docs": "https://docs.bpx.solutions",
  "note": "Credenciais 100% isoladas das de produção. Use os headers userid: sandboxUserId e apikey: sandboxApiKey nos endpoints /sandbox/*..."
}

Campo	Tipo	Descrição
sandboxUserId	string	Identificador da conta sandbox, no formato `SANDBOX:` seguido de 24 letras maiúsculas aleatórias. Use no header `userId` das rotas `/sandbox/*`
sandboxApiKey	string	Chave secreta do sandbox, no formato `SB` seguido de 18 letras maiúsculas (a comparação é sensível a maiúsculas). Use no header `apiKey` das rotas `/sandbox/*`
baseUrl	string	Prefixo das rotas do sandbox: `/sandbox`
seedBalance	number	Saldo simulado atual da conta sandbox, em reais: `10000` no primeiro provision (em chamadas seguintes reflete o saldo do momento)
sandbox	boolean	Sempre `true`: marca que a resposta veio do ambiente simulado
docs	string	Link desta documentação
note	string	Instrução rápida de uso das credenciais

401	Credenciais de produção ausentes ou inválidas
403	`{"error": "Sandbox desabilitada para esta conta."}`

GET /sandbox/balance

Consultar saldo simulado

Retorna o saldo simulado da conta sandbox. Mesmo formato do GET /balance de produção, com o campo extra sandbox: true. O saldo começa em R$ 10.000,00: pix-ins pagos creditam o valor líquido e pix-outs debitam valor mais taxa, usando as mesmas taxas da sua conta. Autentique com o sandboxUserId e o sandboxApiKey.

Requisição · cURL

curl https://api.bpx.solutions/sandbox/balance \
  -H "userId: SANDBOX:KQZJXWMRPLTBAYVGNCHDUFSE" \
  -H "apiKey: SBQKWJRTPLMENXAYVGCH"

Resposta 200

{
  "status": "success",
  "amount": 10000.00,
  "sandbox": true
}

POST /sandbox/createTransaction

Criar transação PIX simulada

Cria uma transação PIX simulada. O corpo da requisição é idêntico ao do POST /createTransaction de produção (mesmos campos, mesmas validações) e a resposta tem o mesmo formato, com o campo extra sandbox: true. O qrCode retornado é um EMV sintético não pagável. Em aproximadamente 15 segundos a transação vira PAID automaticamente, o saldo simulado é creditado com o valor líquido e o postback é disparado para a URL informada em postbackUrl.

Requisição · cURL

curl -X POST https://api.bpx.solutions/sandbox/createTransaction \
  -H "Content-Type: application/json" \
  -H "userId: SANDBOX:KQZJXWMRPLTBAYVGNCHDUFSE" \
  -H "apiKey: SBQKWJRTPLMENXAYVGCH" \
  -d '{
    "paymentMethod": "pix",
    "amount": 400,
    "customer": {
      "name": "José da Silva",
      "document": { "number": "12345678909", "type": "cpf" },
      "email": "jose.silva@example.com",
      "phone": "67989999519"
    },
    "items": [{
      "title": "Camisa Polo Premium",
      "unitPrice": 400,
      "quantity": 1,
      "tangible": false,
      "externalRef": "SKU12345"
    }],
    "externalId": "TESTE-SANDBOX-001",
    "postbackUrl": "https://minhaloja.com.br/webhook-sandbox"
  }'

Resposta 200

{
  "id": "SBXAQZKPLMWXRTYB",
  "status": "PENDING",
  "liquid": 394.50,
  "qrCode": "00020126440014br.gov.bcb.pix0122sandbox@bpx.solutions...",
  "retention": 0,
  "sandbox": true
}

Consulte a lista completa de campos do corpo em POST /createTransaction: o contrato é o mesmo. O liquid reflete as taxas reais configuradas na sua conta. Se não quiser esperar os ~15 segundos da auto-confirmação, force o pagamento com POST /sandbox/simulate/pay/:id.

POST /sandbox/pixOut

Solicitar pix-out simulado

Solicita um saque via PIX simulado. O corpo da requisição é idêntico ao do POST /pixOut de produção e a resposta tem o mesmo formato, com o campo extra sandbox: true. Em aproximadamente 10 segundos o saque vira PAID automaticamente, o saldo simulado é debitado (valor mais taxa da sua conta), um endToEndId no formato SBX... é gerado e o postback é disparado para as URLs em postbackUrls.

Requisição · cURL

curl -X POST https://api.bpx.solutions/sandbox/pixOut \
  -H "Content-Type: application/json" \
  -H "userId: SANDBOX:KQZJXWMRPLTBAYVGNCHDUFSE" \
  -H "apiKey: SBQKWJRTPLMENXAYVGCH" \
  -d '{
    "pixKey": "manoelsouza@gmail.com",
    "pixKeyType": "email",
    "amount": 150.50,
    "description": "Teste de saque no sandbox",
    "externalId": "SBX-PIX-OUT-001",
    "postbackUrls": ["https://minhaloja.com.br/pix-webhook-sandbox"]
  }'

Resposta 200

{
  "status": "processing",
  "id": "SBXPIXOUTQJZKPLM",
  "sandbox": true
}

401	Credenciais sandbox ausentes ou inválidas
402	`{"error": "Saldo insuficiente"}`: o saldo simulado não cobre o valor do saque mais as taxas. Use `POST /sandbox/reset` para re-seedar o saldo

GET /sandbox/pixOutTransactions

Listar pix-outs simulados

Lista os pix-outs simulados da conta sandbox, no mesmo envelope da listagem de pix-out de produção (data.transactions + pagination), com um resumo dos campos de cada saque. Útil para conferir o ciclo completo: PENDING até a auto-confirmação (~10s), depois PAID, com o endToEndId sintético no formato SBX.... Aceita o parâmetro de query limit (padrão 20).

Requisição · cURL

curl https://api.bpx.solutions/sandbox/pixOutTransactions \
  -H "userId: SANDBOX:KQZJXWMRPLTBAYVGNCHDUFSE" \
  -H "apiKey: SBQKWJRTPLMENXAYVGCH"

Resposta 200

{
  "status": "success",
  "sandbox": true,
  "data": {
    "transactions": [
      {
        "id": "SBXPIXOUTQJZKPLM",
        "transactionId": "SBXPIXOUTQJZKPLM",
        "amount": 150.50,
        "status": "PAID",
        "pixKey": "manoelsouza@gmail.com",
        "transactionDate": "2026-08-04T15:30:12.847Z",
        "transactionTime": 1785857412847,
        "description": "Teste de saque no sandbox",
        "endToEndId": "SBX00000000202608041530AKMTQCREVEP",
        "repass": 150.50,
        "profit": 0,
        "sandbox": true
      }
    ],
    "pagination": {
      "limit": 20,
      "count": 1,
      "hasNextPage": false,
      "hasPrevPage": false,
      "nextCursor": null
    }
  }
}

GET /sandbox/transaction/{id}

Consultar transação simulada

Retorna um resumo de uma transação simulada (pix-in ou pix-out) pelo ID, embrulhado em data.transaction, com o campo sandbox: true no topo da resposta. Após a auto-confirmação (ou o simulate/pay), a transação aparece como PAID, com o endToEndId sintético preenchido.

Requisição · cURL

curl https://api.bpx.solutions/sandbox/transaction/SBXAQZKPLMWXRTYB \
  -H "userId: SANDBOX:KQZJXWMRPLTBAYVGNCHDUFSE" \
  -H "apiKey: SBQKWJRTPLMENXAYVGCH"

Resposta 200

{
  "status": "success",
  "sandbox": true,
  "data": {
    "transaction": {
      "id": "SBXAQZKPLMWXRTYB",
      "transactionId": "SBXAQZKPLMWXRTYB",
      "category": "clientPayment",
      "amount": 400,
      "repass": 394.50,
      "status": "PAID",
      "pixKey": null,
      "qrCode": "00020126440014br.gov.bcb.pix0122sandbox@bpx.solutions...",
      "endToEndId": "SBX00000000202608041528AKMTQCREVEP",
      "transactionDate": "2026-08-04T15:28:41.203Z",
      "transactionTime": 1785857321203,
      "description": ""
    }
  }
}

401	Credenciais sandbox ausentes ou inválidas
404	`{"status": "error", "error": "Transação não encontrada"}`: a transação não existe na sua conta sandbox

POST /sandbox/simulate/pay/{id}

Simular pagamento imediato

Força o PAID imediato de uma transação PENDING, sem esperar a auto-confirmação. O efeito é o mesmo do pagamento simulado: o saldo é atualizado e o postback é disparado na hora, com sandbox: true. Ideal para suites de teste automatizadas, onde esperar ~15 segundos por transação inviabiliza o pipeline.

Parâmetro	Tipo	Obrigatoriedade	Descrição
id	string	Obrigatório	ID da transação simulada em `PENDING` (retornado por `/sandbox/createTransaction`)

Requisição · cURL

curl -X POST https://api.bpx.solutions/sandbox/simulate/pay/SBXAQZKPLMWXRTYB \
  -H "userId: SANDBOX:KQZJXWMRPLTBAYVGNCHDUFSE" \
  -H "apiKey: SBQKWJRTPLMENXAYVGCH"

Resposta 200

{
  "status": "success",
  "sandbox": true,
  "transactionId": "SBXAQZKPLMWXRTYB",
  "newStatus": "PAID"
}

401	Credenciais sandbox ausentes ou inválidas
404	Transação não encontrada na sua conta sandbox
409	`{"error": "Transação não está PENDING (status atual: PAID)"}`: a transação já foi confirmada (ou falhou) e não pode ser paga de novo

POST /sandbox/reset

Resetar o ambiente sandbox

Apaga todas as transações e pix-outs simulados da sua conta sandbox e re-seeda o saldo em R$ 10.000,00. As credenciais (sandboxUserId e sandboxApiKey) permanecem as mesmas. Use entre baterias de teste para começar sempre de um estado limpo.

Requisição · cURL

curl -X POST https://api.bpx.solutions/sandbox/reset \
  -H "userId: SANDBOX:KQZJXWMRPLTBAYVGNCHDUFSE" \
  -H "apiKey: SBQKWJRTPLMENXAYVGCH"

Resposta 200

{
  "status": "success",
  "sandbox": true,
  "deleted": 12,
  "balance": 10000
}

POST /sandbox/pixKeys

Criar chave PIX simulada

Cadastra uma chave PIX na conta sandbox autenticada. O corpo da requisição é idêntico ao do POST /pixKeys de produção (mesmos campos, mesmas validações) e a resposta tem o mesmo formato, com o campo extra sandbox: true. A diferença está no DICT: aqui o registro é simulado e instantâneo, então a chave já nasce com status: "REGISTERED" e dictRegistered: true, enquanto em produção ela nasce PENDING com dictRegistered: false. Autentique com o sandboxUserId e o sandboxApiKey: vale tanto para a conta master quanto para uma subconta simulada, cada uma cadastrando as próprias chaves.

Campo	Tipo	Obrigatoriedade	Descrição
keyType	string	Obrigatório	Tipo da chave: `evp`, `cpf`, `cnpj`, `email` ou `phone`
key	string	Condicional	Valor da chave. A obrigatoriedade depende do `keyType`: veja a tabela abaixo

keyType	Campo key	Regra
evp	Não enviar	Chave aleatória: o servidor gera o UUID. Enviar `key` junto responde `400`
cpf	Opcional	Se enviado, precisa ser exatamente o `cpfCnpj` da conta. Se omitido, a API usa o documento da própria conta. A conta precisa ser PF (11 dígitos), senão responde `400`
cnpj	Opcional	Mesma regra do `cpf`, com a conta sendo PJ (14 dígitos)
email	Obrigatório	E-mail válido, normalizado para minúsculo, no máximo 77 caracteres
phone	Obrigatório	Telefone no formato E.164: `+55` mais DDD e número (10 ou 11 dígitos). Aceita só os dígitos e normaliza: `67989999519` vira `+5567989999519`

Titularidade (regra do BACEN). Chave cpf ou cnpj só pode ser o documento do próprio titular da conta. Documento de terceiro é recusado com 400, no sandbox exatamente como em produção: essa validação existe aqui justamente para você bater de frente com ela em teste, e não em produção.

Requisição · cURL

curl -X POST https://api.bpx.solutions/sandbox/pixKeys \
  -H "Content-Type: application/json" \
  -H "userId: SANDBOX:KQZJXWMRPLTBAYVGNCHDUFSE" \
  -H "apiKey: SBQKWJRTPLMENXAYVGCH" \
  -d '{
    "keyType": "evp"
  }'

Resposta 201

{
  "status": "success",
  "sandbox": true,
  "pixKey": {
    "id": "3F9A7C1E4B8D2065AF31CE97B4402D8E5613A7FC",
    "accountId": "SANDBOX:KQZJXWMRPLTBAYVGNCHDUFSE",
    "keyType": "evp",
    "key": "e7c1f0a2-53bd-4a6e-9f10-2c84db77ae31",
    "status": "REGISTERED",
    "dictRegistered": true,
    "createdAt": "2026-08-13T12:00:00.000Z"
  }
}

Campo	Tipo	Descrição
id	string	Identificador da chave no sandbox, derivado do valor da chave. É estável: a mesma chave sempre gera o mesmo `id` dentro do seu sandbox
accountId	string	Conta dona da chave: o `sandboxUserId` do master ou da subconta simulada
keyType	string	Tipo da chave cadastrada: `evp`, `cpf`, `cnpj`, `email` ou `phone`
key	string	Valor final da chave, já normalizado (e-mail em minúsculo, telefone em `+55...`, `evp` com o UUID gerado pelo servidor)
status	string	No sandbox, sempre `REGISTERED`: o DICT é simulado e responde na hora. Em produção a chave nasce `PENDING`
dictRegistered	boolean	No sandbox, sempre `true`. Em produção nasce `false`
createdAt	string	Data e hora do cadastro da chave
sandbox	boolean	Sempre `true`: marca que a resposta veio do ambiente simulado

400	`keyType` ausente ou inválido, `key` faltando ou malformada, `key` enviada junto com `evp`, ou documento diferente do titular da conta
401	Credenciais sandbox ausentes ou inválidas
403	Subconta simulada inativa, ou sandbox do master desabilitada
409	Chave já cadastrada dentro do seu sandbox
429	Limite de chaves da conta atingido: 5 para conta PF, 20 para conta PJ

Unicidade escopada ao seu sandbox. Em produção uma chave PIX é única no banco inteiro. No sandbox a unicidade vale apenas dentro do seu ambiente simulado: dois integradores diferentes podem cadastrar joao@exemplo.com ao mesmo tempo sem um derrubar o teste do outro. O 409 aqui significa "você já cadastrou essa chave", nunca "outro cliente pegou antes".

GET /sandbox/pixKeys

Listar chaves PIX simuladas

Lista as chaves PIX da conta sandbox autenticada, no mesmo envelope do GET /pixKeys de produção (data.pixKeys, data.count e data.limit), com o campo extra sandbox: true. O limit devolvido é o teto de chaves da conta, não um parâmetro de paginação: 5 para conta PF e 20 para conta PJ. Como o DICT é simulado, todas as chaves aparecem como REGISTERED assim que criadas.

Requisição · cURL

curl https://api.bpx.solutions/sandbox/pixKeys \
  -H "userId: SANDBOX:KQZJXWMRPLTBAYVGNCHDUFSE" \
  -H "apiKey: SBQKWJRTPLMENXAYVGCH"

Resposta 200

{
  "status": "success",
  "sandbox": true,
  "data": {
    "pixKeys": [
      {
        "id": "3F9A7C1E4B8D2065AF31CE97B4402D8E5613A7FC",
        "accountId": "SANDBOX:KQZJXWMRPLTBAYVGNCHDUFSE",
        "keyType": "evp",
        "key": "e7c1f0a2-53bd-4a6e-9f10-2c84db77ae31",
        "status": "REGISTERED",
        "dictRegistered": true,
        "createdAt": "2026-08-13T12:00:00.000Z"
      },
      {
        "id": "B27E5D0C9A146F83CD70B1E4529AF6D8340CB915",
        "accountId": "SANDBOX:KQZJXWMRPLTBAYVGNCHDUFSE",
        "keyType": "email",
        "key": "financeiro@minhaloja.com.br",
        "status": "REGISTERED",
        "dictRegistered": true,
        "createdAt": "2026-08-13T12:04:38.512Z"
      }
    ],
    "count": 2,
    "limit": 5
  }
}

Campo	Tipo	Descrição
data.pixKeys	array	Chaves da conta, cada uma com os mesmos campos do objeto `pixKey` retornado na criação
data.count	number	Quantidade de chaves já cadastradas nesta conta sandbox
data.limit	number	Teto de chaves da conta: `5` para PF e `20` para PJ. Atingido o teto, a criação responde `429`

401	Credenciais sandbox ausentes ou inválidas
403	Subconta simulada inativa, ou sandbox do master desabilitada

POST /sandbox/accounts/{accountId}/pixKeys

Criar chave PIX de uma subconta simulada

Cadastra uma chave PIX em nome de uma subconta simulada, usando as credenciais da conta master do sandbox. É o espelho do POST /accounts/:accountId/pixKeys de produção: mesmo corpo, mesmas validações, mesma resposta, com o campo extra sandbox: true. O accountId é o sandboxUserId devolvido por POST /sandbox/accounts e precisa ser uma subconta do master autenticado: subconta de outro sandbox responde 404. Como no restante do sandbox, o DICT é simulado: a chave já nasce REGISTERED com dictRegistered: true.

Parâmetro	Tipo	Obrigatoriedade	Descrição
accountId	string	Obrigatório	Parâmetro de rota: `sandboxUserId` da subconta simulada, no formato `SANDBOX:` seguido das letras aleatórias
keyType	string	Obrigatório	Tipo da chave: `evp`, `cpf`, `cnpj`, `email` ou `phone`
key	string	Condicional	Valor da chave, com as mesmas regras por tipo do `POST /sandbox/pixKeys`

Requisição · cURL

curl -X POST https://api.bpx.solutions/sandbox/accounts/SANDBOX:VNTQBRWLXMDGPKYAHSCFJEZU/pixKeys \
  -H "Content-Type: application/json" \
  -H "userId: SANDBOX:KQZJXWMRPLTBAYVGNCHDUFSE" \
  -H "apiKey: SBQKWJRTPLMENXAYVGCH" \
  -d '{
    "keyType": "phone",
    "key": "67989999519"
  }'

Resposta 201

{
  "status": "success",
  "sandbox": true,
  "pixKey": {
    "id": "7C4B19E0D5A8236FB0E914CD7A65328F1DB40E77",
    "accountId": "SANDBOX:VNTQBRWLXMDGPKYAHSCFJEZU",
    "keyType": "phone",
    "key": "+5567989999519",
    "status": "REGISTERED",
    "dictRegistered": true,
    "createdAt": "2026-08-13T12:11:20.904Z"
  }
}

O documento é o da subconta, não o do master. Ao usar keyType: "cpf" ou "cnpj", a chave tem que ser o cpfCnpj da subconta informada em accountId. Mandar o documento do master (ou de qualquer terceiro) responde 400. O limite de chaves também é o da subconta: 5 se ela for PF, 20 se for PJ.

400	`keyType` ausente ou inválido, `key` faltando ou malformada, `key` enviada junto com `evp`, ou documento diferente do titular da subconta
401	Credenciais sandbox ausentes ou inválidas
403	`{"status": "error", "error": "Apenas a conta master pode gerenciar subcontas no sandbox"}`: a credencial usada é de uma subconta. Para cadastrar a chave dela mesma, use `POST /sandbox/pixKeys` com as credenciais da subconta
404	Subconta não encontrada: o `accountId` não existe ou pertence ao sandbox de outro master
409	Chave já cadastrada dentro do seu sandbox, seja no master ou em outra subconta dele
429	Limite de chaves da subconta atingido: 5 para PF, 20 para PJ

GET /sandbox/accounts/{accountId}/pixKeys

Listar chaves PIX de uma subconta simulada

Lista as chaves PIX de uma subconta simulada, usando as credenciais da conta master do sandbox. Mesmo envelope do GET /sandbox/pixKeys (data.pixKeys, data.count e data.limit), com sandbox: true no topo. A subconta precisa pertencer ao master autenticado: subconta de outro sandbox responde 404.

Parâmetro	Tipo	Obrigatoriedade	Descrição
accountId	string	Obrigatório	Parâmetro de rota: `sandboxUserId` da subconta simulada (retornado por `POST /sandbox/accounts`)

Requisição · cURL

curl https://api.bpx.solutions/sandbox/accounts/SANDBOX:VNTQBRWLXMDGPKYAHSCFJEZU/pixKeys \
  -H "userId: SANDBOX:KQZJXWMRPLTBAYVGNCHDUFSE" \
  -H "apiKey: SBQKWJRTPLMENXAYVGCH"

Resposta 200

{
  "status": "success",
  "sandbox": true,
  "data": {
    "pixKeys": [
      {
        "id": "7C4B19E0D5A8236FB0E914CD7A65328F1DB40E77",
        "accountId": "SANDBOX:VNTQBRWLXMDGPKYAHSCFJEZU",
        "keyType": "phone",
        "key": "+5567989999519",
        "status": "REGISTERED",
        "dictRegistered": true,
        "createdAt": "2026-08-13T12:11:20.904Z"
      }
    ],
    "count": 1,
    "limit": 20
  }
}

401	Credenciais sandbox ausentes ou inválidas
403	`{"status": "error", "error": "Apenas a conta master pode gerenciar subcontas no sandbox"}`: a credencial usada é de uma subconta
404	Subconta não encontrada: o `accountId` não existe ou pertence ao sandbox de outro master

Sandbox

Webhook do Sandbox (Postback)

O postback do sandbox tem o mesmo formato do postback de produção (webhookId, transactionId, status, balanceUpdated, endToEndId), com duas marcações extras para você nunca confundir teste com produção: o campo sandbox: true no corpo e o header X-Sandbox: true na requisição. É disparado na auto-confirmação do pix-in (~15s), do pix-out (~10s) e no simulate/pay.

Campo	Tipo	Descrição
webhookId	string	Identificador do disparo do webhook. No sandbox, espelha o `transactionId`
transactionId	string	ID da transação simulada: use em `GET /sandbox/transaction/:id` para obter os dados completos
status	"PAID"	Pagamento simulado confirmado (pix-in ou pix-out)
balanceUpdated	boolean	Indica se o saldo simulado já foi atualizado quando o webhook foi disparado
endToEndId	string	ID end-to-end sintético, sempre no formato `SBX...`: nunca é um e2e real do Banco Central
sandbox	boolean	Sempre `true`: use este campo (ou o header `X-Sandbox`) para descartar eventos de teste no seu ambiente de produção

Headers recebidos pelo seu servidor

POST https://minhaloja.com.br/webhook-sandbox

Content-Type: application/json
X-Sandbox: true

Payload · Sandbox POST

{
  "webhookId": "SBXAQZKPLMWXRTYB",
  "transactionId": "SBXAQZKPLMWXRTYB",
  "status": "PAID",
  "balanceUpdated": true,
  "endToEndId": "SBX00000000202608041528AKMTQCREVEP",
  "sandbox": true
}

URLs internas são bloqueadas. Por segurança (anti-SSRF), o sandbox não entrega postbacks para endereços internos ou privados: localhost, 127.0.0.1, faixas de rede privada e afins são recusados. Use uma URL https pública: para desenvolvimento local, exponha seu servidor com um túnel (ngrok, Cloudflare Tunnel ou similar). E nunca processe um webhook com sandbox: true como se fosse dinheiro real.

Sandbox

Boas Práticas e Migração para Produção

O sandbox foi desenhado para você validar a integração de ponta a ponta: criação de transação, exibição do QR, recepção do postback, conciliação de saldo e fluxo de saque. Quando tudo estiver verde, a migração para produção é só trocar a base URL e as credenciais.

Testes rápidos

Use POST /sandbox/simulate/pay/:id em vez de esperar os ~15s da auto-confirmação
Valide o postback recebido: campo sandbox: true e header X-Sandbox: true
Confira o saldo com GET /sandbox/balance após cada operação
Use externalId com prefixo de teste para rastrear cada cenário

Estado limpo

Rode POST /sandbox/reset antes de cada bateria de testes
O reset apaga todos os mocks e re-seeda o saldo em R$ 10.000,00
As credenciais sandbox não mudam no reset: só os dados
Perdeu as credenciais? Chame POST /sandbox/provision de novo: ele sempre retorna as mesmas

O que trocar	No sandbox	Em produção
Base URL	`https://api.bpx.solutions/sandbox`	`https://api.bpx.solutions`
Header userId	`SANDBOX:KQZJXWMRPLTBAYVGNCHDUFSE`	Seu `userId` de produção
Header apiKey	`SBQKWJRTPLMENXAYVGCH`	Seu `apiKey` de produção
Corpo e respostas	Criação de transação, pix-out, saldo e postback: o contrato é o mesmo, só some o campo `sandbox: true` e o header `X-Sandbox`. As consultas do sandbox (`transaction/:id` e `pixOutTransactions`) retornam um resumo dos campos de produção

Migração em 2 passos, após a liberação da sua conta em produção: remova o prefixo /sandbox da base URL (ex.: /sandbox/createTransaction vira /createTransaction) e substitua o sandboxUserId/sandboxApiKey pelas credenciais de produção. Recomendamos manter no seu webhook a checagem do campo sandbox: se ele vier true em produção, descarte o evento.

Quem libera a produção é o banco, não a sua integração. Enquanto a conta está em análise, qualquer chamada às rotas de produção responde 403 com "API desabilitada para esta conta", e isso é esperado: significa só que a liberação ainda não foi feita, não que a sua integração está errada. O sandbox continua funcionando normalmente nesse período. Quando a liberação sair, nada muda no seu código além da base URL e das credenciais: contrato, campos, códigos de erro e formato do webhook são os mesmos nos dois ambientes.

BANCO PHOENIXAPI de Pagamentos

Visão Geral da API

Autenticação por Headers

Status da Transação

Notificações via Webhook (Postback)

Testa conexão de api com o servidor

Cria uma transação

Solicita um pix-out

Retorna transações do usuário

Retorna os dados de uma transação

Verifica o saldo de uma conta PHOENIX

BaaS: Subcontas e Transferências Internas

Criar subconta

Listar subcontas

Consultar subconta

Transferência interna entre contas

Webhook de Transferência Interna

Chaves PIX

Criar chave PIX

Listar chaves PIX

Criar chave PIX em subconta

Listar chaves PIX de subconta

Sandbox: Ambiente de Testes

Obter credenciais do sandbox

Consultar saldo simulado

Criar transação PIX simulada

Solicitar pix-out simulado

Listar pix-outs simulados

Consultar transação simulada

Simular pagamento imediato

Resetar o ambiente sandbox

Criar chave PIX simulada

Listar chaves PIX simuladas

Criar chave PIX de uma subconta simulada

Listar chaves PIX de uma subconta simulada

Webhook do Sandbox (Postback)

Boas Práticas e Migração para Produção

BANCO PHOENIX
API de Pagamentos