lavenda-pay-ruby 0.0.2 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b22bd19fa8ee233967739f90119ba9159e36b5650f69a40ceb1aaf4283886e2
-  data.tar.gz: 90b7d4524c3a098c0f497945b6905e134872070449a308129d6a089ab38d8462
+  metadata.gz: ab9c1f7169f3c8a9139e5ae77fd7d32c611e59b089c2210f81ef2670ae93983d
+  data.tar.gz: 3fd5edcbafd5aaf883942e2b49ca718efadd6c6457d5d42b7f5634609269b310
 SHA512:
-  metadata.gz: 8ed16222d6590470b455d4dfb41657dc70716aee12f530faea840bfeab13b369e0fc2be5516bdbb06c21687f360aee9388495d7597689a6e17b6fdbb12a8bae1
-  data.tar.gz: e535aed1df0e7727729e7dae40dc987ac33bc9ac5a1cfe64e9fdb98965c5810fa35488156102d81aea2aea0efa37d52e1aabe0f09bc084c06ec8ad1f44c2664b
+  metadata.gz: 0e931c2d7c3b80e7c8c62957dcafe58be59331806ecac03e9bf7c5df469ec34832f14516b4af4f7d4d00a7a1fde7117bb7be0ab8bb463b9262b770801ac52f8c
+  data.tar.gz: a019be6f2a156a6e24afe598fafcf10272145d64d555d1cefe05b2a26aefd3f555f0003155aa78f3e9b381051b72cd896e4b0dd21ff1f2dc8f7002e1ea2fe25a

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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.
+
 ## 0.0.2
 
 - Read settings from the `lavenda_pay` Rails credentials when the environment variable is not set.

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"
@@ -88,6 +89,62 @@ LavendaPay::Orders::Find.call(order.pid)
 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`.
+
+```ruby
+# The payment pid comes from the payment outcome webhooks.
+payment = LavendaPay::Payments::Confirm.call("pay_...")
+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/confirm.rb

@@ -0,0 +1,16 @@
+module LavendaPay
+  module Payments
+    # Sandbox only: marks a pending payment as paid, and confirms it on the
+    # gateway when the gateway supports it. Production answers 404 (NotFoundError).
+    #
+    # LavendaPay::Payments::Confirm.call("pay_...") # => LavendaPay::Payment
+    class Confirm < Operation
+      def call(pid)
+        body = http.post("/v1/payments/#{escape(pid)}/confirmation")
+        gateway_confirmation = body.dig("meta", "gateway_confirmation")
+
+        Payment.new((body["payment"] || body).merge("gateway_confirmation" => gateway_confirmation))
+      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

@@ -0,0 +1,7 @@
+module LavendaPay
+  class Payment < Resource
+    # 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.2"
+  VERSION = "0.0.4"
 end

data/lib/lavenda_pay.rb

@@ -5,6 +5,9 @@ require_relative "lavenda_pay/http"
 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"
@@ -13,6 +16,12 @@ require_relative "lavenda_pay/customers/list"
 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.2
+  version: 0.0.4
 platform: ruby
 authors:
 - La Venda Software
@@ -118,9 +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
@@ -151,7 +160,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.13
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Ruby client for the Lavenda Pay payments API.
 test_files: []