tinker-pay-ruby-sdk 0.1.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0b952007a71c15acfc412bf15ea914030bad28ff7d85fb947c64e81eb4e354d
-  data.tar.gz: 0c47365417e7520100310c3c87d9e0e72b28b7add64060a8a4c7bac300e93bff
+  metadata.gz: b22b3a0864b689dc0e16a306b043c089d9c9e9e6e26bf48f6dacf21980d2d73d
+  data.tar.gz: 146a36adc5a4685cffe65a69b96f252a7ef48b35307fe396b5fb5c17c55f0ee0
 SHA512:
-  metadata.gz: 827689281ecc69e936adf6edf3ec4e63d7e5425310dc7e47405c2062c4ab2f807abf946a0de279c78f7f1d5308b72db29c56f8b9bb35adf115374bd3179e45d0
-  data.tar.gz: 6c9bab9ab2168427ac3c183dfce37c3560c9fc646e8e9439c0dbe700a4cbd2c0f83ca5ac785d7074b63f606d3a539ed4488e1ba8112c9bcf638f1324d7622949
+  metadata.gz: 474f073c4aeab71b1a9cb28eb61648a3fcfa1a440afb64ce703ddad8d09b8f6a1ec6734abfcfdfc27752d77c6c0e07fe3c6db82afeb4666f0751446662f04cd8
+  data.tar.gz: 1da0ef57ad9119aa1b3377db69f679ba1430a05901632a0c4c5dfb79ca867e47bfc3c218f0867afdef927f691c530c4de5382378d616279c662cab2e5d10c6ca

data/.rubocop.yml

@@ -6,7 +6,6 @@ AllCops:
     - 'spec/spec_helper.rb'
     - 'bin/**/*'
     - 'tmp/**/*'
-    - '*.gemspec'
 
 Style/Documentation:
   Enabled: false

data/README.md

@@ -1,166 +1,291 @@
 # Tinker Payments Ruby SDK
 
-Official Ruby SDK for [Tinker Payments API](https://payments.tinker.co.ke/docs).
+Ruby 3.0+ SDK for payments, subscriptions and signed webhooks. Keep secret keys on the server.
 
-## Installation
+## Install and configure
 
-Add this line to your application's Gemfile:
+Add `gem 'tinker-pay-ruby-sdk'` to your Gemfile and run `bundle install`, or run:
 
-```ruby
-gem 'tinker-pay-ruby-sdk'
+```sh
+gem install tinker-pay-ruby-sdk
 ```
 
-And then execute:
+```ruby
+require 'tinker'
 
-```bash
-bundle install
+tinker = Tinker::Payments.new(api_public_key: 'pk_test_xxx', api_secret_key: 'sk_test_xxx')
 ```
 
-Or install it yourself as:
+Test key prefixes select `https://sandbox-api.tinkerpayments.com/v1/`; other keys select `https://api.tinkerpayments.com/v1/`. Override with `base_url:`. A custom `http_client:` must implement `get(url, headers:)` and `post(url, headers:, body:)`, returning responses with `status_code`, `json` and `headers`.
 
-```bash
-gem install tinker-pay-ruby-sdk
+## Payments
+
+```ruby
+request = Tinker::Model::Dto::InitiatePaymentRequestDto.new(
+  amount: 100, currency: 'KES', gateway: Tinker::Enum::Gateway::MPESA,
+  merchant_reference: 'ORDER-12345',
+  return_url: 'https://merchant.example/payment/return',
+  customer_phone: '+254712345678'
+)
+payment = tinker.transactions.initiate(request)
+result = tinker.transactions.query(Tinker::Model::Dto::QueryPaymentRequestDto.new(
+  payment_reference: 'TXN-abc123xyz', gateway: Tinker::Enum::Gateway::MPESA
+))
 ```
 
-## Requirements
+Any registered provider id works as `gateway:`, so new providers need no SDK release; `Tinker::Enum::Gateway` only lists common ones (`PESAPAL` included). List providers and their features with `tinker.transactions.capabilities(currency: 'KES', country: 'KE')` (both optional). Payment statuses are strings: `completed` becomes `success`, and unknown future statuses are kept as sent (`reversed` is `PaymentStatus::REVERSED`).
 
-- Ruby 3.0 or higher
-- No external runtime dependencies (uses standard library)
+Payments use currency units. Mpesa requires `customer_phone`; `return_url` is the browser destination, while webhooks are configured separately in the dashboard. Hosted providers may return `payment.initiation_data&.authorization_url` for a redirect.
 
-## Quick Start
+### Apple Pay / Google Pay
 
 ```ruby
-require 'tinker'
-
-tinker = Tinker::Payments.new(
-  api_public_key: 'your-public-key',
-  api_secret_key: 'your-secret-key'
+request = Tinker::Model::Dto::InitiatePaymentRequestDto.new(
+  amount: 100, currency: 'USD', gateway: Tinker::Enum::Gateway::STRIPE,
+  merchant_reference: 'ORDER-12345',
+  return_url: 'https://merchant.example/payment/return',
+  payment_method: 'apple_pay' # or 'google_pay'; 'bnpl' is Klarna on Stripe Checkout
 )
+data = tinker.transactions.initiate(request).initiation_data
+# return data.client_secret and data.publishable_key to the browser as JSON
 ```
 
-## Usage
+```html
+<div id="wallet"></div>
+<p id="wallet-error" role="alert"></p>
+<script src="https://js.stripe.com/v3/"></script>
+<script type="module">
+  const { clientSecret, publishableKey } = await fetch("/checkout/wallet", { method: "POST" }).then((r) => r.json());
+  const stripe = Stripe(publishableKey);
+  const elements = stripe.elements({ clientSecret });
+  const wallet = elements.create("expressCheckout", { paymentMethods: { applePay: "always", googlePay: "always" } });
+  wallet.mount("#wallet");
+  wallet.on("confirm", async (event) => {
+    const { error } = await stripe.confirmPayment({ elements, clientSecret, redirect: "if_required", confirmParams: { return_url: location.href } });
+    if (error) {
+      event.paymentFailed({ reason: "fail" });
+      document.querySelector("#wallet-error").textContent = error.message;
+    }
+  });
+</script>
+```
 
-### Initiate a Payment
+The result arrives through `payment.*` webhooks. Apple Pay and Google Pay on the web need the checkout domain registered with Stripe.
 
-```ruby
-require 'tinker'
+Plan-based subscriptions use `tinker.subscriptions.create_plan`, `list_plans`, `create`, `list` and `cancel` with the request DTOs in `Tinker::Model::Dto`.
+
+## Provider examples
 
+Every provider takes the same request. Keys and values are fake.
+
+```ruby
+dto = Tinker::Model::Dto
+tx = tinker.transactions
+return_url = 'https://shop.example/return'
+
+# Redirect (Paystack, Pesapal, PayPal, Flutterwave, DPO, Interswitch, Adyen, Plaid, hosted Stripe):
+# send the customer to payment.initiation_data&.authorization_url.
+payment = tx.initiate(dto::InitiatePaymentRequestDto.new(
+  amount: 2500, currency: 'NGN', gateway: 'paystack', merchant_reference: 'ORDER-1',
+  return_url: return_url, customer_email: 'jane@example.com'
+))
+
+# Phone approval (M-Pesa, MTN MoMo): no authorization_url. The customer approves on their phone
+# and the result arrives as a payment.completed or payment.failed webhook.
+tx.initiate(dto::InitiatePaymentRequestDto.new(
+  amount: 100, currency: 'KES', gateway: 'mpesa', merchant_reference: 'ORDER-2',
+  return_url: return_url, customer_phone: '+254712345678'
+))
+
+# Klarna (payment_method 'bnpl' on Stripe or Adyen) is captured at once. Adyen also needs country
+# (AT DK FI DE NO SE CH NL GB US) and that country's currency.
+tx.initiate(dto::InitiatePaymentRequestDto.new(
+  amount: 49.9, currency: 'EUR', gateway: 'adyen', merchant_reference: 'ORDER-3',
+  return_url: return_url, customer_email: 'jane@example.com', country: 'DE', payment_method: 'bnpl'
+))
+
+# Plaid (plaid_transfer, plaid_payments): customer_name is required.
+# Payment Initiation INITIATED counts as paid.
+tx.initiate(dto::InitiatePaymentRequestDto.new(
+  amount: 40, currency: 'GBP', gateway: 'plaid_payments', merchant_reference: 'ORDER-4',
+  return_url: return_url, customer_email: 'jane@example.com', customer_name: 'Jane Doe', country: 'GB'
+))
+
+# Ask first, then handle a refusal.
+tx.capabilities(currency: 'KES', country: 'KE')['providers'].each do |p|
+  puts "#{p['gateway']} #{p['capabilities']['pay_mobile_money']}"
+end
 begin
-  initiate_request = Tinker::Model::Dto::InitiatePaymentRequestDto.new(
-    amount: 100.00,
-    currency: 'KES',
-    gateway: Tinker::Enum::Gateway::MPESA,
-    merchant_reference: 'ORDER-12345',
-    return_url: 'https://your-app.com/payment/return',
-    customer_phone: '+254712345678',
-    transaction_desc: 'Payment for order #12345',
-    metadata: { order_id: '12345' }
-  )
-
-  transaction = tinker.transactions.initiate(initiate_request)
-  initiation_data = transaction.initiation_data
-
-  if initiation_data&.authorization_url
-    # Redirect user to authorization URL (Paystack, Stripe, etc.)
-    redirect_to initiation_data.authorization_url
-  end
-rescue Tinker::Exception::ApiException => e
-  puts "API Error: #{e.message}"
-rescue Tinker::Exception::NetworkException => e
-  puts "Network Error: #{e.message}"
+  tx.initiate(dto::InitiatePaymentRequestDto.new(
+    amount: 100, currency: 'KES', gateway: 'mpesa', merchant_reference: 'ORDER-5',
+    return_url: return_url, customer_phone: '+254712345678', payment_method: 'apple_pay'
+  ))
+rescue Tinker::Exception::FeatureNotSupportedException => e
+  puts "#{e.gateway} #{e.feature} #{e.alternatives.join(',')}" # retry on one of the alternatives
 end
 ```
 
-**Note:** The `return_url` is where users are redirected after payment completion. Webhooks are configured separately in your dashboard.
+Pay-as-you-go apps use Tinker's provider credentials; your own need a paid plan (HTTP 403 `PAID_PLAN_REQUIRED`).
 
-### Query a Transaction
+## Managed recurring billing
 
-```ruby
-query_request = Tinker::Model::Dto::QueryPaymentRequestDto.new(
-  payment_reference: 'TXN-abc123xyz',
-  gateway: Tinker::Enum::Gateway::MPESA
-)
+Checkout uses exact integer minor-unit prices (`15000` = EUR 150.00), a `month` or `year` interval, and a quantity. The SDK does not convert prices or apply discounts. Responses are unwrapped data maps/objects.
 
-transaction = tinker.transactions.query(query_request)
+| Method | Purpose |
+|---|---|
+| `checkout` | Create an exact-price recurring checkout |
+| `expire_checkout` | Expire an abandoned, unpaid checkout |
+| `billing_resource` | Read a managed billing resource |
+| `change_quantity` | Change the current quantity |
+| `schedule_quantity` | Schedule a quantity change |
+| `clear_scheduled_quantity` | Remove a scheduled quantity change |
+| `set_cancel_at_renewal` | Set cancellation at renewal; pass false to clear it |
+| `set_trial_end` | Move the next charge to a given time |
+| `end_trial` | End a trial now and charge the full period |
+| `billing_operation` | Recover the durable result by idempotency key |
+| `payment_method_portal` | Create a short-lived hosted payment-method link |
+| `billing_payment_history` | Read one page of captured payments and adjustments |
 
-if transaction.successful?
-  query_data = transaction.query_data
-  puts "Amount: #{query_data.amount} #{query_data.currency}"
-end
+```ruby
+billing = tinker.subscriptions
+billing.checkout(Tinker::Model::Dto::ManagedCheckout.new(
+  external_customer_id: 'workspace-123', email: 'buyer@example.com', name: 'Buyer',
+  currency: 'EUR', unit_amount: 15000, quantity: 3, interval: 'year',
+  return_url: 'https://example.com/billing', idempotency_key: 'checkout-123'
+))
+billing.change_quantity('resource-id', 4, 'quantity-123')
+billing.set_cancel_at_renewal('resource-id', false, 'resume-123')
+billing.payment_method_portal('resource-id', 'https://example.com/billing', 'portal-123')
+page = billing.billing_payment_history('resource-id', '', 0)
+# After an uncertain command response, recover using the SAME key:
+operation = billing.billing_operation('quantity-123')
 ```
 
-### Handle Webhooks
+Pass Integer values for minor-unit amounts, quantities and snapshots; do not convert
+through floating-point prices. `ManagedCheckout` exposes `to_hash`.
+
+### Expiring an abandoned checkout
 
-Webhooks support multiple event types: payment, subscription, invoice, and settlement. Check the event type and handle accordingly:
+An abandoned checkout link can still be completed later and create a second subscription. Expire it to close the link.
 
 ```ruby
-require 'tinker'
+billing.expire_checkout('checkout-id', 'expire-123')
+```
 
-event = tinker.webhooks.handle_from_request(request.body.read)
-
-# Check event type
-if event.payment_event?
-  payment_data = event.payment_data
-  # Handle payment.completed, payment.failed, etc.
-elsif event.subscription_event?
-  subscription_data = event.subscription_data
-  # Handle subscription.created, subscription.cancelled, etc.
-elsif event.invoice_event?
-  invoice_data = event.invoice_data
-  # Handle invoice.paid, invoice.failed
-elsif event.settlement_event?
-  settlement_data = event.settlement_data
-  # Handle settlement.processed
-end
+- `open` checkout: becomes `expired` (`managed_state.status` is `canceled`) and the session is returned.
+- Already `expired`: the session is returned unchanged, so retrying is safe.
+- `complete`, including completion while the call is in flight: HTTP 409 `CHECKOUT_COMPLETED` with `outcome: not_applied`. Read the checkout with `billing_resource` and use its subscription.
 
-# Access event details
-puts "Event type: #{event.type}"        # e.g., "payment.completed"
-puts "Event source: #{event.source}"    # e.g., "payment"
-puts "App ID: #{event.meta.app_id}"
-puts "Signature: #{event.security.signature}"
+A non-checkout ID (`sub_...`) returns 400 `INVALID_ID`. An expired checkout sends no `subscription.cancelled` webhook.
+
+### Trials with a required payment method
+
+Set `trial_days` (1 to 730) to collect a card at checkout and charge first when the trial ends. The SDK sends `trial_days` only when it is above 0, so checkouts without a trial keep working against servers released before trial support. A gateway without trial support returns HTTP 422 `FEATURE_NOT_SUPPORTED` with `outcome: not_applied`. Limiting a customer to one trial is the app's responsibility. Alternatively set `trial_end` to an exact end 48 hours to 730 days ahead; it cannot be combined with `trial_days` (HTTP 400), and the SDK sends it only when set.
+
+```ruby
+billing.checkout(Tinker::Model::Dto::ManagedCheckout.new(
+  external_customer_id: 'workspace-123', email: 'buyer@example.com', name: 'Buyer',
+  currency: 'EUR', unit_amount: 15000, quantity: 3, interval: 'year',
+  return_url: 'https://example.com/billing', idempotency_key: 'checkout-124',
+  trial_days: 14
+))
 ```
 
-For payment events only, you can convert to a `Transaction` object:
+### Changing the trial end
 
 ```ruby
-transaction = tinker.webhooks.handle_as_transaction(request.body.read)
-if transaction && transaction.successful?
-  callback_data = transaction.callback_data
-  puts "Payment successful: #{callback_data.reference}"
-end
+billing.set_trial_end('resource-id', Time.now + (30 * 86_400), 'trial-end-123')
+billing.end_trial('resource-id', 'end-trial-123')
 ```
 
-## Custom HTTP Client
+`set_trial_end` moves the next charge to a given time 1 hour to 730 days ahead. On a trialing subscription it moves the trial end earlier or later; on a paid (`active`) subscription only to a time on or after `current_period_end`, which makes it `trialing` without charging. Scheduled seat changes must be cleared first. `end_trial` ends a trial now and charges the full period immediately; if the charge fails the subscription becomes `past_due`. Both return the subscription with `managed_state`; state-dependent rejections arrive as 502 `BILLING_GATEWAY_ERROR` with `outcome: not_applied`. Ending a trial early sends `invoice.paid` and `payment.updated` (not `subscription.renewed`); extending a paid subscription produces a €0 `invoice.paid`.
+
+Checkout and billing resource responses include a provider-neutral `managed_state` map: `status` (`pending`, `trialing`, `active`, `past_due`, `paused` or `canceled`), `trial_ends_at`, `current_period_end` and `cancel_at_period_end`. Read it instead of raw provider fields; grant access while `status` is `trialing` or `active` and `current_period_end` is in the future. Managed subscription webhooks carry `billing_status` and `trial_ends_at`, and `subscription.trial_will_end` arrives up to three days before the trial ends. The trial's €0 invoice sends `invoice.paid` with amount 0 and is not a payment.
+
+Use a stable key per mutation and reuse it with the same payload after a lost response. Recover through the operation lookup; missing or pending results remain uncertain. Only an explicit `outcome` of `not_applied` confirms no mutation.
 
-You can use your own HTTP client by passing it to the constructor:
+The payment-method portal changes payment details only; quantity, price and overdue invoice payment are separate actions. It requires an app-owned managed subscription with a dedicated customer. Reuse the operation key after a lost response and use a new key for a deliberately new session after expiry.
+
+For payment history, keep the returned `snapshot` across `next_cursor` pages until `has_more` is false. Amounts are integer minor units and timestamps are UTC RFC3339. History covers captured cash, tax-exclusive eligible amounts, refunds, and dispute principal withdrawals/reinstatements (`reverses_id` identifies the reversed withdrawal).
+
+Quarantine items with `reconciliation_reason` and verify every page before committing a scan. The snapshot is an event cutoff, not an immutable provider snapshot: rescan from the first page to discover later adjustments, then apply facts idempotently by payment/adjustment ID. Zero-cash invoices advance pagination without an item. Processing/dispute fees are excluded from eligible principal; currency conversion and customer credits need explicit reconciliation.
+
+## Refunds, merchant payouts and checkout cancellation
+
+Payouts withdraw the merchant's available Tinker wallet balance to an existing
+verified payout account. The app owner enables SDK withdrawal access in the
+dashboard; the SDK cannot approve requests or verify payout accounts. Fees come
+out of the requested amount: requesting 100 with a fee of 2 reserves 100 and pays
+98. Quote first and send the quoted fee.
 
 ```ruby
-require 'tinker'
+refund = tinker.transactions.refund(payment_id,
+  Tinker::Model::Dto::RefundRequest.new(reason: 'requested_by_customer', amount: 25), 'refund-order-42')
+destination = tinker.payouts.methods.find { |method| method['is_verified'] && method['status'] == 'active' }
+raise 'Configure an active, verified payout method' unless destination
+method_id = destination['id']
+quote = tinker.payouts.quote(payout_method_id: method_id, amount: 100, currency: destination['currency'])
+payout = tinker.payouts.request_payout(
+  Tinker::Model::Dto::PayoutRequest.new(payout_method_id: method_id, amount: 100,
+    currency: destination['currency'], expected_fee_amount: quote['fee_amount']), 'withdrawal-42')
+status = tinker.payouts.get(payout.withdrawal.id)
+cancellation = tinker.transactions.cancel_checkout(unpaid_payment_id,
+  Tinker::Model::Dto::CancellationRequest.new(reason: 'Order cancelled'), 'cancel-order-42')
+```
 
-# Create a custom HTTP client that responds to #post(url, headers:, body:)
-# and returns an object with #status_code, #body, and #json methods
-custom_client = MyCustomHttpClient.new
+Reuse the same key for retries of one operation. Keys are required, limited to
+255 UTF-8 bytes, and never silently regenerated. Different payloads with one key
+produce a conflict. `pending_review` refunds and `pending_approval` payouts are
+accepted requests, not completed transfers. Only `refunded`, `paid`, or
+provider-confirmed `cancelled` indicate completion. Query `outcome_unknown`
+cancellations instead of assuming failure and retrying.
 
-tinker = Tinker::Payments.new(
-  api_public_key: 'your-public-key',
-  api_secret_key: 'your-secret-key',
-  http_client: custom_client
-)
+Use `refunds`, `get_refund`, `cancellations`, `get_cancellation`, and
+`payouts.list` for history and status. `ApiException#details` preserves the full
+error envelope; `details.dig('error', 'details')` includes the recorded request ID
+for unsupported cancellation (422) or updated quote for a fee conflict (409).
+Subscription cancellation is a separate operation. Existing administrative queues
+handle manual refunds and withdrawals.
+
+Cancellation history returns the newest 100 requests and `has_more`; use the
+single-request lookup to track a known older request. A cancellation with
+`payment_conflict` means later successful collection conflicts with cancellation
+evidence; investigate the successful payment and use a refund if needed.
+
+## Webhooks
+
+```ruby
+event = tinker.webhooks.handle(raw_body)
+raise 'Invalid webhook signature' unless tinker.webhooks.verify_signature(event, webhook_secret)
+transaction = event.to_transaction # nil for setup/lifecycle events
 ```
 
-## Documentation
+Verify the signature before consuming fields or converting the event to a transaction; reuse the parsed event rather than reading the request body twice. Deduplicate by event ID. The SDK verifies HMAC-SHA256 over the envelope excluding `security`, using the server's field order, map ordering and escaping.
 
-For detailed API documentation, visit [Tinker Payments API Documentation](https://payments.tinker.co.ke/docs).
+After verification, acknowledge `setup.webhook_test` (`source: onboarding`) with HTTP 200, 202 or 204; it needs no payment lookup or fulfillment. The signed lifecycle events `refund.updated.v1`, `withdrawal.updated.v1` and `checkout.cancellation.updated.v1` carry `data.resource` with `source: payment`. Their typed resources never convert into payment transactions. Poll request IDs if delivery is delayed.
 
-## Development
+## Errors and response metadata
 
-After checking out the repo, run `bundle install` to install dependencies. Then, run `rake spec` to run the tests.
+API errors retain `http_status`, `error_code`, `provider_code`, `request_id`, `retry_after`, `outcome` and the full envelope in `details`. Request IDs prefer the response body over `X-Request-ID`; `Retry-After` remains its original string. Non-JSON HTTP failures retain status/headers and an uncertain outcome. Only an explicit `not_applied` outcome confirms no mutation. Use `manager.last_meta` or `tinker.last_auth_meta` for response metadata.
 
-## Contributing
+An unsupported feature raises `Tinker::Exception::FeatureNotSupportedException` (an `ApiException`) with `gateway`, `feature` and `alternatives`; it replaces the former `CHECKOUT_CANCELLATION_UNSUPPORTED` code.
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/tinker/payments-ruby-sdk.
+```ruby
+begin
+  tinker.transactions.query(Tinker::Model::Dto::QueryPaymentRequestDto.new(
+    payment_reference: 'TXN-abc123xyz', gateway: Tinker::Enum::Gateway::MPESA
+  ))
+rescue Tinker::Exception::ApiException => error
+  warn "#{error.error_code}: #{error.message}"
+end
+```
 
-## License
+## Development
 
-MIT License
+```sh
+bundle install
+bundle exec rubocop
+bundle exec rake spec
+```
 
+MIT License.

data/lib/tinker/api/base_manager.rb

@@ -1,19 +1,23 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'uri'
 
 module Tinker
   module Api
     class BaseManager
+      attr_reader :last_meta
+
       def initialize(config:, http_client:, auth_manager:)
         @config = config
         @http_client = http_client
         @auth_manager = auth_manager
+        @last_meta = nil
       end
 
       protected
 
-      def request(_method, endpoint, data = {})
+      def request(method, endpoint, data = {}, request_headers = {})
         base_url = @config.base_url.chomp('/')
         endpoint = endpoint[1..] if endpoint.start_with?('/')
         url = "#{base_url}/#{endpoint}"
@@ -25,23 +29,82 @@ module Tinker
           'Content-Type' => 'application/json'
         }
 
-        body = data.empty? ? nil : JSON.generate(data)
-
-        response = @http_client.post(url, headers: headers, body: body)
-        result = response.json
+        headers.merge!(request_headers)
 
-        if response.status_code >= 400
-          message = result.is_a?(Hash) ? (result['message'] || result['error'] || 'Unknown error') : 'Unknown error'
-          raise Exception::ApiException.new(message, Exception::ExceptionCode::API_ERROR)
-        end
+        body = data.nil? || data.empty? ? nil : JSON.generate(data)
+        response = send_request(method, url, headers, body)
+        result = decode_response(response)
+        raise api_error(response, result) if response.status_code >= 400
 
-        result || {}
+        unwrap_response(response, result)
       rescue Exception::ApiException => e
         raise e
       rescue StandardError => e
         raise Exception::NetworkException.new("Failed to communicate with Tinker API: #{e.message}",
                                               Exception::ExceptionCode::NETWORK_ERROR, e)
       end
+
+      def operation_headers(key)
+        key = key.strip
+        unless key.bytesize.between?(1, 255) && !key.match?(/[\r\n]/)
+          raise Exception::InvalidPayloadException, 'Idempotency key must contain 1 to 255 bytes without line breaks'
+        end
+
+        { 'Idempotency-Key' => key }
+      end
+
+      def resource_id(id)
+        raise Exception::InvalidPayloadException, 'Resource ID is required' if id.strip.empty?
+
+        URI.encode_www_form_component(id).gsub('+', '%20')
+      end
+
+      def payment_path(id)
+        "merchant/payment/#{resource_id(id)}"
+      end
+
+      def send_request(method, url, headers, body)
+        verb = method.to_s.downcase
+        return @http_client.get(url, headers: headers) if verb == 'get'
+
+        @http_client.public_send(verb, url, headers: headers, body: body)
+      end
+
+      def decode_response(response)
+        response.json
+      rescue Exception::InvalidPayloadException
+        raise if response.status_code < 400
+
+        {}
+      end
+
+      def unwrap_response(response, result)
+        return result || {} unless result.is_a?(Hash) && result.key?('success')
+
+        @last_meta = Model::ApiMeta.new(result['meta'] || {})
+        raise api_error(response, result) if result['success'] == false
+
+        data = result['data']
+        data.is_a?(Hash) ? data : { 'value' => data }
+      end
+
+      def api_error(response, result)
+        error = result.is_a?(Hash) && result['error'].is_a?(Hash) ? result['error'] : {}
+        feature = Exception::FeatureNotSupportedException
+        klass = error['code'] == feature::CODE ? feature : Exception::ApiException
+        klass.new(extract_error_message(result), http_status: response.status_code,
+                                                 details: result, headers: response.headers || {})
+      end
+
+      def extract_error_message(result)
+        if result.is_a?(Hash)
+          error = result['error']
+          return error['message'] || error['code'] || 'Unknown error' if error.is_a?(Hash)
+
+          return result['message'] || 'Unknown error'
+        end
+        'Unknown error'
+      end
     end
   end
 end

data/lib/tinker/api/payout_manager.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Tinker
+  module Api
+    # Payouts are withdrawals to the merchant's own verified account.
+    class PayoutManager < BaseManager
+      def methods
+        request('GET', 'merchant/payout-methods').fetch('value', [])
+      end
+
+      def quote(payout_method_id:, amount:, currency: nil)
+        params = { payout_method_id: payout_method_id, amount: amount, currency: currency }.compact
+        request('GET', "merchant/payouts/quote?#{URI.encode_www_form(params)}")
+      end
+
+      def request_payout(payload, key)
+        Model::PayoutResult.new(request('POST', 'merchant/payouts', payload.to_hash, operation_headers(key)))
+      end
+
+      def list(page: nil, per_page: nil, status: nil, currency: nil)
+        params = { page: page, per_page: per_page, status: status, currency: currency }.compact
+        query = params.empty? ? '' : "?#{URI.encode_www_form(params)}"
+        request('GET', "merchant/payouts#{query}")
+      end
+
+      def get(id)
+        Model::Payout.new(request('GET', "merchant/payouts/#{resource_id(id)}"))
+      end
+    end
+  end
+end