@polymorphism-tech/morph-spec 8.45.0 → 8.47.0

package/framework/standards/backend/integrations/asaas/asaas-api.md

@@ -5,11 +5,11 @@
 > **Keywords:** asaas, payment, brazilian, pix, boleto, billing
 > **Load When:** asaas or brazilian payment keywords detected
 
-**Verified against:** Asaas REST API v3 (no official Node SDK — direct REST). Last-verified: 2026-05-20.
+**Verified against:** Asaas REST API v3 (docs read via context7 on 2026-10-03: headers, `POST /payments`, `GET /payments?externalReference=`, `pixQrCode`, webhook payload, delivery and error rules) + .NET 10 (SDK 10.0.400-preview, `IHttpClientFactory` from the ASP.NET Core shared framework) + EF Core 10.0.12. The options, client, registration, PIX slice, webhook slice/endpoint and CPF/CNPJ blocks compile with `TreatWarningsAsErrors` over the `Result`/`ErrorHttpMapping` of `result-pattern.md`; the CPF/CNPJ validator was run against valid and invalid documents (numeric and the alphanumeric `12.ABC.345/01DE-35`), and the `BaseUrl` trailing-slash rule and the `dueDate` JSON shape were checked by running them; the SQL is documentary. Last-verified: 2026-10-03.
 
 ---
 
-Brazilian payment gateway integration for PIX, Boleto, and credit card processing.
+Brazilian payment gateway integration for PIX, Boleto, and credit card processing, from the .NET backend. The Next.js frontend never calls Asaas and never sees the API key: it calls the backend endpoints through the proxy (TanStack Query), and the backend talks to Asaas.
 
 ---
 
@@ -22,239 +22,383 @@ Asaas is a Brazilian payment service provider offering:
 - Subscription billing
 - Split payments
 
-**Stack:** .NET Backend
+Asaas publishes **no official .NET SDK** -- integrate against the documented REST API with a typed `HttpClient`. Community wrappers exist but are unofficial and vary in maintenance.
 
 ---
 
 ## Core Principles
 
-1. **Webhook-First**: All payment state changes via webhooks
-2. **Idempotency**: Use idempotency keys for all POST requests
-3. **Security**: Validate webhook signatures, never store full card data
-4. **Brazil-Specific**: Handle CPF/CNPJ validation, Brazilian tax rules
+1. **Webhook-First**: payment state changes arrive by webhook; the local record follows the events
+2. **No duplicate charges**: every charge carries your own id in `externalReference`; before retrying a create, look it up (the create endpoint is not idempotent and Asaas documents no idempotency-key header)
+3. **Security**: compare the webhook token in constant time, never store full card data, the API key lives in configuration
+4. **Brazil-Specific**: validate CPF/CNPJ (including the alphanumeric CNPJ), compute due dates in `America/Sao_Paulo`
+5. **Result, not exceptions**: Asaas 4xx answers become `Result` failures mapped by `ErrorType`; only network/5xx surprises propagate as exceptions
 
 ---
 
 ## API Configuration
 
-### Environment Variables
+### Configuration (user-secrets in dev, Coolify environment variables in prod)
 
 ```bash
-# .env.local
-ASAAS_API_KEY=your_api_key_here
-ASAAS_WEBHOOK_SECRET=your_webhook_secret
-ASAAS_ENVIRONMENT=sandbox # or production
+dotnet user-secrets set "Asaas:ApiKey" "<sandbox-api-key>"
+dotnet user-secrets set "Asaas:WebhookToken" "<webhook-auth-token>"
+# Coolify: Asaas__ApiKey, Asaas__WebhookToken, Asaas__BaseUrl, Asaas__UserAgent
 ```
 
-### REST Client Setup
-
-Asaas has **no official Node SDK** — integrate against the documented REST API
-directly. The API key goes in the `access_token` header; the base URL switches
-between sandbox and production.
-
-```typescript
-// lib/asaas/client.ts
-const ASAAS_BASE_URL =
-  process.env.ASAAS_ENVIRONMENT === 'production'
-    ? 'https://api.asaas.com/v3'
-    : 'https://api-sandbox.asaas.com/v3';
-
-export async function asaasFetch<T>(
-  path: string,
-  init?: RequestInit,
-): Promise<T> {
-  const res = await fetch(`${ASAAS_BASE_URL}${path}`, {
-    ...init,
-    headers: {
-      'Content-Type': 'application/json',
-      access_token: process.env.ASAAS_API_KEY!,
-      ...init?.headers,
-    },
-  });
-  if (!res.ok) {
-    throw new Error(`Asaas ${res.status}: ${await res.text()}`);
-  }
-  return res.json() as Promise<T>;
+| Key | Sandbox | Production |
+|-----|---------|------------|
+| `Asaas:BaseUrl` | `https://api-sandbox.asaas.com/v3/` | `https://api.asaas.com/v3/` |
+| `Asaas:ApiKey` | sandbox key | production key (keys are per environment) |
+| `Asaas:UserAgent` | `MyApp/1.0.0` | `MyApp/1.0.0` |
+| `Asaas:WebhookToken` | token set on the sandbox webhook | token set on the production webhook |
+
+### Options and typed client
+
+Every request carries three headers: `access_token` (the API key -- Asaas does **not** use `Authorization: Bearer`), `Content-Type: application/json`, and `User-Agent` (mandatory for root accounts created from 06/11/2024; send it always). A wrong or missing key answers 401.
+
+```csharp
+// Infrastructure/Asaas/AsaasOptions.cs
+using System.ComponentModel.DataAnnotations;
+
+public sealed class AsaasOptions
+{
+    [Required, Url] public string BaseUrl { get; init; } = string.Empty;
+    [Required] public string ApiKey { get; init; } = string.Empty;
+    [Required] public string UserAgent { get; init; } = string.Empty;
+    [Required] public string WebhookToken { get; init; } = string.Empty;
 }
 ```
 
+```csharp
+// Infrastructure/Asaas/AsaasClient.cs
+using System.Net;
+using System.Net.Http.Json;
+
+public sealed record AsaasCreatePayment(
+    string Customer, string BillingType, decimal Value, DateOnly DueDate, string? Description, string ExternalReference);
+public sealed record AsaasPayment(string Id, string Status, decimal Value, string? ExternalReference);
+public sealed record AsaasPixQrCode(string EncodedImage, string Payload, string? ExpirationDate);
+public sealed record AsaasPage<T>(IReadOnlyList<T> Data);
+public sealed record AsaasErrorItem(string Code, string Description);
+public sealed record AsaasErrorBody(IReadOnlyList<AsaasErrorItem> Errors);
+
+public sealed class AsaasClient(HttpClient http)
+{
+    public async Task<Result<AsaasPayment>> CreatePaymentAsync(AsaasCreatePayment payment, CancellationToken ct) =>
+        await ReadAsync<AsaasPayment>(await http.PostAsJsonAsync("payments", payment, ct), ct);
+
+    public async Task<Result<AsaasPage<AsaasPayment>>> FindByExternalReferenceAsync(string externalReference, CancellationToken ct) =>
+        await ReadAsync<AsaasPage<AsaasPayment>>(
+            await http.GetAsync($"payments?externalReference={Uri.EscapeDataString(externalReference)}", ct), ct);
+
+    public async Task<Result<AsaasPixQrCode>> GetPixQrCodeAsync(string paymentId, CancellationToken ct) =>
+        await ReadAsync<AsaasPixQrCode>(await http.GetAsync($"payments/{paymentId}/pixQrCode", ct), ct);
+
+    private static async Task<Result<T>> ReadAsync<T>(HttpResponseMessage response, CancellationToken ct)
+    {
+        using (response)
+        {
+            if (response.IsSuccessStatusCode)
+                return Result.Create(await response.Content.ReadFromJsonAsync<T>(ct));
+
+            if (response.StatusCode == HttpStatusCode.BadRequest)
+            {
+                var body = await response.Content.ReadFromJsonAsync<AsaasErrorBody>(ct);
+                var errors = body?.Errors.Select(e => Error.Validation($"Asaas.{e.Code}", e.Description)).ToArray() ?? [];
+                return errors.Length == 1 ? errors[0] : new ValidationError(errors);
+            }
+
+            return response.StatusCode == HttpStatusCode.NotFound
+                ? Error.NotFound("Asaas.NotFound", "Recurso não encontrado no Asaas.")
+                : Error.Unexpected("Asaas.Unexpected", $"Asaas respondeu {(int)response.StatusCode}.");
+        }
+    }
+}
+```
+
+```csharp
+// Program.cs (or an AddAsaas extension)
+using Microsoft.Extensions.Options;
+
+public static class AsaasRegistration
+{
+    public static IServiceCollection AddAsaas(this IServiceCollection services)
+    {
+        services.AddOptions<AsaasOptions>()
+            .BindConfiguration("Asaas")
+            .ValidateDataAnnotations()
+            .ValidateOnStart();
+
+        services.AddHttpClient<AsaasClient>((sp, http) =>
+        {
+            var options = sp.GetRequiredService<IOptions<AsaasOptions>>().Value;
+            http.BaseAddress = new Uri(options.BaseUrl);
+            http.DefaultRequestHeaders.Add("access_token", options.ApiKey);
+            http.DefaultRequestHeaders.UserAgent.ParseAdd(options.UserAgent);
+        });
+
+        return services;
+    }
+}
+```
+
+- `BaseUrl` **ends with `/`** and the relative paths do **not** start with `/` (`"payments"`): with `https://api.asaas.com/v3` (no slash) `HttpClient` resolves `payments` to `https://api.asaas.com/payments` and every call 404s.
+- `AsaasClient` is the adapter to an external API (a port), not a service layer between handler and data: the slice handler injects it next to the `ApplicationDbContext`.
+- `ReadFromJsonAsync`/`PostAsJsonAsync` use web defaults (camelCase), which is what Asaas speaks; `DateOnly` serializes as `yyyy-MM-dd`, the `dueDate` format.
+
 ---
 
 ## Common Operations
 
 ### Create PIX Payment
 
-```typescript
-// app/api/payments/pix/route.ts
-import { asaasFetch } from '@/lib/asaas/client';
-
-export async function POST(req: Request) {
-  const { amount, customerId, description } = await req.json();
-
-  // POST /v3/payments — billingType PIX
-  const payment = await asaasFetch<{ id: string }>('/payments', {
-    method: 'POST',
-    body: JSON.stringify({
-      customer: customerId,
-      billingType: 'PIX',
-      value: amount,
-      dueDate: new Date().toISOString().split('T')[0],
-      description,
-    }),
-  });
-
-  // GET /v3/payments/{id}/pixQrCode — PIX copy-paste payload + QR image
-  const pix = await asaasFetch<{ payload: string; encodedImage: string }>(
-    `/payments/${payment.id}/pixQrCode`,
-  );
-
-  return Response.json({
-    paymentId: payment.id,
-    pixCode: pix.payload,
-    qrCode: pix.encodedImage,
-  });
+```csharp
+// Features/PaymentFeature/CreatePixPayment/CreatePixPaymentHandler.cs
+using Microsoft.EntityFrameworkCore;
+
+public sealed record CreatePixPaymentRequest(Guid OrderId, string AsaasCustomerId, decimal Value, string? Description);
+public sealed record CreatePixPaymentResponse(Guid PaymentId, string AsaasPaymentId, string PixCode, string QrCodeImage);
+
+public sealed class CreatePixPaymentHandler(
+    ApplicationDbContext db,
+    AsaasClient asaas,
+    TimeProvider timeProvider)
+    : IHandler<CreatePixPaymentRequest, Result<CreatePixPaymentResponse>>
+{
+    private static readonly TimeZoneInfo SaoPaulo = TimeZoneInfo.FindSystemTimeZoneById("America/Sao_Paulo");
+
+    public async Task<Result<CreatePixPaymentResponse>> HandleAsync(
+        CreatePixPaymentRequest request, CancellationToken cancellationToken)
+    {
+        var externalReference = request.OrderId.ToString();
+
+        var existing = await asaas.FindByExternalReferenceAsync(externalReference, cancellationToken);
+        if (existing.IsFailure)
+            return existing.Error;
+
+        var remote = existing.Value.Data.FirstOrDefault();
+        if (remote is null)
+        {
+            var dueDate = DateOnly.FromDateTime(TimeZoneInfo.ConvertTime(timeProvider.GetUtcNow(), SaoPaulo).DateTime);
+            var created = await asaas.CreatePaymentAsync(
+                new AsaasCreatePayment(request.AsaasCustomerId, "PIX", request.Value, dueDate, request.Description, externalReference),
+                cancellationToken);
+            if (created.IsFailure)
+                return created.Error;
+            remote = created.Value;
+        }
+
+        var pix = await asaas.GetPixQrCodeAsync(remote.Id, cancellationToken);
+        if (pix.IsFailure)
+            return pix.Error;
+
+        var payment = await db.Payments.FirstOrDefaultAsync(p => p.AsaasPaymentId == remote.Id, cancellationToken);
+        if (payment is null)
+        {
+            payment = new Payment
+            {
+                Id = Guid.CreateVersion7(),
+                OrderId = request.OrderId,
+                AsaasPaymentId = remote.Id,
+                Amount = remote.Value,
+                Status = remote.Status,
+                BillingType = "PIX",
+                CreatedAt = timeProvider.GetUtcNow()
+            };
+            db.Payments.Add(payment);
+            await db.SaveChangesAsync(cancellationToken);
+        }
+
+        return new CreatePixPaymentResponse(payment.Id, remote.Id, pix.Value.Payload, pix.Value.EncodedImage);
+    }
 }
 ```
 
+- `POST /payments` with `billingType: "PIX"`, then `GET /payments/{id}/pixQrCode` for the copy-and-paste `payload` and the base64 `encodedImage`.
+- The `GET /payments?externalReference=` before the create is what makes a retried request (double click, timeout, job retry) reuse the charge instead of creating a second one.
+- The due date is "today in São Paulo": `DateTime.UtcNow.Date` rolls to tomorrow after 21:00 BRT.
+
 ### Webhook Handler
 
-Asaas does not HMAC-sign webhooks. Instead, every webhook request carries the
-`authToken` you configured for the webhook in the `asaas-access-token` header —
-compare it against your stored secret. The `authToken` is mandatory: a `POST
-/v3/webhooks` without one makes Asaas auto-generate a high-security token
-(32–255 chars, shown once in the response).
-
-```typescript
-// app/api/webhooks/asaas/route.ts
-import { headers } from 'next/headers';
-
-export async function POST(req: Request) {
-  const body = await req.text();
-
-  // Asaas sends the webhook's authToken in the asaas-access-token header
-  const token = headers().get('asaas-access-token');
-  if (token !== process.env.ASAAS_WEBHOOK_SECRET) {
-    return new Response('Invalid token', { status: 401 });
-  }
-
-  const event = JSON.parse(body);
-
-  // Handle payment events
-  switch (event.event) {
-    case 'PAYMENT_RECEIVED':
-      await handlePaymentReceived(event.payment);
-      break;
-    case 'PAYMENT_CONFIRMED':
-      await handlePaymentConfirmed(event.payment);
-      break;
-  }
-
-  return new Response('OK');
+Asaas does not HMAC-sign webhooks. Every webhook request carries the `authToken` configured on that webhook in the `asaas-access-token` header -- compare it to the stored secret (constant time) and answer 401 on mismatch. The `authToken` is mandatory: a `POST /v3/webhooks` without one makes Asaas generate a high-security token (32-255 chars, shown once in the response).
+
+Delivery is **at-least-once**: the same event (`id` like `evt_...`) can arrive more than once, so the handler records processed event ids. Asaas counts only HTTP 200 as delivered; after 15 consecutive failures the queue is interrupted (events kept for 14 days). Unknown events and payments you do not know still answer 200.
+
+```csharp
+// Features/PaymentFeature/AsaasWebhook/AsaasWebhook.cs
+using System.Security.Cryptography;
+using System.Text;
+using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.Options;
+using ProjectName.Abstractions;
+using ProjectName.Extensions;
+
+public sealed record AsaasWebhookPayment(string Id, string? Status, string? ExternalReference);
+public sealed record AsaasWebhookEvent(string Id, string Event, AsaasWebhookPayment? Payment);
+
+public sealed class ProcessAsaasWebhookHandler(ApplicationDbContext db, TimeProvider timeProvider)
+    : IHandler<AsaasWebhookEvent, Result>
+{
+    public async Task<Result> HandleAsync(AsaasWebhookEvent webhook, CancellationToken cancellationToken)
+    {
+        if (await db.ProcessedWebhookEvents.AnyAsync(e => e.EventId == webhook.Id, cancellationToken))
+            return Result.Success();
+
+        if (webhook.Event is "PAYMENT_CONFIRMED" or "PAYMENT_RECEIVED" && webhook.Payment is not null)
+        {
+            var payment = await db.Payments.FirstOrDefaultAsync(p => p.AsaasPaymentId == webhook.Payment.Id, cancellationToken);
+            if (payment is not null)
+                payment.Status = webhook.Payment.Status ?? webhook.Event;
+        }
+
+        db.ProcessedWebhookEvents.Add(new ProcessedWebhookEvent
+        {
+            EventId = webhook.Id,
+            ProcessedAt = timeProvider.GetUtcNow()
+        });
+        await db.SaveChangesAsync(cancellationToken);
+        return Result.Success();
+    }
+}
+
+internal sealed class AsaasWebhookEndpoint : IApiEndpoint
+{
+    public void MapEndpoint(IEndpointRouteBuilder app)
+    {
+        app.MapPost("webhooks/asaas", async (
+            HttpRequest request,
+            AsaasWebhookEvent webhook,
+            IOptions<AsaasOptions> options,
+            IHandler<AsaasWebhookEvent, Result> handler,
+            CancellationToken cancellationToken) =>
+        {
+            var received = Encoding.UTF8.GetBytes(request.Headers["asaas-access-token"].ToString());
+            var expected = Encoding.UTF8.GetBytes(options.Value.WebhookToken);
+            if (!CryptographicOperations.FixedTimeEquals(received, expected))
+                return Results.Unauthorized();
+
+            var result = await handler.HandleAsync(webhook, cancellationToken);
+            return result.Match(
+                onSuccess: () => Results.Ok(),
+                onFailure: error => error.ToHttpResult());
+        })
+        .ExcludeFromDescription();
+    }
 }
 ```
 
+`ProcessedWebhookEvent.EventId` has a **unique index**: two deliveries of the same event racing each other make the second `SaveChangesAsync` fail, Asaas sees a non-200 and redelivers, and the redelivery finds the id and answers 200. No catch is needed for that path.
+
 ---
 
 ## Database Schema (PostgreSQL / Neon)
 
 ```sql
--- Store payment records
-create table payments (
-  id uuid primary key default gen_random_uuid(),
-  user_id uuid references auth.users(id),
+create table public.payments (
+  id uuid primary key,                         -- Guid.CreateVersion7() in the handler
+  order_id uuid not null,
+  user_id uuid references public.users(id),
   asaas_payment_id text unique not null,
-  amount decimal(10,2) not null,
-  status text not null, -- pending, confirmed, received
-  billing_type text not null, -- PIX, BOLETO, CREDIT_CARD
-  created_at timestamptz default now(),
-  updated_at timestamptz default now()
+  amount numeric(10,2) not null,
+  status text not null,                        -- PENDING, CONFIRMED, RECEIVED, ...
+  billing_type text not null,                  -- PIX, BOLETO, CREDIT_CARD
+  created_at timestamptz not null,
+  updated_at timestamptz default now() not null
 );
 
--- RLS policies
-alter table payments enable row level security;
+create table public.processed_webhook_events (
+  event_id text primary key,                   -- Asaas evt_... id
+  processed_at timestamptz not null
+);
+
+alter table public.payments enable row level security;
 
 create policy "Users read own payments"
-  on payments for select
+  on public.payments for select
   using (auth.user_id() = user_id);
 ```
 
+Ids come from the app (`Guid.CreateVersion7()`), never from a `gen_random_uuid()` default; with EF Core the tables come from migrations (`backend/database/postgresql/database.md`).
+
 ---
 
 ## Best Practices
 
 ### CPF/CNPJ Validation
 
-```typescript
-export function validateCPF(cpf: string): boolean {
-  cpf = cpf.replace(/[^\d]/g, '');
-  if (cpf.length !== 11) return false;
-
-  // Validation logic...
-  return true;
-}
-
-export function validateCNPJ(cnpj: string): boolean {
-  cnpj = cnpj.replace(/[^\d]/g, '');
-  if (cnpj.length !== 14) return false;
-
-  // Validation logic...
-  return true;
+CPF is 11 digits; CNPJ is 14 characters and, for CNPJs issued from July 2026, **alphanumeric** in the first 12 positions (IN RFB 2.229/2024) -- a digits-only validator rejects valid new companies. Both use the mod-11 check digits; for the CNPJ each character is worth its ASCII code minus 48.
+
+```csharp
+// Features/Shared/BrazilianDocument.cs
+public static class BrazilianDocument
+{
+    public static bool IsValidCpf(string value)
+    {
+        var digits = new string(value.Where(char.IsDigit).ToArray());
+        if (digits.Length != 11 || digits.Distinct().Count() == 1)
+            return false;
+
+        return CheckDigit(digits[..9], 10) == digits[9] - '0'
+            && CheckDigit(digits[..10], 11) == digits[10] - '0';
+
+        static int CheckDigit(string body, int startWeight)
+        {
+            var sum = body.Select((c, i) => (c - '0') * (startWeight - i)).Sum();
+            var rest = sum % 11;
+            return rest < 2 ? 0 : 11 - rest;
+        }
+    }
+
+    public static bool IsValidCnpj(string value)
+    {
+        var chars = new string(value.Where(char.IsLetterOrDigit).Select(char.ToUpperInvariant).ToArray());
+        if (chars.Length != 14 || !chars[..12].All(c => char.IsAsciiDigit(c) || char.IsAsciiLetterUpper(c))
+            || !chars[12..].All(char.IsAsciiDigit) || chars.Distinct().Count() == 1)
+            return false;
+
+        return CheckDigit(chars[..12]) == chars[12] - '0'
+            && CheckDigit(chars[..13]) == chars[13] - '0';
+
+        static int CheckDigit(string body)
+        {
+            var sum = 0;
+            for (var i = 0; i < body.Length; i++)
+            {
+                var weight = 2 + (body.Length - 1 - i) % 8;
+                sum += (body[i] - '0') * weight;
+            }
+            var rest = sum % 11;
+            return rest < 2 ? 0 : 11 - rest;
+        }
+    }
 }
 ```
 
-### Idempotency Keys
+Use them in the slice validator (`RuleFor(x => x.CpfCnpj).Must(v => BrazilianDocument.IsValidCpf(v) || BrazilianDocument.IsValidCnpj(v))`) so a bad document becomes a 400 before any Asaas call.
 
-Pass a stable idempotency key in the request header so a retried POST does not
-create a duplicate charge:
+### Never store card data
 
-```typescript
-await asaasFetch('/payments', {
-  method: 'POST',
-  headers: { 'Idempotency-Key': `payment-${userId}-${requestId}` },
-  body: JSON.stringify({ /* ... payment data ... */ }),
-});
-```
+Card numbers and CVV go from the browser to Asaas (tokenization / hosted checkout), never through or into your database. Store only the Asaas ids and statuses.
 
 ---
 
 ## Error Handling
 
-Asaas returns failures as HTTP 400 with a JSON body shaped `{ errors: [{ code,
-description }] }`. `asaasFetch` throws on non-OK responses — catch and inspect
-the `errors[]` array:
-
-```typescript
-type AsaasError = { errors: { code: string; description: string }[] };
+Asaas returns validation failures as HTTP 400 with `{ "errors": [{ "code": "...", "description": "..." }] }` (e.g. `invalid_cpfCnpj`). `AsaasClient.ReadAsync` turns each item into `Error.Validation("Asaas.<code>", description)` (several into a `ValidationError`), 404 into `NotFound` and any other non-success into `Unexpected`; the endpoint maps them with `error.ToHttpResult()` (400 with `errors[]`, 404, 500). There is no `try/catch`: a network failure or timeout is an exception nobody handles locally, which surfaces as a 500 (or, inside a Hangfire job, as a retry).
 
-try {
-  await asaasFetch('/payments', { method: 'POST', body: JSON.stringify(data) });
-} catch (error) {
-  // asaasFetch throws `Asaas <status>: <raw body>` — parse the body
-  const body = (error as Error).message.replace(/^Asaas \d+: /, '');
-  let parsed: AsaasError | null = null;
-  try { parsed = JSON.parse(body) as AsaasError; } catch { /* non-JSON */ }
-
-  const code = parsed?.errors?.[0]?.code;
-  if (code === 'invalid_cpfCnpj') {
-    return Response.json({ error: 'CPF/CNPJ inválido' }, { status: 400 });
-  }
-
-  console.error('Asaas API error:', body);
-  return Response.json({ error: 'Erro no processamento' }, { status: 500 });
-}
-```
+Credit-card charges (`POST /payments/{id}/payWithCreditCard`) are explicitly **not idempotent**: never retry one automatically; read the charge status first.
 
 ---
 
 ## References
 
 - [Asaas API Documentation](https://docs.asaas.com/)
+- [Asaas Authentication (headers)](https://docs.asaas.com/docs/authentication-2)
 - [Asaas Webhooks](https://docs.asaas.com/docs/about-webhooks)
+- [Webhook idempotence](https://docs.asaas.com/docs/how-to-implement-idempotence-in-webhooks)
 - PIX Specification: Brazilian Central Bank
 
-> Asaas publishes **no official Node SDK** — integrate against the REST API
-> directly. Community wrappers exist but are unofficial and vary in maintenance.
-
 ---
 
 *MORPH-SPEC by Polymorphism Tech*