azul-sdk 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 06b284006deac2dc97f3f2621adba6f610be97d3e753ab02da1570cb9ded95c8
+  data.tar.gz: 92123bef51ec5147e0a4c60f73e48536ccb4dd38ae09d9cd81a48ad3d1c61b1f
+SHA512:
+  metadata.gz: a8d005327eda8ad543667a87d03309a6d8cd6cce73b1206570a03b4d27a23fdb88f2133f5b5247e9663f539c2abdd74826583de3d91b2894e99789eb47ab32b9
+  data.tar.gz: e8d2fa4f154c7c9fd21e7840b722e0fa5954c59df4f9f9c854e5eda2a8c7e699f9123344e3bc1f990513d0bbe1201ce0c1d5ffef6b727d73146befb467aebc34

data/.rubocop.yml

@@ -0,0 +1,40 @@
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  SuggestExtensions: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/Documentation:
+  Enabled: false
+
+Naming/MemoizedInstanceVariableName:
+  Enabled: false
+
+Naming/VariableNumber:
+  Enabled: false
+
+Style/SymbolArray:
+  Enabled: false
+
+Style/WordArray:
+  Enabled: false
+
+Metrics/AbcSize:
+  Max: 25
+
+Layout/ElseAlignment:
+  Enabled: False
+
+Layout/EndAlignment:
+  Enabled: False
+
+Layout/IndentationWidth:
+  Enabled: False
+
+Lint/SymbolConversion:
+  Enabled: false

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Rafael Montas
+
+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,259 @@
+# Azul SDK
+
+Azul SDK provee acceso a la implementación de Webservices Azul.
+
+## Instalación
+
+Para utilizar esta librería puedes correr el siguiente comando:
+
+```bash
+gem install azul-sdk
+```
+
+Si utilizas Bundler, puedes agregar la siguiente línea a tu archivo `Gemfile`:
+
+```ruby
+gem "azul-sdk", require: "azul"
+```
+
+## Requerimientos
+
+- Ruby 3.1 o superior
+
+## Configuración
+
+Esta librería necesita ser configurada con las credenciales facilitadas por Servicions Digitales Azul. Los siguientes parametros son configurables:
+
+
+| Parametro | Tipo | Descripción |
+| --- | --- | --- |
+| merchant_id | `String` | Identificador del comercio. |
+| environment | `String` `Symbol` | Ambiente a utilizar. De este valor dependen los URLs del API a utilizar. <br><br> **Posibles valores: `:development`, `:production`** |
+| auth_1 | `String` | Valor de autenticación enviado en el header del requerimiento. |
+| auth_2 | `String` | Valor de autenticación enviado en el header del requerimiento. |
+| client_certificate | `String` | Certificado del cliente emitido por Azul para la autenticación mutua. |
+| client_key | `String` | Llave privada del Certificate Signing Request (CSR) utilizado para la emisión del certificado. |
+| client_certificate_path | `String` | Ruta del certificado del cliente en el sistema en caso de preferir utilizar el archivo en lugar del valor. |
+| client_key_path | `String` | Ruta de la llave privada del Certificate Signing Request (CSR) en el sistema en caso de preferir utilizar el archivo en lugar del valor. |
+| timeout | `Integer` | Tiempo de espera en segundos para las solicitudes. Este valor establece el tiempo máximo que se esperará en las siguientes configuraciones: `ssl_timeout`, `open_timeout`, `read_timeout`, `write_timeout`. <br><br> **Valor por defecto: `120` (120 segundos)** |
+
+Puedes configurar la librería en un initializer llamado `azul.rb`, por ejemplo, si estas utilizando Rails en `config/initializers/azul.rb`:
+
+```ruby
+require "azul"
+
+Azul.configure do |config|
+  config.merchant_id = ENV.fetch("merchant_id")
+  config.auth_1 = ENV.fetch("auth_1")
+  config.auth_2 = ENV.fetch("auth_2")
+  config.client_certificate = ENV.fetch("client_certificate")
+  config.client_key = ENV.fetch("client_key")
+  config.environment = "development"
+end
+```
+
+### Ambientes
+
+Basado en la configuración del ambiente, la librería utilizará los endpoints y credenciales apropiados para cada caso.
+
+- development: `https://pruebas.azul.com.do/WebServices/JSON/Default.aspx`
+- production: `https://pagos.azul.com.do/WebServices/JSON/Default.aspx`
+
+## Uso
+
+Los métodos definidos en esta librería permiten interactuar con los servicios web de Azul de manera sencilla. A continuación se presentan algunos ejemplos de uso:
+
+### Transacciones de venta
+
+Esta es la transacción principal utilizada para someter una autorización de una tarjeta.
+
+Las ventas realizadas con la transacción “Sale” son capturadas automáticamente para su liquidación, por lo que sólo pueden ser anuladas con una transacción de “Void” en un lapso de no más de 20 minutos luego de recibir respuesta de aprobación (ver Método ProcessVoid).
+
+Luego de transcurridos estos 20 minutos, la transacción será liquidada y se debe realizar una transacción de “Refund” o devolución para devolver los fondos a la tarjeta.
+
+```ruby
+response = Azul::Payment.sale({
+  card_number: "411111******1111",
+  expiration: "202812",
+  cvc: "123",
+  amount: 100000,
+  itbis: 18000,
+})
+```
+
+### Transacciones de preautorización (hold)
+
+Se puede separar la autorización del posteo o captura en dos mensajes distintos:
+
+- Hold: pre-autorización y reserva de los fondos en la tarjeta del cliente.
+- Post: se hace la captura o el “posteo” de la transacción.
+
+```ruby
+response = Azul::Payment.hold({
+  card_number: "411111******1111",
+  expiration: "202812",
+  cvc: "123",
+  amount: 100000,
+  itbis: 18000,
+})
+```
+
+### Transacciones de captura (posteo) de una preautorización (hold)
+
+Permita capurar una preautorización (hold) previamente realizada para su liquidación. 
+
+```ruby
+response = Azul::Payment.capture({
+  azul_order_id: "44772511",
+  amount: 100000,
+  itbis: 18000,
+})
+```
+
+### Transacciones para anular ventas, capturas (posteo) o preautorizaciones (hold)
+
+Las transacciones de venta o post se pueden anular antes de los 20 minutos de haber recibido la respuesta de aprobación. Las transacciones de hold que no han sido posteadas no tienen límite de tiempo para anularse.
+
+```ruby
+response = Azul::Payment.void({ azul_order_id: "44772511" })
+```
+
+### Transacciones de devolución (refund)
+
+La devolución (refund) permite reembolsarle los fondos a una tarjeta luego de haberse
+liquidado la transacción.
+
+Para poder realizar una devolución se debe haber procesado exitosamente una transacción de venta o captura y se deben utilizar los datos de la transacción original para enviar la devolución.
+
+- El monto a devolver puede ser el mismo o menor.
+- Se permite hacer una devolución, múltiples devoluciones o devoluciones parciales para cada transacción realizada.
+
+```ruby
+response = Azul::Refund.create({
+  azul_order_id: "44772511",
+  amount: 100000,
+  itbis: 18000,
+})
+```
+
+### Verificación de transacciones (verify)
+
+Este método permite verificar la respuesta enviada por el webservice de una transacción anterior, identificada por el campo `custom_order_id`.
+
+```ruby
+response = Azul::Transaction.verify({ custom_order_id: "123456789" })
+```
+
+### Consulta de transacciones (search)
+
+Este método permite extraer los detalles de una o varias transacciones anteriormente procesadas de un rango de fechas previamente establecido.
+
+```ruby
+response = Azul::Transaction.search({
+  date_from: "2025-08-01",
+  date_to: "2025-08-31"
+})
+```
+
+### Objeto de respuesta y atributos (response)
+
+Todos estos métodos devuelven una instancia [`Azul::Response`](lib/azul/response.rb) que representa la respuesta del API y contiene información sobre la transacción procesada.
+
+Se puede utilizar `accessors` para leer los atributos de la respuesta de manera sencilla. Si el atributo no existe, retornará `nil`.
+
+```ruby
+
+response = Azul::Payment.sale({
+  card_number: "411111******1111",
+  expiration: "202812",
+  cvc: "123",
+  amount: 100000,
+  itbis: 18000,
+  custom_order_id: "xyz11001"
+})
+
+puts response.azul_order_id # "44772544"
+puts response.response_code # "ISO8583"
+puts response.response_message # "APROBADA"
+puts response.raw_response # <Net::HTTPOK:0x0000ffff603cc458>
+puts response.body
+
+# {
+#   "AuthorizationCode"=>"OK2930",
+#   "AzulOrderId"=>"44772544",
+#   "CountryCode"=>"SGP",
+#   "CustomOrderId"=>"xyz11001",
+#   "DateTime"=>"20250808155452",
+#   "ErrorDescription"=>"",
+#   "IsoCode"=>"00",
+#   "LotNumber"=>"",
+#   "RRN"=>"2025080815545644772544",
+#   "ResponseCode"=>"ISO8583",
+#   "ResponseCodeThreeDS"=>"4",
+#   "ResponseMessage"=>"APROBADA",
+#   "Ticket"=>"1"
+# }
+```
+
+### Objeto de requerimiento (request)
+
+A través del objeto de respuesta `response.request` se puede acceder a los datos enviados en la solicitud original para su revisión.
+
+El objeto de requerimiento (request) contiene las siguientes propiedades:
+
+| Nombre | Tipo | Descripción | Ejemplo |
+| --- | --- | --- | --- |
+| api_url | `String` | URL del API al que se envió la solicitud. |
+| headers | `Hash` | Encabezados HTTP enviados en la solicitud. |
+| method | `Symbol` | Método HTTP utilizado en la solicitud. |
+| params | `Hash` | Parámetros enviados en la solicitud. |
+| payment_method_metadata | `Hash` | Metadatos del método de pago utilizado. |
+
+```ruby
+puts response.request.api_url
+# https://pruebas.azul.com.do/WebServices/JSON/Default.aspx
+
+puts response.request.headers
+# { "Content-Type": "application/json", "User-Agent"=>"Ruby" }, "Auth1"=>"...", "Auth2"=>"..."
+
+puts response.request.method
+# :post
+
+puts response.request.params
+# { "card_number": "4111********1111", "expiration": "[FILTERED]", "cvc": "[FILTERED]", "amount": 100000, "itbis": 18000, "custom_order_id": "xyz11001" }
+
+puts response.request.payment_method_metadata
+# {:last4=>"0117", :brand=>"Visa", :exp_month=>"12", :exp_year=>"2028"}
+```
+
+### Requerimientos exitosos
+
+Para considerar una respuesta como exitosa, se considera que el atributo `iso_code` debe ser igual a `"00"`, `"3D"` o `"3D2METHOD"` o que el attributo `response_message` sea igual a `"APROBADA"`.
+
+En el caso de consultas de transacciones (search), se considera exitosa si el attributo `response_code` es igual a `"SEARCHED"`.
+
+### Errores (Errors)
+
+Cuando el API retorna un error o el atributo `iso_code` no es considerado exitoso, se lanza una excepción basada en los valores retornados en los campos `iso_code` y `error_description`.
+
+| Códigos de error | Descripción | Clase de Excepción |
+| --- | --- | --- |
+| "03", "04", "05", "07", "12", "13", "14", "41", "43", "46", "51", "54", "57", "59", "61", "62", "63", "82", "83", "91" | Códigos de respuesta del banco emisor o procesador | [`Azul::DeclineError`](lib/azul/errors.rb) |
+| "99" | Error de procesamiento | [`Azul::ProcessingError`](lib/azul/errors.rb) |
+| "08", "3D" | Error de autenticación | [`Azul::AuthenticationError`](lib/azul/errors.rb) |
+| "" | Error sin `iso_code` | [`Azul::ApiError`](lib/azul/errors.rb) |
+
+```ruby
+begin
+  response = Azul::Payment.sale({
+    card_number: "411111******1111",
+    expiration: "202812",
+    amount: 100000,
+    itbis: 18000,
+  })
+rescue Azul::ApiError => e
+  puts e.message # "Azul API Error: VALIDATION_ERROR:CVC - "
+  puts e.response.body # Azul API response parsed from JSON
+end
+```
+

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: :rubocop

data/lib/azul/configuration.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Azul
+  class Configuration
+    attr_writer :merchant_id, :environment, :auth_1, :auth_2, :client_certificate, :client_key
+    attr_accessor :timeout, :client_certificate_path, :client_key_path
+
+    def initialize
+      @merchant_id = nil
+      @environment = nil
+      @auth_1 = nil
+      @auth_2 = nil
+      @client_certificate = nil
+      @client_key = nil
+      @client_certificate_path = nil
+      @client_key_path = nil
+      @timeout = 120
+    end
+
+    def merchant_id
+      return @merchant_id if @merchant_id
+
+      error_message = "Azul merchant id es requerido!"
+      raise ConfigurationError, error_message
+    end
+
+    def environment
+      if [:production, :development].include?(@environment&.to_sym)
+        @environment&.to_sym
+      else
+        error_message = "Azul environment (:production or :development) es requerido!"
+        raise ConfigurationError, error_message
+      end
+    end
+
+    def auth_1
+      return @auth_1 if @auth_1
+
+      error_message = "Azul Auth1 es requerido!"
+      raise ConfigurationError, error_message
+    end
+
+    def auth_2
+      return @auth_2 if @auth_2
+
+      error_message = "Azul Auth2 es requerido!"
+      raise ConfigurationError, error_message
+    end
+
+    def client_certificate
+      if @client_certificate_path && File.exist?(@client_certificate_path)
+        File.read(@client_certificate_path)
+      elsif @client_certificate
+        @client_certificate
+      else
+        error_message = "Azul client certificate es requerido para autenticación mTLS!"
+        raise ConfigurationError, error_message
+      end
+    end
+
+    def client_key
+      if @client_key_path && File.exist?(@client_key_path)
+        File.read(@client_key_path)
+      elsif @client_key
+        @client_key
+      else
+        error_message = "Azul client key es requerido para autenticación mTLS!"
+        raise ConfigurationError, error_message
+      end
+    end
+  end
+end

data/lib/azul/errors.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Azul
+  module Errors
+    class ConfigurationError < StandardError; end
+
+    class ApiError < StandardError
+      attr_reader :response
+
+      def initialize(response)
+        @response = response
+        super(build_error_message(response))
+      end
+
+      private
+
+      def build_error_message(response)
+        "Azul API Error: #{response.error_description} - #{response.response_message}"
+      end
+    end
+
+    class DeclineError < ApiError; end
+    class ProcessingError < ApiError; end
+    class AuthenticationError < ApiError; end
+
+    class Error < StandardError
+      DECLINE_CODES = %w[03 04 05 07 12 13 14 41 43 46 51 54 57 59 61 62 63 82 83 91].freeze
+      PROCESSING_CODES = %w[99].freeze
+      AUTH_CODES = %w[08 3D].freeze
+
+      def self.from_response(response)
+        case response.iso_code
+        when *DECLINE_CODES
+          DeclineError.new(response)
+        when *PROCESSING_CODES
+          ProcessingError.new(response)
+        when *AUTH_CODES
+          AuthenticationError.new(response)
+        else
+          ApiError.new(response)
+        end
+      end
+    end
+  end
+
+  ConfigurationError = Errors::ConfigurationError
+  ApiError = Errors::ApiError
+  DeclineError = Errors::DeclineError
+  ProcessingError = Errors::ProcessingError
+  AuthenticationError = Errors::AuthenticationError
+  Error = Errors::Error
+end

data/lib/azul/http_client.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Azul
+  class HttpClient
+    def initialize
+      @config = Azul.configuration
+      @url_builder = UrlBuilder.new(@config.environment)
+    end
+
+    def post(params = {}, action: nil)
+      required_params = { "Channel": "EC", "PosInputMode": "E-Commerce", "Store": @config.merchant_id }
+      api_url = @url_builder.build(action: action)
+
+      perform_request(:post, api_url, params.merge(required_params))
+    end
+
+    private
+
+    def perform_request(method, api_url, params)
+      uri = URI(api_url)
+      http = create_http_client(uri)
+      net_request = build_net_request(method, uri, params)
+
+      request = build_request_object(method, api_url, net_request, params)
+      response = http.request(net_request)
+
+      Response.new(response, request)
+    end
+
+    def create_http_client(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.ssl_timeout = @config.timeout
+      http.open_timeout = @config.timeout
+      http.read_timeout = @config.timeout
+      http.write_timeout = @config.timeout
+
+      # Configure SSL
+      http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+      http.cert = OpenSSL::X509::Certificate.new(@config.client_certificate)
+      http.key = OpenSSL::PKey::RSA.new(@config.client_key)
+
+      http
+    end
+
+    def build_net_request(method, uri, params)
+      case method
+      when :get
+        Net::HTTP::Get.new(uri.request_uri)
+      when :post
+        req = Net::HTTP::Post.new(uri.request_uri)
+        req.body = params.to_json
+        req
+      end.tap { |req| add_headers(req) }
+    end
+
+    def add_headers(request)
+      request["Auth1"] = @config.auth_1
+      request["Auth2"] = @config.auth_2
+      request["Content-Type"] = "application/json"
+    end
+
+    def build_request_object(method, api_url, net_request, params)
+      headers = {}
+      net_request.each_header { |k, v| headers[k] = v }
+      Request.new(method, api_url, headers, params)
+    end
+  end
+end

data/lib/azul/request.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Azul
+  class Request
+    attr_reader :method, :api_url, :headers, :params, :payment_method_metadata
+
+    def initialize(method, api_url, headers, params)
+      @method = method
+      @api_url = api_url
+      @headers = headers
+
+      # Extract payment method details before filtering
+      @payment_method_metadata = extract_payment_metadata(params)
+
+      @params = filter_sensitive_params(params)
+    end
+
+    private
+
+    def extract_payment_metadata(params)
+      return {} if params["CardNumber"].blank?
+
+      clean_number = params["CardNumber"].to_s.gsub(/\D/, "")
+
+      {
+        last4: clean_number[-4..],
+        brand: identify_card_brand(clean_number),
+        exp_month: extract_exp_month(params["Expiration"]),
+        exp_year: extract_exp_year(params["Expiration"])
+      }
+    end
+
+    def identify_card_brand(card_number)
+      case card_number
+      when /^4/
+        "Visa"
+      when /^5[1-5]/, /^222[1-9]/, /^22[3-9]/, /^2[3-6]/, /^27[0-1]/, /^2720/
+        "Mastercard"
+      when /^3[47]/
+        "American Express"
+      when /^6011/, /^622126/, /^62212[7-9]/, /^6221[3-9]/, /^622[2-8]/, /^6229[0-1]/, /^62292[0-5]/, /^64[4-9]/, /^65/
+        "Discover"
+      end
+    end
+
+    def extract_exp_month(expiration)
+      return if expiration.blank?
+
+      # Format: YYYYMM
+      expiration.to_s[-2..]
+    end
+
+    def extract_exp_year(expiration)
+      return if expiration.blank?
+
+      # Format: YYYYMM
+      expiration.to_s[0..3]
+    end
+
+    def filter_sensitive_params(params)
+      return params unless params.is_a?(Hash)
+
+      params.each do |key, value|
+        case key
+        when "CardNumber"
+          params[key] = mask_card_number(value) if value.present?
+        when "Expiration", "CVC"
+          params[key] = "[FILTERED]" if value.present?
+        end
+      end
+
+      params
+    end
+
+    def mask_card_number(card_number)
+      return card_number unless card_number.is_a?(String) && card_number.length >= 8
+
+      first_four = card_number[0..3]
+      last_four = card_number[-4..]
+      masked_middle = "*" * (card_number.length - 8)
+
+      "#{first_four}#{masked_middle}#{last_four}"
+    end
+  end
+end

data/lib/azul/resources/base.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Azul
+  module Resources
+    class Base
+      attr_reader :params, :response
+
+      PARAM_MAPPING = {
+        card_number: "CardNumber",
+        expiration: "Expiration",
+        cvc: "CVC",
+        amount: "Amount",
+        itbis: "Itbis",
+        trx_type: "TrxType",
+        order_number: "OrderNumber",
+        customer_service_phone: "CustomerServicePhone",
+        ecommerce_url: "ECommerceURL",
+        custom_order_id: "CustomOrderId",
+        alt_merchant_name: "AltMerchantName",
+        apple_pay: "ApplePay",
+        payment_token: "PaymentToken",
+        cryptogram: "Cryptogram",
+        eci_indicator: "ECIIndicator",
+        google_pay: "GooglePay",
+        data_vault_token: "DataVaultToken",
+        save_to_data_vault: "SaveToDataVault",
+        force_no_3ds: "ForceNo3DS",
+        three_ds_auth: "ThreeDSAuth",
+        term_url: "TermUrl", # Nested in three_ds_auth
+        method_notification_url: "MethodNotificationUrl", # Nested in three_ds_auth
+        requestor_challenge_indicator: "RequestorChallengeIndicator", # Nested in three_ds_auth
+        card_holder_info: "CardHolderInfo",
+        name: "Name", # Nested in card_holder_info
+        email: "Email", # Nested in card_holder_info
+        phone_mobile: "PhoneMobile", # Nested in card_holder_info
+        browser_info: "BrowserInfo",
+        accept_header: "AcceptHeader", # Nested in browser_info
+        ip_address: "IPAddress", # Nested in browser_info
+        user_agent: "UserAgent", # Nested in browser_info
+        language: "Language", # Nested in browser_info
+        color_depth: "ColorDepth", # Nested in browser_info
+        screen_width: "ScreenWidth", # Nested in browser_info
+        screen_height: "ScreenHeight", # Nested in browser_info
+        time_zone: "TimeZone", # Nested in browser_info
+        javascript_enable: "JavaScriptEnable", # Nested in browser_info
+        method_notification_status: "MethodNotificationStatus",
+        cres: "CRes",
+        original_date: "OriginalDate",
+        original_trx_ticket_nr: "OriginalTrxTicketNr",
+        azul_order_id: "AzulOrderId",
+        response_code: "ResponseCode",
+        rrn: "RRN",
+        date_from: "DateFrom",
+        date_to: "DateTo",
+        acquirer_ref_data: "AcquirerRefData"
+      }.freeze
+
+      def initialize(params = {})
+        @params = params
+      end
+
+      def create(action: nil)
+        @http_client ||= HttpClient.new
+        @response = @http_client.post(request_params, action: action)
+
+        if @response.success?
+          @response
+        else
+          error = Error.from_response(@response)
+          raise error
+        end
+      end
+
+      private
+
+      def request_params
+        mapped = map_parameters_to_api_format
+
+        # If data_vault_token is present, add empty card_number and expiration
+        if params[:data_vault_token] || params["data_vault_token"]
+          mapped["CardNumber"] ||= ""
+          mapped["Expiration"] ||= ""
+        end
+
+        mapped
+      end
+
+      def map_parameters_to_api_format
+        params.each_with_object({}) do |(key, value), result|
+          api_param = PARAM_MAPPING[key.to_sym] || to_pascal_case(key.to_s)
+          result[api_param] = value.is_a?(Hash) ? process_nested_params(value) : value
+        end
+      end
+
+      def process_nested_params(hash)
+        result = {}
+
+        hash.each do |key, value|
+          api_param = PARAM_MAPPING[key.to_sym] || to_pascal_case(key.to_s)
+
+          result[api_param] = value.is_a?(Hash) ? process_nested_params(value) : value
+        end
+
+        result
+      end
+
+      def to_pascal_case(string)
+        string.split("_").map(&:capitalize).join
+      end
+    end
+  end
+end

data/lib/azul/resources/payment.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Azul
+  module Resources
+    class Payment < Base
+      def self.sale(params = {})
+        new(params.merge(trx_type: "Sale")).create
+      end
+
+      def self.hold(params = {})
+        new(params.merge(trx_type: "Hold", acquirer_ref_data: "1")).create
+      end
+
+      def self.capture(params = {})
+        new(params).create(action: :post)
+      end
+
+      def self.void(params = {})
+        new(params).create(action: :void)
+      end
+
+      def self.process_threeds_method(params = {})
+        new(params).create(action: :process_threeds_method)
+      end
+
+      def self.process_threeds_challenge(params = {})
+        new(params).create(action: :process_threeds_challenge)
+      end
+    end
+  end
+end

data/lib/azul/resources/refund.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Azul
+  module Resources
+    class Refund < Base
+      def self.create(params = {})
+        new(params.merge(trx_type: "Refund")).create
+      end
+    end
+  end
+end

data/lib/azul/resources/transaction.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Azul
+  module Resources
+    class Transaction < Base
+      def self.search(params = {})
+        new(params).create(action: :search)
+      end
+
+      def self.verify(params = {})
+        new(params).create(action: :verify)
+      end
+    end
+  end
+end

data/lib/azul/response.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Azul
+  class Response
+    attr_reader :raw_response, :request
+
+    def initialize(raw_response, request)
+      @raw_response = raw_response
+      @request = request
+    end
+
+    def success?
+      http_success? && azul_success?
+    end
+
+    def body
+      @body ||= parse_body
+    end
+
+    def iso_code
+      body["IsoCode"]
+    end
+
+    def response_code
+      body["ResponseCode"]
+    end
+
+    def response_message
+      body["ResponseMessage"]
+    end
+
+    def error_description
+      body["ErrorDescription"]
+    end
+
+    def authorization_code
+      body["AuthorizationCode"]
+    end
+
+    def azul_order_id
+      body["AzulOrderId"]
+    end
+
+    def country_code
+      body["CountryCode"]
+    end
+
+    def custom_order_id
+      body["CustomOrderId"]
+    end
+
+    def date_time
+      body["DateTime"]
+    end
+
+    def lot_number
+      body["LotNumber"]
+    end
+
+    def rrn
+      body["RRN"]
+    end
+
+    def ticket
+      body["Ticket"]
+    end
+
+    def threeds_method
+      body["ThreeDSMethod"]
+    end
+
+    def threeds_challenge
+      body["ThreeDSChallenge"]
+    end
+
+    # Token related methods
+    def data_vault_token
+      body["DataVaultToken"]
+    end
+
+    def data_vault_expiration
+      body["DataVaultExpiration"]
+    end
+
+    def data_vault_brand
+      body["DataVaultBrand"]
+    end
+
+    # Payment method details from request metadata
+    def payment_method_details
+      @request.payment_method_metadata
+    end
+
+    def http_success?
+      @raw_response.is_a?(Net::HTTPSuccess)
+    end
+
+    def azul_success?
+      ["00", "3D2METHOD", "3D"].include?(iso_code) || response_message == "APROBADA" || response_code == "SEARCHED"
+    end
+
+    def parse_body
+      return {} if raw_response.body.blank?
+
+      JSON.parse(raw_response.body)
+    end
+  end
+end

data/lib/azul/url_builder.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Azul
+  class UrlBuilder
+    ENDPOINTS = {
+      development: "https://pruebas.azul.com.do/WebServices/JSON/Default.aspx",
+      production: "https://pagos.azul.com.do/WebServices/JSON/Default.aspx"
+    }.freeze
+
+    ACTIONS = {
+      post: "ProcessPost",
+      void: "ProcessVoid",
+      verify: "VerifyPayment",
+      search: "SearchPayments",
+      process_threeds_method: "processthreedsmethod",
+      process_threeds_challenge: "processthreedschallenge"
+    }.freeze
+
+    def initialize(environment)
+      @environment = environment
+    end
+
+    def build(action: nil)
+      base_url = ENDPOINTS[@environment]
+
+      return base_url unless action
+
+      uri = URI(base_url)
+      query_param = ACTIONS[action]
+
+      uri.query = query_param if query_param
+
+      uri.to_s
+    end
+  end
+end

data/lib/azul/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Azul
+  VERSION = "0.5.0"
+end

data/lib/azul.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "azul/configuration"
+require_relative "azul/errors"
+require_relative "azul/url_builder"
+require_relative "azul/http_client"
+require_relative "azul/request"
+require_relative "azul/response"
+require_relative "azul/resources/base"
+require_relative "azul/resources/payment"
+require_relative "azul/resources/refund"
+require_relative "azul/resources/transaction"
+require_relative "azul/version"
+
+module Azul
+  class << self
+    attr_accessor :configuration
+
+    def configure
+      @configuration ||= Configuration.new
+      yield(@configuration)
+    end
+  end
+
+  # Aliasing the resource classes at the module level
+  Base = Resources::Base
+  Payment = Resources::Payment
+  Refund = Resources::Refund
+  Transaction = Resources::Transaction
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: azul-sdk
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- Rafael Montas
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-08-09 00:00:00.000000000 Z
+dependencies: []
+description: Implementación de Azul Webservices API.
+email:
+- rafaelmontas1@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/azul.rb
+- lib/azul/configuration.rb
+- lib/azul/errors.rb
+- lib/azul/http_client.rb
+- lib/azul/request.rb
+- lib/azul/resources/base.rb
+- lib/azul/resources/payment.rb
+- lib/azul/resources/refund.rb
+- lib/azul/resources/transaction.rb
+- lib/azul/response.rb
+- lib/azul/url_builder.rb
+- lib/azul/version.rb
+homepage: https://github.com/rafaelmontas/azul-sdk
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/rafaelmontas/azul-sdk
+  source_code_uri: https://github.com/rafaelmontas/azul-sdk
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: Implementación de Azul Webservices API.
+test_files: []