🏢 DexCard para o Participante

Esta página é para quem administra uma conta de participante e precisa acompanhar o DexCard dos seus usuários: quem tem cartão, quanto foi movimentado, o que está parado na análise, quantos cartões ainda pode emitir e quais taxas você cobra.

A emissão em si é feita pelo usuário, com o token dele — o caminho completo está na página DexCard. Aqui está tudo o que você enxerga e controla sozinho.

1. A Fronteira: o Que É Seu e o Que Não É

Assunto	Por esta API?
Ver seus titulares — quem tem cartão, saldo, últimos quatro dígitos, situação	✅ Leitura
Ver movimentos — extrato consolidado, extrato de um cartão, detalhe de um movimento, exportação	✅ Leitura
Acompanhar a análise — fila de solicitações e o detalhe de cada uma, com a situação documento a documento e o motivo da recusa	✅ Leitura
KPIs — cartões ativos, carregado e resgatado no mês, volume, uso de cota	✅ Leitura
Cota de emissão	✅ Leitura e pedido de aumento
Suas taxas de emissão, recarga e resgate	✅ Leitura e configuração
Solicitar cartão, recarregar, resgatar	❌ É o usuário, com o token dele — veja DexCard
Aprovar ou recusar uma solicitação, ou um documento	❌ Compliance da plataforma
Abrir o arquivo de um documento enviado pelo titular	❌ A análise documental não é sua
Decidir sobre recarga retida em análise	❌ Compliance da plataforma
Congelar, bloquear ou cancelar o cartão de um usuário	❌ Titular (congelar) ou suporte
Limites de recarga e resgate	❌ Limite é controle de risco e não é delegado

A linha é sempre a mesma: você vê tudo dos seus titulares e não decide nada sobre eles. Decisão sobre cartão de usuário e limite de risco ficam com a plataforma — não é etapa pendente, é desenho.

2. Credencial Necessária

Estes endpoints exigem a credencial pessoal de um usuário que administra a sua conta de participante — gerada em Integrações → API, como qualquer credencial de usuário.

curl -X POST https://api.dexkey.finance/v1/auth/api-key \
  -H "Content-Type: application/json" \
  -d '{ "clientId": "...", "clientSecret": "..." }'

Use o accessToken retornado nas chamadas abaixo.

> Não use a credencial de participante (client_id/client_secret da empresa) aqui. Ela é de leitura sobre os seus usuários e não resolve para um administrador — a chamada é recusada com 403.

Se o administrador não estiver vinculado a um participante, a resposta é 403 ADMIN_SCOPE_UNDEFINED.

3. Como a Hierarquia Funciona

Os endpoints de leitura desta página são os mesmos que a nossa equipe usa no painel interno. O que muda é o alcance: o servidor decide, a partir do seu token, que você só enxerga os seus titulares. Esse recorte não é um filtro que você aplica — é uma regra que você não consegue contornar.

Regra	O que significa na prática
O alcance vem do token, nunca da requisição	Não existe parâmetro `participantId` que você possa enviar para enxergar outro participante. Se enviar, ele é ignorado
Pedir algo de outro participante responde `404`, e não `403`	É proposital: um `403` confirmaria que aquele identificador existe. Aqui, `404` pode significar tanto "não existe" quanto "não é seu"
Listagens já vêm filtradas	`GET /admin/cards/participants` devolve uma linha só: a sua. `GET /admin/cards/users` devolve só os seus titulares
Ver não é decidir	Você abre a solicitação e acompanha a situação de cada documento; aprovar e recusar devolvem `403`

Estes endpoints devolvem dado pessoal dos seus titulares — nome, e-mail e documento mascarado. São seus usuários, e por isso você os vê; o tratamento desse dado no seu lado é responsabilidade sua. Não registre em log e não repasse a terceiros.

4. Visão Sobre os Seus Titulares

4.1 KPIs

curl https://api.dexkey.finance/v1/admin/cards/dashboard \
  -H "Authorization: Bearer $TOKEN"

{
  "totalCardsActive": 412,
  "totalCardsAllStatuses": 487,
  "totalLoadedUsdCentsThisMonth": "18450000",
  "totalRedeemedUsdCentsThisMonth": "2310000",
  "totalTransactionVolumeUsdCents": "94820000",
  "pendingApprovals": 7,
  "quotaUtilization": [
    { "participantId": "83e5b214-2d7a-4c11-9f0e-5a6b7c8d9e01", "used": 487, "total": 500 }
  ],
  "brl": {
    "usdToBrlRate": "5.49800000",
    "loadedThisMonthBrlCents": "101438100",
    "quotedAt": "2026-09-15T12:00:00.000Z"
  }
}

quotaUtilization traz só a sua linha, mesmo sendo uma lista. brl vem null quando a cotação do dólar está indisponível no momento — nesse caso mostre os valores em dólar, em vez de deixar a tela vazia.

4.2 Seus titulares

curl "https://api.dexkey.finance/v1/admin/cards/users?limit=20&offset=0&search=maria" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [
    {
      "approvalRequestId": "3f2a1b0c-9d8e-4c7b-8a6f-5e4d3c2b1a09",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Maria Silva",
      "email": "maria@exemplo.com",
      "participantName": "Digital Sales",
      "cardId": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
      "cardLastFour": "4821",
      "balanceUsdCents": "23450",
      "cardStatus": "active",
      "approvalStatus": "provider_approved",
      "requestedAt": "2026-09-01T12:20:00.000Z"
    }
  ],
  "meta": { "total": 487, "limit": 20, "offset": 0, "hasMore": true }
}

Uma linha por solicitação de cartão, e não por pessoa: quem pediu duas vezes aparece duas vezes. A busca aceita nome, e-mail, documento e os últimos quatro dígitos do cartão — é o que você costuma ter em mãos quando o cliente liga.

Atenção a um detalhe do filtro de situação: FROZEN descreve o cartão, enquanto os outros valores descrevem a solicitação. A consulta cobre os dois, mas eles não são a mesma coisa.

GET /admin/cards/participants devolve a sua linha consolidada (cartões ativos, titulares por situação, volume, cota), e GET /admin/cards/participants/{id}/overview e /participants/{id}/users abrem a mesma visão — com o seu id; com o de outro, 404.

4.3 Fila de análise

curl "https://api.dexkey.finance/v1/admin/cards/approvals?limit=20" -H "Authorization: Bearer $TOKEN"
curl https://api.dexkey.finance/v1/admin/cards/approvals/{id}    -H "Authorization: Bearer $TOKEN"

O detalhe mostra a situação documento a documento, e é onde você descobre por que uma solicitação não anda:

{
  "approvalRequestId": "3f2a1b0c-9d8e-4c7b-8a6f-5e4d3c2b1a09",
  "status": "pending_adjustment",
  "requestedAt": "2026-09-01T12:20:00.000Z",
  "canReapply": false,
  "cardStatus": "pending",
  "holder": {
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Maria Silva",
    "email": "maria@exemplo.com",
    "participantName": "Digital Sales",
    "documentMasked": "***.***.789-00"
  },
  "terms": {
    "accepted": true,
    "acceptedAt": "2026-09-01T12:20:00.000Z",
    "signatureHash": "e3b0c44298fc…"
  },
  "documents": [
    { "documentType": "IDENTITY_FRONT", "state": "APPROVED", "documentId": "fe84c527-…", "rejectionReason": null },
    { "documentType": "IDENTITY_BACK", "state": "REJECTED", "documentId": "a1b2c3d4-…", "rejectionReason": "A foto corta o canto inferior direito do documento" },
    { "documentType": "SELFIE_WITH_DOCUMENT", "state": "PENDING", "documentId": "c3d4e5f6-…", "rejectionReason": null }
  ]
}

> status: "pending_adjustment" com um documento REJECTED significa que a bola está com o titular, não com a análise. É o caso em que faz sentido você falar com ele — o rejectionReason é exatamente o que ele precisa corrigir.

> A análise documental é da plataforma. Você acompanha o resultado de cada documento (state) e o motivo da recusa (rejectionReason) — que é o que permite orientar o titular. Aprovar e reprovar documento são do compliance, e o arquivo enviado não faz parte desta visão.

4.4 Movimentos

curl "https://api.dexkey.finance/v1/admin/cards/transactions?limit=20&offset=0" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [
    {
      "id": "c9d8e7f6-a5b4-4c3d-9e2f-1a0b9c8d7e6f",
      "userName": "Maria Silva",
      "userEmail": "maria@exemplo.com",
      "participantName": "Digital Sales",
      "cardLastFour": "4821",
      "type": "PURCHASE",
      "status": "COMPLETED",
      "amountUsdCents": "1990",
      "originalAmount": "10940",
      "originalCurrency": "BRL",
      "merchantName": "SPOTIFY BR",
      "occurredAt": "2026-09-14T20:11:00.000Z",
      "statementSyncedAt": "2026-09-15T02:00:00.000Z",
      "totalFeeUsdCents": "0",
      "feeCurrency": null,
      "platformFeeAmount": null,
      "participantFeeAmount": null
    }
  ],
  "meta": { "total": 3120, "limit": 20, "offset": 0, "hasMore": true }
}

Endpoint	O que devolve
`GET /admin/cards/transactions`	Todos os movimentos dos seus titulares, paginado
`GET /admin/cards/transactions/{transactionId}`	Um movimento específico
`GET /admin/cards/transactions/export`	O mesmo recorte em CSV ou PDF
`GET /admin/cards/{id}/balance`	Saldo de um cartão seu, com conversão de exibição
`GET /admin/cards/{id}/statement`	Extrato de um cartão seu

> participantFeeAmount é a sua parcela da tarifa; platformFeeAmount é a da plataforma. Os dois aparecem para você conferir a conta — é o mesmo número que fecha o seu repasse.

5. Cota de Emissão

5.1 Quanto ainda dá para emitir

curl https://api.dexkey.finance/v1/admin/participant/cards/my-quota \
  -H "Authorization: Bearer $TOKEN"

{
  "totalQuota": 500,
  "usedQuota": 487,
  "availableQuota": 13,
  "isExhausted": false,
  "lastQuotaIncreaseAt": "2026-07-30T12:00:00.000Z",
  "utilizationRatio": 0.974,
  "isNearingLimit": true
}

Campo	O que é
`totalQuota`	Total contratado
`usedQuota`	Já consumido. Uma solicitação consome cota no momento do pedido, não na aprovação
`availableQuota`	Quanto resta
`isExhausted`	Novas emissões já estão bloqueadas — seus usuários recebem o bloqueador `QUOTA_EXHAUSTED`
`isNearingLimit`	Sinal para pedir aumento antes de travar

> Sem cota contratada a resposta vem zerada e com isExhausted: true. Não é um estado ilimitado — é emissão bloqueada.

5.2 Pedir aumento

curl -X POST https://api.dexkey.finance/v1/admin/participant/cards/quota/increase-requests \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requestedQuota": 750,
    "reason": "Fechamos contrato com uma rede de 120 lojas que entra em operacao no proximo mes, e cada gerente de loja precisa de um cartao nominal para despesas operacionais."
  }'

{
  "id": "9f1c2d3e-4b5a-6c7d-8e9f-0a1b2c3d4e5f",
  "participantId": "83e5b214-2d7a-4c11-9f0e-5a6b7c8d9e01",
  "participantName": "Digital Sales",
  "currentQuota": 500,
  "requestedQuota": 750,
  "increaseBy": 250,
  "reason": "Fechamos contrato com uma rede de 120 lojas…",
  "status": "pending",
  "createdAt": "2026-09-15T09:31:00.000Z",
  "reviewedAt": null,
  "decisionNote": null
}

> requestedQuota** é o TOTAL desejado, não o incremento.** Sobre uma cota de 500, pedir 750 significa 250 cartões a mais. Pedir 250 seria um total menor que o atual, e é recusado com 422 CARD_QUOTA_REQUEST_INVALID_AMOUNT.

Regra	Detalhe
`reason`	Entre 100 e 1000 caracteres. É a única informação que o analista tem sobre a sua operação — menos que isso é recusado com `400`
Uma por vez	Enquanto houver pedido em análise, um novo é recusado com `409 CARD_QUOTA_REQUEST_ALREADY_OPEN`, e `details.openRequestId` aponta o que está aberto
Efeito	A cota só muda quando a plataforma aprova. `pending` não libera nada

5.3 Acompanhar os pedidos

curl "https://api.dexkey.finance/v1/admin/participant/cards/quota/increase-requests?limit=20&offset=0" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [
    {
      "id": "9f1c2d3e-4b5a-6c7d-8e9f-0a1b2c3d4e5f",
      "currentQuota": 500,
      "requestedQuota": 750,
      "increaseBy": 250,
      "status": "approved",
      "createdAt": "2026-09-15T09:31:00.000Z",
      "reviewedAt": "2026-09-15T14:02:00.000Z",
      "decisionNote": "Aprovado conforme volume projetado."
    }
  ],
  "meta": { "total": 4, "limit": 20, "offset": 0, "hasMore": false }
}

Da mais recente para a mais antiga. status é pending, approved ou rejected, e decisionNote traz a observação escrita pelo analista — inclusive nas recusas.

6. Suas Taxas de Cartão

6.1 O que está valendo

curl https://api.dexkey.finance/v1/admin/participant/cards/my-fees \
  -H "Authorization: Bearer $TOKEN"

[
  { "feeType": "CARD_ISSUANCE", "currency": "USD",  "fixedAmount": "5.00", "percentageRate": "0",   "inheritsPlatformFee": false },
  { "feeType": "CARD_LOAD",     "currency": "BRT",  "fixedAmount": null,   "percentageRate": null,  "inheritsPlatformFee": true },
  { "feeType": "CARD_LOAD",     "currency": "USDC", "fixedAmount": "1.50", "percentageRate": "0.5", "inheritsPlatformFee": false },
  { "feeType": "CARD_LOAD",     "currency": "USDT", "fixedAmount": "1.50", "percentageRate": "0.5", "inheritsPlatformFee": false },
  { "feeType": "CARD_REDEEM",   "currency": "BRT",  "fixedAmount": null,   "percentageRate": null,  "inheritsPlatformFee": true },
  { "feeType": "CARD_REDEEM",   "currency": "USDC", "fixedAmount": null,   "percentageRate": null,  "inheritsPlatformFee": true },
  { "feeType": "CARD_REDEEM",   "currency": "USDT", "fixedAmount": null,   "percentageRate": null,  "inheritsPlatformFee": true }
]

Um item por combinação tarifável. A lista é sempre completa — as combinações sem regra própria aparecem com null.

> inheritsPlatformFee: true** significa que vale a taxa da plataforma, não que a operação é gratuita.** É o engano mais comum nesta tela.

6.2 Combinações válidas

`feeType`	Moedas aceitas	Por quê
`CARD_ISSUANCE`	`USD` apenas	O cartão é denominado em dólar e o titular não escolhe moeda ao pedir. A conversão para a moeda que sai do saldo acontece na cobrança
`CARD_LOAD`	`BRT`, `USDC`, `USDT`	A taxa é procurada pela moeda de origem da operação
`CARD_REDEEM`	`BRT`, `USDC`, `USDT`	Idem, pela moeda de destino

Uma regra de CARD_LOAD cadastrada em USD seria aceita pelo banco e nunca casaria com recarga nenhuma — taxa configurada, cobrança inexistente, sem erro em lugar nenhum. Por isso a combinação é validada no cadastro: fora dessa tabela, a chamada é recusada com CARD_FEE_INVALID_CURRENCY.

6.3 Configurar uma taxa

curl -X PUT https://api.dexkey.finance/v1/admin/participant/cards/my-fees \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "feeType": "CARD_LOAD",
    "currency": "USDT",
    "fixedAmount": "1.50",
    "percentageRate": "0.5",
    "description": "Ajuste comercial acordado para o segundo semestre"
  }'

{
  "feeType": "CARD_LOAD",
  "currency": "USDT",
  "fixedAmount": "1.50",
  "percentageRate": "0.5"
}

Campo	O que é
`fixedAmount`	Parcela fixa, na unidade humana da moeda (`"1.50"` = 1,50 USDT)
`percentageRate`	Alíquota em porcento: `"0.5"` é 0,5%, não 50%
`currency`	Pode ser omitido quando a operação aceita uma única moeda (`CARD_ISSUANCE`); com mais de uma, é obrigatório

A cobrança é (valor × percentual) + fixa, com arredondamento bancário.

> Salvar cria uma versão nova da taxa, em vez de alterar a atual. Uma transação antiga continua registrada com a taxa que valia no dia — é isso que permite auditar um extrato de meses atrás. Não existe "desfazer": para voltar ao valor anterior, cadastre-o novamente.

A sua taxa soma com a da plataforma — não substitui. O usuário enxerga apenas o total na simulação, e cada parcela é creditada separadamente.

7. Erros Desta Área

Código	HTTP	Significa
`ADMIN_ROLE_INSUFFICIENT`	403	O token não é de um administrador de participante
`ADMIN_SCOPE_UNDEFINED`	403	O administrador não está vinculado a um participante
`CARD_QUOTA_REQUEST_ALREADY_OPEN`	409	Já existe pedido em análise; `details.openRequestId` aponta qual
`CARD_QUOTA_REQUEST_INVALID_AMOUNT`	422	Total pedido não é maior que a cota atual, ou passa do teto
`CARD_FEE_INVALID_CURRENCY`	400	Combinação `feeType` + `currency` fora da tabela da seção 6.2
`CARD_FEE_CURRENCY_REQUIRED`	400	A operação aceita mais de uma moeda e nenhuma foi informada
—	400	`reason` com menos de 100 caracteres, ou quantidade não inteira

Todo erro segue o formato padrão da API. Trate pelo code, não pelo texto.

8. O Que Acompanhar no Dia a Dia

Consulte my-quota com regularidade. isNearingLimit é o sinal para pedir aumento antes de a emissão travar: a aprovação não é instantânea.
Cota é consumida no pedido. Um usuário que solicita e é recusado pelo emissor já consumiu uma unidade. Considere isso ao dimensionar.
Não existe aviso automático (webhook) de cartão — nem para você, nem para o usuário. Cota, taxas e andamento das solicitações são acompanhados por consulta.
Mudança de taxa não é retroativa: vale a partir do instante em que é salva. Combine a data com o seu time comercial antes de salvar.

💳 DEXCARD

📖 Referência Completa do Ledger (Saldo, Extrato e Comprovante)