abacatepay-ruby 1.1.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 604226a94737477c55324bf08cb81736cce65fdf482453bd2667572c8986b010
-  data.tar.gz: 4e292b8d7db21a444cc4348bd59bc2cf396849ff8d99db4d4463ab1b651962fe
+  metadata.gz: 65f1214bed1683aa366b68ef9055d85a318ca11901f90c36669fb3202c0b9be5
+  data.tar.gz: 0f1374d3702f53204228345237a8072a23918151cb3e2b9d13bd374b558cb04a
 SHA512:
-  metadata.gz: 55eeee33fcf8a4b509c849f85d90ccb3f0fb4a2b4aad040325da4a6ed19bf2b60394190ce848ff0b03fa98ec56b0bddccf2fae677c19b1db1dfc7c744819286a
-  data.tar.gz: e8258c5ba01696d7d76fb85b4314a047052b04f13e0a90c4a826fe83f14ce967ea817cb445d3158a61be27a6ec4af99da9fc0c4dd477449c1bf1b60412f7f612
+  metadata.gz: de8e7e809c16a249b698f02ed6d7f5eb0d1df24e6e2cab086f32a49fe90c818665a31c1cd642fae49f9a57174482470d64ec681ee99a55cb35e400d2d9fa6188
+  data.tar.gz: 22fd62f1e9e223d5d2e956c466b1d9de1d6128930d3b8651f4c72369e5827596e3a46c4c30db5171673eee95dd1bce49ef16a1739a351c64f1c73babeb37ff8a

data/.rubocop.yml

@@ -58,6 +58,7 @@ Naming/MethodParameterName:
 Naming/PredicateMethod:
   AllowedMethods:
     - verify!
+    - verify_secret!
 
 # Faraday errors carry a response payload, not just a message; the compact
 # form is how Faraday itself documents constructing them.
@@ -119,8 +120,14 @@ RSpec/SpecFilePathFormat:
 
 # These specs deliberately cut across the whole library rather than describing
 # a single class.
+# The file name must match the gem name so Bundler's default require works.
+Naming/FileName:
+  Exclude:
+    - "lib/abacatepay-ruby.rb"
+
 RSpec/DescribeClass:
   Exclude:
+    - "spec/load_spec.rb"
     - "spec/clients/request_contract_spec.rb"
     - "spec/clients/pagination_spec.rb"
     - "spec/clients/resilience_spec.rb"

data/CHANGELOG.md

@@ -7,6 +7,75 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.1] - 2026-08-06
+
+Inclui tudo o que estava previsto para a 1.2.0, que nunca chegou a ser
+publicada. Todas as correções abaixo foram encontradas exercitando o SDK
+contra o sandbox da AbacatePay e contra uma aplicação Rails real, e não contra
+a própria suíte de testes.
+
+### Fixed
+
+- **Webhook signature verification rejected every genuine delivery.** The SDK
+  compared against `OpenSSL::HMAC.hexdigest`, but AbacatePay sends the HMAC
+  base64-encoded. The [security
+  spec](https://docs.abacatepay.com/pages/webhooks/security) and its Node,
+  Python and Go samples all use base64. `verify!` therefore failed every real
+  webhook while accepting a hex signature nobody sends, making webhook
+  verification inoperative since it was introduced. Reported by @danieldenis01
+  in #6, found while building a `pay-rails/pay` adapter against the sandbox and
+  production, along with the three fixes above.
+- **`qr_code` and `qr_code_image` always returned nil for transparent PIX.** The
+  API sends the copy-and-paste payload as `brCode` and the image as
+  `brCodeBase64`; the readers looked for the older `qrCode`/`qrCodeImage`
+  spelling. Both are accepted now, preferring `qr*` when present. `platform_fee`
+  and `receipt_url` were missing entirely.
+- **`simulate_payment` sent the id in the body.** The API reads it from the
+  query string on this endpoint, like `check`, and body-only requests fail with
+  "Expected property 'id'".
+- **Optional fields were sent as explicit nulls.** The API rejects
+  `{"cellphone": null}` with HTTP 400 `Expected property 'cellphone' to be
+  string but found: null`, and payload builders emit nils for anything the
+  caller left unset. Payloads are now compacted recursively at the request
+  boundary, so this cannot be forgotten by a future endpoint. Also reported in
+  #6; the fix covers `products`, `coupons`, `payouts`, `pix` and
+  `subscriptions`, which had the same defect.
+
+- **`gem "abacatepay-ruby"` did not load the SDK.** Bundler requires a gem by
+  its own name, so Rails called `require "abacatepay-ruby"`, and the entry
+  point was `lib/abacate_pay.rb`. The require failed, but the gemspec had
+  already defined `AbacatePay` with nothing but `VERSION` in it, so the first
+  call raised `undefined method 'configure' for module AbacatePay` instead of a
+  missing-constant error. Every Rails user had to discover `require:
+  "abacate_pay"` on their own. There is now an entry point matching the gem
+  name.
+- **Customer responses dropped every field except the id.** The API returns
+  `name`, `email`, `cellphone` and `taxId` at the top level of the customer
+  object with an empty `metadata`; the resource only mapped a nested
+  `metadata`, so `customers.list` and `customers.get` returned objects with
+  nothing usable and `customer.metadata.name` was always nil. The fields are
+  exposed directly now, and `metadata` keeps answering for code written against
+  the previous interface.
+- **`AbacatePay.store.get` always failed.** The API serves this as
+  `stores/get`, plural. The singular path documented in the reference answers
+  HTTP 400.
+
+### Added
+
+- `AbacatePay::Webhooks::PUBLIC_KEY`, the fixed key AbacatePay signs with, now
+  the default for `secret:`. It is public and global, so it proves body
+  integrity only: anyone can compute a valid signature with it.
+- `AbacatePay::Webhooks.verify_secret!(received:, expected:)` for the
+  `webhookSecret` query parameter, which is what actually authenticates the
+  origin. The docs instruct using both mechanisms together; the SDK previously
+  offered only the HMAC half.
+
+### Changed
+
+- The README no longer implies `has_more?` is always available. List responses
+  only carry pagination metadata when the API sends it; otherwise they are
+  plain Arrays, exactly as before.
+
 ## [1.1.0] - 2026-08-05
 
 ### Added
@@ -19,16 +88,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `br_code_base64` and `expires_at`.
 - **Cursor pagination.** List endpoints cap at 100 items and report `hasMore`
   plus a cursor; the SDK discarded that metadata, making record 101
-  unreachable. `list` now returns an `AbacatePay::Collection` — Enumerable and
-  Array-compatible, so existing code is unaffected — carrying `has_more?` and
-  `next_cursor`. `each_page` and `auto_paging_each` walk every page.
+  unreachable. `list` now returns an `AbacatePay::Collection`. It is Enumerable and
+  Array-compatible, so existing code is unaffected, and it carries `has_more?`
+  and `next_cursor`. `each_page` and `auto_paging_each` walk every page.
 - **Retries with exponential backoff and jitter** on 429 and 5xx, configurable
   via `config.max_retries` (default 2). Only idempotent methods are retried;
   POST never is, because repeating `checkouts/create` after a timeout could
   charge a customer twice and the API exposes no idempotency key.
 - **Optional request logging** via `config.logger`, with the bearer token
   redacted and bodies never logged.
-- `SubscriptionClient#change_plan` and `#record_usage` — the last two of the 45
+- `SubscriptionClient#change_plan` and `#record_usage`: the last two of the 45
   documented v2 endpoints. All 45 are now covered.
 - `subscription.payment_failed` and `subscription.trial_started` webhook event
   types. `payment_failed` is the dunning signal.
@@ -50,9 +119,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Corrected
 
 - The 1.0.0 notes stated that the v1 API "has been retired and answers Not found
-  for every path". That is wrong: v1 is still served, under a different dialect
-  — singular paths (`/v1/billing/`, `/v1/customer/`) and different resource
-  names (`pixQrCode`). The original diagnosis tested v2-shaped paths against
+  for every path". That is wrong: v1 is still served, under a different dialect.
+  It uses singular paths (`/v1/billing/`, `/v1/customer/`) and different
+  resource names (`pixQrCode`). The original diagnosis tested v2-shaped paths against
   `/v1`. The fix itself stands: this SDK only ever spoke v2's dialect, so 10 of
   the 12 paths it calls do not exist on v1 and routing there produced 404s.
 
@@ -65,15 +134,15 @@ versions and will not change without a major bump.
 
 - Full API coverage: checkouts, coupons, customers, payouts, PIX transfers,
   products, store, subscriptions and transparent checkout.
-- `AbacatePay::Webhooks.construct_event` — verifies the signature and parses the
+- `AbacatePay::Webhooks.construct_event`, which verifies the signature and parses the
   body in a single call, so an unverified payload cannot be acted on.
 - `AbacatePay::Webhooks::PayloadError` for malformed or non-object webhook bodies.
-- `PaymentLinkClient` (`AbacatePay.payment_links`) — reusable multi-payment links.
-- `WebhookClient` (`AbacatePay.webhook_endpoints`) — webhook endpoint registration,
+- `PaymentLinkClient` (`AbacatePay.payment_links`) for reusable multi-payment links.
+- `WebhookClient` (`AbacatePay.webhook_endpoints`) for webhook endpoint registration,
   with local HTTPS validation so a bad endpoint fails before the round trip.
-- `CheckoutClient#refund`, `TransparentClient#refund`, `PaymentLinkClient#refund` —
-  refunds were previously impossible through the SDK.
-- `SubscriptionClient#cancel` — a subscription created through the SDK could not
+- `CheckoutClient#refund`, `TransparentClient#refund`, `PaymentLinkClient#refund`.
+  Refunds were previously impossible through the SDK.
+- `SubscriptionClient#cancel`. A subscription created through the SDK could not
   be cancelled through it.
 - CI workflow running the suite on Ruby 3.2, 3.3, 3.4 and 4.0, plus RuboCop, a
   dependency audit and a gem build check on every pull request.
@@ -111,7 +180,7 @@ versions and will not change without a major bump.
   without `X-Webhook-Signature` reached `secure_compare` as `nil` and raised
   `NoMethodError`, so `valid?` returned neither `true` nor `false` and the
   endpoint returned a server error instead of rejecting the request. Missing and
-  empty signatures — and a missing secret — are now `SignatureError`.
+  empty signatures, plus a missing secret, are now `SignatureError`.
 - **`Webhooks.parse` leaked parser internals.** Malformed JSON raised
   `JSON::ParserError` and a non-object JSON body raised `TypeError`; both now
   raise `PayloadError`.
@@ -121,7 +190,7 @@ versions and will not change without a major bump.
 - **Changing the token at runtime had no effect.** Clients were memoized on first
   use and never rebuilt, so `AbacatePay.configure` after a first API call kept
   sending the previous bearer token. `configure` now discards memoized clients.
-- `Configuration#api_url` was declared twice — as an `attr_reader` and as a
+- `Configuration#api_url` was declared twice, as an `attr_reader` and as a
   method. The dead reader has been removed.
 - `CustomerClient#get` and `#delete` had no test coverage at all.
 - The `customer` and `billing` specs stubbed singular endpoint paths while the
@@ -142,13 +211,13 @@ versions and will not change without a major bump.
 ### Changed
 
 - **BREAKING: `required_ruby_version` is now `>= 3.2.0`** (was `>= 2.6.0`). The
-  old floor was never installable — faraday 2.x requires Ruby 3.0 or newer — so
+  old floor was never installable: faraday 2.x requires Ruby 3.0 or newer, so
   no working installation is losing support, but a `bundle update` on Ruby 2.6
   or 3.1 will now refuse to resolve instead of failing later.
 - **`config.environment` is deprecated and now warns.** It was declared,
   defaulted, and validated, but read by nothing. Per AbacatePay's own
-  documentation the environment is decided by the API key — Dev mode keys
-  simulate transactions — so the setting could never have worked. It is kept as
+  documentation the environment is decided by the API key (Dev mode keys
+  simulate transactions), so the setting could never have worked. It is kept as
   an accepted no-op so existing initializers keep loading.
 - `validate!` no longer rejects unknown `environment` values, and now rejects an
   empty or whitespace-only token.
@@ -163,13 +232,14 @@ versions and will not change without a major bump.
 - Publishing to GitHub Packages. The step never executed successfully in any run
   and nothing consumed the gem from that registry.
 - `sig/abacatepay/rails.rbs`. Leftover `bundle gem` scaffolding declaring an
-  `Abacatepay::Rails` module that does not exist in this codebase — and it was
+  `Abacatepay::Rails` module that does not exist in this codebase, and that was
   shipping inside the published gem, where a type checker would read it.
 
 ## [0.1.0] - 2024-12-13
 
 - Initial release
 
+[1.2.1]: https://github.com/AbacatePay/abacatepay-ruby-sdk/releases/tag/v1.2.1
 [1.1.0]: https://github.com/AbacatePay/abacatepay-ruby-sdk/releases/tag/v1.1.0
 [1.0.0]: https://github.com/AbacatePay/abacatepay-ruby-sdk/releases/tag/v1.0.0
 [0.1.0]: https://github.com/AbacatePay/abacatepay-ruby-sdk/releases/tag/v0.1.0

data/README.md

@@ -8,7 +8,7 @@ O [`abacatepay-ruby`](https://rubygems.org/gems/abacatepay-ruby) é um **wrapper
 
 <img src="https://res.cloudinary.com/dkok1obj5/image/upload/v1767631413/avo_clhmaf.png" width="100%" alt="AbacatePay Open Source"/>
 
-Funciona em qualquer aplicação Ruby — Rails, Sinatra, Hanami ou Ruby puro.
+Funciona em qualquer aplicação Ruby: Rails, Sinatra, Hanami ou Ruby puro.
 
 Referência completa da API [aqui](https://abacatepay.readme.io/reference).
 
@@ -56,7 +56,7 @@ Nunca utilize sua API key diretamente no código.
 
 Em Rails, coloque isso em `config/initializers/abacatepay.rb`.
 
-Trocar o token em runtime tem efeito imediato — os clients são reconstruídos a cada `configure`.
+Trocar o token em runtime tem efeito imediato: os clients são reconstruídos a cada `configure`.
 
 ### Criando uma cobrança
 
@@ -103,42 +103,53 @@ AbacatePay.checkouts.list(status: 'PAID', email: 'user@example.com')
 
 <div align="center">
 
-Listas retornam no máximo 100 itens. O resultado é uma `Collection` — funciona como Array, e ainda carrega o cursor:
+Listas retornam no máximo 100 itens.
 
 </div>
 
 ```ruby
 page = AbacatePay.customers.list
 page.first.id     # funciona como Array
-page.has_more?    # => true
-page.next_cursor  # => "cust_abc123"
 
 # Para percorrer tudo sem lidar com cursor:
 AbacatePay.customers.auto_paging_each { |customer| puts customer.id }
-AbacatePay.customers.each_page { |page| puts page.size }
+```
+
+<div align="center">
+
+Quando a API envia metadados de paginação, o resultado é uma `Collection` que carrega o cursor. Quando não envia, é um Array puro, então cheque antes de usar:
+
+</div>
+
+```ruby
+if page.respond_to?(:has_more?) && page.has_more?
+  proxima = AbacatePay.customers.list(after: page.next_cursor)
+end
 ```
 
 <div align="center">
 
 ## Versionamento
 
-O SDK fala **exclusivamente a v2** — `https://api.abacatepay.com/v2`. A v1 ainda existe para integrações legadas, mas usa outro dialeto (caminhos no singular como `/v1/billing/`, `/v1/customer/`) que este SDK nunca implementou. Se você precisa da v1, chame a API diretamente.
+O SDK fala **exclusivamente a v2**, em `https://api.abacatepay.com/v2`. A v1 ainda existe para integrações legadas, mas usa outro dialeto (caminhos no singular como `/v1/billing/`, `/v1/customer/`) que este SDK nunca implementou. Se você precisa da v1, chame a API diretamente.
 
-O ambiente (dev mode x produção) é definido **pela chave de API**, não por configuração: chaves de Dev mode geram transações simuladas. Por isso `config.environment` não faz nada — ela continua aceita para não quebrar initializers existentes, mas emite aviso de depreciação.
+O ambiente (dev mode x produção) é definido **pela chave de API**, não por configuração: chaves de Dev mode geram transações simuladas. Por isso `config.environment` não faz nada. Ela continua aceita para não quebrar initializers existentes, mas emite aviso de depreciação.
 
-O `BillingClient` também está descontinuado, substituído pelo `CheckoutClient`. Ele emite um aviso ao ser instanciado, e seus endpoints `/billings/*` não existem na v2:
+O `BillingClient` também está descontinuado, substituído pelo `CheckoutClient`. Seus endpoints `/billings/*` não existem em nenhuma versão da API: toda chamada falha. Será removido na 2.0.0:
 
 </div>
 
 ```
-[DEPRECATION] BillingClient is deprecated. Use CheckoutClient instead.
+[DEPRECATION] BillingClient calls /billings/* endpoints that do not exist on the
+AbacatePay API, every request will fail. Use AbacatePay.checkouts instead.
+This class will be removed in 2.0.0.
 ```
 
 <div align="center">
 
 ## Tratamento de erros
 
-Diferente do SDK de Node, **este SDK levanta exceções** — ele não retorna `{ data, error, success }`. Toda falha vira uma exceção tipada que herda de `AbacatePay::Error`, então você pode capturar tudo de uma vez ou tratar caso a caso.
+Diferente do SDK de Node, **este SDK levanta exceções**. Ele não retorna `{ data, error, success }`. Toda falha vira uma exceção tipada que herda de `AbacatePay::Error`, então você pode capturar tudo de uma vez ou tratar caso a caso.
 
 </div>
 
@@ -166,18 +177,26 @@ Erros de rede e timeout são normalizados para `ApiError`, com a mensagem da API
 
 ## Webhooks
 
-Endpoints de webhook são públicos e não autenticados. Use `construct_event`, que **verifica a assinatura antes de fazer o parse** — é o único ponto de entrada que não permite agir sobre um payload não verificado.
+Endpoints de webhook são públicos. A AbacatePay usa **dois mecanismos**, e a documentação orienta usar os dois: o `webhookSecret` na query autentica a origem, e a assinatura HMAC garante que o corpo não foi alterado. A chave HMAC é pública e global: ela sozinha não prova origem.
 
 </div>
 
 ```ruby
 payload   = request.body.read
 signature = request.headers['X-Webhook-Signature']
-secret    = ENV['ABACATEPAY_WEBHOOK_SECRET']
 
 begin
+  # 1. Autentica a origem com o secret que você definiu ao criar o webhook,
+  #    enviado pela AbacatePay como query parameter.
+  AbacatePay::Webhooks.verify_secret!(
+    received: params[:webhookSecret],
+    expected: ENV['ABACATEPAY_WEBHOOK_SECRET']
+  )
+
+  # 2. Verifica a integridade do corpo. A chave HMAC é pública, então este
+  #    passo sozinho não prova origem. Por isso os dois juntos.
   event = AbacatePay::Webhooks.construct_event(
-    payload: payload, signature: signature, secret: secret
+    payload: payload, signature: signature
   )
 rescue AbacatePay::Webhooks::SignatureError
   return head :unauthorized
@@ -194,7 +213,7 @@ end
 
 <div align="center">
 
-Header ausente, secret vazio, assinatura forjada e corpo malformado são todos tratados como casos esperados — levantam erro tipado em vez de derrubar o endpoint. A comparação de assinatura é feita em tempo constante.
+Header ausente, secret vazio, assinatura forjada e corpo malformado são todos tratados como casos esperados: levantam erro tipado em vez de derrubar o endpoint. A comparação de assinatura é feita em tempo constante.
 
 Os métodos de baixo nível continuam disponíveis:
 
@@ -204,7 +223,7 @@ Os métodos de baixo nível continuam disponíveis:
 # Levanta SignatureError se a assinatura estiver ausente ou inválida
 AbacatePay::Webhooks.verify!(payload: payload, signature: signature, secret: secret)
 
-# Contraparte booleana — nunca levanta exceção
+# Contraparte booleana. Nunca levanta exceção
 AbacatePay::Webhooks.valid?(payload: payload, signature: signature, secret: secret)
 
 # Faz parse de um corpo já verificado
@@ -219,7 +238,7 @@ AbacatePay::Webhooks.parse(payload)
 |---|---|
 | Checkout | `checkout.completed`, `checkout.refunded`, `checkout.disputed` |
 | Transparent | `transparent.completed`, `transparent.refunded`, `transparent.disputed` |
-| Subscription | `subscription.completed`, `subscription.renewed`, `subscription.cancelled` |
+| Subscription | `subscription.completed`, `subscription.renewed`, `subscription.cancelled`, `subscription.payment_failed`, `subscription.trial_started` |
 | Transfer | `transfer.completed`, `transfer.failed` |
 | Payout | `payout.completed`, `payout.failed` |
 
@@ -404,7 +423,7 @@ AbacatePay.checkouts.create(
 
 <div align="center">
 
-No checkout transparente, o boleto exige nome e CPF/CNPJ do pagador — o SDK valida antes de chamar a API:
+No checkout transparente, o boleto exige nome e CPF/CNPJ do pagador, o SDK valida antes de chamar a API:
 
 </div>
 
@@ -442,7 +461,7 @@ AbacatePay.checkouts.create(
 
 ### Links de pagamento
 
-Um link reutilizável, pago por vários clientes de forma independente — vendas em massa, rifas, formulários de inscrição. Para uma cobrança por cliente, use `checkouts`.
+Um link reutilizável, pago por vários clientes de forma independente, vendas em massa, rifas, formulários de inscrição. Para uma cobrança por cliente, use `checkouts`.
 
 </div>
 
@@ -464,7 +483,7 @@ puts link.url # compartilhe esta URL
 
 ### Estornos
 
-O estorno é sempre integral — a AbacatePay não faz estorno parcial.
+O estorno é sempre integral, a AbacatePay não faz estorno parcial.
 
 </div>
 
@@ -485,10 +504,10 @@ Cancela imediatamente; parcelas futuras pendentes são canceladas junto.
 ```ruby
 AbacatePay.subscriptions.cancel('subs_abc123xyz')
 
-# Upgrade/downgrade — vale a partir do próximo ciclo
+# Upgrade/downgrade, vale a partir do próximo ciclo
 AbacatePay.subscriptions.change_plan('subs_abc123xyz', product_id: 'prod_pro', quantity: 1)
 
-# Cobrança por uso — produto sem ciclo
+# Cobrança por uso, produto sem ciclo
 AbacatePay.subscriptions.record_usage('subs_abc123xyz', product_id: 'prod_api', units: 50)
 ```
 
@@ -531,7 +550,7 @@ AbacatePay.store.revenue(start_date: '2026-01-01', end_date: '2026-03-30')
 
 ## Enums
 
-Os valores são validados na construção do recurso — um valor inválido levanta `ArgumentError` antes de qualquer chamada de rede.
+Os valores são validados na construção do recurso, um valor inválido levanta `ArgumentError` antes de qualquer chamada de rede.
 
 | Enum | Valores |
 |---|---|
@@ -558,7 +577,7 @@ bundle exec rake        # specs + rubocop
 
 <div align="center">
 
-Antes de abrir um PR, garanta que `bundle exec rake` passa e que a cobertura não caiu — o CI roda os specs em Ruby 3.2, 3.3, 3.4 e 4.0, mais RuboCop, auditoria de dependências e build do gem.
+Antes de abrir um PR, garanta que `bundle exec rake` passa e que a cobertura não caiu, o CI roda os specs em Ruby 3.2, 3.3, 3.4 e 4.0, mais RuboCop, auditoria de dependências e build do gem.
 
 ## Licença
 

data/abacatepay-ruby.gemspec

@@ -48,7 +48,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rspec", "~> 3.12"
   spec.add_development_dependency "rubocop", "~> 1.57"
   spec.add_development_dependency "rubocop-rspec", "~> 3.0"
-  spec.add_development_dependency "simplecov", "~> 0.22"
+  spec.add_development_dependency "simplecov", "~> 1.0"
 
   # For more information and examples about making a new gem, check out our
   # guide at: https://bundler.io/guides/creating_gem.html

data/lib/abacate_pay/clients/billing_client.rb

@@ -5,7 +5,7 @@ module AbacatePay
     # Deprecated client for the v1 billing endpoints.
     #
     # The endpoints this class calls (`/billings/create`, `/billings/list`) do
-    # not exist on either API version — v2 replaced them with `/checkouts/*`,
+    # not exist on either API version, v2 replaced them with `/checkouts/*`,
     # and v1 uses the singular `/billing/*`. Every call raises ApiError.
     #
     # Kept only so existing code keeps loading; it will be removed in 2.0.0.
@@ -19,7 +19,7 @@ module AbacatePay
       # @deprecated Use {CheckoutClient} instead
       def initialize(client = nil)
         warn "[DEPRECATION] BillingClient calls /billings/* endpoints that do not exist on the " \
-             "AbacatePay API — every request will fail. Use AbacatePay.checkouts instead. " \
+             "AbacatePay API, so every request fails. Use AbacatePay.checkouts instead. " \
              "This class will be removed in 2.0.0."
         super(URI, client)
       end

data/lib/abacate_pay/clients/checkout_client.rb

@@ -35,7 +35,7 @@ module AbacatePay
       end
 
       # Refunds a paid checkout in full. AbacatePay does not support partial
-      # refunds — the original amount is always returned.
+      # refunds, the original amount is always returned.
       #
       # @param id [String] Public checkout ID (`bill_...`) or charge ID
       #   (`char_...`, `pix_char_...`, `card_...`)

data/lib/abacate_pay/clients/client.rb

@@ -10,7 +10,7 @@ module AbacatePay
     # This class handles API requests using Faraday and provides a way to manage
     # authentication and communication with the AbacatePay service.
     class Client
-      # Statuses worth retrying. 429 is rate limiting and 5xx are transient —
+      # Statuses worth retrying. 429 is rate limiting and 5xx are transient -
       # AbacatePay's own reference tells integrators to back off on both.
       RETRIABLE_STATUSES = [429, 500, 502, 503, 504].freeze
 
@@ -75,16 +75,11 @@ module AbacatePay
       # @param method [String] The HTTP method (e.g., GET, POST)
       # @param uri [String] The endpoint URI relative to the base URI
       # @param options [Hash] Optional settings and parameters for the request
-      # @return [Hash, AbacatePay::Collection] The response data — a Collection
+      # @return [Hash, AbacatePay::Collection] The response data, a Collection
       #   when the API reports pagination, the raw data otherwise
       # @raise [ApiError] If an error occurs during the request
       def request(method, uri, options = {})
-        response = @client.public_send(method.downcase) do |req|
-          req.url uri
-          req.params = options[:params] if options[:params]
-          req.body = options[:json].to_json if options[:json]
-        end
-
+        response = send_request(method, uri, options)
         parsed = JSON.parse(response.body)
         raise ApiError, "API error: #{parsed["error"]}" if parsed["error"]
 
@@ -100,6 +95,45 @@ module AbacatePay
         raise ApiError, "API response is missing the 'data' field"
       end
 
+      # Issues the HTTP call.
+      #
+      # @param method [String] The HTTP method
+      # @param uri [String] The endpoint URI relative to the base URI
+      # @param options [Hash] Params and JSON body
+      # @return [Faraday::Response]
+      def send_request(method, uri, options)
+        @client.public_send(method.downcase) do |req|
+          req.url uri
+          req.params = options[:params] if options[:params]
+          req.body = compact_payload(options[:json]).to_json if options[:json]
+        end
+      end
+
+      # Removes nil values from an outgoing payload, at every depth.
+      #
+      # The API rejects explicit nulls: `{"cellphone": null}` comes back as
+      # HTTP 400 "Expected property 'cellphone' to be string but found: null",
+      # and payload builders naturally produce them for optional fields the
+      # caller left unset. Doing this at the boundary means no endpoint, present
+      # or future, can forget it.
+      #
+      # @param payload [Object] The payload about to be serialised
+      # @return [Object] The payload without nil entries
+      def compact_payload(payload)
+        case payload
+        when Hash
+          payload.each_with_object({}) do |(key, value), result|
+            next if value.nil?
+
+            result[key] = compact_payload(value)
+          end
+        when Array
+          payload.compact.map { |item| compact_payload(item) }
+        else
+          payload
+        end
+      end
+
       # Maps a list response into resources without losing the page cursor.
       #
       # @param response [Array, AbacatePay::Collection] The raw list response
@@ -123,7 +157,7 @@ module AbacatePay
           url: base_url,
           headers: build_headers(configuration),
           # Without an explicit timeout a hung gateway blocks the caller's
-          # thread indefinitely — inside a Rails request, that is an outage.
+          # thread indefinitely, inside a Rails request, that is an outage.
           request: {
             timeout: configuration.timeout,
             open_timeout: configuration.timeout

data/lib/abacate_pay/clients/payment_link_client.rb

@@ -4,8 +4,8 @@ module AbacatePay
   module Clients
     # Client for reusable payment links in the AbacatePay API.
     #
-    # A payment link can be paid by many customers independently — mass sales,
-    # raffles, sign-up forms — without creating one checkout per customer.
+    # A payment link can be paid by many customers independently, mass sales,
+    # raffles, sign-up forms, without creating one checkout per customer.
     # Use CheckoutClient when each customer needs their own charge.
     class PaymentLinkClient < Client
       URI = "payment-links"

data/lib/abacate_pay/clients/store_client.rb

@@ -12,7 +12,9 @@ module AbacatePay
 
       # @return [Resources::Store]
       def get
-        response = request("GET", "store/get")
+        # The API serves this as `stores/get`, plural, even though the reference
+        # documents `store/get`. The singular path answers HTTP 400.
+        response = request("GET", "stores/get")
         Resources::Store.new(response)
       end
 

data/lib/abacate_pay/clients/subscription_client.rb

@@ -52,7 +52,7 @@ module AbacatePay
       end
 
       # Changes the main product of an active subscription. The new price takes
-      # effect on the next billing cycle — the current cycle is untouched.
+      # effect on the next billing cycle, the current cycle is untouched.
       #
       # @param id [String] The subscription ID (`subs_...`)
       # @param product_id [String] The new product ID (`prod_...`), which must have a cycle

data/lib/abacate_pay/clients/transparent_client.rb

@@ -45,12 +45,14 @@ module AbacatePay
       # @param id [String] QR code ID (dev mode only)
       # @return [Resources::Transparents]
       def simulate_payment(id)
-        response = request("POST", "simulate-payment", json: { id: id })
+        # The API reads the id from the query string here, like #check. Sending
+        # it only in the body fails with "Expected property 'id'".
+        response = request("POST", "simulate-payment", params: { id: id }, json: {})
         Resources::Transparents.new(response)
       end
 
       # Refunds a transparent payment in full. AbacatePay does not support
-      # partial refunds — the original amount is always returned.
+      # partial refunds, the original amount is always returned.
       #
       # @param id [String] Public charge ID (`pix_char_...`, `card_...`, `char_...`)
       # @return [Resources::Transparents] The refunded charge

data/lib/abacate_pay/clients/webhook_client.rb

@@ -32,7 +32,7 @@ module AbacatePay
 
       # Registers a new webhook endpoint.
       #
-      # The secret is what AbacatePay signs deliveries with — pass the same
+      # The secret is what AbacatePay signs deliveries with, pass the same
       # value to {AbacatePay::Webhooks.construct_event} when handling them.
       #
       # @param name [String] Identifying name

data/lib/abacate_pay/clients.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Client must load first — every other client inherits from it.
+# Client must load first: every other client inherits from it.
 require "abacate_pay/clients/client"
 
 require "abacate_pay/clients/billing_client"

data/lib/abacate_pay/configuration.rb

@@ -9,8 +9,8 @@ module AbacatePay
   # @api public
   class Configuration
     # The only base URL this SDK speaks. v1 still exists, but under a
-    # different dialect — singular paths (`/v1/billing/`, `/v1/customer/`) and
-    # different resource names (`pixQrCode`) — which this SDK has never
+    # different dialect, singular paths (`/v1/billing/`, `/v1/customer/`) and
+    # different resource names (`pixQrCode`), which this SDK has never
     # implemented. Deriving a base URL from the token prefix only produced 404s
     # against v1 while sending v2-shaped paths.
     API_BASE_URL = "https://api.abacatepay.com/v2"
@@ -43,7 +43,7 @@ module AbacatePay
       @api_token = nil
     end
 
-    # @deprecated The environment is determined by the API key itself — keys
+    # @deprecated The environment is determined by the API key itself, keys
     #   created in Dev mode produce simulated transactions, production keys
     #   produce real ones. This setting has never had any effect and is kept
     #   only so existing initializers keep loading.

data/lib/abacate_pay/enums/billings/methods.rb

@@ -14,7 +14,7 @@ module AbacatePay
         # @return [String] Credit card payment
         CARD = "CARD"
 
-        # Boleto bancário. Supports a due date and late-payment interest/fine —
+        # Boleto bancário. Supports a due date and late-payment interest/fine -
         # see Resources::Checkouts#due_date, #interest and #fine.
         # @return [String] Boleto payment method
         BOLETO = "BOLETO"

data/lib/abacate_pay/enums/webhooks/event_types.rb

@@ -14,7 +14,7 @@ module AbacatePay
         SUBSCRIPTION_RENEWED = "subscription.renewed"
         SUBSCRIPTION_CANCELLED = "subscription.cancelled"
 
-        # Recurring charge failed — the dunning signal. Without handling this,
+        # Recurring charge failed, the dunning signal. Without handling this,
         # a failing subscription looks identical to a healthy one.
         SUBSCRIPTION_PAYMENT_FAILED = "subscription.payment_failed"
 

data/lib/abacate_pay/resources/customers.rb

@@ -2,45 +2,86 @@
 
 module AbacatePay
   module Resources
-    # Represents a customer resource in the AbacatePay payment system.
+    # Represents a customer in the AbacatePay system.
     #
-    # This class handles customer data including identification and metadata,
-    # providing a structured way to manage customer information within the system.
+    # The API returns the customer fields at the top level of the object:
+    #
+    #   { "id": "cust_...", "name": "Ana", "email": "ana@example.com",
+    #     "cellphone": "...", "taxId": "...", "metadata": {} }
+    #
+    # Earlier versions of this class only mapped `id` and a nested `metadata`,
+    # so every other field was silently dropped and `customer.metadata.name`
+    # came back nil for real API data.
+    #
+    # Both shapes work now: the fields are exposed directly, and `metadata`
+    # keeps answering for code written against the previous interface.
     class Customers < Resource
-      # Maps property names to their corresponding resource classes
       RESOURCE_PROPERTIES = {
         metadata: "AbacatePay::Resources::Customers::Metadata"
       }.freeze
 
-      # @return [String, nil] The unique identifier for the customer
-      attr_reader :id
+      # Fields the API sends inside the customer object.
+      IDENTITY_FIELDS = %i[name email cellphone tax_id].freeze
 
-      # @return [Metadata, nil] Additional customer information
-      attr_reader :metadata
+      attr_reader :id, :country, :zip_code, :dev_mode
 
-      # Creates a new Customer instance
-      #
-      # @param data [Hash] The raw customer data
-      # @raise [ArgumentError] If the data is invalid
+      # @return [String, nil] Customer's name
+      attr_reader :name
+
+      # @return [String, nil] Customer's email address
+      attr_reader :email
+
+      # @return [String, nil] Customer's cellphone number
+      attr_reader :cellphone
+
+      # @return [String, nil] Customer's tax identification number
+      attr_reader :tax_id
+
+      # @param data [Hash] The customer properties
       def initialize(data)
         fill(data)
       end
 
-      private
+      # @return [Boolean, nil] Whether this customer belongs to Dev mode
+      def dev_mode?
+        @dev_mode
+      end
 
-      # Process a value based on its property
+      # The identity fields, wrapped.
       #
+      # Kept because `customer.metadata.name` is what the README documented and
+      # what existing integrations call. When the API sends the fields at the
+      # top level, this builds the wrapper from them rather than returning the
+      # empty object the API puts in `metadata`.
+      #
+      # @return [Customers::Metadata, nil]
+      def metadata
+        return @metadata if metadata_populated?(@metadata)
+
+        identity = IDENTITY_FIELDS.to_h { |field| [field, public_send(field)] }.compact
+        return @metadata if identity.empty?
+
+        Customers::Metadata.new(identity)
+      end
+
+      private
+
+      # @param metadata [Customers::Metadata, nil]
+      # @return [Boolean] Whether the API actually filled the nested object
+      def metadata_populated?(metadata)
+        return false if metadata.nil?
+
+        IDENTITY_FIELDS.any? { |field| metadata.public_send(field) }
+      end
+
       # @param property [String] The property name
-      # @param value [Object] The value to process
+      # @param value [Object] The raw value
       # @return [Object] The processed value
       def process_value(property, value)
         return nil if value.nil?
 
         if RESOURCE_PROPERTIES.key?(property.to_sym)
-          initialize_resource(
-            Object.const_get(RESOURCE_PROPERTIES[property.to_sym]),
-            value
-          )
+          initialize_resource(Object.const_get(RESOURCE_PROPERTIES[property.to_sym]), value)
         else
           value
         end
@@ -48,8 +89,8 @@ module AbacatePay
 
       protected
 
-      # @!visibility private
-      attr_writer :id, :metadata
+      attr_writer :id, :metadata, :name, :email, :cellphone, :tax_id,
+                  :country, :zip_code, :dev_mode
     end
   end
 end

data/lib/abacate_pay/resources/resource.rb

@@ -51,7 +51,7 @@ module AbacatePay
         resource_class.new(value)
       end
 
-      # Default value processor — returns the value as-is.
+      # Default value processor, returns the value as-is.
       # Subclasses override this to handle enums, datetimes, and nested resources.
       #
       # @param _property [String] The property name

data/lib/abacate_pay/resources/transparents.rb

@@ -10,19 +10,36 @@ module AbacatePay
 
       DATETIME_PROPERTIES = %w[created_at updated_at expires_at].freeze
 
+      # qr_code and qr_code_image are defined below rather than generated here:
+      # they fall back to the br_code fields the API actually sends.
       attr_reader :id, :amount, :status, :method, :description,
-                  :expires_in, :qr_code, :qr_code_image, :customer,
+                  :expires_in, :customer,
                   :metadata, :dev_mode, :created_at, :updated_at,
                   # Boleto: due date sent on create, plus the payment slip the
-                  # API returns — digitable line, viewing URL, and the PIX
+                  # API returns: digitable line, viewing URL, and the PIX
                   # fallback issued for the same charge.
                   :due_date, :bar_code, :url, :br_code, :br_code_base64,
-                  :expires_at
+                  :expires_at, :platform_fee, :receipt_url
 
       def initialize(data)
         fill(data)
       end
 
+      # The API returns the copy-and-paste payload as `brCode` and the image as
+      # `brCodeBase64`. Older documentation used `qrCode`/`qrCodeImage`, so both
+      # spellings are accepted: the reader prefers the `qr*` value when the API
+      # sends one and falls back to `br*`.
+      #
+      # @return [String, nil] PIX copy-and-paste payload
+      def qr_code
+        @qr_code || br_code
+      end
+
+      # @return [String, nil] PIX QR code image as a data URI
+      def qr_code_image
+        @qr_code_image || br_code_base64
+      end
+
       def dev_mode?
         @dev_mode
       end
@@ -47,7 +64,7 @@ module AbacatePay
                   :expires_in, :qr_code, :qr_code_image, :customer,
                   :metadata, :dev_mode, :created_at, :updated_at,
                   :due_date, :bar_code, :url, :br_code, :br_code_base64,
-                  :expires_at
+                  :expires_at, :platform_fee, :receipt_url
     end
   end
 end

data/lib/abacate_pay/resources/webhook_endpoints.rb

@@ -4,7 +4,7 @@ module AbacatePay
   module Resources
     # Represents a registered webhook endpoint in the AbacatePay system.
     #
-    # This is the endpoint *registration* — the URL AbacatePay delivers events
+    # This is the endpoint *registration*, the URL AbacatePay delivers events
     # to. For verifying and parsing an inbound delivery, see {AbacatePay::Webhooks}.
     class WebhookEndpoints < Resource
       # @return [String, nil] Webhook ID

data/lib/abacate_pay/resources.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Resource must load first — every other resource inherits from it.
+# Resource must load first: every other resource inherits from it.
 require "abacate_pay/resources/resource"
 
 require "abacate_pay/resources/billings"

data/lib/abacate_pay/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AbacatePay
-  VERSION = "1.1.0"
+  VERSION = "1.2.1"
 end

data/lib/abacate_pay/webhooks.rb

@@ -17,33 +17,65 @@ module AbacatePay
     # Raised when a webhook body is not a JSON object the SDK can interpret.
     class PayloadError < AbacatePay::Error; end
 
-    # Verifies a webhook signature using HMAC-SHA256.
+    # AbacatePay signs every delivery with this fixed key, published at
+    # https://docs.abacatepay.com/pages/webhooks/security and hard-coded in the
+    # Node, Python and Go samples there.
+    #
+    # It is public and global, so it proves only that the body was not altered
+    # in transit, it does NOT prove the request came from AbacatePay, since
+    # anyone can compute a valid signature with it. Origin is authenticated by
+    # the `webhookSecret` query parameter; see {verify_secret!}. Use both.
+    PUBLIC_KEY = "t9dXRhHHo3yDEj5pVDYz0frf7q6bMKyMRmxxCPIPp3RCplBfXRxqlC6ZpiWmOqj4L63qEaeUOtrCI8P0VMU" \
+                 "go6iIga2ri9ogaHFs0WIIywSMg0q7RmBfybe1E5XJcfC4IW3alNqym0tXoAKkzvfEjZxV6bE0oG2zJrNNYmU" \
+                 "CKZyV0KZ3JS8Votf9EAWWYdiDkMkpbMdPggfh1EqHlVkMiTady6jOR3hyzGEHrIz2Ret0xHKMbiqkr9HS1Jh" \
+                 "NHDX9"
+
+    # Verifies the `X-Webhook-Signature` header: HMAC-SHA256 over the raw body,
+    # base64-encoded.
     #
     # @param payload [String] The raw request body
     # @param signature [String] The X-Webhook-Signature header value
-    # @param secret [String] Your webhook secret/public key
+    # @param secret [String] HMAC key. Defaults to {PUBLIC_KEY}, which is what
+    #   AbacatePay signs with.
     # @return [true] if signature is valid
     # @raise [SignatureError] if the signature is missing or invalid
-    def self.verify!(payload:, signature:, secret:)
+    def self.verify!(payload:, signature:, secret: PUBLIC_KEY)
       raise SignatureError, "Missing webhook signature" if signature.nil? || signature.to_s.empty?
       raise SignatureError, "Missing webhook secret" if secret.nil? || secret.to_s.empty?
 
-      expected = OpenSSL::HMAC.hexdigest("SHA256", secret.to_s, payload.to_s)
+      expected = base64_hmac(secret.to_s, payload.to_s)
       raise SignatureError, "Invalid webhook signature" unless secure_compare(expected, signature.to_s)
 
       true
     end
 
+    # Verifies the `webhookSecret` query parameter, which is what actually
+    # authenticates the request as coming from AbacatePay.
+    #
+    # The HMAC signature alone cannot do this: it is computed with a public key.
+    #
+    # @param received [String] The `webhookSecret` query parameter as received
+    # @param expected [String] The secret you configured on the webhook
+    # @return [true] if they match
+    # @raise [SignatureError] if either is missing or they differ
+    def self.verify_secret!(received:, expected:)
+      raise SignatureError, "Missing webhook secret parameter" if received.nil? || received.to_s.empty?
+      raise SignatureError, "Missing expected webhook secret" if expected.nil? || expected.to_s.empty?
+      raise SignatureError, "Invalid webhook secret" unless secure_compare(expected.to_s, received.to_s)
+
+      true
+    end
+
     # Checks if a webhook signature is valid.
     #
-    # Never raises for untrusted input — a missing header, an empty secret, or a
+    # Never raises for untrusted input, a missing header, an empty secret, or a
     # forged signature all return false.
     #
     # @param payload [String] The raw request body
     # @param signature [String] The X-Webhook-Signature header value
     # @param secret [String] Your webhook secret/public key
     # @return [Boolean]
-    def self.valid?(payload:, signature:, secret:)
+    def self.valid?(payload:, signature:, secret: PUBLIC_KEY)
       verify!(payload: payload, signature: signature, secret: secret)
       true
     rescue SignatureError
@@ -78,11 +110,25 @@ module AbacatePay
     # @return [Event] The verified, parsed event
     # @raise [SignatureError] if the signature is missing or invalid
     # @raise [PayloadError] if the body is not a JSON object
-    def self.construct_event(payload:, signature:, secret:)
+    def self.construct_event(payload:, signature:, secret: PUBLIC_KEY)
       verify!(payload: payload, signature: signature, secret: secret)
       parse(payload)
     end
 
+    # Base64-encoded HMAC-SHA256, matching what AbacatePay sends.
+    #
+    # Uses Array#pack rather than the base64 gem: base64 stopped being a default
+    # gem in Ruby 3.4, and requiring it would add a runtime dependency for one
+    # call.
+    #
+    # @param secret [String] The HMAC key
+    # @param payload [String] The raw body
+    # @return [String] The base64 signature
+    def self.base64_hmac(secret, payload)
+      [OpenSSL::HMAC.digest("SHA256", secret, payload)].pack("m0")
+    end
+    private_class_method :base64_hmac
+
     # Constant-time comparison to prevent timing attacks.
     #
     # @param expected [String] The signature computed from the payload

data/lib/abacatepay-ruby.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Entry point matching the gem name.
+#
+# Bundler requires a gem by its own name, so `gem "abacatepay-ruby"` in a
+# Gemfile makes Rails call `require "abacatepay-ruby"` (and then
+# `require "abacatepay/ruby"`). Neither matched `lib/abacate_pay.rb`, so the SDK
+# silently failed to load and the first call raised
+# `undefined method 'configure' for module AbacatePay` — the module existed with
+# only VERSION in it, defined as a side effect of the gemspec.
+#
+# This file makes the default `gem "abacatepay-ruby"` work without a `require:`
+# option. `require "abacate_pay"` keeps working for anyone already using it.
+require_relative "abacate_pay"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: abacatepay-ruby
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.1
 platform: ruby
 authors:
 - Matheus Cardoso
@@ -105,14 +105,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.22'
+        version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.22'
+        version: '1.0'
 description: The easiest way to integrate your Ruby application with AbacatePay Gateway
   for payments, subscriptions, PIX transfers, and more.
 email:
@@ -178,6 +178,7 @@ files:
 - lib/abacate_pay/version.rb
 - lib/abacate_pay/webhooks.rb
 - lib/abacate_pay/webhooks/event.rb
+- lib/abacatepay-ruby.rb
 homepage: https://www.abacatepay.com/
 licenses:
 - MIT