abacatepay-ruby 1.0.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8249cc166bb8f5534c7299d4da8aac7c08193e8a33df8e7a7618737adb44a08c
-  data.tar.gz: f939f4979946f82d9e5a189d634ca4a7c99aa11e555646aec213b2f34dd4b817
+  metadata.gz: 65f1214bed1683aa366b68ef9055d85a318ca11901f90c36669fb3202c0b9be5
+  data.tar.gz: 0f1374d3702f53204228345237a8072a23918151cb3e2b9d13bd374b558cb04a
 SHA512:
-  metadata.gz: 4a14de54241b2901c7873becb95bab7bcceee8e7208b60b02114138eba6c72b1b6c16d5167c9f26f1b96fa9343bbe40097153f8b801b927b5c5dff02b3c0585c
-  data.tar.gz: e70fc7b7efea2223fbe1093f6f792e394f697da22fe92f01c738bec6a016df8116d09c5d4eec56accd4dbd5cd63a4628a8b6bb721742b76695f1436edc1139e7
+  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,7 +120,24 @@ 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"
+
+# `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
+# different question.
+Naming/PredicatePrefix:
+  AllowedMethods:
+    - has_more?

data/CHANGELOG.md

@@ -7,6 +7,124 @@ 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
+
+- **BOLETO support.** The method was rejected outright by the `Billings::Methods`
+  enum even though it is a first-class payment method in the v2 API. Adds the
+  enum value, the boleto-only `due_date`/`interest`/`fine` fields on checkouts,
+  and a `method:` argument on `TransparentClient#create` (which previously
+  hard-coded PIX). Boleto responses now expose `bar_code`, `url`, `br_code`,
+  `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`. 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
+  documented v2 endpoints. All 45 are now covered.
+- `subscription.payment_failed` and `subscription.trial_started` webhook event
+  types. `payment_failed` is the dunning signal.
+- Checkout fields the v2 API accepts but the SDK never sent: `max_installments`
+  (nested under `card`), `up_sell_product_id` and `custom_metadata`.
+- A `User-Agent` identifying the SDK and Ruby version.
+
+### Fixed
+
+- `Webhooks.parse` aside, malformed API responses raised `JSON::ParserError`
+  and a missing `data` field raised `KeyError`; both are now `ApiError`.
+
+### Changed
+
+- `BillingClient`'s deprecation warning now states that its `/billings/*`
+  endpoints do not exist on either API version, so every call fails. It will be
+  removed in 2.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.
+  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.
+
 ## [1.0.0] - 2026-08-05
 
 First stable release. The public surface is now covered by CI on four Ruby
@@ -16,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.
@@ -62,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`.
@@ -72,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
@@ -93,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.
@@ -114,12 +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).
 
@@ -42,8 +42,10 @@ gem 'abacatepay-ruby'
 
 ```ruby
 AbacatePay.configure do |config|
-  config.api_token = ENV['ABACATEPAY_TOKEN']
-  config.timeout = 30 # opcional, em segundos
+  config.api_token  = ENV['ABACATEPAY_TOKEN']
+  config.timeout    = 30      # opcional, segundos (default 30)
+  config.max_retries = 2      # opcional, retry em 429/5xx (default 2, 0 desliga)
+  config.logger     = Rails.logger # opcional, token é redigido
 end
 ```
 
@@ -54,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
 
@@ -101,25 +103,53 @@ AbacatePay.checkouts.list(status: 'PAID', email: 'user@example.com')
 
 <div align="center">
 
+Listas retornam no máximo 100 itens.
+
+</div>
+
+```ruby
+page = AbacatePay.customers.list
+page.first.id     # funciona como Array
+
+# Para percorrer tudo sem lidar com cursor:
+AbacatePay.customers.auto_paging_each { |customer| puts customer.id }
+```
+
+<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 foi desligada pela AbacatePay e responde `{"error":"Not found"}` em toda rota, então não há o que negociar.
+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>
 
@@ -147,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
@@ -175,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:
 
@@ -185,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
@@ -200,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` |
 
@@ -214,7 +252,7 @@ Todos os recursos são acessíveis pela fachada `AbacatePay.<recurso>`.
 | `products` | `list` `get` `create` `delete` |
 | `coupons` | `list` `get` `create` `delete` `toggle` |
 | `checkouts` | `list` `get` `create` `refund` |
-| `subscriptions` | `list` `create` `cancel` |
+| `subscriptions` | `list` `create` `cancel` `change_plan` `record_usage` |
 | `transparents` | `list` `create` `check` `simulate_payment` `refund` |
 | `pix` | `list` `get` `send_pix` |
 | `payouts` | `list` `get` `create` |
@@ -363,9 +401,67 @@ AbacatePay.payouts.create(
 
 <div align="center">
 
+### Boleto
+
+Boleto tem vencimento, juros e multa próprios. Todos os valores em centavos.
+
+</div>
+
+```ruby
+AbacatePay.checkouts.create(
+  AbacatePay::Resources::Checkouts.new(
+    methods: ['BOLETO'],
+    due_date: '2026-08-15',              # opcional; default 3 dias úteis
+    interest: { value: 100 },            # juros ao mês
+    fine: { value: 200, type: 'PERCENTAGE' }, # ou type: 'FIXED'
+    products: [
+      AbacatePay::Resources::Billings::Product.new(external_id: 'prod_123', quantity: 1)
+    ]
+  )
+)
+```
+
+<div align="center">
+
+No checkout transparente, o boleto exige nome e CPF/CNPJ do pagador, o SDK valida antes de chamar a API:
+
+</div>
+
+```ruby
+charge = AbacatePay::Resources::Transparents.new(amount: 25_000, due_date: '2026-08-15')
+# charge.customer precisa ter metadata.name e metadata.tax_id
+
+boleto = AbacatePay.transparents.create(charge, method: 'BOLETO')
+boleto.bar_code        # linha digitável
+boleto.url             # PDF para impressão
+boleto.br_code         # PIX alternativo da mesma cobrança
+```
+
+<div align="center">
+
+### Parcelamento e order bump
+
+</div>
+
+```ruby
+AbacatePay.checkouts.create(
+  AbacatePay::Resources::Checkouts.new(
+    methods: ['CARD'],
+    max_installments: 12,
+    up_sell_product_id: 'prod_bump',
+    custom_metadata: { origem: 'app-mobile' },
+    products: [
+      AbacatePay::Resources::Billings::Product.new(external_id: 'prod_123', quantity: 1)
+    ]
+  )
+)
+```
+
+<div align="center">
+
 ### 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>
 
@@ -387,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>
 
@@ -407,6 +503,12 @@ Cancela imediatamente; parcelas futuras pendentes são canceladas junto.
 
 ```ruby
 AbacatePay.subscriptions.cancel('subs_abc123xyz')
+
+# 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
+AbacatePay.subscriptions.record_usage('subs_abc123xyz', product_id: 'prod_api', units: 50)
 ```
 
 <div align="center">
@@ -448,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 |
 |---|---|
@@ -475,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

@@ -41,13 +41,14 @@ Gem::Specification.new do |spec|
   # NestedParamsEncoder). The lockfile only protects this repo — consumers are
   # protected by the constraint here.
   spec.add_dependency "faraday", "~> 2.14", ">= 2.14.3"
+  spec.add_dependency "faraday-retry", "~> 2.3"
 
   # Development dependencies
   spec.add_development_dependency "bundler-audit", "~> 0.9"
   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

@@ -2,7 +2,15 @@
 
 module AbacatePay
   module Clients
-    # Client class for managing billing-related operations in the AbacatePay API.
+    # 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/*`,
+    # 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.
+    #
+    # @deprecated Use {CheckoutClient} instead.
     class BillingClient < Client
       # API endpoint for billing-related operations
       URI = "billings"
@@ -10,7 +18,9 @@ module AbacatePay
       # @param client [Faraday::Connection, nil] Optional Faraday client for custom configurations
       # @deprecated Use {CheckoutClient} instead
       def initialize(client = nil)
-        warn "[DEPRECATION] BillingClient is deprecated. Use CheckoutClient instead."
+        warn "[DEPRECATION] BillingClient calls /billings/* endpoints that do not exist on the " \
+             "AbacatePay API, so every request fails. Use AbacatePay.checkouts instead. " \
+             "This class will be removed in 2.0.0."
         super(URI, client)
       end
 
@@ -19,7 +29,7 @@ module AbacatePay
       # @return [Array<Resources::Billing>] Array of Billing objects
       def list
         response = request("GET", "list")
-        Array(response).map { |data| Resources::Billings.new(data) }
+        build_list(response, Resources::Billings)
       end
 
       # Creates a new billing

data/lib/abacate_pay/clients/checkout_client.rb

@@ -17,7 +17,7 @@ module AbacatePay
       # @return [Array<Resources::Checkouts>]
       def list(**params)
         response = request("GET", "list", params: params.empty? ? nil : params)
-        Array(response).map { |data| Resources::Checkouts.new(data) }
+        build_list(response, Resources::Checkouts)
       end
 
       # @param id [String] Checkout ID
@@ -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_...`)
@@ -62,8 +62,29 @@ module AbacatePay
           items: data.products&.map { |product| { id: product.external_id, quantity: product.quantity } },
           externalId: data.external_id,
           coupons: data.coupons,
-          customerId: customer_id.to_s.empty? ? nil : customer_id
-        }.compact
+          customerId: customer_id.to_s.empty? ? nil : customer_id,
+          upSellProductId: data.up_sell_product_id,
+          metadata: data.custom_metadata
+        }.merge(boleto_options(data)).merge(card_options(data)).compact
+      end
+
+      # BOLETO-only fields. The API rejects them for other methods, so they are
+      # only sent when the caller actually set them.
+      #
+      # @param data [Resources::Checkouts] The checkout to serialize
+      # @return [Hash] The boleto payload fragment
+      def boleto_options(data)
+        { dueDate: data.due_date, interest: data.interest, fine: data.fine }
+      end
+
+      # CARD-only instalment cap, which the API nests under `card`.
+      #
+      # @param data [Resources::Checkouts] The checkout to serialize
+      # @return [Hash] The card payload fragment
+      def card_options(data)
+        return {} unless data.max_installments
+
+        { card: { maxInstallments: data.max_installments } }
       end
     end
   end