AbacatePayDotNet 1.0.0

AbacatePay .NET SDK

Unofficial AbacatePay SDK for .NET - Accept payments in seconds with a simple integration.

?? AbacatePay is a modern payment platform focused on the Brazilian market, offering seamless PIX integration and billing management.

?? Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Usage Examples
• Configuration
• API Reference
• Error Handling
• Testing
• Contributing
• License

? Features

• ? PIX Payment Support - Brazilian instant payment system
• ? Billing Management - Create and manage payment links
• ? Customer Management - Store and retrieve customer information
• ? Async/Await - Full asynchronous support
• ? Dependency Injection - First-class DI support for ASP.NET Core
• ? Automatic Retry - Built-in retry logic with exponential backoff
• ? Type Safety - Strongly typed models and enums
• ? Error Handling - Comprehensive exception types
• ? .NET Standard 2.0 - Compatible with .NET Framework 4.6.1+, .NET Core 2.0+, .NET 5+
• ? Thread-Safe - Safe for concurrent operations
• ? Well Documented - XML comments for IntelliSense

?? Requirements

• .NET Standard 2.0 or higher
• Compatible with:
  • .NET Framework 4.6.1+
  • .NET Core 2.0+
  • .NET 5, 6, 7, 8+
  • Xamarin
  • Unity (with .NET Standard 2.0 profile)

?? Installation

Using .NET CLI

dotnet add package AbacatePay

Using Package Manager Console

Install-Package AbacatePay

Using Visual Studio

1. Right-click on your project
2. Select "Manage NuGet Packages"
3. Search for "AbacatePay"
4. Click "Install"

?? Quick Start

Simple Usage

using AbacatePay;
using AbacatePay.Models.Billing;
using AbacatePay.Models.Customer;
using AbacatePay.Models.Enums;

// Initialize the client
var client = new AbacatePayClient("your_api_key");

// Create a customer
var customer = await client.Customer.Create(new CustomerMetadata
{
    Name = "Jo�o Silva",
    Email = "joao@example.com",
    Cellphone = "+5511999999999",
    TaxId = "12345678900"
});

// Create a billing
var billing = await client.Billing.Create(new BillingRequest
{
    Frequency = BillingFrequency.OneTime,
    Methods = new List<PaymentMethod> { PaymentMethod.Pix },
    Products = new List<Product>
    {
        new Product
        {
            ExternalId = "PROD-001",
            Name = "Premium Plan",
            Quantity = 1,
            Price = 9900 // R$ 99,00 in cents
        }
    },
    ReturnUrl = "https://yoursite.com/return",
    CompletionUrl = "https://yoursite.com/success",
    CustomerId = customer.Id
});

Console.WriteLine($"Payment URL: {billing.Url}");

ASP.NET Core Integration

Startup.cs / Program.cs

using AbacatePay.Configuration;

// Add services
builder.Services.AddAbacatePay(options =>
{
    options.ApiKey = builder.Configuration["AbacatePay:ApiKey"];
    options.BaseUrl = "https://api.abacatepay.com/v1";
    options.TimeoutSeconds = 30;
    options.MaxRetryAttempts = 3;
});

appsettings.json

{
  "AbacatePay": {
    "ApiKey": "your_api_key_here"
  }
}

Controller

using AbacatePay;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/[controller]")]
public class PaymentController : ControllerBase
{
    private readonly IAbacatePayClient _abacatePay;

    public PaymentController(IAbacatePayClient abacatePay)
    {
        _abacatePay = abacatePay;
    }

    [HttpPost("create")]
    public async Task<IActionResult> CreatePayment([FromBody] CreatePaymentRequest request)
    {
        try
        {
            var billing = await _abacatePay.Billing.Create(new BillingRequest
            {
                Frequency = BillingFrequency.OneTime,
                Methods = new List<PaymentMethod> { PaymentMethod.Pix },
                Products = request.Products,
                ReturnUrl = "https://yoursite.com/return",
                CompletionUrl = "https://yoursite.com/success",
                Customer = request.Customer
            });

            return Ok(new { paymentUrl = billing.Url });
        }
        catch (AbacatePayException ex)
        {
            return BadRequest(new { error = ex.Message });
        }
    }
}

?? Usage Examples

Creating a Billing with Multiple Products

var billing = await client.Billing.Create(new BillingRequest
{
    Frequency = BillingFrequency.OneTime,
    Methods = new List<PaymentMethod> { PaymentMethod.Pix },
    Products = new List<Product>
    {
        new Product
        {
            ExternalId = "CURSO-001",
            Name = ".NET Advanced Course",
            Description = "Complete .NET Core and C# course",
            Quantity = 1,
            Price = 49900 // R$ 499,00
        },
        new Product
        {
            ExternalId = "EBOOK-001",
            Name = "Design Patterns E-book",
            Quantity = 1,
            Price = 5000 // R$ 50,00
        }
    },
    ReturnUrl = "https://yoursite.com/courses",
    CompletionUrl = "https://yoursite.com/success",
    Customer = new CustomerMetadata
    {
        Name = "Maria Santos",
        Email = "maria@example.com",
        Cellphone = "+5511988887777"
    },
    AllowCoupons = true,
    Coupons = new List<string> { "PROMO10", "BLACKFRIDAY" }
});

Listing All Billings

var billings = await client.Billing.List();

foreach (var billing in billings)
{
    Console.WriteLine($"ID: {billing.Id}");
    Console.WriteLine($"Amount: R$ {billing.Amount / 100.0:F2}");
    Console.WriteLine($"Status: {billing.Status}");
    Console.WriteLine($"Created: {billing.CreatedAt}");
    Console.WriteLine();
}

Managing Customers

// Create customer
var customer = await client.Customer.Create(new CustomerMetadata
{
    Name = "Pedro Oliveira",
    Email = "pedro@example.com",
    Cellphone = "+5511977776666",
    TaxId = "12345678900"
});

// List all customers
var customers = await client.Customer.List();

## ?? Configuration

### Configuration Options

```csharp
services.AddAbacatePay(options =>
{
    // Required: Your API key
    options.ApiKey = "your_api_key";
    
    // Optional: Base URL (default: production)
    options.BaseUrl = "https://api.abacatepay.com/v1";
    
    // Optional: Request timeout in seconds (default: 30)
    options.TimeoutSeconds = 30;
    
    // Optional: Max retry attempts (default: 3)
    options.MaxRetryAttempts = 3;
    
    // Optional: Development mode (default: false)
    options.DevMode = false;
});

Environment Variables

For security, it's recommended to use environment variables:

options.ApiKey = Environment.GetEnvironmentVariable("ABACATEPAY_API_KEY")
    ?? throw new InvalidOperationException("API key not configured");

?? API Reference

BillingService

CreateAsync

Creates a new billing.

Task<Billing> Create(BillingRequest request, CancellationToken cancellationToken = default)

ListAsync

Lists all billings.

Task<List<Billing>> List(CancellationToken cancellationToken = default)

CustomerService

CreateAsync

Creates a new customer.

Task<Customer> Create(CustomerMetadata metadata, CancellationToken cancellationToken = default)

ListAsync

Lists all customers.

Task<List<Customer>> List(CancellationToken cancellationToken = default)

?? Error Handling

The SDK provides specific exception types for different error scenarios:

try
{
    var billing = await client.Billing.Create(request);
}
catch (ValidationException ex)
{
    // Handle validation errors
    Console.WriteLine($"Validation error: {ex.Message}");
}
catch (AuthenticationException ex)
{
    // Handle authentication errors
    Console.WriteLine($"Authentication failed: {ex.Message}");
}
catch (ApiException ex)
{
    // Handle API errors
    Console.WriteLine($"API error: {ex.Message}");
    Console.WriteLine($"Status code: {ex.StatusCode}");
    Console.WriteLine($"Error code: {ex.ErrorCode}");
}
catch (AbacatePayException ex)
{
    // Handle general AbacatePay errors
    Console.WriteLine($"Error: {ex.Message}");
}

Exception Hierarchy

• AbacatePayException - Base exception
  • ApiException - API-related errors
    • AuthenticationException - Authentication failures
  • ValidationException - Request validation errors

?? Testing

Unit Tests

dotnet test

Integration Tests

Set your API key as an environment variable:

export ABACATEPAY_TEST_API_KEY="your_test_api_key"
dotnet test --filter "Category=Integration"

?? Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

1. Clone the repository

git clone https://github.com/Tabgyn/abacatepay-dotnet-sdk.git

2. Restore dependencies

dotnet restore

3. Build the project

dotnet build

4. Run tests

dotnet test

?? License

This project is licensed under the MIT License - see the LICENSE file for details.

?? Links

• Official Documentation
• API Reference
• GitHub Repository
• NuGet Package
• Report Issues

?? Support

• ?? Email: ajuda@abacatepay.com
• ?? Discord: Join our community
• ?? Documentation: docs.abacatepay.com

?? Show Your Support

If you find this SDK helpful, please give it a ?? on GitHub!

Made with ?? by Tiago