Banco Phoenix
Prod api.bpx.solutions
v1.0

Documentação REST API

Banco Phoenix
Payment API

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 Banco 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
  1. Chame /createTransaction com paymentMethod: "pix"
  2. Exiba o qrCode retornado ao cliente
  3. Aguarde o webhook com status: "PAID"
  4. Confirme o pagamento na sua base de dados
Fluxo Cartão de Crédito
  1. Chame /createTransaction com paymentMethod: "credit_card"
  2. Inclua os dados do cartão no campo card e installments
  3. O retorno já traz CONFIRMED ou REFUSED de forma síncrona
  4. Consulte /transaction/:id para conferir os detalhes
Fluxo Saque (Pix-Out)
  1. Verifique o saldo disponível com /balance
  2. Chame /pixOut com a chave PIX e o valor desejado
  3. Aguarde o webhook com status: "PAID" ou "FAILED"
  4. Confira balanceUpdated para garantir que o saldo foi atualizado
Webhooks
  1. Informe postbackUrl na criação da transação
  2. A Phoenix enviará um POST de confirmação quando o pagamento for concluído
  3. Responda com HTTP 200 em até 5 segundos
  4. Valide o transactionId recebido na sua base antes de processar
Ambiente URL Base Uso
Produção https://api.bpx.solutions Ambiente real — use com credenciais de produção
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 Banco 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 Banco Phoenix — use em GET /transaction/:id para obter os dados completos
status "PAID" | "FAILED" PAID — pagamento confirmado e creditado  ·  FAILED — pix-out que não pôde ser processado
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 são aceitas (http somente para localhost).

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" PAID — saque processado com sucesso  ·  FAILED — saque não pôde ser processado  ·  PENDING — saque aceito pelo provedor, aguardando confirmação (status intermediário; balanceUpdated vem false)
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 Banco 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" PAID — saque processado com sucesso  ·  FAILED — saque não pôde ser processado  ·  PENDING — saque aceito pelo provedor, aguardando confirmação (status intermediário; balanceUpdated vem false)
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 Banco 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
}