manza 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23d95fcba1fba943b2dd02913102b71a982ad3548745a5a249245ab2ff120211
-  data.tar.gz: 38790ad40aa6bb4c3183f5114eee891e473bff53cbfcb1b2810b0ce986ba9b7e
+  metadata.gz: 460a7caba9195a45a73b84bbadbd1fdc3476ad4fdf8244e0d554fd451b493b28
+  data.tar.gz: ecabf7b8a26eeb01ff6405821305ad54e9192674f77982df77f3b53437aefeaa
 SHA512:
-  metadata.gz: ee8d889d2ec4437866067a0806ae30d381f4efdb3a6548dd79fa9223dee1c831b890dfef7f5ee0c3068147af6acf4ad23ffaec78967b5f7776c05ceb7e51f299
-  data.tar.gz: 28f2074be599fe6edced2ca521b636797cd066f49d40a0a9e5dc22b8705df6884757763fd51420ee8be13a36d33b54b83f67598ed0f4d6de940843328da873df
+  metadata.gz: b17cb8c504555b47d2c26322880a22c9187396617a1fcfdbda5a4d176e6e4671e5ca4164d528454ba69008ec11841658a42c262a9619219a07b9605dba0e23fc
+  data.tar.gz: c69b5d6f786843c19f815a8eb1b201653b833d90fe4128796f30b7eee81f46df59096df33d0b9c6d04e08e7f00d595b3d837c7bb3677d856ab3e2243ff45509d

data/CHANGELOG.md

@@ -7,6 +7,47 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### Added
+
+- `manza.payments` (`Manza::Resources::Payments`): `create`, `get`,
+  `authorize` and `decline` on the API's canonical paths, `POST
+  /api/payments`, `GET /api/payments/:id`, `POST /api/payments/:id/authorize`
+  and `POST /api/payments/:id/decline`. The API renamed transfer drafts to
+  payments; request and response bodies are unchanged, and so is the
+  `Manza::TransferAuthorization` signature input.
+
+### Deprecated
+
+- `manza.transfer_drafts` and `Manza::Resources::TransferDrafts`. Both keep
+  working for all of 1.x: the accessor returns `manza.payments` and the
+  constant names the same class, so the old name now calls `/api/payments`
+  too. They warn only when Ruby's deprecation warnings are on
+  (`Warning[:deprecated] = true` or `ruby -W:deprecated`). The server keeps
+  `/api/transfer_drafts` as a permanent alias.
+
+### Changed (cassettes)
+
+The nine payment cassettes moved from `transfer_drafts/` to `payments/`
+and match a new URI. An SDK that replays `cassettes-v1.3.0` sends:
+
+| Cassette | Request |
+|---|---|
+| `payments/create` | `POST https://ma.manza.dev/api/payments` |
+| `payments/create_duplicate` | `POST https://ma.manza.dev/api/payments` |
+| `payments/get` | `GET https://ma.manza.dev/api/payments/fixture-transfer-draft-id` |
+| `payments/get_refused` | `GET https://ma.manza.dev/api/payments/fixture-refused-draft-id` |
+| `payments/authorize` | `POST https://ma.manza.dev/api/payments/fixture-authorizable-draft-id/authorize` |
+| `payments/authorize_bad_signature` | `POST https://ma.manza.dev/api/payments/fixture-bad-signature-draft-id/authorize` |
+| `payments/authorize_same_key` | `POST https://ma.manza.dev/api/payments/fixture-authorizable-draft-id/authorize` |
+| `payments/authorize_new_payee` | `POST https://ma.manza.dev/api/payments/fixture-new-payee-draft-id/authorize` |
+| `payments/decline` | `POST https://ma.manza.dev/api/payments/fixture-declinable-draft-id/decline` |
+
+Each was `/api/transfer_drafts…` with the same rest of the path, under
+`transfer_drafts/<name>`. The fixture placeholders keep their names
+(`fixture-transfer-draft-id`, …). Every other cassette was re-recorded with
+the same method, URI and request body as in `cassettes-v1.2.0`, and every
+response keeps its status and the same JSON keys.
+
 ## [1.2.0]
 
 1.1.0 was never published: its changes (the webhook verifier and the

data/README.md

@@ -88,14 +88,15 @@ manza.beneficiaries.create_external_account("01a0...", account_number: "007780..
 manza.payee_trust_requests.create(external_account_ids: ["01a1..."])
 manza.payee_trust_requests.get("01a2...")
 
-manza.transfer_drafts.create(
+manza.payments.create(
   account_id: "019dde7d-...",
   beneficiary_id: "01a0...",
   amount: "2500.00",
   client_reference: "po_1042" # unique per entity; a duplicate raises Manza::ConflictError
 )
-manza.transfer_drafts.get("01a3...")            # authorization: status, refusal_reason
-manza.transfer_drafts.decline("01a3...", authorization_id: "01a4...", reason: "Not ours")
+manza.payments.get("01a3...")  # authorization: status, refusal_reason
+manza.payments.decline("01a3...", authorization_id: "01a4...", reason: "Not ours")
+# manza.transfer_drafts is a deprecated alias of manza.payments (same methods, /api/payments)
 
 manza.transfer_authorizer.get  # status, suspension_reason, limits, daily_authorized_total; NotFoundError: none enrolled
 
@@ -167,7 +168,7 @@ input = Manza::TransferAuthorization.signature_input(
 signature = Manza::TransferAuthorization.sign(secret: signing_secret, signature_input: input)
 
 authorizer = Manza.new(api_key: ENV["MANZA_AUTHORIZER_API_KEY"])
-authorizer.transfer_drafts.authorize(draft["id"], authorization_id: webhook["data"]["authorization"]["id"], signature: signature)
+authorizer.payments.authorize(draft["id"], authorization_id: webhook["data"]["authorization"]["id"], signature: signature)
 ```
 
 A wrong signature raises `Manza::ValidationError` (`type` `invalid_signature`). Five on one challenge send the draft to your in-app approvers; five in a row suspend the authorizer.

data/lib/manza/client.rb

@@ -87,6 +87,10 @@ module Manza
       @payment_links ||= Resources::PaymentLinks.new(self)
     end
 
+    def payments
+      @payments ||= Resources::Payments.new(self)
+    end
+
     def payee_trust_requests
       @payee_trust_requests ||= Resources::PayeeTrustRequests.new(self)
     end
@@ -95,8 +99,12 @@ module Manza
       @transfer_authorizer ||= Resources::TransferAuthorizer.new(self)
     end
 
+    # @deprecated Use {#payments}. Kept for all of 1.x: returns the same
+    #   resource, which calls `/api/payments`. Warns when Ruby's deprecation
+    #   warnings are on (`Warning[:deprecated] = true` or `-W:deprecated`).
     def transfer_drafts
-      @transfer_drafts ||= Resources::TransferDrafts.new(self)
+      warn("[manza] transfer_drafts is deprecated; use payments instead.", category: :deprecated, uplevel: 1)
+      payments
     end
 
     def webhook_endpoints

data/lib/manza/resources/payments.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Manza
+  module Resources
+    # API-initiated transfers, called payments (formerly transfer drafts;
+    # `/api/transfer_drafts` stays a permanent server-side alias). 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.
+    #
+    # A draft's `authorization` says which way it went: `pending` (a
+    # challenge was sent), `authorized`, `declined` (the draft is deleted),
+    # or one of two outcomes that send the draft to the in-app approvers,
+    # each with a `refusal_reason`:
+    #
+    # - `refused`: it did not qualify, at create time (no webhook is sent)
+    #   or again when the challenge was answered: `untrusted_payee`,
+    #   `unrestricted_api_key`, `over_new_payee_limit`,
+    #   `over_transfer_limit`, `over_daily_limit`, `currency_mismatch`,
+    #   `suspended` or `secret_expired`.
+    # - `expired` / `superseded` / `failed`: a challenge was sent and closed
+    #   without an authorize: `expired` (no answer within the hour),
+    #   `stale` (the draft, its payee's bank details or the endpoint changed
+    #   while it was open) or `signature_failed` (five invalid signatures).
+    #   One exception: the in-app approval that finalizes the draft while
+    #   its challenge is open supersedes it (`stale`), and the draft
+    #   executes or is scheduled; the draft's own `status` shows which.
+    #
+    # `authorization` is nil when no authorizer was enrolled.
+    #
+    # With "Approve transfers to new payees" on (enrolment, in the app),
+    # a draft to bank details the entity never trusted is challenged too,
+    # up to the new-payee limit, when the creating key has an IP
+    # allowlist; authorizing it also trusts the payee.
+    class Payments < Base
+      # POST /api/payments
+      #
+      # 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, client_reference (unique per entity, at most 128
+      # characters; a duplicate raises {Manza::ConflictError} whose
+      # `payment_id` names the existing draft).
+      def create(**attributes)
+        http_post("api/payments", body: attributes)
+      end
+
+      # GET /api/payments/:id
+      def get(id)
+        http_get(encode_path("api/payments", id))
+      end
+
+      # POST /api/payments/:id/authorize
+      #
+      # Executes the draft. `authorization_id` comes from the
+      # `payment.authorization_requested` webhook; build `signature` with
+      # {Manza::TransferAuthorization}. Requires the `transfers:authorize`
+      # scope on a key other than the draft's creator (otherwise 403
+      # `same_key_forbidden`), bound to an IP allowlist (otherwise 403
+      # `unrestricted_api_key`). A 409 {Manza::ConflictError} with `type`
+      # `authorization_busy` means a bank-detail edit, trust or trust
+      # revocation on the payee was in flight: retry. A blank signature
+      # raises {Manza::ArgumentError} and is never sent: the API would count
+      # it as a failed attempt. Five invalid signatures fail the challenge.
+      def authorize(id, authorization_id:, signature:)
+        raise Manza::ArgumentError, "signature cannot be blank" if signature.to_s.strip.empty?
+
+        http_post(
+          encode_path("api/payments", id, "authorize"),
+          body: { authorization_id: authorization_id, signature: signature }
+        )
+      end
+
+      # POST /api/payments/:id/decline
+      #
+      # Declines the challenge and deletes the draft. Returns the
+      # authorization (`status: "declined"`, `declined_at`, and a nil
+      # `refusal_reason`).
+      def decline(id, authorization_id:, reason: nil)
+        http_post(
+          encode_path("api/payments", id, "decline"),
+          body: { authorization_id: authorization_id, reason: reason }.compact
+        )
+      end
+    end
+  end
+end

data/lib/manza/resources/transfer_drafts.rb

@@ -2,91 +2,9 @@
 
 module Manza
   module Resources
-    # 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.
-    #
-    # A draft's `authorization` says which way it went: `pending` (a
-    # challenge was sent), `authorized`, `declined` (the draft is deleted),
-    # or one of two outcomes that send the draft to the in-app approvers,
-    # each with a `refusal_reason`:
-    #
-    # - `refused`: it did not qualify, at create time (no webhook is sent)
-    #   or again when the challenge was answered: `untrusted_payee`,
-    #   `unrestricted_api_key`, `over_new_payee_limit`,
-    #   `over_transfer_limit`, `over_daily_limit`, `currency_mismatch`,
-    #   `suspended` or `secret_expired`.
-    # - `expired` / `superseded` / `failed`: a challenge was sent and closed
-    #   without an authorize: `expired` (no answer within the hour),
-    #   `stale` (the draft, its payee's bank details or the endpoint changed
-    #   while it was open) or `signature_failed` (five invalid signatures).
-    #   One exception: the in-app approval that finalizes the draft while
-    #   its challenge is open supersedes it (`stale`), and the draft
-    #   executes or is scheduled; the draft's own `status` shows which.
-    #
-    # `authorization` is nil when no authorizer was enrolled.
-    #
-    # With "Approve transfers to new payees" on (enrolment, in the app),
-    # a draft to bank details the entity never trusted is challenged too,
-    # up to the new-payee limit, when the creating key has an IP
-    # allowlist; authorizing it also trusts the payee.
-    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, client_reference (unique per entity, at most 128
-      # characters; a duplicate raises {Manza::ConflictError} whose
-      # `payment_id` names the existing draft).
-      def create(**attributes)
-        http_post("api/transfer_drafts", body: attributes)
-      end
-
-      # GET /api/transfer_drafts/:id
-      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
-      # {Manza::TransferAuthorization}. Requires the `transfers:authorize`
-      # scope on a key other than the draft's creator (otherwise 403
-      # `same_key_forbidden`), bound to an IP allowlist (otherwise 403
-      # `unrestricted_api_key`). A 409 {Manza::ConflictError} with `type`
-      # `authorization_busy` means a bank-detail edit, trust or trust
-      # revocation on the payee was in flight: retry. A blank signature
-      # raises {Manza::ArgumentError} and is never sent: the API would count
-      # it as a failed attempt. Five invalid signatures fail the challenge.
-      def authorize(id, authorization_id:, signature:)
-        raise Manza::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"`, `declined_at`, and a nil
-      # `refusal_reason`).
-      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
+    # @deprecated Use {Payments} (`manza.payments`). Kept for all of 1.x;
+    #   it is the same class and calls `/api/payments`.
+    TransferDrafts = Payments
+    deprecate_constant :TransferDrafts
   end
 end

data/lib/manza/transfer_authorization.rb

@@ -11,7 +11,7 @@ module Manza
   # 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}:
+  # result to {Resources::Payments#authorize}:
   #
   #   input = Manza::TransferAuthorization.signature_input(
   #     payment_id: draft["id"], nonce: nonce, amount: draft["amount"],
@@ -20,7 +20,7 @@ module Manza
   #     client_reference: draft["client_reference"]
   #   )
   #   signature = Manza::TransferAuthorization.sign(secret: signing_secret, signature_input: input)
-  #   manza.transfer_drafts.authorize(draft["id"], authorization_id: authorization_id, signature: signature)
+  #   manza.payments.authorize(draft["id"], authorization_id: authorization_id, signature: signature)
   module TransferAuthorization
     SIGNATURE_VERSION = "manza.transfer-authorization.v1"
 

data/lib/manza/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Manza
-  VERSION = "1.2.0"
+  VERSION = "1.3.0"
 end

data/lib/manza.rb

@@ -31,6 +31,7 @@ require_relative "manza/resources/entity"
 require_relative "manza/resources/invoices"
 require_relative "manza/resources/payee_trust_requests"
 require_relative "manza/resources/payment_links"
+require_relative "manza/resources/payments"
 require_relative "manza/resources/transfer_authorizer"
 require_relative "manza/resources/transfer_drafts"
 require_relative "manza/resources/webhook_endpoints"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: manza
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Manza
@@ -76,6 +76,7 @@ files:
 - lib/manza/resources/invoices.rb
 - lib/manza/resources/payee_trust_requests.rb
 - lib/manza/resources/payment_links.rb
+- lib/manza/resources/payments.rb
 - lib/manza/resources/transfer_authorizer.rb
 - lib/manza/resources/transfer_drafts.rb
 - lib/manza/resources/webhook_endpoints.rb