Documentação REST API

SANTS
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 SANTS é 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 SANTS

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 SANTS 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.bancosants.com`	Domínio oficial SANTS: use com credenciais de produção
Produção · Alternativo	`https://api.bpx.solutions`	Endereço alternativo: mesma API e mesmas credenciais, mantido por compatibilidade

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 SANTS.
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 SANTS 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 SANTS: 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 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 SANTS
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 SANTS
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 SANTS. 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 SANTS"
}

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 SANTS
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 SANTS",
          "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 SANTS

Ver saldo de conta SANTS. 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 SANTS: 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

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.bancosants.com/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 SANTS. 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.bancosants.com/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.bancosants.com/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.bancosants.com/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 SANTS 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.

SANTSAPI 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 SANTS

BaaS: Subcontas e Transferências Internas

Criar subconta

Listar subcontas

Consultar subconta

Transferência interna entre contas

Webhook de Transferência Interna

SANTS
API de Pagamentos