1. Cartão (Checkout Transparente)
Dotfy - Documentação
  • Dotfy Module
    • Raiz
      • Conta (Dados do Seller)
        • Identificar a conta (dados do seller)
      • Cobranças PIX
        • Criar cobrança PIX
        • Listar cobranças
        • Consultar cobrança por correlationID
        • Histórico de webhooks de uma cobrança
      • Cartão (Checkout Transparente)
        • Criar pagamento com cartão (PAN via API)
          POST
      • Saldo
        • Consultar saldo
      • Saques e Chaves PIX
        • Listar chaves PIX cadastradas
        • Cadastrar chave PIX
        • Listar saques
        • Solicitar saque
        • Cancelar saque pendente
      • Clientes
        • Listar clientes
        • Detalhe de um cliente
      • Produtos e Links de Pagamento
        • Links de compra por comprador (Purchase Links)
          • Criar link de compra (por comprador)
          • Listar links de compra do produto
          • Detalhe/status do link de compra
          • Revogar link de compra
        • Listar produtos
        • Criar produto
        • Detalhe do produto
        • Carrinhos abandonados do produto
      • Splits
        • Analytics de splits enviados
        • Splits recebidos
      • Disputas e MEDs
        • Listar disputas
        • Listar MEDs com estatísticas
        • Evidências de uma disputa
        • Histórico de uma disputa
      • Subcontas White-Label (BaaS)
        • Criar subconta
        • Listar subcontas
        • Detalhe da subconta
        • Atualizar subconta
        • Excluir subconta (soft delete)
        • Enviar KYC da subconta (multipart)
        • Consultar status do KYC da subconta
        • Cadastrar chave PIX da subconta
        • Listar chaves PIX da subconta
        • Remover chave PIX da subconta
        • Criar cobrança da subconta
        • Listar cobranças da subconta
        • Detalhe de cobrança da subconta
        • Saldo da subconta
        • Extrato (transações) da subconta
        • Solicitar saque da subconta
        • Listar saques da subconta
        • Atualizar taxas da subconta
      • Webhooks (Gerenciar Endpoints)
        • Listar endpoints
        • Criar endpoint
        • Atualizar endpoint
        • Remover endpoint
      • Webhooks (Eventos Recebidos)
        • EVENT:CHARGE_CREATED — cobrança criada
        • EVENT:CHARGE_PAID — cobrança paga (atualização principal)
        • EVENT:CHARGE_EXPIRED — cobrança expirada
        • EVENT:SPLIT_RECEIVED — você recebeu um split
        • EVENT:DISPUTE_OPENED — MED/disputa aberta
        • EVENT:DISPUTE_WON — disputa ganha
        • EVENT:DISPUTE_LOST — disputa perdida
        • EVENT:DISPUTE_CANCELED — disputa cancelada
        • EVENT:WITHDRAWAL_COMPLETED — saque concluído
        • EVENT:WITHDRAWAL_FAILED — saque falhou
        • EVENT:SUBACCOUNT_KYC_APPROVED — KYC da subconta aprovado
        • EVENT:SUBACCOUNT_KYC_REJECTED — KYC da subconta recusado
        • EVENT:SUBACCOUNT_PIX_KEY_APPROVED — chave PIX da subconta aprovada
        • EVENT:SUBACCOUNT_PIX_KEY_REJECTED — chave PIX da subconta recusada
      • Notificações
        • Listar notificações
      • Dashboard / Analytics
        • Stats gerais
        • Atividade recente
        • Atividade (timeline)
        • Receita por período
        • Volume por período
        • Taxa de conversão
        • Métodos de pagamento
        • Transações (gráfico)
        • Analytics avançado
  1. Cartão (Checkout Transparente)

Criar pagamento com cartão (PAN via API)

POST
/api/card-payments

Autenticação#

Esta rota exige Bearer Token (sua API Key) no header. Envie EXATAMENTE assim:
Substitua o valor após Bearer pela sua API Key real (vk_live_* produção, vk_test_* sandbox). Crie a chave em https://app.dotfy.com.br/dashboard/chaves-api. Sem o header → 401. Com chave inválida/revogada → 401. Com chave sem o escopo necessário → 403 insufficient_scope.

Criar pagamento com cartão (PAN via API)#

Escopo: charges:write (Bearer API Key).
Checkout transparente de cartão: sua plataforma envia os dados do cartão crus (PAN/CVV) para esta API; o Dotfy tokeniza server-side no nosso processador de cartão e processa o pagamento (aprovado/recusado) na mesma request — o equivalente ao POST /api/charges, mas para cartão.

⚠️ Recurso liberado POR USUÁRIO#

Este endpoint só funciona se a sua conta tiver o switch "Cartão via API (PAN cru)" habilitado pelo admin (User.rawCardApiEnabled). Sem ele → 403. Contas de teste (isTestUser) → 400. Além disso, o processamento de cartão (nosso processador de cartão) precisa estar disponível na plataforma.

Segurança do cartão (PCI)#

Recebemos o cartão cru, tokenizamos imediatamente e processamos.
O cartão NUNCA é armazenado: guardamos apenas os últimos 4 dígitos (cardLastFour) e a bandeira (cardBrand).
PAN/CVV nunca são logados. Sempre use HTTPS.

Body#

CampoTipoObrigatórioDescrição
valuenumbersimValor em REAIS (ex: 149.90). Livre, > 0.
installmentsintnãoParcelas, 1–12. Default: 1.
descriptionstringnãoDescrição/statement. Respeita a preferência de envio ao adquirente da conta.
correlationIDstringnão (recomendado)Alias externo único para conciliação e idempotência de retry. Se repetido → 409. Sem ele, um retry pode gerar cobrança duplicada.
webhook_urlstringnãoURL HTTPS para o webhook desta cobrança (sobrescreve endpoints estáticos).
customer.namestringsimNome do titular/comprador.
customer.emailstringsimEmail válido (antifraude).
customer.taxIDstringsimCPF (11 dígitos) ou CNPJ (14 dígitos). Apenas números.
customer.phonestringnãoFormato E.164 (ex: +5511999998888).
card.numberstringsimPAN do cartão. Nunca armazenado.
card.holderNamestringsimNome impresso no cartão.
card.expMonthintsimMês de expiração (1–12).
card.expYearintsimAno de expiração (4 dígitos, ex: 2030).
card.cvvstringsimCódigo de segurança. Nunca armazenado.
billing.streetstringsimEndereço de cobrança — logradouro.
billing.numberstringnãoNúmero (opcional).
billing.zipstringsimCEP (apenas números).
billing.citystringsimCidade.
billing.statestringsimUF (2 letras).
billing.countrystringnãoPaís ISO-2 (default BR).
billing é OBRIGATÓRIO — o nosso processador de cartão exige billing_address no processamento de cartão.

Resposta#

200 OK com { id, correlationId, paymentMethod: "CARD", status, cardLastFour, cardBrand, installments, amount, paid, userMessage }. amount em centavos.

Códigos de status#

200 — processado na hora (paid: true aprovado; paid: false = ainda em processamento).
202 — em processamento (status: "processing"): resultado INDETERMINADO (timeout/instabilidade do adquirente). A captura PODE ter ocorrido — NÃO reenvie com o mesmo cartão; aguarde o webhook EVENT:CHARGE_PAID (conciliar pelo correlationID).
400 — cartão recusado / dados inválidos.
403 — conta sem o switch de cartão via API (ou modo de teste).
409 — correlationID já usado (idempotência): já existe uma cobrança com esse id.

Webhook e liquidação#

Uma cobrança paga dispara o webhook EVENT:CHARGE_PAID pela via padrão — concilie pelo correlationID.
O dinheiro de cartão fica retido por D+N antes de ficar disponível para saque (mesma retenção de qualquer cobrança de cartão).

Requisição

Authorization
Forneça seu token bearer no cabeçalho
Authorization
ao fazer requisições para recursos protegidos.
Exemplo:
Authorization: Bearer ********************
Parâmetros Header

Parâmetros Bodyapplication/json

Examples

Respostas

🟢200
application/json
Bodyapplication/json

🟠403
🟠400
🟢202
🟠409
Request Request Example
Shell
JavaScript
Java
Swift
curl --location '/api/card-payments' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "value": 149.9,
  "installments": 1,
  "description": "Pedido #123",
  "correlationID": "order_123",
  "customer": {
    "name": "Maria Silva",
    "email": "maria@exemplo.com",
    "taxID": "12345678901",
    "phone": "+5511999998888"
  },
  "card": {
    "number": "4000000000000010",
    "holderName": "MARIA SILVA",
    "expMonth": 12,
    "expYear": 2030,
    "cvv": "123"
  },
  "billing": {
    "street": "Av Paulista",
    "number": "1000",
    "zip": "01310100",
    "city": "Sao Paulo",
    "state": "SP",
    "country": "BR"
  }
}'
Response Response Example
200 - Aprovado (200)
{
  "id": "clch_card_001",
  "correlationId": "order_123",
  "paymentMethod": "CARD",
  "status": "paid",
  "cardLastFour": "0010",
  "cardBrand": "visa",
  "installments": 1,
  "amount": 14990,
  "paid": true,
  "userMessage": "Pagamento aprovado com sucesso"
}
Modificado em 2026-07-02 06:57:27
Página anterior
Cartão (Checkout Transparente)
Próxima página
Saldo
Built with