zazu-ruby 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71bc6633249ecc429eb365ac5421ec4877d05f51f0b9b96bbcb1e45d8b65eaae
-  data.tar.gz: eea60136a9acaea0d9cbade450c6a8e08893c30c4258605d7242b396d4b6d06f
+  metadata.gz: 78fd31e6e0f84fd07c1e55e9af4b5828d232d39d1d040829a6d8518c33e176d2
+  data.tar.gz: 9760600e49b71b6bed3383677d7e108874740ca665c2e601cc6b7a87c1c8210b
 SHA512:
-  metadata.gz: b62cd7f7eba2cd18e82d6b3d464a7aa9abf86d9047d9bca26627788eef33714d6defd64cba0842a75cdae9d3290e25cad9b3f9a89adbb8a8d08daa727d78d1d3
-  data.tar.gz: e5aa06c535d57287791b49e0a22f9c9a9f9b9df146ed9e53784bf2637950f00dc742b4d386fe5b42c991a7c77b0921ada67a3f18710f8ef1337660419adffb3c
+  metadata.gz: 283a136fd5ca23c3db9d38f5007758bbc021eeeff6336cc117eb8342585d8b29ac09d8349a4db823c9f9743bdf1842c564ef4c2cffbe59aef005402dd64c1971
+  data.tar.gz: 5542a59251e3f5608c03ef92c4eadc2147ade849576662af02e67bd98b4c3e78673474ef0f82d929ec12db7e6ea6079b4e186254fe1f41298a17de7b2bad9b05

data/CHANGELOG.md

@@ -7,6 +7,50 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### Added
+
+- `Zazu::ConflictError` (409), the 10th error class. A duplicate
+  `client_reference` on a transfer draft raises it with `#payment_id`
+  naming the existing draft. 400 now maps to `Zazu::ValidationError`
+  (lists return 400 for a malformed `limit`/`cursor`).
+- `TransferDrafts#authorize(id, authorization_id:, signature:)` and
+  `#decline(id, authorization_id:, reason: nil)` for machine-authorized
+  transfers. A blank signature raises `Zazu::ArgumentError` locally —
+  the API would count it as a failed attempt.
+- `TransferDrafts#create` documents the new optional `client_reference`;
+  responses carry `client_reference` and `authorization`.
+- `Zazu::TransferAuthorization` — `signature_input`, `sign` and
+  `payee_for`, the HMAC-SHA256 signer for authorization challenges, with
+  a fixed test vector shared across SDKs
+  (`spec/zazu/transfer_authorization_spec.rb`).
+- `Beneficiaries#create`, `#list_external_accounts`,
+  `#get_external_account` and `#create_external_account`.
+- `Zazu::Resources::PayeeTrustRequests` (`zazu.payee_trust_requests`) —
+  `create(external_account_ids:)` and `get(id)`.
+- Docs for new pass-through fields: checkout session `customer_name`,
+  `collect_billing_address`, `billing_address`, `settled_at`,
+  `transaction` and the `clearing` status; payment link billing fields;
+  customer `registration_number` / `vat_number` (and MA-only `tax_id` /
+  `ice_number`).
+
+### Changed
+
+- Default base URL is now `https://ma.manza.finance` (Morocco production;
+  South Africa is `https://za.manza.finance`). Cassettes are recorded
+  against staging at `https://ma.manza.dev`. The old `zazu.ma` hosts are
+  still served.
+- Cassettes scrub `Manza-Version`, `account_number`, `bank_identifier`
+  and the authorize request `signature`. The three authorize cassettes
+  match the request body minus `signature` (`body_without_signature`),
+  which replay cannot reproduce; other SDKs should do the same.
+- `rake fixtures:seed` needs a second, authorizer API key, the
+  authorizer endpoint's signing secret and a tunnel to a local webhook
+  receiver (see the one-time setup in `lib/tasks/fixtures.rake`).
+  Re-recording now executes a real 10.00 MAD transfer (the API minimum).
+- Every cassette is re-recorded against `ma.manza.dev`, including the
+  full machine-authorization path (authorize 200, decline 200, bad
+  signature 422, same key 403, duplicate client_reference 409).
+
 ## [0.2.1]
 
 ### Added

data/README.md

@@ -1,6 +1,6 @@
 # Zazu Ruby SDK
 
-Ruby SDK for the [Zazu API](https://zazu.ma). Faraday + HTTPX adapter for HTTP/2 + persistent connections.
+Ruby SDK for the [Manza API](https://ma.manza.finance). Faraday + HTTPX adapter for HTTP/2 + persistent connections.
 
 ```ruby
 gem "zazu-ruby"
@@ -14,8 +14,8 @@ The gem is published as `zazu-ruby` on RubyGems but loaded as `zazu` in code (th
 require "zazu"
 
 zazu = Zazu.new(api_key: ENV["ZAZU_API_KEY"])
-# Or with explicit base URL (defaults to https://zazu.ma):
-zazu = Zazu.new(api_key: ENV["ZAZU_API_KEY"], base_url: "https://zazu.africa")
+# Or with explicit base URL (defaults to https://ma.manza.finance, Morocco):
+zazu = Zazu.new(api_key: ENV["ZAZU_API_KEY"], base_url: "https://za.manza.finance")
 
 entity = zazu.entity.get
 # => #<Zazu::Response status=200 ...>
@@ -79,6 +79,24 @@ zazu.checkout_sessions.create(
 )
 zazu.checkout_sessions.get("cs_...")
 
+zazu.beneficiaries.list
+zazu.beneficiaries.create(beneficiary_type: "business", company_name: "Acme Supplies", email: "ap@acme.com")
+zazu.beneficiaries.list_external_accounts("01a0...")
+zazu.beneficiaries.get_external_account("01a0...", "01a1...")
+zazu.beneficiaries.create_external_account("01a0...", account_number: "007780...", name: "Main account")
+
+zazu.payee_trust_requests.create(external_account_ids: ["01a1..."])
+zazu.payee_trust_requests.get("01a2...")
+
+zazu.transfer_drafts.create(
+  account_id: "019dde7d-...",
+  beneficiary_id: "01a0...",
+  amount: "2500.00",
+  client_reference: "po_1042" # unique per entity; a duplicate raises Zazu::ConflictError
+)
+zazu.transfer_drafts.get("01a3...")
+zazu.transfer_drafts.decline("01a3...", authorization_id: "01a4...", reason: "Not ours")
+
 zazu.webhook_endpoints.list
 zazu.webhook_endpoints.create(
   url: "https://example.com/webhooks/zazu",
@@ -90,6 +108,28 @@ zazu.webhook_endpoints.enable("01a0...")
 zazu.webhook_endpoints.disable("01a0...")
 ```
 
+## Machine-authorized transfers
+
+A draft inside your entity's authorization envelope (trusted payee, within limits) is sent to your enrolled authorizer endpoint as a `payment.authorization_requested` webhook carrying an `authorization.id` and a one-time `nonce`. Sign the draft from **your own record** of it with the endpoint's signing secret, and authorize it with a **different API key** from the one that created it (the creating key gets 403 `same_key_forbidden`):
+
+```ruby
+input = Zazu::TransferAuthorization.signature_input(
+  payment_id: draft["id"],
+  nonce: webhook["data"]["authorization"]["nonce"],
+  amount: draft["amount"],               # the API's decimal string, e.g. "2500.0"
+  currency_code: draft["currency_code"],
+  account_id: draft["account_id"],
+  payee: Zazu::TransferAuthorization.payee_for(external_account_id: draft["external_account_id"]),
+  client_reference: draft["client_reference"]
+)
+signature = Zazu::TransferAuthorization.sign(secret: signing_secret, signature_input: input)
+
+authorizer = Zazu.new(api_key: ENV["ZAZU_AUTHORIZER_API_KEY"])
+authorizer.transfer_drafts.authorize(draft["id"], authorization_id: webhook["data"]["authorization"]["id"], signature: signature)
+```
+
+A wrong signature raises `Zazu::ValidationError` (`type` `invalid_signature`). Five on one challenge send the draft to your in-app approvers; five in a row suspend the authorizer.
+
 ## Pagination
 
 Every list endpoint returns a `Zazu::Page`. The SDK enforces a hard cap of **100 records per page** — there is no auto-pagination across pages.
@@ -117,7 +157,9 @@ Every non-2xx response raises a subclass of `Zazu::Error`:
 |---|---|
 | 401 | `Zazu::AuthenticationError` |
 | 403 | `Zazu::ForbiddenError` |
+| 400 | `Zazu::ValidationError` (malformed request, e.g. bad `limit`/`cursor`) |
 | 404 | `Zazu::NotFoundError` |
+| 409 | `Zazu::ConflictError` (carries `#payment_id` for a duplicate `client_reference`) |
 | 422 | `Zazu::ValidationError` |
 | 429 | `Zazu::RateLimitError` (carries `#retry_after`) |
 | 5xx | `Zazu::ServerError` |
@@ -141,7 +183,7 @@ end
 zazu = Zazu.new(api_key: "...", api_version: "2026-03-27")
 ```
 
-Or via env: `ZAZU_API_VERSION=2026-03-27`. The header is sent on every request; the API echoes it back in `Zazu-Version`.
+Or via env: `ZAZU_API_VERSION=2026-03-27`. The header is sent on every request; the API echoes it back in both `Zazu-Version` and `Manza-Version`.
 
 ## Development
 
@@ -157,10 +199,45 @@ To re-record cassettes against staging:
 
 ```bash
 cp .env.example .env
-# fill in ZAZU_STAGING_API_KEY and the ZAZU_FIXTURE_*_ID values
+# fill in the keys, ZAZU_FIXTURE_ACCOUNT_ID and ZAZU_FIXTURE_BENEFICIARY_ID
+cloudflared tunnel --config ~/.cloudflared/zazu-sdk-authorizer.yml run zazu-sdk-authorizer   # separate terminal
 bundle exec rake fixtures:record
 ```
 
+Recording executes a real 10.00 MAD transfer on staging (the authorize cassette). The one-time staging setup (keys, authorizer enrolment, trusted payee) is listed at the top of `lib/tasks/fixtures.rake`.
+
+### The authorizer tunnel
+
+The machine-authorization cassettes need the `payment.authorization_requested` webhook, which staging sends to the webhook endpoint enrolled as transfer authorizer. During `rake fixtures:record` the seeder listens for it on `127.0.0.1:${ZAZU_STAGING_AUTHORIZER_PORT:-4599}`, so a tunnel must forward the endpoint's public URL to that port. The endpoint URL cannot change once enrolled, so the tunnel needs a **stable hostname** (a throwaway `trycloudflare.com` URL won't do).
+
+The existing setup uses a named Cloudflare tunnel `zazu-sdk-authorizer` → `https://sdk-authorizer.manza.dev/`. To run it on a new machine:
+
+```bash
+brew install cloudflared
+cloudflared tunnel login                    # pick the manza.dev zone
+cloudflared tunnel token --cred-file ~/.cloudflared/zazu-sdk-authorizer.json zazu-sdk-authorizer
+cat > ~/.cloudflared/zazu-sdk-authorizer.yml <<YML
+tunnel: zazu-sdk-authorizer
+credentials-file: $HOME/.cloudflared/zazu-sdk-authorizer.json
+ingress:
+  - hostname: sdk-authorizer.manza.dev
+    service: http://127.0.0.1:4599
+  - service: http_status:404
+YML
+cloudflared tunnel --config ~/.cloudflared/zazu-sdk-authorizer.yml run zazu-sdk-authorizer
+```
+
+To create one from scratch instead (then point a new webhook endpoint at it and enrol that one as authorizer):
+
+```bash
+cloudflared tunnel create zazu-sdk-authorizer
+cloudflared tunnel route dns zazu-sdk-authorizer sdk-authorizer.manza.dev
+```
+
+The tunnel's `service` port must match `ZAZU_STAGING_AUTHORIZER_PORT`: if you change one, change the other, or deliveries never reach the seeder and `fixtures:record` times out waiting for them.
+
+Check it end to end: with the tunnel running and nothing on port 4599, `curl -X POST https://sdk-authorizer.manza.dev/` returns 502. During a record run the seeder answers unsigned requests with 401.
+
 Cassettes are scrubbed before write — bearer tokens and request IDs are rewritten to placeholders. Even if a real key is in `.env`, the committed cassette never contains it.
 
 ## Cassettes for other-language SDKs

data/lib/zazu/client.rb

@@ -18,7 +18,8 @@ module Zazu
   # uses a connection pool via the HTTPX adapter — multiple threads
   # can share one client.
   class Client
-    DEFAULT_BASE_URL = "https://zazu.ma"
+    # Morocco production. South Africa: https://za.manza.finance.
+    DEFAULT_BASE_URL = "https://ma.manza.finance"
     DEFAULT_TIMEOUT = 30
     USER_AGENT = "zazu-ruby/#{VERSION}".freeze
 
@@ -69,6 +70,10 @@ module Zazu
       @payment_links ||= Resources::PaymentLinks.new(self)
     end
 
+    def payee_trust_requests
+      @payee_trust_requests ||= Resources::PayeeTrustRequests.new(self)
+    end
+
     def transfer_drafts
       @transfer_drafts ||= Resources::TransferDrafts.new(self)
     end
@@ -130,6 +135,7 @@ module Zazu
     # is matched separately because Range keys don't work in Hash
     # lookup the way exact integers do.
     ERROR_BY_STATUS = {
+      400 => [ValidationError, "Bad request"],
       401 => [AuthenticationError, "Authentication failed"],
       403 => [ForbiddenError, "Forbidden"],
       404 => [NotFoundError, "Not found"],
@@ -147,7 +153,7 @@ module Zazu
         return klass.new(message || default_message, **kwargs)
       end
 
-      build_special_error(response, message, kwargs)
+      build_special_error(response, payload, message, kwargs)
     end
 
     def error_payload(body)
@@ -166,8 +172,10 @@ module Zazu
       }
     end
 
-    def build_special_error(response, message, kwargs)
+    def build_special_error(response, payload, message, kwargs)
       case response.status
+      when 409
+        ConflictError.new(message || "Conflict", payment_id: payload["payment_id"], **kwargs)
       when 429
         retry_after = response.headers["retry-after"]&.to_i
         RateLimitError.new(message || "Rate limited", retry_after: retry_after, **kwargs)

data/lib/zazu/errors.rb

@@ -42,10 +42,29 @@ module Zazu
   # see it).
   class NotFoundError < Error; end
 
-  # 422 — request body or query params failed validation. `#param`
-  # carries the offending field name when the API supplies it.
+  # 400 / 422 — request body or query params failed validation (400 for
+  # a malformed request such as a bad `limit`/`cursor`, 422 for a
+  # well-formed one the API rejects). `#param` carries the offending
+  # field name when the API supplies it.
   class ValidationError < Error; end
 
+  # 409 — the request conflicts with an existing resource. For a
+  # duplicate `client_reference` on a transfer draft (`type`
+  # "duplicate_client_reference"), `#payment_id` names the draft that
+  # already holds it.
+  class ConflictError < Error
+    attr_reader :payment_id
+
+    def initialize(message = nil, payment_id: nil, **)
+      super(message, **)
+      @payment_id = payment_id
+    end
+
+    def to_h
+      super.merge(payment_id:).compact
+    end
+  end
+
   # 429 — rate limited. Retry after the `Retry-After` header (seconds).
   class RateLimitError < Error
     attr_reader :retry_after

data/lib/zazu/resources/beneficiaries.rb

@@ -2,10 +2,9 @@
 
 module Zazu
   module Resources
-    # Read-only directory of saved transfer recipients. Each
-    # beneficiary embeds its bank accounts; the one flagged `default`
-    # is used when a transfer names only the beneficiary_id.
-    # Beneficiaries are created and managed in the Zazu dashboard.
+    # Saved transfer recipients. Each beneficiary embeds its bank
+    # accounts; the one flagged `default` is used when a transfer names
+    # only the beneficiary_id. There is no update or delete via the API.
     class Beneficiaries < Base
       # GET /api/beneficiaries
       def list(limit: MAX_PER_PAGE, cursor: nil)
@@ -16,6 +15,35 @@ module Zazu
       def get(id)
         http_get(encode_path("api/beneficiaries", id))
       end
+
+      # POST /api/beneficiaries
+      #
+      # Keys: beneficiary_type ("individual" | "business"; inferred from
+      # person_name / company_name when omitted), person_name, company_name, email,
+      # phone_number. Values must be strings. Shares a 10/minute limit
+      # with {#create_external_account}.
+      def create(**attributes)
+        http_post("api/beneficiaries", body: attributes)
+      end
+
+      # GET /api/beneficiaries/:beneficiary_id/external_accounts
+      def list_external_accounts(beneficiary_id, limit: MAX_PER_PAGE, cursor: nil)
+        list_page(encode_path("api/beneficiaries", beneficiary_id, "external_accounts"), limit: limit, cursor: cursor)
+      end
+
+      # GET /api/beneficiaries/:beneficiary_id/external_accounts/:id
+      def get_external_account(beneficiary_id, id)
+        http_get(encode_path("api/beneficiaries", beneficiary_id, "external_accounts", id))
+      end
+
+      # POST /api/beneficiaries/:beneficiary_id/external_accounts
+      #
+      # Required: account_number. Optional: name, country_code,
+      # currency_code, account_type ("bank" only), bank_identifier
+      # (required in ZA, rejected in MA, where it is derived from the RIB).
+      def create_external_account(beneficiary_id, **attributes)
+        http_post(encode_path("api/beneficiaries", beneficiary_id, "external_accounts"), body: attributes)
+      end
     end
   end
 end

data/lib/zazu/resources/checkout_sessions.rb

@@ -4,8 +4,9 @@ module Zazu
   module Resources
     # One-off hosted checkout sessions. Pre-API there's no list,
     # update, or delete — sessions are created and inspected by id.
-    # State (`open`, `processing`, `complete`, `expired`) transitions
-    # are read-only from the SDK's perspective.
+    # State (`open`, `processing`, `clearing`, `complete`, `expired`)
+    # transitions are read-only from the SDK's perspective. Responses
+    # carry `settled_at` and the paying `transaction`.
     class CheckoutSessions < Base
       # GET /api/checkout_sessions/:id
       def get(id)
@@ -16,7 +17,8 @@ module Zazu
       #
       # @param attributes [Hash] checkout-session attributes — see API docs.
       #   Required: account_id, amount, success_url.
-      #   Optional: metadata, customer_email, cancel_url, description, expires_at.
+      #   Optional: metadata, customer_email, customer_name, cancel_url,
+      #   description, expires_at, collect_billing_address, billing_address.
       def create(**attributes)
         http_post("api/checkout_sessions", body: attributes)
       end

data/lib/zazu/resources/customers.rb

@@ -20,8 +20,10 @@ module Zazu
       #
       # @param attributes [Hash] customer attributes — see API docs.
       #   Common keys: customer_type ("individual"|"business"),
-      #   person_name, company_name, email, phone, tax_id, ice_number,
-      #   billing_address (Hash with street/city/postal_code/country/country_code).
+      #   person_name, company_name, email, phone, registration_number,
+      #   vat_number, billing_address (Hash with street/city/postal_code/
+      #   country/country_code). Morocco only: tax_id, ice_number — these
+      #   keys are absent from responses in other markets.
       def create(**attributes)
         http_post("api/customers", body: attributes)
       end

data/lib/zazu/resources/payee_trust_requests.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Zazu
+  module Resources
+    # Requests to trust payees for machine-authorized transfers. The API
+    # key can only ask: a member holding payment-authorize permission
+    # approves the request in the Zazu app. Status: pending → approved /
+    # declined / cancelled. There is no list, update, or delete.
+    class PayeeTrustRequests < Base
+      # POST /api/payee_trust_requests
+      #
+      # @param external_account_ids [Array<String>] at most 100 bank accounts.
+      def create(external_account_ids:)
+        http_post("api/payee_trust_requests", body: { external_account_ids: external_account_ids })
+      end
+
+      # GET /api/payee_trust_requests/:id
+      def get(id)
+        http_get(encode_path("api/payee_trust_requests", id))
+      end
+    end
+  end
+end

data/lib/zazu/resources/payment_links.rb

@@ -21,6 +21,9 @@ module Zazu
       end
 
       # POST /api/payment_links
+      #
+      # Optional billing keys: collect_billing_address, billing_address.
+      # Responses carry `settled_at`; status includes `clearing`.
       def create(**attributes)
         http_post("api/payment_links", body: attributes)
       end

data/lib/zazu/resources/transfer_drafts.rb

@@ -2,19 +2,25 @@
 
 module Zazu
   module Resources
-    # API-initiated transfers. Creating a draft routes it into the
-    # workspace's in-app approval flow — the API never executes a
-    # transfer itself. A manager or legal representative approves in
-    # the Zazu app; poll {#get} (status: requested → processing →
-    # completed / failed) or subscribe to the `transfer.executed`
-    # webhook to follow execution.
+    # API-initiated transfers. Creating a draft never executes a
+    # transfer by itself. A draft inside the entity's machine-
+    # authorization envelope (trusted payee, within limits) is sent to
+    # the enrolled transfer authorizer as a `payment.authorization_requested`
+    # webhook; answer it with {#authorize} or {#decline}, using an API
+    # key other than the one that created the draft. Every other draft
+    # goes to the in-app approval flow, where a manager or legal
+    # representative approves it. Poll {#get} (status: requested →
+    # processing → completed / failed) or subscribe to the
+    # `transfer.executed` webhook to follow execution.
     class TransferDrafts < Base
       # POST /api/transfer_drafts
       #
       # Required: account_id, amount, and exactly one of beneficiary_id
       # (external transfer) or destination_account_id (own-account move).
       # Optional: external_account_id, currency_code, payment_reference,
-      # internal_notes.
+      # internal_notes, client_reference (unique per entity, at most 128
+      # characters; a duplicate raises {Zazu::ConflictError} whose
+      # `payment_id` names the existing draft).
       def create(**attributes)
         http_post("api/transfer_drafts", body: attributes)
       end
@@ -23,6 +29,34 @@ module Zazu
       def get(id)
         http_get(encode_path("api/transfer_drafts", id))
       end
+
+      # POST /api/transfer_drafts/:id/authorize
+      #
+      # Executes the draft. `authorization_id` comes from the
+      # `payment.authorization_requested` webhook; build `signature` with
+      # {Zazu::TransferAuthorization}. Requires the `transfers:authorize`
+      # scope on a key other than the draft's creator (otherwise 403
+      # `same_key_forbidden`). A blank signature is refused locally: the
+      # API counts it as a failed attempt, and five fail the challenge.
+      def authorize(id, authorization_id:, signature:)
+        raise Zazu::ArgumentError, "signature cannot be blank" if signature.to_s.strip.empty?
+
+        http_post(
+          encode_path("api/transfer_drafts", id, "authorize"),
+          body: { authorization_id: authorization_id, signature: signature }
+        )
+      end
+
+      # POST /api/transfer_drafts/:id/decline
+      #
+      # Declines the challenge and deletes the draft. Returns the
+      # authorization (`status: "declined"`).
+      def decline(id, authorization_id:, reason: nil)
+        http_post(
+          encode_path("api/transfer_drafts", id, "decline"),
+          body: { authorization_id: authorization_id, reason: reason }.compact
+        )
+      end
     end
   end
 end

data/lib/zazu/resources/webhook_endpoints.rb

@@ -27,11 +27,16 @@ module Zazu
       end
 
       # PATCH /api/webhook_endpoints/:id
+      #
+      # Changing `url` on the endpoint enrolled as transfer authorizer
+      # raises {Zazu::ValidationError}.
       def update(id, **attributes)
         http_patch(encode_path("api/webhook_endpoints", id), body: attributes)
       end
 
       # DELETE /api/webhook_endpoints/:id
+      #
+      # A soft delete (still 204).
       def delete(id)
         http_delete(encode_path("api/webhook_endpoints", id))
       end
@@ -42,6 +47,8 @@ module Zazu
       end
 
       # POST /api/webhook_endpoints/:id/regenerate_secret
+      #
+      # Raises {Zazu::ValidationError} on the enrolled transfer authorizer.
       def regenerate_secret(id)
         http_post(encode_path("api/webhook_endpoints", id, "regenerate_secret"))
       end

data/lib/zazu/transfer_authorization.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Zazu
+  # Signs a machine-authorization challenge for an API-created transfer
+  # draft. Pure functions — no HTTP.
+  #
+  # The `payment.authorization_requested` webhook delivers the
+  # authorization id and a one-time nonce. Build the signature input
+  # from your *own* record of the transfer (not the webhook's
+  # `signature_input`, which is there only to compare against), sign
+  # it with the authorizer endpoint's signing secret, and pass the
+  # result to {Resources::TransferDrafts#authorize}:
+  #
+  #   input = Zazu::TransferAuthorization.signature_input(
+  #     payment_id: draft["id"], nonce: nonce, amount: draft["amount"],
+  #     currency_code: draft["currency_code"], account_id: draft["account_id"],
+  #     payee: Zazu::TransferAuthorization.payee_for(external_account_id: draft["external_account_id"]),
+  #     client_reference: draft["client_reference"]
+  #   )
+  #   signature = Zazu::TransferAuthorization.sign(secret: signing_secret, signature_input: input)
+  #   zazu.transfer_drafts.authorize(draft["id"], authorization_id: authorization_id, signature: signature)
+  module TransferAuthorization
+    SIGNATURE_VERSION = "manza.transfer-authorization.v1"
+
+    module_function
+
+    # `amount` must be the API's decimal string verbatim (e.g. "2500.0").
+    # `client_reference` is empty when the transfer has none.
+    def signature_input(payment_id:, nonce:, amount:, currency_code:, account_id:, payee:, client_reference: nil)
+      raise Zazu::ArgumentError, "amount must be the API's decimal string (got #{amount.inspect})" unless amount.is_a?(String)
+
+      [
+        SIGNATURE_VERSION, payment_id, nonce, amount, currency_code, account_id, payee, client_reference.to_s
+      ].join("|")
+    end
+
+    # Hex HMAC-SHA256 of the signature input under the authorizer
+    # endpoint's signing secret.
+    def sign(secret:, signature_input:)
+      OpenSSL::HMAC.hexdigest("SHA256", secret, signature_input)
+    end
+
+    # The payee token: `ext:<id>` for a beneficiary's bank account,
+    # `own:<id>` for one of the entity's own accounts. Pass exactly one.
+    def payee_for(external_account_id: nil, destination_account_id: nil)
+      unless external_account_id.nil? ^ destination_account_id.nil?
+        raise Zazu::ArgumentError, "pass exactly one of external_account_id or destination_account_id"
+      end
+
+      destination_account_id ? "own:#{destination_account_id}" : "ext:#{external_account_id}"
+    end
+  end
+end

data/lib/zazu/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zazu
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

data/lib/zazu.rb

@@ -20,6 +20,7 @@ require_relative "zazu/version"
 require_relative "zazu/errors"
 require_relative "zazu/response"
 require_relative "zazu/page"
+require_relative "zazu/transfer_authorization"
 require_relative "zazu/resources/base"
 require_relative "zazu/resources/accounts"
 require_relative "zazu/resources/beneficiaries"
@@ -27,6 +28,7 @@ require_relative "zazu/resources/checkout_sessions"
 require_relative "zazu/resources/customers"
 require_relative "zazu/resources/entity"
 require_relative "zazu/resources/invoices"
+require_relative "zazu/resources/payee_trust_requests"
 require_relative "zazu/resources/payment_links"
 require_relative "zazu/resources/transfer_drafts"
 require_relative "zazu/resources/webhook_endpoints"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zazu-ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Zazu
@@ -74,10 +74,12 @@ files:
 - lib/zazu/resources/customers.rb
 - lib/zazu/resources/entity.rb
 - lib/zazu/resources/invoices.rb
+- lib/zazu/resources/payee_trust_requests.rb
 - lib/zazu/resources/payment_links.rb
 - lib/zazu/resources/transfer_drafts.rb
 - lib/zazu/resources/webhook_endpoints.rb
 - lib/zazu/response.rb
+- lib/zazu/transfer_authorization.rb
 - lib/zazu/version.rb
 homepage: https://github.com/getzazu/zazu-ruby
 licenses: