pay-abacatepay 0.1.0.pre.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e2ab67254ae39892abe3501a42c66727a625849a722fb619264986e9956194f9
+  data.tar.gz: 12af82bfd3ec2b1caf6fbcc980cbfa42bca571af77abdb2e6b1d15d1ed58e2a3
+SHA512:
+  metadata.gz: fe3d6ac447067fa8ea24479b282456f4de5a46c01acf556c3b17a1f826c00bc752bb3a948cb87b51f5e3fc967fb700221e51524a674782ae1b7dea61bee9617c
+  data.tar.gz: 56e74d4a3213b2036dd02dbb57cf72e2e8e78bc5d3a85a845a05e9f544a6b4e8500edb83ca6009898bc35ded6b02b945249853c5160bef61539d3c6e6b8a231d

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [Unreleased]
+
+### Added
+- Initial scaffold with Rails engine structure
+- `Pay::AbacatePay::Customer` with `api_record`, `api_record_attributes`, `update_api_record`
+- Document validation (`document`/`cpf`/`cnpj`) on billable model
+- Configuration via Rails credentials or environment variables
+- Integration with official `abacatepay-ruby` SDK as HTTP layer

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Daniel Moreira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,248 @@
+# pay-abacatepay
+
+AbacatePay processor for the [Pay gem](https://github.com/pay-rails/pay) (Rails payments engine).
+
+> [!WARNING]
+> This gem is a work in progress and is **not ready for production use**. Public API may break until 1.0.
+
+> This gem is not affiliated with AbacatePay. It is a community-maintained adapter.
+
+## Status
+
+- [x] Customer creation
+- [x] One-time charges — hosted checkout via `Customer#charge` + `checkout.*` webhooks
+- [ ] Transparent PIX (QR Code inline) — planned (Fase 5)
+- [x] Subscriptions — webhook-driven lifecycle + cancel (gaps below)
+- [x] Webhooks — infrastructure + subscription and checkout handlers
+- [ ] Chargeback/dispute handling — planned (Fase 5)
+- [ ] Payment methods — planned
+
+## Installation
+
+```bash
+bundle add pay-abacatepay
+```
+
+Make sure the `pay` gem is installed and mounted: https://github.com/pay-rails/pay/blob/main/docs/1_installation.md
+
+## Configuration
+
+### Rails credentials
+
+```bash
+rails credentials:edit --environment=development
+```
+
+```yaml
+abacatepay:
+  api_key: abc_dev_xxxxx
+```
+
+### Environment variables
+
+- `ABACATEPAY_API_KEY` — required
+- `ABACATEPAY_WEBHOOK_SECRET` — optional, reserved for webhooks (not yet implemented)
+
+### Environment (sandbox vs production)
+
+The AbacatePay API version is inferred from the **token prefix**:
+
+| Token prefix | API version | Typical use |
+|---|---|---|
+| `abc_dev_*`  | v2 | sandbox |
+| `abc_live_*` | v2 | production |
+| other        | v1 | legacy |
+
+There is no environment switch to configure — give the gem the right token and it routes correctly.
+
+## Customer
+
+To create an AbacatePay customer the billable model **must** expose a document (CPF or CNPJ). The gem checks, in order, `document`, `cpf`, then `cnpj`. Non-digit characters are stripped before being sent to the API.
+
+```ruby
+class User < ApplicationRecord
+  pay_customer default_payment_processor: :abacatepay
+end
+
+user = User.create!(email: "user@example.com", name: "Daniel", document: "123.456.789-01")
+user.payment_processor.customer  # creates a customer on AbacatePay, stores processor_id
+```
+
+If the document is missing or blank, a `Pay::AbacatePay::Error` is raised before any HTTP request.
+
+### Idempotency
+
+AbacatePay's `POST /v2/customers/create` is idempotent by `taxId`: submitting the same document returns the existing customer with HTTP 200. The adapter stores whichever id the API returns — no client-side deduplication is needed.
+
+### Updates
+
+AbacatePay does not expose a customer update endpoint. `update_api_record` is a **no-op with a warning**. If you rename a user, the AbacatePay record will not reflect it until the API grows `PATCH /v2/customers`.
+
+## One-time charges
+
+`Customer#charge` creates an AbacatePay **hosted checkout** and returns a struct you can redirect the payer to. A pending `Pay::Abacatepay::Charge` is persisted immediately so the app can render "payment in progress" UI and reconcile against the webhook later.
+
+```ruby
+result = user.payment_processor.charge(
+  5000,                                      # amount in cents
+  methods: ["PIX", "CARD"],                  # defaults shown
+  return_url: "https://app.example.com/cart",
+  completion_url: "https://app.example.com/thanks",
+  external_id: "order-1234"                  # optional, for your reconciliation
+)
+
+redirect_to result.url                       # send the user to AbacatePay
+result.id                                    # "chk_xxx" — also result.charge.processor_id
+result.charge                                # Pay::Abacatepay::Charge, status: "pending"
+```
+
+### Product on-the-fly
+
+AbacatePay's v2 `/checkouts/create` expects pre-registered products in `items[]`. When `product_id:` is omitted, the gem creates an ephemeral product via `POST /products/create` with `name: "Cobrança avulsa"` (overridable via `product_name:`). This costs an extra API call but keeps the host app's code free of product bookkeeping. Pass `product_id:` to skip this step when you manage products yourself.
+
+### Completion flow
+
+Once the payer completes the checkout, AbacatePay delivers a `checkout.completed` webhook. The handler:
+
+1. Skips the event if `data.checkout.frequency != "ONE_TIME"` — subscription payments are handled by `subscription.renewed` (see [Subscriptions](#subscriptions)).
+2. Locates the `Pay::Customer` by `processor_id` (no auto-creation — the customer must already exist from the app signup flow).
+3. Updates the pending `Pay::Abacatepay::Charge` (same `processor_id` as `result.id`) to `status: "paid"`, filling in `amount_refunded`, `application_fee_amount`, and `created_at`. If the checkout originated outside `Customer#charge`, a new charge is created instead.
+
+### Refunds
+
+AbacatePay **does not expose a programmatic refund endpoint** (confirmed in SDK v0.2.0 and in the public API docs as of April 2026). Calling `Pay::Abacatepay::Charge#refund!` raises `Pay::Abacatepay::Error` with a message pointing you to the dashboard.
+
+```
+AbacatePay does not expose a refund endpoint. Process the refund in the
+AbacatePay dashboard; the checkout.refunded webhook will update this
+Pay::Charge automatically.
+```
+
+When the refund is issued in the dashboard, AbacatePay delivers `checkout.refunded`; the gem updates `amount_refunded` and `status: "refunded"` on the matching charge. If the charge is not found (refund for a checkout the app never registered), the handler logs a warning and no-ops.
+
+### Status mapping
+
+`Pay::Abacatepay::Charge` stores status in `data` via `store_accessor`. The mapping is intentionally narrow:
+
+| AbacatePay | `Pay::Abacatepay::Charge#status` |
+|---|---|
+| `PENDING` | `"pending"` |
+| `PAID` | `"paid"` |
+| `REFUNDED` | `"refunded"` |
+| `DISPUTED` | `"disputed"` (see Fase 5) |
+| `EXPIRED` | *(no charge is created — the payment never succeeded)* |
+| `CANCELLED` | *(no charge is created)* |
+
+## Subscriptions
+
+Subscriptions are managed primarily through webhooks: when AbacatePay delivers `subscription.completed`, `subscription.renewed`, or `subscription.cancelled`, the gem creates or updates the corresponding `Pay::Subscription` and, for paid events, the matching `Pay::Charge` (with `data.payment.id` as `processor_id`).
+
+### Install the dedup migration
+
+Before deploying, run the generator and migrate:
+
+```bash
+bin/rails generate pay_abacatepay:install:migrations
+bin/rails db:migrate
+```
+
+The migration creates `pay_abacatepay_processed_webhooks`, a permanent table with a unique `(event_type, event_id)` index. It protects against double-processing on AbacatePay retries — `Pay::Webhook` records are destroyed after processing, so without this table a retry that arrives after the original ACK would create a duplicate `Pay::Charge`.
+
+### Supported operations
+
+| Operation | Support |
+|---|---|
+| Webhook-driven `Pay::Subscription` create/update | yes |
+| `Pay::Charge` creation per renewal | yes, idempotent via `processor_id = data.payment.id` |
+| `#cancel_now!` (immediate cancellation) | yes (calls `POST /v2/subscriptions/cancel` directly — SDK does not cover) |
+| `#cancel` | delegates to `#cancel_now!` with a `Rails.logger.warn`; see gap below |
+
+### Known gaps
+
+AbacatePay's API is narrower than Stripe's, so several `Pay::Subscription` affordances are intentionally not implemented:
+
+- **No cancel-at-period-end.** AbacatePay cancels immediately. `#cancel` delegates to `#cancel_now!` and logs a warning so code paths that assume Stripe-like grace periods notice the divergence.
+- **No plan swap.** `#swap` raises `NotImplementedError`. Cancel and create a new subscription instead.
+- **No resume.** `#resume` raises `NotImplementedError`. Cancelled subscriptions cannot be reactivated.
+- **No quantity changes.** `#change_quantity` raises `NotImplementedError`.
+- **No `past_due` state.** AbacatePay does not emit payment-failure events, so `#past_due?` always returns `false`.
+- **No `Subscriptions.retrieve` / `Subscriptions.cancel` in the SDK (v0.2.x).** Both calls are made via the SDK's Faraday client directly. Filed upstream.
+- **`subscription.trial_started`.** Handler is registered but raises `NotImplementedError` — the event is not listed in `AbacatePay::Enums::Webhooks::EventTypes`, so we fail-loud until it is confirmed.
+
+### Webhook idempotency
+
+Each event has a permanent `id` (e.g. `log_abc123xyz`). The handler wraps its side effects in `Pay::Abacatepay::ProcessedWebhook.process!(event_type:, event_id:)`, which relies on the unique index to short-circuit retries. A second delivery of the same event returns `:already_processed` and produces no side effects.
+
+## Webhooks
+
+The gem mounts `POST /pay/webhooks/abacatepay` on the Pay engine (so the full URL is whatever `Pay.routes_path` resolves to — `/pay/webhooks/abacatepay` by default). Point AbacatePay's dashboard webhook at that path on your public host.
+
+### Secret and signature
+
+Each webhook created in AbacatePay's dashboard has its own `secret`. Expose it to the gem via Rails credentials or environment:
+
+```yaml
+# config/credentials.yml.enc
+abacatepay:
+  webhook_secret: wsec_xxxxx
+```
+
+Or set `ABACATEPAY_WEBHOOK_SECRET` in the environment.
+
+Every incoming request is verified with **HMAC-SHA256** over the raw request body. The expected header is `X-Webhook-Signature`. Verification happens before any parsing or persistence; the gem delegates to the official SDK's `AbacatePay::Webhooks.verify!`.
+
+### Response codes
+
+| Scenario | Status |
+|---|---|
+| Valid signature + known event | `200 OK` |
+| Valid signature + unknown event type | `200 OK` (ignored, no record) |
+| Duplicate delivery (same `data.id`, same type) while a previous copy is still queued | `200 OK` (dedup, no double-processing) |
+| Missing or invalid `X-Webhook-Signature` | `401 Unauthorized` |
+| Malformed JSON | `400 Bad Request` |
+
+Note: Idempotency is scoped to the window between reception and processing (`Pay::Webhook` records are destroyed by `Pay::Webhooks::ProcessJob#process!`). AbacatePay retries that arrive after a successful handler run will be re-processed; handlers must therefore be individually idempotent — or upgrade this strategy in a later phase.
+
+### Supported events
+
+| Event | Handler | Status |
+|---|---|---|
+| `checkout.completed` | `Pay::Abacatepay::Webhooks::CheckoutCompleted` | active (one-time only; subscription payments skipped) |
+| `checkout.refunded` | `Pay::Abacatepay::Webhooks::CheckoutRefunded` | active |
+| `checkout.disputed` | `Pay::Abacatepay::Webhooks::CheckoutDisputed` | stub (Fase 5) |
+| `checkout.lost` | `Pay::Abacatepay::Webhooks::CheckoutLost` | stub (Fase 5) |
+| `transparent.completed` | `Pay::Abacatepay::Webhooks::TransparentCompleted` | stub (Fase 4) |
+| `transparent.refunded` | `Pay::Abacatepay::Webhooks::TransparentRefunded` | stub (Fase 4) |
+| `transparent.disputed` | `Pay::Abacatepay::Webhooks::TransparentDisputed` | stub (Fase 5) |
+| `transparent.lost` | `Pay::Abacatepay::Webhooks::TransparentLost` | stub (Fase 5) |
+| `subscription.completed` | `Pay::Abacatepay::Webhooks::SubscriptionCompleted` | active |
+| `subscription.cancelled` | `Pay::Abacatepay::Webhooks::SubscriptionCancelled` | active |
+| `subscription.renewed` | `Pay::Abacatepay::Webhooks::SubscriptionRenewed` | active |
+| `subscription.trial_started` | `Pay::Abacatepay::Webhooks::SubscriptionTrialStarted` | raises `NotImplementedError` (see gap) |
+| `payout.completed` | `Pay::Abacatepay::Webhooks::PayoutCompleted` | stub |
+| `payout.failed` | `Pay::Abacatepay::Webhooks::PayoutFailed` | stub |
+| `transfer.completed` | `Pay::Abacatepay::Webhooks::TransferCompleted` | stub |
+| `transfer.failed` | `Pay::Abacatepay::Webhooks::TransferFailed` | stub |
+
+To override or extend a handler from your own app, subscribe after the gem registers its defaults:
+
+```ruby
+# config/initializers/pay.rb
+Pay::Webhooks.configure do |events|
+  events.subscribe "abacatepay.subscription.renewed", ->(event) { MyJob.perform_later(event) }
+end
+```
+
+## Development
+
+```bash
+bin/setup
+bundle exec rake test
+bundle exec standardrb
+```
+
+Tests run against an in-memory SQLite database inside `test/dummy`, using `webmock` for HTTP stubs.
+
+## License
+
+Released under the [MIT License](MIT-LICENSE).

data/app/controllers/pay/webhooks/abacatepay_controller.rb

@@ -0,0 +1,104 @@
+module Pay
+  module Webhooks
+    class AbacatepayController < ActionController::API
+      # Authenticates a webhook delivery per the official AbacatePay scheme
+      # (https://docs.abacatepay.com/pages/webhooks/security).
+      #
+      # AbacatePay combines two complementary mechanisms — neither alone is
+      # sufficient, but **either** is enough to mark a delivery as genuine for
+      # this gem (we accept the strongest available):
+      #
+      #   1. **`webhookSecret` query parameter** — AbacatePay appends the
+      #      per-webhook secret you configured in the dashboard to the URL:
+      #      `?webhookSecret=...`. This authenticates the **origin** because
+      #      only AbacatePay knows your secret. Compared against
+      #      `Pay::Abacatepay.webhook_secret`.
+      #
+      #   2. **`X-Webhook-Signature` header (HMAC-SHA256, base64)** — protects
+      #      **body integrity**. Computed by AbacatePay over the raw body
+      #      using their fixed `PUBLIC_KEY` (in the SDK as a constant). The
+      #      key is public, so this alone does NOT prove origin — it only
+      #      proves the body wasn't tampered with in transit.
+      #
+      # Sandbox compatibility: the current AbacatePay sandbox occasionally
+      # delivers `webhookSecret` inside the JSON body instead of the URL.
+      # We accept that as a third path (compared against the same configured
+      # secret) so dev/staging environments work without painel reconfiguration.
+      #
+      # The request is rejected with 401 if none of the three pass.
+      def create
+        payload = request.body.read
+
+        unless authenticated?(payload)
+          return head(:unauthorized)
+        end
+
+        event_hash = JSON.parse(payload)
+        event_type = event_hash["event"] || event_hash["type"]
+        event_id = event_hash["id"] || event_hash.dig("data", "id")
+
+        return head(:ok) if already_recorded?(event_type, event_id)
+
+        queue_event(event_type, event_hash)
+        head :ok
+      rescue JSON::ParserError
+        head :bad_request
+      end
+
+      private
+
+      def authenticated?(payload)
+        configured_secret = Pay::Abacatepay.webhook_secret
+        return false if configured_secret.blank?
+
+        # 1. Query parameter (official scheme)
+        query_secret = request.query_parameters["webhookSecret"]
+        if query_secret.present?
+          return secrets_match?(query_secret, configured_secret)
+        end
+
+        # 2. HMAC-SHA256 base64 in X-Webhook-Signature header.
+        # Uses AbacatePay's fixed PUBLIC_KEY (NOT the per-webhook secret).
+        if (signature = request.headers["X-Webhook-Signature"]).present?
+          return ::AbacatePay::Webhooks.valid?(payload: payload, signature: signature)
+        end
+
+        # 3. Sandbox compatibility: webhookSecret inside JSON body
+        body_secret = extract_body_secret(payload)
+        return false if body_secret.blank?
+
+        secrets_match?(body_secret, configured_secret)
+      end
+
+      def secrets_match?(received, expected)
+        ActiveSupport::SecurityUtils.secure_compare(received.to_s, expected.to_s)
+      end
+
+      def extract_body_secret(payload)
+        parsed = JSON.parse(payload)
+        parsed["webhookSecret"] || parsed.dig("webhook_secret")
+      rescue JSON::ParserError
+        nil
+      end
+
+      def already_recorded?(event_type, event_id)
+        return false if event_id.blank?
+
+        Pay::Webhook
+          .where(processor: "abacatepay", event_type: event_type)
+          .find_each
+          .any? { |w| w.event.is_a?(Hash) && (w.event["id"] == event_id.to_s || w.event.dig("data", "id") == event_id.to_s) }
+      end
+
+      def queue_event(event_type, event_hash)
+        unless Pay::Webhooks.delegator.listening?("abacatepay.#{event_type}")
+          Rails.logger.debug { "[pay-abacatepay] no listener for abacatepay.#{event_type}; ignoring" }
+          return
+        end
+
+        record = Pay::Webhook.create!(processor: :abacatepay, event_type: event_type, event: event_hash)
+        Pay::Webhooks::ProcessJob.perform_later(record)
+      end
+    end
+  end
+end

data/lib/generators/pay_abacatepay/install/install_generator.rb

@@ -0,0 +1,21 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module PayAbacatepay
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Copies pay-abacatepay migrations into the host application."
+
+      def copy_migrations
+        migration_template(
+          "create_pay_abacatepay_processed_webhooks.rb.tt",
+          "db/migrate/create_pay_abacatepay_processed_webhooks.rb"
+        )
+      end
+    end
+  end
+end

data/lib/generators/pay_abacatepay/install/templates/create_pay_abacatepay_processed_webhooks.rb.tt

@@ -0,0 +1,15 @@
+class CreatePayAbacatepayProcessedWebhooks < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :pay_abacatepay_processed_webhooks do |t|
+      t.string :event_type, null: false
+      t.string :event_id, null: false
+      t.datetime :processed_at, null: false
+      t.datetime :created_at, null: false
+    end
+
+    add_index :pay_abacatepay_processed_webhooks,
+      [:event_type, :event_id],
+      unique: true,
+      name: "index_pay_abacatepay_processed_webhooks_unique"
+  end
+end

data/lib/pay/abacatepay/charge.rb

@@ -0,0 +1,77 @@
+module Pay
+  module Abacatepay
+    class Charge < Pay::Charge
+      # AbacatePay checkout status → Pay::Charge status (stored in data).
+      # PENDING is created eagerly by Customer#charge so the app can render
+      # "payment in progress" UI before the webhook arrives.
+      # EXPIRED and CANCELLED never become a Pay::Charge — the payment never
+      # succeeded and there is nothing to track.
+      STATUS_MAP = {
+        "PENDING" => "pending",
+        "PAID" => "paid",
+        "REFUNDED" => "refunded",
+        "DISPUTED" => "disputed"
+      }.freeze
+
+      store_accessor :data, :status
+      store_accessor :data, :checkout_url
+      store_accessor :data, :payment_method
+
+      def self.sync(charge_id, object: nil)
+        object ||= ::AbacatePay.checkouts.get(charge_id)
+
+        customer_id = extract_customer_id(object)
+        if customer_id.blank?
+          Rails.logger.debug("[pay-abacatepay] checkout #{charge_id} has no customer; skipping sync")
+          return
+        end
+
+        pay_customer = Pay::Customer.find_by(processor: "abacatepay", processor_id: customer_id)
+        if pay_customer.nil?
+          Rails.logger.debug("[pay-abacatepay] Pay::Customer #{customer_id} not found while syncing checkout #{charge_id}")
+          return
+        end
+
+        charge = Pay::Abacatepay::Charge.find_or_initialize_by(
+          customer: pay_customer,
+          processor_id: charge_id
+        )
+        charge.amount = object.amount if object.respond_to?(:amount) && object.amount
+        charge.currency ||= "BRL"
+        charge.status = STATUS_MAP[object.status] || charge.status || "pending" if object.respond_to?(:status)
+        charge.checkout_url = object.url if object.respond_to?(:url) && object.url
+        charge.save!
+        charge
+      rescue ::AbacatePay::Error => e
+        raise Pay::Abacatepay::Error, e.message
+      end
+
+      def api_record
+        ::AbacatePay.checkouts.get(processor_id)
+      rescue ::AbacatePay::Error => e
+        raise Pay::Abacatepay::Error, e.message
+      end
+
+      def refund!(_amount_to_refund = nil)
+        raise Pay::Abacatepay::Error,
+          "AbacatePay does not expose a refund endpoint. " \
+          "Process the refund in the AbacatePay dashboard; the checkout.refunded " \
+          "webhook will update this Pay::Charge automatically."
+      end
+
+      def charged_back?
+        status == "disputed"
+      end
+
+      def self.extract_customer_id(object)
+        return object.dig("customer", "id") if object.is_a?(Hash)
+        customer = object.respond_to?(:customer) ? object.customer : nil
+        return nil if customer.nil?
+        customer.respond_to?(:id) ? customer.id : customer["id"]
+      end
+      private_class_method :extract_customer_id
+    end
+  end
+end
+
+ActiveSupport.run_load_hooks :pay_abacatepay_charge, Pay::Abacatepay::Charge

data/lib/pay/abacatepay/customer.rb

@@ -0,0 +1,136 @@
+module Pay
+  module Abacatepay
+    class Customer < Pay::Customer
+      has_many :charges, dependent: :destroy, class_name: "Pay::Abacatepay::Charge"
+      has_many :subscriptions, dependent: :destroy, class_name: "Pay::Abacatepay::Subscription"
+      has_many :payment_methods, dependent: :destroy, class_name: "Pay::Abacatepay::PaymentMethod"
+      has_one :default_payment_method, -> { where(default: true) }, class_name: "Pay::Abacatepay::PaymentMethod"
+
+      def api_record_attributes
+        {
+          name: customer_name,
+          email: email,
+          cellphone: owner.try(:cellphone) || owner.try(:phone),
+          tax_id: extract_document
+        }
+      end
+
+      def api_record
+        with_lock do
+          if processor_id?
+            ::AbacatePay.customers.get(processor_id)
+          else
+            attrs = api_record_attributes
+            resource = build_customer_resource(attrs)
+            created = ::AbacatePay.customers.create(resource)
+            update!(processor_id: created.id)
+            created
+          end
+        end
+      rescue ::AbacatePay::Error => e
+        raise Pay::Abacatepay::Error, e.message
+      end
+
+      # AbacatePay's API does not expose an update endpoint for customers
+      # (POST /v2/customers/create and DELETE are the only mutations).
+      # TODO: Remove this no-op once the API adds PATCH/PUT support.
+      def update_api_record(**attributes)
+        logger = defined?(Rails) ? Rails.logger : nil
+        logger&.warn(
+          "[pay-abacatepay] AbacatePay does not support customer updates; update_api_record is a no-op."
+        )
+        nil
+      end
+
+      CheckoutResult = Struct.new(:id, :url, :charge, keyword_init: true)
+
+      def charge(amount, product_id: nil, methods: ["PIX", "CARD"], return_url: nil, completion_url: nil, external_id: nil, product_name: "Cobrança avulsa", metadata: nil)
+        api_record unless processor_id?
+
+        product_id ||= create_one_time_product(amount, product_name)
+        resource = build_checkout_resource(
+          product_id: product_id,
+          quantity: 1,
+          methods: methods,
+          return_url: return_url,
+          completion_url: completion_url,
+          external_id: external_id
+        )
+        created = ::AbacatePay.checkouts.create(resource)
+
+        pay_charge = Pay::Abacatepay::Charge.find_or_initialize_by(
+          customer: self,
+          processor_id: created.id
+        )
+        pay_charge.amount = amount
+        pay_charge.currency ||= "BRL"
+        pay_charge.status = "pending"
+        pay_charge.checkout_url = created.url
+        pay_charge.metadata = metadata if metadata.present?
+        pay_charge.save!
+
+        CheckoutResult.new(id: created.id, url: created.url, charge: pay_charge)
+      rescue ::AbacatePay::Error => e
+        raise Pay::Abacatepay::Error, e.message
+      end
+
+      def subscribe(name: Pay.default_product_name, plan: Pay.default_plan_name, **options)
+        raise NotImplementedError, "Pay::Abacatepay::Customer#subscribe is planned for a future release"
+      end
+
+      def add_payment_method(payment_method_id, default: false)
+        raise NotImplementedError, "Pay::Abacatepay::Customer#add_payment_method is planned for a future release"
+      end
+
+      private
+
+      def create_one_time_product(amount, product_name)
+        resource = ::AbacatePay::Resources::Products.new(
+          external_id: "pay-abacatepay-#{SecureRandom.hex(8)}",
+          name: product_name,
+          price: amount,
+          currency: "BRL"
+        )
+        created = ::AbacatePay.products.create(resource)
+        created.id
+      end
+
+      def build_checkout_resource(product_id:, quantity:, methods:, return_url:, completion_url:, external_id:)
+        ::AbacatePay::Resources::Checkouts.new(
+          frequency: "ONE_TIME",
+          methods: methods,
+          metadata: {returnUrl: return_url, completionUrl: completion_url}.compact,
+          products: [{externalId: product_id, quantity: quantity}],
+          customer: {id: processor_id},
+          externalId: external_id
+        )
+      end
+
+      def build_customer_resource(attrs)
+        ::AbacatePay::Resources::Customers.new(
+          metadata: ::AbacatePay::Resources::Customers::Metadata.new(
+            name: attrs[:name],
+            email: attrs[:email],
+            cellphone: attrs[:cellphone],
+            tax_id: attrs[:tax_id]
+          )
+        )
+      end
+
+      def extract_document
+        raw = %i[document cpf cnpj].filter_map { |m| owner.send(m) if owner.respond_to?(m) }.find(&:present?)
+
+        unless %i[document cpf cnpj].any? { |m| owner.respond_to?(m) }
+          raise Pay::Abacatepay::Error,
+            "#{owner.class} must respond to :document, :cpf, or :cnpj for AbacatePay"
+        end
+
+        raise Pay::Abacatepay::Error, "document is required for AbacatePay customers" if raw.blank?
+
+        raw.to_s.gsub(/\D/, "")
+      end
+    end
+  end
+end
+
+ActiveSupport.run_load_hooks :pay_abacatepay_customer, Pay::Abacatepay::Customer

data/lib/pay/abacatepay/engine.rb

@@ -0,0 +1,33 @@
+require "rails/engine"
+
+module Pay
+  module Abacatepay
+    class Engine < ::Rails::Engine
+      engine_name "pay_abacatepay"
+
+      initializer "pay_abacatepay.register_processor" do
+        Pay.enabled_processors << :abacatepay unless Pay.enabled_processors.include?(:abacatepay)
+      end
+
+      initializer "pay_abacatepay.attributes" do
+        ActiveSupport.on_load(:active_record) do
+          include Pay::Attributes
+        end
+      end
+
+      initializer "pay_abacatepay.routes" do
+        Pay::Engine.routes.append do
+          post "webhooks/abacatepay", to: "pay/webhooks/abacatepay#create"
+        end
+      end
+
+      initializer "pay_abacatepay.webhooks", after: "pay_abacatepay.register_processor" do
+        Pay::Abacatepay.configure_webhooks
+      end
+
+      config.to_prepare do
+        Pay::Abacatepay.setup if Pay::Abacatepay.enabled? && Pay::Abacatepay.api_key
+      end
+    end
+  end
+end