CodiePay 8.0.4

CodiePay 🚀

CodiePay é uma abstração de hub de pagamentos moderna e flexível projetada para suportar múltiplos provedores de pagamentos. Atualmente com suporte completo para Asaas, nossa arquitetura permite expansão futura para outros gateways como Stripe, Mercado Pago, PayPal e mais, mantendo uma API unificada e consistente.

🎯 Visão de Futuro

Enquanto nossa implementação atual foca no provedor Asaas (com suporte a 100% das funcionalidades), a arquitetura do CodiePay foi concebida para crescimento escalável:

• ✅ Asaas - Suporte completo implementado
• 🚧 Stripe - Em desenvolvimento
• 📋 Mercado Pago - Roadmap
• 📋 PayPal - Roadmap
• 📋 Outros provedores - Arquitetura pronta para expansão

✨ Funcionalidades (Suporte Asaas)

• 🎯 API Unificada - Interface simples preparada para múltiplos provedores
• 💳 Múltiplos Métodos - Pix, Boleto, Cartão de Crédito
• 🔄 Assinaturas - Cobranças recorrentes com ciclos flexíveis
• 💰 Splits - Divisão de pagamentos entre múltiplas contas
• 🔁 Estornos - Processamento de reembolsos simplificado
• 📊 Paginação - Listagem de pagamentos com filtros avançados
• ✅ Validação - Validação automática de dados com FluentValidation
• 🏗️ Arquitetura Extensível - Fácil adição de novos provedores

📦 Instalação

dotnet add package CodiePay

🚀 Configuração Rápida

using Microsoft.Extensions.DependencyInjection;
using CodiePay.Hub;
using CodiePay.Infra.Factories;

// Configurar serviços
var services = new ServiceCollection();
var serviceProvider = services.BuildServiceProvider();

// Criar factory e PayHub
var factory = new HubProviderFactory(serviceProvider);
var payHub = new PayHub(factory);

💡 Exemplos de Uso

1. Criar Cobrança Pix

var dto = new CheckoutDto
{
    // Dados do cliente
    CustomerName = "João da Silva",
    CustomerCpfCnpj = "12345678909",
    CustomerEmail = "joao@example.com",
    CustomerPhone = "43984298786",
    CustomerPostalCode = "86010190",
    CustomerCity = "Londrina",
    CustomerState = "PR",
    CustomerStreet = "Avenida Duque de Caxias",
    CustomerNumber = "1726",
    
    // Dados do pagamento
    PaymentBillingType = BillingType.Pix,
    PaymentValue = 100.00m,
    PaymentDueDate = DateTime.UtcNow,
    
    // Configuração do provedor (atualmente Asaas)
    ApiKey = "sua_api_key_aqui",
    ProviderType = ProviderType.Asaas, // Único provedor disponível atualmente
    BaseUrl = "https://api-sandbox.asaas.com/v3/"
};

var result = await payHub.DoPaymentCheckout(dto);

if (result.Success)
{
    Console.WriteLine($"Pagamento criado: {result.Result.PaymentId}");
    Console.WriteLine($"QR Code Pix: {result.Result.PixQrCode}");
    Console.WriteLine($"Imagem QR Code: {result.Result.PixQrCodeImage}");
}

2. Criar Cobrança com Cartão de Crédito

var dto = new CheckoutDto
{
    // Dados do cliente
    CustomerName = "Maria Santos",
    CustomerCpfCnpj = "98765432100",
    CustomerEmail = "maria@example.com",
    
    // Dados do pagamento
    PaymentBillingType = BillingType.Credit,
    PaymentValue = 150.50m,
    PaymentDueDate = DateTime.UtcNow,
    
    // Dados do cartão
    CreditCardHolderName = "Maria Santos",
    CreditCardNumber = "4111111111111111",
    CreditCardExpiryMonth = "12",
    CreditCardExpiryYear = "2027",
    CreditCardCCV = "123",
    RemoteIp = "189.45.123.10",
    
    // Dados do titular do cartão
    CreditCardHolderInfoName = "Maria Santos",
    CreditCardHolderInfoEmail = "maria@example.com",
    CreditCardHolderInfoCpfCnpj = "98765432100",
    CreditCardHolderInfoPostalCode = "86020010",
    CreditCardHolderInfoAddressNumber = "123",
    CreditCardHolderInfoMobilePhone = "43999998888",
    
    // Configuração do provedor (atualmente Asaas)
    ApiKey = "sua_api_key_aqui",
    ProviderType = ProviderType.Asaas, // Único provedor disponível atualmente
    BaseUrl = "https://api-sandbox.asaas.com/v3/"
};

var result = await payHub.DoPaymentCheckout(dto);

if (result.Success)
{
    Console.WriteLine($"Pagamento aprovado: {result.Result.PaymentId}");
    Console.WriteLine($"URL do recibo: {result.Result.TransactionReceiptUrl}");
}

3. Criar Assinatura Mensal

var dto = new CheckoutDto
{
    // Dados do cliente
    CustomerName = "Empresa ABC Ltda",
    CustomerCpfCnpj = "12345678909",
    CustomerEmail = "financeiro@empresaabc.com",
    
    // Dados da assinatura
    SubscriptionBillingType = BillingType.Pix,
    SubscriptionValue = 29.90m,
    SubscriptionNextDueDate = DateTime.UtcNow,
    SubscriptionCycle = BillingInterval.Monthly,
    SubscriptionDescription = "Plano Premium Mensal",
    SubscriptionUpdatePendingPayments = true,
    
    // Configuração do provedor (atualmente Asaas)
    ApiKey = "sua_api_key_aqui",
    ProviderType = ProviderType.Asaas, // Único provedor disponível atualmente
    BaseUrl = "https://api-sandbox.asaas.com/v3/"
};

var result = await payHub.DoSubscriptionCheckout(dto);

if (result.Success)
{
    Console.WriteLine($"Assinatura criada: {result.Result.SubscriptionId}");
    Console.WriteLine($"QR Code para primeira cobrança: {result.Result.PixQrCode}");
    Console.WriteLine($"Status: {result.Result.StatusPaymentSubscription}");
}

4. Criar Cobrança com Splits

var dto = new CheckoutDto
{
    // Dados do cliente
    CustomerName = "Loja Exemplo",
    CustomerCpfCnpj = "12345678909",
    
    // Dados do pagamento
    PaymentBillingType = BillingType.Pix,
    PaymentValue = 1000.00m,
    PaymentDueDate = DateTime.UtcNow,
    
    // Configuração dos splits
    Splits = new List<SplitDto>
    {
        new() { 
            WalletId = "wallet_id_principal", 
            FixedValue = 700.00m,
            Description = "Receita principal"
        },
        new() { 
            WalletId = "wallet_id_secundario", 
            FixedValue = 300.00m,
            Description = "Comissão parceiro"
        }
    },
    
    // Configuração do provedor (atualmente Asaas)
    ApiKey = "sua_api_key_aqui",
    ProviderType = ProviderType.Asaas, // Único provedor disponível atualmente
    BaseUrl = "https://api-sandbox.asaas.com/v3/"
};

var result = await payHub.DoPaymentCheckout(dto);

if (result.Success)
{
    Console.WriteLine($"Pagamento com splits criado: {result.Result.PaymentId}");
    Console.WriteLine($"Valor total: {result.Result.Value}");
    Console.WriteLine($"Splits configurados: {dto.Splits.Count}");
}

5. Listar Pagamentos

var request = new PaymentSearchRequestDto
{
    ApiKey = "sua_api_key_aqui",
    ProviderType = ProviderType.Asaas, // Único provedor disponível atualmente
    BaseUrl = "https://api-sandbox.asaas.com/v3/",
    Status = "PENDING", // PENDING, CONFIRMED, RECEIVED, OVERDUE, REFUNDED
    Page = 1,
    PageSize = 20,
    Customer = "customer_id_opcional",
    BillingType = "PIX" // PIX, BOLETO, CREDIT_CARD
};

var result = await payHub.GetPaymentsPaginatedAsync(request);

Console.WriteLine($"Total de pagamentos: {result.TotalCount}");
Console.WriteLine($"Página atual: {result.Offset / result.Limit + 1}");

foreach (var payment in result.Data)
{
    Console.WriteLine($"ID: {payment.Id}");
    Console.WriteLine($"Valor: R$ {payment.Value}");
    Console.WriteLine($"Status: {payment.Status}");
    Console.WriteLine($"Vencimento: {payment.DueDate:dd/MM/yyyy}");
    Console.WriteLine("---");
}

6. Atualizar Pagamento

var dto = new PaymentDto
{
    PaymentId = "pay_123456789",
    Value = 150.00m,
    DueDate = DateTime.Now.AddDays(5),
    Description = "Pagamento atualizado - " + DateTime.Now.ToString(),
    ApiKey = "sua_api_key_aqui",
    ProviderType = ProviderType.Asaas, // Único provedor disponível atualmente
    BaseUrl = "https://api-sandbox.asaas.com/v3/"
};

var result = await payHub.UpdatePayment(dto);

if (result != null)
{
    Console.WriteLine($"Pagamento atualizado: {result.Id}");
    Console.WriteLine($"Novo valor: R$ {result.Value}");
    Console.WriteLine($"Nova data de vencimento: {result.DueDate:dd/MM/yyyy}");
}

7. Cancelar Pagamento

var dto = new RequestDto
{
    Id = "pay_123456789",
    ApiKey = "sua_api_key_aqui",
    ProviderType = ProviderType.Asaas, // Único provedor disponível atualmente
    BaseUrl = "https://api-sandbox.asaas.com/v3/"
};

var result = await payHub.CancelPayment(dto);

if (result)
{
    Console.WriteLine("Pagamento cancelado com sucesso");
}

8. Estornar Pagamento Boleto

var dto = new RequestDto
{
    Id = "pay_123456789",
    ApiKey = "sua_api_key_aqui",
    ProviderType = ProviderType.Asaas, // Único provedor disponível atualmente
    BaseUrl = "https://api-sandbox.asaas.com/v3/"
};

var result = await payHub.RefundBoletoPayment(dto);

if (!string.IsNullOrEmpty(result))
{
    Console.WriteLine($"Solicitação de estorno criada: {result}");
    Console.WriteLine("Acompanhe o status através da URL retornada");
}

9. Estornar Pagamento Pix/Cartão

var dto = new CreditOrPixRefundDto
{
    Id = "pay_123456789",
    Value = 50.00m, // Valor opcional (se não informado, estorna valor total)
    Description = "Estorno parcial - produto devolvido",
    ApiKey = "sua_api_key_aqui",
    ProviderType = ProviderType.Asaas, // Único provedor disponível atualmente
    BaseUrl = "https://api-sandbox.asaas.com/v3/"
};

var result = await payHub.RefundCreditOrPixPayment(dto);

if (result.Success)
{
    Console.WriteLine($"✅ {result.Message}");
    Console.WriteLine("Estorno processado com sucesso");
}
else
{
    Console.WriteLine($"❌ {result.Message}");
    Console.WriteLine("Não foi possível processar o estorno");
}

📋 Respostas da API

CheckoutResponse

public class CheckoutResponse
{
    public string PaymentId { get; set; }
    public string SubscriptionId { get; set; }
    public BillingType BillingType { get; set; }
    public decimal Value { get; set; }
    public string Status { get; set; }
    public string PixQrCode { get; set; }
    public string PixQrCodeImage { get; set; }
    public string BankSlipUrl { get; set; }
    public string TransactionReceiptUrl { get; set; }
    public string InvoiceUrl { get; set; }
    public DateTime DueDate { get; set; }
    public string StatusPaymentSubscription { get; set; }
}

RefundResultResponse

public class RefundResultResponse
{
    public bool Success { get; set; }
    public string Message { get; set; }
}

ResultDto<T>

public class ResultDto<T>
{
    public bool Success { get; set; }
    public T Result { get; set; }
    public List<string> Errors { get; set; }
}

🔧 Configuração de Ambiente (Asaas)

Sandbox (Desenvolvimento)

BaseUrl = "https://api-sandbox.asaas.com/v3/"

Produção

BaseUrl = "https://www.asaas.com/api/v3/"

Nota: Atualmente o CodiePay suporta apenas o provedor Asaas. A arquitetura foi projetada para permitir fácil expansão para outros provedores no futuro.

🎯 Tipos de Dados

BillingType

• Pix - Pagamento instantâneo via QR Code
• Boleto - Boleto bancário
• Credit - Cartão de crédito

BillingInterval (Assinaturas)

• Weekly - Semanal
• Monthly - Mensal
• Yearly - Anual

PaymentStatus

• Pending - Aguardando pagamento
• Confirmed - Confirmado
• Received - Recebido
• Overdue - Vencido
• Refunded - Estornado
• RefundInProgress - Estorno em andamento
• RefundRequest - Solicitação de estorno

🛡️ Segurança

• Nunca exponha sua API Key em código cliente
• Utilize sempre HTTPS em produção
• Implemente validação adicional no backend
• Configure webhooks para receber notificações de status

🤝 Contribuição

Contribuições são bem-vindas! Estamos especialmente interessados em:

• 🚀 Novos Provedores - Ajuda a implementar Stripe, Mercado Pago, PayPal
• 🐛 Bug Fixes - Correções e melhorias
• 📚 Documentação - Exemplos e guias
• ✨ Features - Novas funcionalidades

Por favor:

1. Fork o projeto
2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
4. Push para a branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request

🛣️ Roadmap de Provedores

• ✅ Asaas - Suporte completo
• 🚧 Stripe - Em desenvolvimento
• 📋 Mercado Pago - Próximo da fila
• 📋 PayPal - Planejado
• 📋 Open Finance - Futuro

📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

🆘 Suporte

• 📧 Email: codiebackend@gmail.com

Feito com ❤️ pela equipe Codie Digital