abacatepay-ruby 1.1.0 → 1.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 604226a94737477c55324bf08cb81736cce65fdf482453bd2667572c8986b010
-  data.tar.gz: 4e292b8d7db21a444cc4348bd59bc2cf396849ff8d99db4d4463ab1b651962fe
+  metadata.gz: 6049a0d508a75825d5bd94835dd27ec3241a0040129299165cb122de1af4636c
+  data.tar.gz: 8d2e2a858ac296de096f69ebf9acbab31c220d127631bd7a9534f30aa5caf5a7
 SHA512:
-  metadata.gz: 55eeee33fcf8a4b509c849f85d90ccb3f0fb4a2b4aad040325da4a6ed19bf2b60394190ce848ff0b03fa98ec56b0bddccf2fae677c19b1db1dfc7c744819286a
-  data.tar.gz: e8258c5ba01696d7d76fb85b4314a047052b04f13e0a90c4a826fe83f14ce967ea817cb445d3158a61be27a6ec4af99da9fc0c4dd477449c1bf1b60412f7f612
+  metadata.gz: 7733ebca9a9176869461cdbf726933ff32836f8953df5cd4a4a4c64c1021261c0ec6d5a75e753b382071f68b93928a928db8364c0dc280e050aed59a0b9a534e
+  data.tar.gz: f90e64c56b1681d41ee820ba3ba05e9e7fa0b9ff61afd2d9adf1daf8d6debf68d62f9865f49f5d956744843f1eb51fecc9cfbc49146a7717c7bbbf7a39a7d078

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,14 +120,21 @@ 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"
     - "spec/clients/logging_spec.rb"
     - "spec/clients/boleto_spec.rb"
     - "spec/packaging_spec.rb"
+    - "spec/api_conformance_spec.rb"
 
 # `has_more?` mirrors the API's own `hasMore` field and matches the convention
 # other payment SDKs use for cursor pagination. `more?` would read as a

data/CHANGELOG.md

@@ -7,6 +7,122 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.2] - 2026-08-06
+
+Found by exercising all 39 public calls against the live sandbox.
+
+### Fixed
+
+- **`customers.delete`, `products.delete` and `coupons.delete` always failed.**
+  Every delete endpoint reads the id from the query string; sending it only in
+  the body fails with "Expected property 'id' to be string but found:
+  undefined". Same defect as `webhook_endpoints.delete`.
+- **`pix.send_pix` and `payouts.create` always failed.** The API nests the
+  destination under `pix` as `{ key, type }`. The SDK sent `key`/`keyType` at
+  the top level, which fails with "Property 'pix' is missing". `Payouts` gained
+  `pix_key` and `pix_key_type`, without which a payout has no destination at
+  all.
+- **`subscriptions.create` always failed.** Line items take the product `id`,
+  the same shape checkouts use; the SDK sent `externalId`, which fails with
+  "Expected property 'items.0.id' to be string".
+- **Parsing a response could crash on a value the SDK did not know.**
+  `initialize_enum` validated while reading API responses, so any status
+  AbacatePay introduced turned into an `ArgumentError` inside `list` and `get`
+  for every integration at once. It happened with the coupon status `DISABLED`
+  and the payment-link status `ACTIVE`, which made `coupons.toggle` and
+  `payment_links.create` fail outright. Unknown values now pass through with a
+  warning; use the enum's `validate!` when you want a hard failure on a value
+  you are about to send.
+- **`Coupons#code` and `#current_redeems` were always nil.** The API uses the
+  coupon code as the object's `id` and sends the counter as `redeemsCount`.
+  Adds `redeems_count`, `notes` and `dev_mode?`; `code` falls back to the id
+  and `current_redeems` keeps answering.
+- **`webhook_endpoints.delete` always failed.** The API reads the id from the
+  query string on that endpoint, and answers `{"success":true,"error":null}`
+  with no `data` key, which the SDK then rejected as malformed. A successful
+  response carrying no payload is no longer an error.
+- Building a resource from an empty payload raised `NoMethodError`.
+
+### Added
+
+- `webhook_endpoints.create` refuses a secret shorter than 32 characters
+  locally, which is what the API requires.
+- `pix.list` documents that the API requires an `id`; despite the name it
+  filters rather than lists.
+
+### Changed
+
+- The coupon and checkout status enums gained `DISABLED` and `ACTIVE`.
+
+## [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 +135,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 +166,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 +181,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 +227,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 +237,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 +258,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 +279,15 @@ 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.2]: https://github.com/AbacatePay/abacatepay-ruby-sdk/releases/tag/v1.2.2
+[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,29 +75,80 @@ 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"]
 
-        data = parsed.fetch("data")
-        # Preserve the cursor when the API sends one; dropping it made paging
-        # past the first 100 records impossible.
-        parsed["pagination"] ? Collection.new(data, parsed["pagination"]) : data
+        extract_data(parsed)
       rescue Faraday::Error => e
         handle_request_error(e)
       rescue JSON::ParserError => e
         raise ApiError, "Malformed API response: #{e.message}"
-      rescue KeyError
-        raise ApiError, "API response is missing the 'data' field"
+      end
+
+      # Pulls the payload out of the `{data, error, success}` envelope.
+      #
+      # Some endpoints answer a successful call with no `data` at all, for
+      # example `webhooks/delete` returning `{"success":true,"error":null}`.
+      # Treating that as malformed turned a working call into an ApiError.
+      #
+      # @param parsed [Hash] The decoded response body
+      # @return [Object, nil] The payload, or nil when the call carries none
+      # @raise [ApiError] if the envelope has neither data nor a success flag
+      def extract_data(parsed)
+        unless parsed.key?("data")
+          return nil if parsed["success"]
+
+          raise ApiError, "Unexpected API response: #{parsed.inspect[0, 120]}"
+        end
+
+        data = parsed["data"]
+        # Preserve the cursor when the API sends one; dropping it made paging
+        # past the first 100 records impossible.
+        parsed["pagination"] ? Collection.new(data, parsed["pagination"]) : data
+      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.
@@ -123,7 +174,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/coupon_client.rb

@@ -42,7 +42,10 @@ module AbacatePay
       # @param id [String] Coupon ID
       # @return [Resources::Coupons]
       def delete(id)
-        response = request("POST", "delete", json: { id: id })
+        # The API reads the id from the query string on delete endpoints.
+        # Sending it only in the body fails with
+        # "Expected property 'id' to be string but found: undefined".
+        response = request("POST", "delete", params: { id: id }, json: {})
         Resources::Coupons.new(response)
       end
 

data/lib/abacate_pay/clients/customer_client.rb

@@ -50,7 +50,10 @@ module AbacatePay
       # @param id [String] The customer ID
       # @return [Resources::Customers] The deleted Customer object
       def delete(id)
-        response = request("POST", "delete", json: { id: id })
+        # The API reads the id from the query string on delete endpoints.
+        # Sending it only in the body fails with
+        # "Expected property 'id' to be string but found: undefined".
+        response = request("POST", "delete", params: { id: id }, json: {})
         Resources::Customers.new(response)
       end
     end

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"