wompi-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: eccdc54723ba105e0a434ba266a7fd26ad1e7d9c6bbbe12b77ceb76b19280947
+  data.tar.gz: 0d61f01183970ac8c726f2e8772245bf181957340a3664c87a57ad6a1ea29e13
+SHA512:
+  metadata.gz: 1c6b67a6ae65f0be6c5942d47e9cd565d954343554a7b09ec1a52f3a8100b5d42fda05f4f3ff28927b4bc368078b303c22c2f787ae83a15e6dd57bf655c480c9
+  data.tar.gz: 6c618486813eedec788180b329aa7984d07905ed9e07c3dc3e74a91940f2700f94039715e1ecae049955217ee9ec83fd4c6bc7c13969ca17eae68dde78cccbd6

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-12-26
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 wjorellano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,178 @@
+# Wompi::Ruby
+
+Una gema de Ruby de **alto nivel** diseñada para integrar la pasarela de pagos **Wompi Colombia** de forma sencilla. Esta gema abstrae la complejidad técnica de la API, encargándose automáticamente de la **firma de integridad**, el manejo de entornos y la tokenización.
+
+## Características
+
+* ✅ **Firma de Integridad Automática**: Generación de hash SHA-256 para transacciones seguras.
+* ✅ **Multimedio de Pago**: Soporte completo para Tarjetas, PSE y Nequi.
+* ✅ **Links de Pago**: Creación y gestión de URLs de cobro con parámetros de seguridad.
+* ✅ **Gestión de Transacciones**: Consulta de estados individuales y listado histórico con paginación inteligente.
+* ✅ **Seguridad**: Manejo diferenciado de llaves públicas y privadas según los requisitos de cada endpoint.
+
+---
+
+## Instalación
+
+Instala la gema y añádela a tu Gemfile ejecutando:
+
+```bash
+gem 'wompi-ruby'
+```
+
+Configuración
+Configura tus credenciales en un inicializador (ej. config/initializers/wompi.rb en Rails):
+
+```ruby
+Wompi.configure do |config|
+  config.public_key  = 'pub_test_XXXXX'
+  config.private_key = 'prv_test_XXXXX'
+  config.environment = :sandbox # O :production
+end
+```
+
+## Uso
+1. Requisito Legal: Token de Aceptación
+Wompi requiere que el usuario acepte términos y condiciones. Debes obtener este token antes de procesar cualquier transacción
+
+```ruby
+merchant = Wompi::Merchant.info
+acceptance_token = merchant.dig('data', 'presigned_acceptance', 'acceptance_token')
+```
+2. Pagos con Tarjeta de Crédito
+```ruby
+# 1. Tokenizar la tarjeta (Requiere Llave Pública)
+token_res = Wompi::Token.create_card(
+  number: "4242424242424242",
+  cvc: "789",
+  exp_month: "12",
+  exp_year: "30",
+  card_holder: "juan perz"
+)
+card_token = token_res.dig('data', 'id')
+
+# 2. Crear transacción (Maneja firma SHA-256 automáticamente)
+transaction = Wompi::Transaction.create(
+  amount_in_cents: 3000000, # $30.000 COP
+  currency: "COP",
+  reference: "REF_#{Time.now.to_i}",
+  customer_email: "usuario@ejemplo.com",
+  payment_method: {
+    type: "CARD",
+    token: card_token,
+    installments: 1
+  },
+  acceptance_token: acceptance_token,
+)
+```
+
+3. Pagos con PSE (Transferencia Bancaria)
+```ruby
+# 1. Listar bancos disponibles
+banks = Wompi::Pse.financial_institutions
+
+# 2. Crear transacción
+res = Wompi::Transaction.create(
+  amount_in_cents: 5000000,
+  currency: "COP",
+  reference: "PSE_#{Time.now.to_i}",
+  customer_email: "cliente@correo.com",
+  payment_method: {
+    type: "PSE",
+    financial_institution_code: "1022", # Código del banco obtenido del listado
+    user_type: 0, # 0: Persona, 1: Empresa
+    user_legal_id_type: "CC",
+    user_legal_id: "12345678",
+    payment_description: "Pago de suscripción"
+  },
+  redirect_url: "https://tu-tienda.com/pago/resultado",
+  acceptance_token: acceptance_token,
+)
+
+# El usuario debe ser redirigido a la URL del banco:
+url_pago = res.dig('data', 'payment_method', 'extra', 'async_payment_url')
+```
+
+4. Pagos con Nequi
+```ruby
+# 1. Tokenizar número celular (Llave Pública)
+nequi_token = Wompi::Token.create_nequi("3004444444").dig('data', 'id')
+
+# 2. Crear transacción
+res = Wompi::Transaction.create(
+  amount_in_cents: 2500000,
+  currency: "COP",
+  reference: "NEQUI_#{Time.now.to_i}",
+  customer_email: "usuario@ejemplo.com",
+  payment_method: {
+    type: "NEQUI",
+    token: nequi_token,
+    phone_number: "3004444444"
+  },
+  acceptance_token: acceptance_token,
+)
+# El usuario recibirá una notificación PUSH en su app Nequi para aprobar el pago.
+```
+
+5. Links de Pago
+Genera una URL compartible para tus clientes sin necesidad de un checkout propio:
+```ruby
+link = Wompi::PaymentLink.create(
+  name: "Producto Digital",
+  amount_in_cents: 5000000,
+  currency: "COP",
+  single_use: true,
+  collect_shipping: false,
+  reference: "LNK_#{Time.now.to_i}",
+)
+puts "URL de Cobro: [https://checkout.wompi.co/l/#](https://checkout.wompi.co/l/#){link.dig('data', 'id')}"
+```
+
+6. Historial de Transacciones
+La gema maneja la paginación y filtros obligatorios automáticamente:
+```ruby
+# Obtener transacciones de los últimos 30 días (Valores por defecto)
+history = Wompi::Transaction.all
+
+# Búsqueda con filtros y rango extendido
+history = Wompi::Transaction.all(
+  from_date: "2025-01-01T00:00:00",
+  until_date: "2025-12-31T23:59:59",
+  page_size: 50
+)
+```
+
+Manejo de Errores
+La gema utiliza excepciones específicas para ayudarte a identificar problemas rápidamente:
+```ruby
+begin
+  # Operación de Wompi
+rescue Wompi::InvalidRequestError => e
+  # Error 422: Parámetros inválidos o error de validación de la API
+  puts "Errores detectados: #{e.messages}"
+rescue Wompi::NotFoundError => e
+  # Error 404: No se encontró el recurso (ID inexistente)
+  puts "No encontrado: #{e.message}"
+rescue Wompi::ApiError => e
+  # Otros errores de la API (500, 401, etc.)
+  puts "Error del servidor: #{e.message}"
+end
+```
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/wjorellano/wompi-ruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/wompi/client.rb

@@ -0,0 +1,37 @@
+require 'faraday'
+require 'json'
+
+module Wompi
+  class Client
+    def initialize(config = Wompi.configuration)
+      @config = config
+    end
+
+    def connection
+      Faraday.new(url: @config.base_url) do |f|
+        f.request :json
+        f.response :json
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def call(method, path, params = {}, auth_type: :private)
+      key = auth_type == :private ? @config.private_key : @config.public_key
+      response = connection.send(method, path, params) do |req|
+        req.headers['Authorization'] = "Bearer #{key}"
+      end
+      handle_response(response)
+    end
+
+    private
+
+    def handle_response(response)
+      case response.status
+      when 200, 201 then response.body
+      when 404 then raise NotFoundError, response.body.dig('error', 'reason')
+      when 422 then raise InvalidRequestError, response.body.dig('error', 'messages')
+      else raise ApiError, "Error: #{response.status}"
+      end
+    end
+  end
+end

data/lib/wompi/configuration.rb

@@ -0,0 +1,13 @@
+module Wompi
+  class Configuration
+    attr_accessor :public_key, :private_key, :integrity_secret, :environment
+
+    def initialize
+      @environment = :sandbox
+    end
+
+    def base_url
+      @environment == :production ? "https://production.wompi.co/v1" : "https://sandbox.wompi.co/v1"
+    end
+  end
+end

data/lib/wompi/error.rb

@@ -0,0 +1,16 @@
+module Wompi
+  class Error < StandardError; end
+  class ApiError < Error; end
+
+  # Error 404: "La entidad solicitada no existe"
+  class NotFoundError < Error; end
+
+  # Error 422: Validaciones de entrada fallidas
+  class InvalidRequestError < Error
+    attr_reader :messages
+    def initialize(messages)
+      @messages = messages
+      super("Errores de validación: #{messages}")
+    end
+  end
+end

data/lib/wompi/resource.rb

@@ -0,0 +1,11 @@
+module Wompi
+  class Resource
+    def self.get(path, params = {}, auth_type: :private)
+      Client.new.call(:get, path, params, auth_type: auth_type)
+    end
+
+    def self.post(path, params = {}, auth_type: :private)
+      Client.new.call(:post, path, params, auth_type: auth_type)
+    end
+  end
+end

data/lib/wompi/resources/merchant.rb

@@ -0,0 +1,7 @@
+module Wompi
+  class Merchant < Resource
+    def self.info
+      get("merchants/#{Wompi.configuration.public_key}", {}, auth_type: :public)
+    end
+  end
+end

data/lib/wompi/resources/payment_link.rb

@@ -0,0 +1,18 @@
+module Wompi
+  class PaymentLink < Resource
+    def self.create(params = {})
+      secret = params.delete(:integrity_secret) || Wompi.configuration.integrity_secret
+
+      if secret
+        params[:signature] = Security::Signature.generate(
+          params[:reference],
+          params[:amount_in_cents],
+          params[:currency],
+          secret
+        )
+      end
+
+      post("payment_links", params, auth_type: :private)
+    end
+  end
+end

data/lib/wompi/resources/pse.rb

@@ -0,0 +1,7 @@
+module Wompi
+  class Pse < Resource
+    def self.financial_institutions
+      get("pse/financial_institutions", {}, auth_type: :public)
+    end
+  end
+end

data/lib/wompi/resources/token.rb

@@ -0,0 +1,15 @@
+module Wompi
+  class Token < Resource
+    def self.create_card(params = {})
+      post("tokens/cards", params, auth_type: :public)
+    end
+
+    def self.create_nequi(phone_number)
+      post("tokens/nequi", { phone_number: phone_number }, auth_type: :public)
+    end
+
+    def self.check_nequi_status(token_id)
+      get("tokens/nequi/#{token_id}", {}, auth_type: :public)
+    end
+  end
+end

data/lib/wompi/resources/transaction.rb

@@ -0,0 +1,55 @@
+require 'date'
+
+module Wompi
+  class Transaction < Resource
+    def self.create(params = {})
+      secret = params.delete(:integrity_secret) || Wompi.configuration.integrity_secret
+
+      if secret
+        params[:signature] = Security::Signature.generate(
+          params[:reference],
+          params[:amount_in_cents],
+          params[:currency],
+          secret
+        )
+      end
+
+      post("transactions", params, auth_type: :private)
+    end
+
+    def self.void(id, params = {})
+      post("transactions/#{id}/void", params, auth_type: :private)
+    end
+
+    def self.find(id)
+      get("transactions/#{id}", {}, auth_type: :private)
+    end
+
+    def self.all(params = {})
+      now = DateTime.now
+      defaults = {
+        from_date: (now - 30).strftime('%Y-%m-%dT%H:%M:%S'),
+        until_date: now.strftime('%Y-%m-%dT%H:%M:%S'),
+        page: 1,
+        page_size: 20
+      }
+      get("transactions", defaults.merge(params), auth_type: :private)
+    end
+
+    def self.all_pages(params = {})
+      all_records = []
+      current_page = 1
+
+      loop do
+        response = all(params.merge(page: current_page))
+        records = response['data']
+        break if records.empty?
+
+        all_records.concat(records)
+        current_page += 1
+      end
+
+      all_records
+    end
+  end
+end

data/lib/wompi/security/signature.rb

@@ -0,0 +1,12 @@
+require 'digest'
+
+module Wompi
+  module Security
+    class Signature
+      def self.generate(reference, amount_in_cents, currency, secret)
+        raw_string = "#{reference}#{amount_in_cents}#{currency}#{secret}"
+        Digest::SHA256.hexdigest(raw_string)
+      end
+    end
+  end
+end

data/lib/wompi/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Wompi
+  module Ruby
+    VERSION = "0.1.0"
+  end
+end

data/lib/wompi-ruby.rb

@@ -0,0 +1,22 @@
+require_relative "wompi/version"
+require_relative "wompi/configuration"
+require_relative "wompi/error"
+require_relative "wompi/client"
+require_relative "wompi/resource"
+require_relative "wompi/security/signature"
+require_relative "wompi/resources/token"
+require_relative "wompi/resources/transaction"
+require_relative "wompi/resources/merchant"
+require_relative "wompi/resources/pse"
+require_relative "wompi/resources/payment_link"
+
+module Wompi
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configure
+    self.configuration ||= Configuration.new
+    yield(configuration)
+  end
+end

data/sig/wompi/ruby.rbs

@@ -0,0 +1,6 @@
+module Wompi
+  module Ruby
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: wompi-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- wjorellano
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: A lightweight Ruby library to integrate Wompi payments, supporting PSE,
+  Credit Cards, Nequi, and Payment Links.
+email:
+- wilmanjunior2001@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/wompi-ruby.rb
+- lib/wompi/client.rb
+- lib/wompi/configuration.rb
+- lib/wompi/error.rb
+- lib/wompi/resource.rb
+- lib/wompi/resources/merchant.rb
+- lib/wompi/resources/payment_link.rb
+- lib/wompi/resources/pse.rb
+- lib/wompi/resources/token.rb
+- lib/wompi/resources/transaction.rb
+- lib/wompi/security/signature.rb
+- lib/wompi/version.rb
+- sig/wompi/ruby.rbs
+homepage: https://github.com/wjorellano/wompi-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/wjorellano/wompi-ruby
+  source_code_uri: https://github.com/wjorellano/wompi-ruby
+  changelog_uri: https://github.com/wjorellano/wompi-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/wjorellano/wompi-ruby/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Ruby SDK for Wompi Payment Gateway integration.
+test_files: []