Contas gerenciadas

Você opera duas camadas de conta:

Conta raiz

A sua conta PJ na PrismaPay, à qual a credencial está vinculada. É dela que GET /v1/balance fala.

As contas PF e PJ que você abriu pela API para os seus clientes. Você só enxerga as suas.

GET /v1/accounts devolve as duas camadas: a sua conta raiz aparece na lista, junto com as contas dos clientes. Ao reconciliar carteira de clientes, ignore a linha cujo accountId é o da conta raiz, a mesma que GET /v1/balance reporta.

Método	Endpoint	Escopo	Retorno
`GET`	`/v1/accounts`	`accounts:read`	Lista paginada das contas que você gerencia
`GET`	`/v1/balance`	`accounts:read`	Saldo da conta raiz
`GET`	`/v1/accounts/{accountId}/balance`	`accounts:read`	Saldo de uma conta gerenciada
`GET`	`/v1/accounts/{accountId}/status`	`accounts:read`	Status do onboarding
`GET`	`/v1/accounts/{accountId}/transactions/{transactionId}`	`transactions:read`	Status de uma transação
`POST`	`/v1/accounts/pf`	`subaccounts:create`	Abertura PF, `202`
`POST`	`/v1/accounts/pj`	`subaccounts:create`	Abertura PJ, `201`

Saldo e transação exigem cadastro aprovado. As rotas /accounts/{accountId}/balance e /accounts/{accountId}/transactions/{...} respondem 404 account_not_found enquanto o cadastro não estiver approved, mesmo sendo uma conta sua.GET /v1/accounts/{accountId}/status é a única rota por conta que funciona desde a criação. Use-a para acompanhar o onboarding e só chame saldo depois de approved.

O mesmo 404 account_not_found cobre conta inexistente, conta de outro parceiro, vínculo suspenso, vínculo revogado e cadastro não aprovado. A resposta é idêntica em todos os casos, de propósito, e nenhuma consulta ao provedor é feita.

Listar contas

curl "https://api.prismapay.com.br/v1/accounts?limit=50&offset=0" \
  -H "X-Api-Key: pk_live_seu_key_id" \
  -H "X-Timestamp: 1767000000" \
  -H "X-Signature: assinatura_hex"

Parâmetro	Valores
`limit`	1 a 100, padrão 50
`offset`	a partir de 0, padrão 0

A query é validada em modo estrito: qualquer parâmetro fora desta tabela devolve 422 invalid_request. Não acrescente parâmetro de rastreamento nem quebra-cache na URL.

{
  "data": [
    {
      "accountId": "4b7c2a11-1f56-4e63-a8c1-81d2cb1b31c8",
      "status": "active",
      "accountType": "pf",
      "displayName": "Maria da Silva",
      "accountStatus": "approved",
      "createdAt": "2026-09-01T12:00:00.000Z",
      "updatedAt": "2026-09-02T09:30:00.000Z",
      "revokedAt": null
    }
  ],
  "pagination": { "limit": 50, "offset": 0, "hasMore": false }
}

Dois status convivem na mesma linha e significam coisas diferentes:

Campo	Sobre	Valores
`status`	o vínculo entre a conta e a sua credencial	na prática, sempre `active`
`accountStatus`	o onboarding do cliente	`pending`, `under_review`, `compliance_review`, `approved`, `rejected`, `failed`, `unknown`

A lista traz apenas vínculos ativos. Contas suspensas, revogadas, bloqueadas ou excluídas não aparecem: elas simplesmente somem do resultado, e o revokedAt volta sempre null. Não trate a ausência de uma conta como erro seu; consulte o accountId diretamente e trate o 404.

accountStatus: "compliance_review" e status: "under_review" em GET /v1/accounts/{accountId}/status podem se referir à mesma conta: a rota de status resume compliance_review como under_review, a listagem não resume. Se você compara os dois valores, normalize compliance_review para under_review do seu lado.

Só uma conta com accountStatus: "approved" movimenta dinheiro e responde às rotas de saldo. Um cadastro em análise ainda não opera. Pagine enquanto hasMore for true, somando limit ao offset.

Consultar saldo

GET /v1/balance responde pela conta raiz. GET /v1/accounts/{accountId}/balance responde por uma conta gerenciada. O formato é o mesmo:

{
  "available": 1250000,
  "blocked": 0,
  "currencyCode": "BRL",
  "reservedForFees": 3500,
  "reservedBreakdown": [
    { "group": "pix_out", "count": 7, "cents": 3500 }
  ]
}

Campo	Significado
`available`	o que dá para gastar agora, em centavos, já descontadas as tarifas do dia
`blocked`	valor retido, em centavos
`currencyCode`	sempre `BRL`
`reservedForFees`	tarifas em aberto, cobradas uma vez por dia
`reservedBreakdown`	as tarifas em aberto, por grupo de operação

Use available para decidir se uma operação cabe. Ele já está líquido de reservedForFees. Somar os dois superestima o saldo e leva a 422 insufficient_balance.

Consultar status do onboarding

GET /v1/accounts/{accountId}/status

{
  "accountId": "4b7c2a11-1f56-4e63-a8c1-81d2cb1b31c8",
  "status": "under_review",
  "type": "pf",
  "createdAt": "2026-09-01T12:00:00.000Z",
  "updatedAt": "2026-09-01T12:05:00.000Z",
  "rejectionReason": null,
  "kycSubmittedAt": "2026-09-01T12:04:00.000Z"
}

Status	Leitura
`pending`	conta criada, cliente ainda não enviou os documentos
`under_review`	documentos enviados, análise em andamento
`approved`	conta aprovada e apta a operar. É a partir daqui que saldo e transação respondem
`rejected`	análise recusou a conta; veja `rejectionReason`
`failed`	o processo falhou tecnicamente e precisa ser reiniciado

rejectionReason, quando presente, assume um destes valores: kyc_document_invalid, kyc_selfie_mismatch, kyc_fraud_indicators, kyc_age_minor, kyc_restricted_list, kyc_duplicate_account, other.

Consulte o status por evento do seu lado (o cliente terminou o onboarding) ou por polling em intervalo largo, de minutos. Não faça polling em segundos: existe teto de requisições por credencial.

Consultar o status de uma transação

GET /v1/accounts/{accountId}/transactions/{transactionId}

{
  "transactionId": "9f2c1b7e-51b2-4a7d-93a2-5c9a1c0f42a1",
  "status": "pending"
}

Os status possíveis são completed, pending e failed. A resposta traz apenas o identificador e o status normalizado. Ela não expõe contraparte nem qualquer outro dado pessoal do extrato, mesmo que a transação tenha esses dados.

Comece aqui

Fundamentos

Contas

Movimentação

Contas gerenciadas

Conta raiz