Cartão de Crédito - Avantti Finance

O Cartão de Crédito permite que você receba pagamentos online de forma imediata através de transações com cartões de crédito das principais bandeiras. Ideal para e-commerce, assinaturas, serviços digitais e vendas onde a confirmação instantânea é necessária. A aprovação ocorre em tempo real, permitindo liberar o produto ou serviço imediatamente após a autorização.

🚀 Como Funciona

O Card funciona através da criação de uma transação utilizando os dados do cartão do cliente. Esses dados são enviados de forma segura e tokenizados antes de serem processados na rede adquirente.

📱 Você cria uma cobrança na API

Você gera uma cobrança com valor específico através da API

💳 Os dados do cartão são enviados com segurança

Tokenizamos o cartão para que os dados sejam enviados de forma segura.

⚡A transação é autorizada pela operadora do cartão

Você recebe confirmação assim que o pagamento for validado

💰 Retornamos o resultado imediatamente

Valor fica disponível imediatamente em sua conta para antecipação.

🛠️ Implementação Rápida

1. Criar Token do cartão

curl -X POST 'https://api.avanttifinance.com/v1/card-token' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <seu_token>' \
  -d '{
  "number": "4111111111111111",
  "holderName": "JOAO SILVA",
  "expirationMonth": "12",
  "expirationYear": "28",
  "cvv": "123"
}'

2. Resposta com token gerado

{
  "success": true,
  "token": "ct_AbCdEfGhIjKlMnOpQrStUvWxYz1234567890"
}

📊 Parâmetros Detalhados

Campos Obrigatórios

Campo	Tipo	Descrição
`number`	`string`	Número do cartão (13–19 dígitos, Luhn válido)
`holderName`	`string`	Nome do titular (mín. 2 caracteres)
`expirationMonth`	`string`	Mês (01–12)
`expirationYear`	`string`	Ano (2 dígitos ex: “28” ou 4 ex: “2028”)
`cvv`	`string`	Código de segurança (3 ou 4 dígitos)

3. Criar transação

⚠️ Validação do valor total da transação

O campo amountInCents enviado fora do array items representa o valor total da cobrança. Para que a requisição seja aceita, esse valor deve ser exatamente igual à soma do valor de cada item multiplicado por sua respectiva quantidade. Em outras palavras:

O total da transação precisa corresponder ao somatório de amountInCents × quantity de todos os itens informados.

curl -X POST 'https://api.avanttifinance.com/v1/card' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <seu_token>' \
  -d '{
  "postbackUrl": "https://seu-sistema.com/webhooks/avantti",
  "amountInCents": 9990,
  "description": "Compra Produto X",
  "card": {
    "cardToken": "ct_AbCdEfGhIjKlMnOpQrStUvWxYz1234567890",
    "installments": 1,
    "holderName": "JOAO SILVA"
  },
  "customer": {
    "name": "João da Silva",
    "email": "joao@email.com",
    "documentType": "cpf",
    "document": "12345678909",
    "phone": "11999999999",
    "billingAddress": {
      "street": "Rua das Flores",
      "number": "100",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "zipCode": "01310100"
    }
  },
  "items": [
    {
      "title": "Produto X",
      "tangible": false,
      "quantity": 1,
      "amountInCents": 9990
    }
  ]
}'

4. Resposta Transação Aprovada

{
  "success": true,
  "message": "Transação criada com sucesso",
  "data": {
    "id": "clxyz123abc456",
    "card": {
      "token": "tok_xxxx",
      "brand": "Visa",
      "last4": "1111"
    },
    "status": "paid",
    "fees": 350
  }
}

4. Resposta Transação Recusada

{
  "success": false,
  "message": "Erro ao criar transação"
}

📊 Parâmetros Detalhados

Campos Obrigatórios

Campo	Tipo	Descrição
`amountInCents`	`number`	Valor total em centavos (9990 = R$ 99,90)
`card.cardToken`	`string`	Token retornado por `/v1/card-token` ou token da Pagar.me
`expirationYear`	`string`	Ano (2 dígitos ex: “28” ou 4 ex: “2028”)
`items`	`array`	Itens da venda
`customer`	`object`	Dados do comprador (documentType: cpf/cnpj, document válido)
`customer.billingAddress`	`object`	Endereço de cobrança (recomendado para Pagar.me)
`customer.email`	`string`	Email do cliente
`customer.documentType`	`string`	Tipo do documento (`cpf` ou `cnpj`)
`customer.document`	`string`	Números do documento do cliente
`customer.phone`	`string`	Telefone do cliente
`customer.name`	`customer`	Nome completo do cliente

Campos Opcionais

Campo	Tipo	Descrição
`description`	`string`	Descrição da transação (máx. 140 caracteres)
`postbackUrl`	`string`	URL específica para webhooks desta transação
`seller`	`object`	informações sobre vendedor
`card.installments`	`number`	Parcelas (default: 1)
`card.holderNamer`	`string`	Nome do titular

📡 Recebendo Confirmações

Via Webhook

Criado:

{
  "id": "uuid-do-webhook",
  "type": "transaction",
  "event": "transaction_created",
  "scope": "postback",
  "transaction": {
    "id": "clxyz123abc456",
    "amount": 9990,
    "status": "paid",
    "pix": null
  }
}

Recusado:

{
  "id": "uuid-do-webhook",
  "type": "transaction",
  "event": "card_declined",
  "scope": "postback",
  "transaction": {
    "id": "clxyz123abc456",
    "amount": 9990,
    "status": "refused",
    "pix": null
  }
}

Chargeback:

{
  "id": "uuid-do-webhook",
  "type": "transaction",
  "event": "transaction_refunded",
  "scope": "postback",
  "transaction": {
    "id": "clxyz123abc456",
    "amount": 9990,
    "status": "refund",
    "pix": null
  }
}

📋 Status das Transações

Status	Descrição	Próximo Passo
`pending`	Aguardando pagamento	Mostrar QR Code para cliente
`paid`	Pago com sucesso	Liberar produto/serviço
`canceled`	Cancelado	Gerar novo QR Code se necessário
`refunded`	Estornado	Valor devolvido ao pagador

🛡️ Boas Práticas

Segurança

🔒 Validação de Dados

Sempre valide CPF/CNPJ antes de enviar
Sanitize dados de entrada
Verifique valores mínimos e máximos
Use HTTPS obrigatoriamente

🔄 Idempotência

Use IDs únicos para cada transação
Implemente verificação de duplicatas
Mantenha referências internas
Trate reenvios de webhook adequadamente

📊 Monitoramento

Monitore taxa de conversão
Acompanhe tempos de pagamento
Verifique abandono de carrinho
Alerte sobre falhas de webhook

Performance

Timeout: Configure timeouts adequados para requisições
Retry: Implemente retry para chamadas falhadas
Batch: Agrupe operações quando possível

🎯 Próximos Passos

📝 Criar QR Code

Guia detalhado para criar QR Codes PIX

🔗 Configurar Webhooks

Configure notificações automáticas

🚀 PIX OUT

Aprenda a enviar transferências PIX

📊 Relatórios

Monitore suas transações

​🚀 Como Funciona

📱 Você cria uma cobrança na API

💳 Os dados do cartão são enviados com segurança

⚡A transação é autorizada pela operadora do cartão

💰 Retornamos o resultado imediatamente

​🛠️ Implementação Rápida

​1. Criar Token do cartão

​2. Resposta com token gerado

​📊 Parâmetros Detalhados

​Campos Obrigatórios

​3. Criar transação

​⚠️ Validação do valor total da transação

​4. Resposta Transação Aprovada

​4. Resposta Transação Recusada

​📊 Parâmetros Detalhados

​Campos Obrigatórios

​Campos Opcionais

​📡 Recebendo Confirmações

​Via Webhook

​📋 Status das Transações

​🛡️ Boas Práticas

​Segurança

​Performance

​🎯 Próximos Passos

📝 Criar QR Code

🔗 Configurar Webhooks

🚀 PIX OUT

📊 Relatórios

🚀 Como Funciona

🛠️ Implementação Rápida

1. Criar Token do cartão

2. Resposta com token gerado

📊 Parâmetros Detalhados

Campos Obrigatórios

3. Criar transação

⚠️ Validação do valor total da transação

4. Resposta Transação Aprovada

4. Resposta Transação Recusada

📊 Parâmetros Detalhados

Campos Obrigatórios

Campos Opcionais

📡 Recebendo Confirmações

Via Webhook

📋 Status das Transações

🛡️ Boas Práticas

Segurança

Performance

🎯 Próximos Passos