ruby-eupago 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43a13811487c270301ef4dc2e07cdd5036c11de8981e821ba119017c14ce6a23
-  data.tar.gz: 72307c343896aa908f4d25757a5764d5aaee1bc08d43c480b8b4a628e0e871fd
+  metadata.gz: 8dc8afa36b112dced935208f0172bc416c2f028266463770498c97aa2cf82458
+  data.tar.gz: 3bf972bdc874d59c93d732b172509bc477f33fa64139c3385bb2a64a284d0c12
 SHA512:
-  metadata.gz: 1393f9d679601c196e3b104fcaf17f27f4830a6b71d849e5a8279561af9d4d5879c7d34c2b3ea3c2142be9b674548b10c294591491e978edbc5cf3d0025568fe
-  data.tar.gz: 558528c12d48b575a6447c4835f1dccdf6f0f680574b0675bf85e52afb6f5527bb895043c18485855a808a816b79c2a669ce4cfc0834ddac8e1de3d4d688baf9
+  metadata.gz: a77c60d2b49067ce1aa5cf1b56f26c9b260a12188e380d5b592796d8fb0263054707d6e4a0185348e8ecab12187739e25657cc2a2de7c245e0fb154137456679
+  data.tar.gz: 431dcaee318d4b3d618c72cce44c2409e277d21712f701004fb25d22d034e82b8f9f048612131251e8e3918ddf62f355fbe3ee77eec90c2c202233ecdb764552

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [v0.1.0] - 2025-09-15
+
+### Added
+- MBWay payment support
+- Credit card recurrent payments
+- Direct debit payments

data/README.md

@@ -4,7 +4,53 @@ This is a not official Ruby SDK for the EuPago payment gateway.
 
 ## Installation
 
-WIP
+```ruby
+gem 'ruby-eupago', '~> 0.2.0'
+```
+
+## Usage
+
+First, set your credentials as environment variables:
+
+```bash
+export EUPAGO_CLIENT_ID=your_client_id
+export EUPAGO_CLIENT_SECRET=your_client_secret
+export EUPAGO_API_KEY=your_api_key
+```
+
+Then, in your Ruby code:
+
+```ruby
+require 'ruby-eupago'
+
+# Example: Create a direct debit authorization
+response = EuPago::Api::V1::DirectDebit.authorization({
+	"debtor" => {
+		"name" => "John Doe",
+		"iban" => "PT50123443211234567890172",
+		"email" => "john@example.com",
+		"address" => {
+			"zipCode" => "1234-5678",
+			"country" => "PT",
+			"street" => "Rua das coisas",
+			"locality" => "Lisboa"
+		},
+		"bic" => "CGDIPTPL"
+	},
+	"payment" => {
+		"autoProcess" => "0",
+		"type" => EuPago::Constants::PAYMENT_TYPES[:recurring],
+		"date" => "2025-09-15",
+		"amount" => 20,
+		"periodicity" => EuPago::Constants::RECURRENT_PAYMENT_INTERVALS[:monthly]
+	},
+	"identifier" => "Test Direct Debit Subscription"
+})
+
+puts response
+```
+
+For more advanced usage, see the `spec/` directory for real-world examples.
 
 ## Testing
 

data/lib/ruby-eupago/api/auth.rb

@@ -3,12 +3,26 @@ module EuPago
     module Auth
       # https://eupago.readme.io/reference/generate-bearer-token
       def self.token(body)
-        result = EuPago::Client.new.post("/auth/token", body: body, headers: {
+        result = EuPago::Client.new({ prefix_base_url: "/api" }).post("/auth/token", body: body, headers: {
           "Content-Type" => "application/x-www-form-urlencoded",
         })
         EuPago::Current.auth = result
         result
       end
+
+      def self.ensure_valid_token
+        if EuPago::Current.access_token.nil? || EuPago::Current.token_expired?
+          fetch_client_credentials_token
+        end
+      end
+
+      def self.fetch_client_credentials_token
+        token(
+          grant_type: EuPago::Constants::GRANT_TYPES[:client_credentials],
+          client_id: ENV["EUPAGO_CLIENT_ID"],
+          client_secret: ENV["EUPAGO_CLIENT_SECRET"],
+        )
+      end
     end
   end
 end

data/lib/ruby-eupago/api/v1/credit_card.rb

@@ -3,13 +3,18 @@ module EuPago
     module V1
       class CreditCard
         # https://eupago.readme.io/reference/credit-card-recurrence-authorization
-        def self.subscription(params)
-          V1.client.post("/v1.02/creditcard/subscription", body: params)
+        def self.subscription(body)
+          V1.client.post("/creditcard/subscription", body: body)
         end
 
         # https://eupago.readme.io/reference/credit-card-recurrence-payment
-        def self.payment(recurrent_id, params)
-          V1.client.post("/v1.02/creditcard/payment/#{recurrent_id}", body: params)
+        def self.payment(recurrent_id, body)
+          V1.client.post("/creditcard/payment/#{recurrent_id}", body: body)
+        end
+
+        # https://eupago.readme.io/reference/credit-card
+        def self.create(body)
+          V1.client.post("/creditcard/create", body: body)
         end
       end
     end

data/lib/ruby-eupago/api/v1/direct_debit.rb

@@ -3,13 +3,13 @@ module EuPago
     module V1
       class DirectDebit
         # https://eupago.readme.io/reference/direct-debit-authorization
-        def self.authorization(params)
-          V1.client.post("/v1.02/directdebit/authorization", body: params)
+        def self.authorization(body)
+          V1.client.post("/directdebit/authorization", body: body)
         end
 
         # https://eupago.readme.io/reference/direct-debit-payment
-        def self.payment(reference, params)
-          V1.client.post("/v1.02/directdebit/payment/#{reference}", body: params)
+        def self.payment(reference, body)
+          V1.client.post("/directdebit/payment/#{reference}", body: body)
         end
       end
     end

data/lib/ruby-eupago/api/v1/mbway.rb

@@ -3,8 +3,8 @@ module EuPago
     module V1
       class MBWay
         # https://eupago.readme.io/reference/mbway
-        def self.payment(params)
-          V1.client.post("/v1.02/mbway/create", body: params)
+        def self.payment(body)
+          V1.client.post("/mbway/create", body: body)
         end
       end
     end

data/lib/ruby-eupago/api/v1/payouts.rb

@@ -0,0 +1,27 @@
+module EuPago
+  module Api
+    module V1
+      class Payouts
+        # Fetches payout transactions with optional parameters.
+        #
+        # @param params [Hash] Optional parameters for the request.
+        # @option params [String] :start_date The first date to filter payouts (YYYY-MM-DD).
+        # @option params [String] :end_date The final date to filter payouts (YYYY-MM-DD).
+        #
+        # @docs https://eupago.readme.io/reference/payouts-transactions
+        def self.transactions(params = {})
+          V1.oauth_client.get("/management/v1.02/payouts/transactions", query: params)
+        end
+
+        # Fetches payout transactions by transaction ID (trid).
+        #
+        # @param trid [String] The transaction ID to filter the request.
+        #
+        # @docs https://eupago.readme.io/reference/trid-information
+        def self.transaction_details(trid)
+          V1.oauth_client.get("/management/v1.02/payouts/transactions/#{trid}")
+        end
+      end
+    end
+  end
+end

data/lib/ruby-eupago/api/v1/references.rb

@@ -0,0 +1,53 @@
+module EuPago
+  module Api
+    module V1
+      class References
+        # Fetches references with optional parameters.
+        #
+        # @param params [Hash] Optional parameters for the request.
+        # @option params [String] :identifier Insert the identifier that you want to find on your search.
+        # @option params [String] :reference Insert the reference you want to find in your search.
+        # @option params [String] :start_date Specify the first date you want to search (YYYY-MM-DD). We will provide all references since that date.
+        #
+        # @docs https://eupago.readme.io/reference/advanced-search
+        def self.list(params = {})
+          V1.oauth_client.get("/management/v1.02/references/info", query: params)
+        end
+
+        # Fetches references by status with optional parameters.
+        #
+        # @param params [Hash] Optional parameters for the request.
+        # @option params [String] :status Choose the status to search (EuPago::Constants::REFERENCE_STATUS)
+        # @docs https://eupago.readme.io/reference/references-by-status
+        #
+        def self.list_by_status(params = {})
+          V1.oauth_client.get("/management/v1.02/references", query: params)
+        end
+
+        # Fetches reference information by reference and entity.
+        #
+        # @param body [Hash] Required parameters for the request.
+        # @option body [String] :referencia Reference identifier to search for.
+        # @option body [String] :entidade Entity associated with the reference (Not all services have an entity).
+        #
+        # @return [Hash] Reference information response from the API.
+        #
+        # @docs https://eupago.readme.io/reference/reference-information
+        def self.find(body)
+          V1.body_client.post("/clientes/rest_api/multibanco/info", body: body)
+        end
+
+        # =========
+        # Alias Methods
+        # =========
+
+        # Fetches reference information by reference.
+        # @alias find_by_reference for find method with reference parameter.
+        #
+        def self.find_by_reference(reference, body = {})
+          find(body.merge({ referencia: reference }))
+        end
+      end
+    end
+  end
+end

data/lib/ruby-eupago/api/v1.rb

@@ -4,6 +4,14 @@ module EuPago
       def self.client
         @client ||= EuPago::Api.client
       end
+
+      def self.oauth_client
+        @oauth_client ||= EuPago::Api.oauth_client
+      end
+
+      def self.body_client
+        @body_client ||= EuPago::Api.body_client
+      end
     end
   end
 end
@@ -11,3 +19,5 @@ end
 require "ruby-eupago/api/v1/credit_card"
 require "ruby-eupago/api/v1/mbway"
 require "ruby-eupago/api/v1/direct_debit"
+require "ruby-eupago/api/v1/payouts"
+require "ruby-eupago/api/v1/references"

data/lib/ruby-eupago/api.rb

@@ -1,7 +1,20 @@
 module EuPago
   module Api
+    # EuPago current REST API uses three different types of authentication:
+    #
+    # 1 - ApiKey Auth (API Key sent as an header param)
     def self.client
-      @client ||= EuPago::Client.new({ include_api_key: true })
+      @client ||= EuPago::Client.new({ include_api_key: true, prefix_base_url: "/api/v1.02" })
+    end
+
+    # 2 -OAuth 2.0 (Bearer Token sent as an header param)
+    def self.oauth_client
+      @oauth_client ||= EuPago::OAuthClient.new({ prefix_base_url: "/api" })
+    end
+
+    # 3 - API Key sent as a body param
+    def self.body_client
+      @body_client ||= EuPago::Client.new({ include_api_key: false, include_api_key_in_body: true })
     end
   end
 end

data/lib/ruby-eupago/constants.rb

@@ -19,6 +19,17 @@ module EuPago
       once: "OOFF",
       recurring: "RCUR",
       final: "FNAL",
-    }
+    }.freeze
+
+    REFERENCE_STATUS = {
+      paid: "paga",
+      pending: "pendente",
+      expired: "expirada",
+      error: "erro",
+      canceled: "cancelada",
+      refunded: "reembolsada",
+      returned: "devolvida",
+      archived: "arquivada",
+    }.freeze
   end
 end

data/lib/ruby-eupago/current.rb

@@ -1,17 +1,25 @@
 module EuPago
   module Current
     @auth = {}
+    @token_expires_at = nil
 
     def self.auth=(value)
       @auth = Hash[value.map { |(k, v)| [k.to_sym, v] }]
+      @token_expires_at = Time.now + @auth[:expires_in].to_i if @auth[:expires_in]
     end
 
     def self.access_token
       @auth[:access_token] if @auth && !@auth.empty?
     end
 
+    def self.token_expired?
+      return true if @token_expires_at.nil?
+
+      Time.now >= @token_expires_at
+    end
+
     def self.logged_in?
-      !access_token.nil? && !access_token.empty?
+      !access_token.nil? && !access_token.empty? && !token_expired?
     end
   end
 end

data/lib/ruby-eupago/mixins/initializer.rb

@@ -5,15 +5,16 @@ module EuPago
     module Client
       def initialize(config = {})
         options = Hash[config.map { |(k, v)| [k.to_sym, v] }]
-        @base_url = options[:base_url] || build_base_url
+        @base_url = build_base_url(options.fetch(:prefix_base_url, ""))
         @include_api_key = options.fetch(:include_api_key, false)
+        @include_api_key_in_body = options.fetch(:include_api_key_in_body, false)
       end
 
       def build_base_url(append_base_url = "")
         if ENV["EUPAGO_PRODUCTION"].to_s.empty?
-          "https://sandbox.eupago.pt/api#{append_base_url}"
+          "https://sandbox.eupago.pt#{append_base_url}"
         else
-          "https://clientes.eupago.pt/api#{append_base_url}"
+          "https://clientes.eupago.pt#{append_base_url}"
         end
       end
 
@@ -31,6 +32,7 @@ module EuPago
 
       def post(api_url, body: {}, headers: {})
         kheader = build_headers(headers)
+        body[:chave] = ENV.fetch("EUPAGO_API_KEY", "") if @include_api_key_in_body && body[:chave].nil?
         kbody = kheader["Content-Type"] == "application/json" ? body.to_json : body
 
         result = HTTParty.post(

data/lib/ruby-eupago/oauth_client.rb

@@ -0,0 +1,29 @@
+require "ruby-eupago/mixins/initializer"
+
+module EuPago
+  class OAuthClient
+    include EuPago::Mixins::Client
+
+    def get(api_url, query: {}, headers: {})
+      EuPago::Api::Auth.ensure_valid_token
+      super(api_url, query: query, headers: headers)
+    end
+
+    def post(api_url, body: {}, headers: {})
+      EuPago::Api::Auth.ensure_valid_token
+      super(api_url, body: body, headers: headers)
+    end
+
+    private
+
+    def build_headers(additional_headers = {})
+      headers = super(additional_headers)
+
+      if EuPago::Current.access_token
+        headers["Authorization"] = "Bearer #{EuPago::Current.access_token}"
+      end
+
+      headers
+    end
+  end
+end

data/lib/ruby-eupago/version.rb

@@ -1,7 +1,7 @@
 module EuPago
   module Version
     MAJOR = 0
-    MINOR = 1
+    MINOR = 2
     PATCH = 0
     STRING = "#{MAJOR}.#{MINOR}.#{PATCH}"
   end

data/lib/ruby-eupago.rb

@@ -1,6 +1,7 @@
 require_relative "ruby-eupago/constants"
 require_relative "ruby-eupago/current"
 require_relative "ruby-eupago/client"
+require_relative "ruby-eupago/oauth_client"
 
 require_relative "ruby-eupago/api"
 require_relative "ruby-eupago/api/v1"

data/ruby-eupago.gemspec

@@ -4,8 +4,8 @@ Gem::Specification.new do |spec|
   spec.name = 'ruby-eupago'
   spec.version     = EuPago::Version::STRING
   spec.date        = '2025-09-10'
-  spec.summary     = 'Eupago Ruby SDK'
-  spec.description = 'Eupago Ruby SDK'
+  spec.summary     = 'Unofficial Ruby SDK for EuPago payment gateway.'
+  spec.description = 'A convenient, unofficial Ruby SDK for integrating with the EuPago payment gateway. Includes authentication helpers, VCR-based test suite, and a structure SDK.'
   spec.authors     = ['Alexandro Castro']
   spec.email       = 'alexoliveira7x@gmail.com'
   spec.license = 'MIT'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-eupago
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Alexandro Castro
@@ -136,7 +136,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Eupago Ruby SDK
+description: A convenient, unofficial Ruby SDK for integrating with the EuPago payment
+  gateway. Includes authentication helpers, VCR-based test suite, and a structure
+  SDK.
 email: alexoliveira7x@gmail.com
 executables: []
 extensions: []
@@ -151,10 +153,13 @@ files:
 - lib/ruby-eupago/api/v1/credit_card.rb
 - lib/ruby-eupago/api/v1/direct_debit.rb
 - lib/ruby-eupago/api/v1/mbway.rb
+- lib/ruby-eupago/api/v1/payouts.rb
+- lib/ruby-eupago/api/v1/references.rb
 - lib/ruby-eupago/client.rb
 - lib/ruby-eupago/constants.rb
 - lib/ruby-eupago/current.rb
 - lib/ruby-eupago/mixins/initializer.rb
+- lib/ruby-eupago/oauth_client.rb
 - lib/ruby-eupago/version.rb
 - ruby-eupago.gemspec
 homepage:
@@ -179,5 +184,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Eupago Ruby SDK
+summary: Unofficial Ruby SDK for EuPago payment gateway.
 test_files: []