lavenda-pay-ruby 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39b5e1f0ee482056108e319e7c1231913d9cc2c34947b884176ee26214df40dd
-  data.tar.gz: 14d74a9dfec2e429cdc6f7f18099384b2d19162a1c3a0eb992f5d3ac3b7f9dfa
+  metadata.gz: ab9c1f7169f3c8a9139e5ae77fd7d32c611e59b089c2210f81ef2670ae93983d
+  data.tar.gz: 3fd5edcbafd5aaf883942e2b49ca718efadd6c6457d5d42b7f5634609269b310
 SHA512:
-  metadata.gz: 4e771c230db541ff2f90b2e1178891a9d4cc341df303e457f8af55a6f80ebc6761a8f3cd9b88385405b0f29b41920c32792bb662daf3b76d73a4b79ec763f4dd
-  data.tar.gz: 2962469cbe01f0bd57645dfb997504f482e678ad7c1b02ba9d44281aaeec63bafc665fde208e218fc2829ae076f5e095d63e2c663936b808afbf518c541e193b
+  metadata.gz: 0e931c2d7c3b80e7c8c62957dcafe58be59331806ecac03e9bf7c5df469ec34832f14516b4af4f7d4d00a7a1fde7117bb7be0ab8bb463b9262b770801ac52f8c
+  data.tar.gz: a019be6f2a156a6e24afe598fafcf10272145d64d555d1cefe05b2a26aefd3f555f0003155aa78f3e9b381051b72cd896e4b0dd21ff1f2dc8f7002e1ea2fe25a

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.0.4
+
+- Add `LavendaPay::PaymentLinks` (`Create`, `Find`, `List`, `End`) and `LavendaPay::PaymentLink`.
+- `LavendaPay::Order` exposes `payment_link_pid`.
+- Add `LavendaPay::Payments::Simulate` to preview the options for an amount, with the card fee passed on to the customer.
+- `LavendaPay::Orders::Create` accepts `max_installment_count`, and `LavendaPay::Order` exposes it.
+- `LavendaPay::Payment` exposes `installment_count`, `surcharge` and `charged_total`.
+
 ## 0.0.3
 
 - Add `LavendaPay::Payments::Confirm` to confirm a pending payment outside production.

data/README.md

@@ -77,7 +77,8 @@ order = LavendaPay::Orders::Create.call(
   eid: "ORD-0123",
   frequency: "once",
   currency: "brl",
-  items_attributes: [{product_title: "Material didático", quantity: 1, unit_price: 450.0}]
+  items_attributes: [{product_title: "Material didático", quantity: 1, unit_price: 450.0}],
+  max_installment_count: 3 # optional: up to how many card installments, 1 to 12, defaults to 12
 )
 order.pid    # => "order_..."
 order.status # => "draft"
@@ -90,6 +91,20 @@ LavendaPay::Url.order_path(order.pid) # => "https://pay.example.com/orders/order
 
 ## Payments
 
+Preview the options for the amount the merchant wants to receive, before redirecting the customer to
+the order's payment page. The card fee is passed on to the customer; Pix passes nothing on, so its
+`fee` and `net_amount` are `nil`, meaning unknown rather than zero. A simulation has no order, so it ignores
+an order's `max_installment_count`, and it binds no price: the customer chooses the installments on the payment page, where the server computes the amount again.
+Card data never goes through the API.
+
+```ruby
+simulation = LavendaPay::Payments::Simulate.call(amount: 100.0)
+simulation.options.map { |o| [o.payment_method_kind, o.installment_count, o.installment_value, o.total] }
+# => [["pix", 1, 100.0, 100.0], ["credit_card", 1, 102.54, 102.54], ["credit_card", 2, 51.27, 102.54], ...]
+
+LavendaPay::Url.order_path(order.pid) # send the customer here to choose and pay
+```
+
 Sandbox only: confirm a pending payment as if the customer had paid it, to test your payment flow
 end to end. LavendaPay marks it as paid and, when the gateway supports it, confirms it there too.
 The endpoint does not exist in production, where it raises `LavendaPay::NotFoundError`.
@@ -101,6 +116,35 @@ payment.status               # => "paid"
 payment.gateway_confirmation # => "confirmed", "failed" or "unsupported"
 ```
 
+## Payment links
+
+A reusable public page: each payer identifies themself there and generates their own order. Omit
+`amount` to let the payer type it. `amount` is the base price: what a payment charges depends on
+the payment method.
+
+```ruby
+payment_link = LavendaPay::PaymentLinks::Create.call(
+  name: "Mentoria",
+  billing_type: "undefined", # "undefined" (Pix and card), "pix" or "credit_card"
+  charge_type: "detached",
+  amount: 150.0,
+  end_date: "2027-12-31",
+  due_date_limit_days: 3,
+  eid: "LINK-0123",
+  success_url: "https://example.com/thanks",
+  auto_redirect: true,
+  requires_billing_address: false
+)
+payment_link.url    # => the public page to share
+payment_link.status # => "active"
+
+LavendaPay::PaymentLinks::Find.call(payment_link.pid)
+LavendaPay::PaymentLinks::List.call(name: "Mentoria", eid: "LINK-0123", page: 1)
+LavendaPay::PaymentLinks::End.call(payment_link.pid) # final; existing orders stay as they are
+```
+
+Orders generated by a link carry its `payment_link_pid`.
+
 ## Errors
 
 Non-2xx responses raise a `LavendaPay::ApiError` subclass exposing `status`, `body` and `errors`:

data/lib/lavenda_pay/orders/create.rb

@@ -3,7 +3,8 @@ module LavendaPay
     # LavendaPay::Orders::Create.call(
     #   customer_pid: "...", payment_method_kinds: ["pix", "credit_card"],
     #   description: "...", eid: "ORD-1", frequency: "once", currency: "brl",
-    #   items_attributes: [{product_title: "...", quantity: 1, unit_price: 450.0}]
+    #   items_attributes: [{product_title: "...", quantity: 1, unit_price: 450.0}],
+    #   max_installment_count: 3 # optional, 1 to 12, defaults to 12
     # ) # => LavendaPay::Order
     class Create < Operation
       def call(params)

data/lib/lavenda_pay/payment_links/create.rb

@@ -0,0 +1,13 @@
+module LavendaPay
+  module PaymentLinks
+    # LavendaPay::PaymentLinks::Create.call(
+    #   name: "Mentoria", billing_type: "undefined", charge_type: "detached", amount: 150.0
+    # ) # => LavendaPay::PaymentLink
+    class Create < Operation
+      def call(params)
+        body = http.post("/v1/payment_links", body: {payment_link: params})
+        PaymentLink.new(body["payment_link"] || body)
+      end
+    end
+  end
+end

data/lib/lavenda_pay/payment_links/end.rb

@@ -0,0 +1,14 @@
+module LavendaPay
+  module PaymentLinks
+    # Final: nobody can pay through the link anymore. Orders and payments it
+    # generated stay as they are.
+    #
+    # LavendaPay::PaymentLinks::End.call("payment_link_...") # => LavendaPay::PaymentLink
+    class End < Operation
+      def call(pid)
+        body = http.post("/v1/payment_links/#{escape(pid)}/ending")
+        PaymentLink.new(body["payment_link"] || body)
+      end
+    end
+  end
+end

data/lib/lavenda_pay/payment_links/find.rb

@@ -0,0 +1,11 @@
+module LavendaPay
+  module PaymentLinks
+    # LavendaPay::PaymentLinks::Find.call("payment_link_...") # => LavendaPay::PaymentLink
+    class Find < Operation
+      def call(pid)
+        body = http.get("/v1/payment_links/#{escape(pid)}")
+        PaymentLink.new(body["payment_link"] || body)
+      end
+    end
+  end
+end

data/lib/lavenda_pay/payment_links/list.rb

@@ -0,0 +1,14 @@
+module LavendaPay
+  module PaymentLinks
+    FILTER_KEYS = %i[name eid].freeze
+
+    # LavendaPay::PaymentLinks::List.call(name: "Mentoria", page: 1)
+    # # => [LavendaPay::PaymentLink, ...]
+    class List < Operation
+      def call(page: nil, **filters)
+        body = http.get("/v1/payment_links", params: {page:}.merge(filters.slice(*FILTER_KEYS)))
+        Array(body["payment_links"]).map { |attributes| PaymentLink.new(attributes) }
+      end
+    end
+  end
+end

data/lib/lavenda_pay/payments/simulate.rb

@@ -0,0 +1,18 @@
+module LavendaPay
+  module Payments
+    # Previews the options for the amount the merchant wants to receive: one per
+    # credit card installment count, with the card fee passed on to the customer,
+    # and one for Pix at the plain amount. It binds no price: the customer chooses
+    # the installments on the order's payment page, where the amount is computed
+    # again.
+    #
+    # LavendaPay::Payments::Simulate.call(amount: 100.0) # => LavendaPay::PaymentSimulation
+    class Simulate < Operation
+      def call(amount:)
+        body = http.post("/v1/payment_simulations", body: {payment_simulation: {amount: amount}})
+
+        PaymentSimulation.new(body["payment_simulation"] || body)
+      end
+    end
+  end
+end

data/lib/lavenda_pay/resources/order.rb

@@ -1,6 +1,7 @@
 module LavendaPay
   class Order < Resource
-    # Attributes: pid, status, expires_at, requires_billing_address, customer.
+    # Attributes: pid, status, expires_at, requires_billing_address,
+    # max_installment_count, payment_link_pid, customer.
     def customer
       value = self["customer"]
       value.is_a?(Hash) ? Customer.new(value) : value

data/lib/lavenda_pay/resources/payment.rb

@@ -1,6 +1,7 @@
 module LavendaPay
   class Payment < Resource
-    # Attributes: pid, status, and gateway_confirmation after a sandbox
+    # Attributes: pid, status, installment_count, surcharge (the fees passed on
+    # to the customer), charged_total, and gateway_confirmation after a sandbox
     # confirmation ("confirmed", "failed" or "unsupported").
   end
 end

data/lib/lavenda_pay/resources/payment_link.rb

@@ -0,0 +1,10 @@
+module LavendaPay
+  class PaymentLink < Resource
+    # Attributes: pid, status, url, name, description, billing_type, charge_type,
+    # amount, end_date, ended_at, due_date_limit_days, eid, success_url,
+    # auto_redirect, requires_billing_address.
+    #
+    # `amount` is the offer's base price, nil when the payer types it. What a
+    # payment charges depends on the payment method.
+  end
+end

data/lib/lavenda_pay/resources/payment_simulation.rb

@@ -0,0 +1,14 @@
+module LavendaPay
+  class PaymentOption < Resource
+    # Attributes: payment_method_kind ("pix" or "credit_card"), installment_count,
+    # installment_value, total, fee, net_amount. On Pix, which passes nothing on,
+    # fee and net_amount are nil: unknown, not zero.
+  end
+
+  class PaymentSimulation < Resource
+    # Attributes: amount, options.
+    def options
+      Array(self["options"]).map { |option| PaymentOption.new(option) }
+    end
+  end
+end

data/lib/lavenda_pay/version.rb

@@ -1,3 +1,3 @@
 module LavendaPay
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

data/lib/lavenda_pay.rb

@@ -6,6 +6,8 @@ require_relative "lavenda_pay/resource"
 require_relative "lavenda_pay/resources/customer"
 require_relative "lavenda_pay/resources/order"
 require_relative "lavenda_pay/resources/payment"
+require_relative "lavenda_pay/resources/payment_link"
+require_relative "lavenda_pay/resources/payment_simulation"
 require_relative "lavenda_pay/client"
 require_relative "lavenda_pay/operation"
 require_relative "lavenda_pay/customers/create"
@@ -15,6 +17,11 @@ require_relative "lavenda_pay/customers/find_by"
 require_relative "lavenda_pay/orders/create"
 require_relative "lavenda_pay/orders/find"
 require_relative "lavenda_pay/payments/confirm"
+require_relative "lavenda_pay/payment_links/create"
+require_relative "lavenda_pay/payment_links/find"
+require_relative "lavenda_pay/payment_links/list"
+require_relative "lavenda_pay/payment_links/end"
+require_relative "lavenda_pay/payments/simulate"
 require_relative "lavenda_pay/url"
 require_relative "lavenda_pay/webhooks"
 require_relative "lavenda_pay/engine" if defined?(Rails::Engine)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lavenda-pay-ruby
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - La Venda Software
@@ -118,11 +118,18 @@ files:
 - lib/lavenda_pay/operation.rb
 - lib/lavenda_pay/orders/create.rb
 - lib/lavenda_pay/orders/find.rb
+- lib/lavenda_pay/payment_links/create.rb
+- lib/lavenda_pay/payment_links/end.rb
+- lib/lavenda_pay/payment_links/find.rb
+- lib/lavenda_pay/payment_links/list.rb
 - lib/lavenda_pay/payments/confirm.rb
+- lib/lavenda_pay/payments/simulate.rb
 - lib/lavenda_pay/resource.rb
 - lib/lavenda_pay/resources/customer.rb
 - lib/lavenda_pay/resources/order.rb
 - lib/lavenda_pay/resources/payment.rb
+- lib/lavenda_pay/resources/payment_link.rb
+- lib/lavenda_pay/resources/payment_simulation.rb
 - lib/lavenda_pay/url.rb
 - lib/lavenda_pay/version.rb
 - lib/lavenda_pay/webhooks.rb
@@ -153,7 +160,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.22
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Ruby client for the Lavenda Pay payments API.
 test_files: []