nxgate 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 26aaf6e56c28024006e8b39d22220851836bceaf0dc5a094ca8ba6879323fcd5
+  data.tar.gz: b96af5c8e0a12381144bce2d9b2a8df0d5603480898d7607bdecbfe606fdbe4b
+SHA512:
+  metadata.gz: 6befe2c59740cd39eb9be1139c294473e440c133dfbb97263308cb60000612a3dc5c4d113dcc030c66ee13f951c2e2adc84b36fe93eb1a3dd255e2824d3dae95
+  data.tar.gz: c7339b2ea6be7b4416382d1492d8538ab75ab2e5decf46acea9840791b1d5aa4c66ec87bc5a5f8f624ef9f48c8613202c7786f7c83685cfdd98e4c367ed68f90

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 NXGATE
+
+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,320 @@
+# NXGATE PIX SDK para Ruby
+
+SDK oficial da NXGATE para integracoes PIX em Ruby. Permite gerar cobrancas (cash-in), realizar saques (cash-out), consultar saldo e transacoes, alem de processar webhooks.
+
+## Requisitos
+
+- Ruby 3.0 ou superior
+- Sem dependencias externas (utiliza apenas `net/http`, `json` e `openssl` da stdlib)
+
+## Instalacao
+
+Adicione ao seu `Gemfile`:
+
+```ruby
+gem 'nxgate'
+```
+
+E execute:
+
+```bash
+bundle install
+```
+
+Ou instale diretamente:
+
+```bash
+gem install nxgate
+```
+
+## Configuracao
+
+```ruby
+require 'nxgate'
+
+# Configuracao basica
+nx = NXGate::Client.new(
+  client_id: 'nxgate_xxx',
+  client_secret: 'secret'
+)
+
+# Com assinatura HMAC (opcional)
+nx = NXGate::Client.new(
+  client_id: 'nxgate_xxx',
+  client_secret: 'secret',
+  hmac_secret: 'sua_chave_hmac'
+)
+
+# Com URL customizada e timeout
+nx = NXGate::Client.new(
+  client_id: 'nxgate_xxx',
+  client_secret: 'secret',
+  base_url: 'https://sandbox.nxgate.com.br',
+  timeout: 60
+)
+```
+
+## Uso
+
+### Gerar Cobranca PIX (Cash-in)
+
+Gera uma cobranca PIX e retorna o QR Code para pagamento.
+
+```ruby
+charge = nx.pix_generate(
+  valor: 100.00,
+  nome_pagador: 'Joao da Silva',
+  documento_pagador: '12345678901',
+  webhook: 'https://meusite.com/webhook'
+)
+
+puts charge.status            # "OK"
+puts charge.id_transaction    # "tx_abc123"
+puts charge.payment_code      # Codigo PIX copia e cola
+puts charge.payment_code_base64  # QR Code em Base64
+```
+
+#### Parametros opcionais
+
+```ruby
+charge = nx.pix_generate(
+  valor: 250.00,
+  nome_pagador: 'Maria Santos',
+  documento_pagador: '98765432100',
+  forcar_pagador: true,
+  email_pagador: 'maria@email.com',
+  celular: '11999999999',
+  descricao: 'Pedido #12345',
+  webhook: 'https://meusite.com/webhook',
+  magic_id: 'pedido_12345',
+  api_key: 'chave_api',
+  split_users: [
+    { username: 'lojista1', percentage: 70 },
+    { username: 'lojista2', percentage: 30 }
+  ]
+)
+```
+
+### Saque PIX (Cash-out)
+
+Realiza uma transferencia PIX para a chave informada.
+
+```ruby
+withdrawal = nx.pix_withdraw(
+  valor: 50.0,
+  chave_pix: 'joao@email.com',
+  tipo_chave: 'EMAIL'
+)
+
+puts withdrawal.status              # "OK"
+puts withdrawal.message             # "Saque realizado"
+puts withdrawal.internal_reference  # "ref_xyz"
+```
+
+#### Tipos de chave aceitos
+
+| Tipo    | Descricao            |
+|---------|----------------------|
+| `CPF`   | CPF do destinatario  |
+| `CNPJ`  | CNPJ do destinatario |
+| `PHONE` | Telefone celular     |
+| `EMAIL` | Endereco de e-mail   |
+| `RANDOM`| Chave aleatoria      |
+
+### Consultar Saldo
+
+```ruby
+balance = nx.get_balance
+
+puts balance.balance    # Saldo total
+puts balance.blocked    # Saldo bloqueado
+puts balance.available  # Saldo disponivel
+```
+
+### Consultar Transacao
+
+```ruby
+tx = nx.get_transaction(type: 'cash-in', txid: 'tx_abc123')
+
+puts tx.id_transaction  # "tx_abc123"
+puts tx.status          # "PAID"
+puts tx.amount          # 100.0
+puts tx.paid_at         # "2025-01-15T10:30:00Z"
+puts tx.end_to_end      # "e2e_xyz"
+puts tx.raw             # Hash completo da resposta
+```
+
+## Webhooks
+
+### Processar Evento de Webhook
+
+```ruby
+# Em um controller Rails, Sinatra, etc.
+event = NXGate::Webhook.parse(request.body.read)
+
+# Ou a partir de um Hash
+event = NXGate::Webhook.parse(params)
+
+puts event.type   # Tipo do evento
+puts event.data   # Dados do evento
+
+# Verificacoes de tipo
+event.cash_in?    # true se for evento de cash-in
+event.cash_out?   # true se for evento de cash-out
+event.success?    # true se for pagamento/saque bem-sucedido
+event.refunded?   # true se houve reembolso
+event.error?      # true se houve erro (apenas cash-out)
+```
+
+### Tipos de Evento
+
+#### Cash-in (QR Code)
+
+| Tipo                                | Descricao               |
+|-------------------------------------|-------------------------|
+| `QR_CODE_COPY_AND_PASTE_PAID`       | Pagamento confirmado    |
+| `QR_CODE_COPY_AND_PASTE_REFUNDED`   | Pagamento reembolsado   |
+
+#### Cash-out (Saque)
+
+| Tipo                    | Descricao               |
+|-------------------------|-------------------------|
+| `PIX_CASHOUT_SUCCESS`   | Saque realizado         |
+| `PIX_CASHOUT_ERROR`     | Erro no saque           |
+| `PIX_CASHOUT_REFUNDED`  | Saque reembolsado       |
+
+### Exemplo com Sinatra
+
+```ruby
+require 'sinatra'
+require 'nxgate'
+
+post '/webhook' do
+  payload = request.body.read
+
+  begin
+    event = NXGate::Webhook.parse(payload)
+
+    if event.cash_in? && event.success?
+      # Pagamento confirmado
+      puts "Pagamento recebido: R$ #{event.data[:amount]}"
+      puts "Transacao: #{event.data[:tx_id]}"
+    elsif event.cash_out? && event.success?
+      # Saque realizado
+      puts "Saque realizado: R$ #{event.data[:amount]}"
+    elsif event.error?
+      # Erro no saque
+      puts "Erro no saque: #{event.data[:id_transaction]}"
+    end
+
+    status 200
+    'OK'
+  rescue NXGate::Error => e
+    status 400
+    e.message
+  end
+end
+```
+
+## Assinatura HMAC
+
+Quando o `hmac_secret` e fornecido na inicializacao do client, todas as requisicoes sao automaticamente assinadas com HMAC-SHA256.
+
+### Headers adicionados
+
+| Header              | Descricao                                    |
+|---------------------|----------------------------------------------|
+| `X-Client-ID`       | ID do cliente                                |
+| `X-HMAC-Signature`  | Assinatura HMAC-SHA256 em Base64             |
+| `X-HMAC-Timestamp`  | Timestamp ISO 8601 da requisicao             |
+| `X-HMAC-Nonce`      | String unica por requisicao (UUID)           |
+
+### Payload assinado
+
+```
+METHOD\nPATH\nTIMESTAMP\nNONCE\nBODY
+```
+
+### Verificacao de assinatura (para webhooks)
+
+```ruby
+signer = NXGate::HmacSigner.new(
+  client_id: 'nxgate_xxx',
+  hmac_secret: 'sua_chave_hmac'
+)
+
+valido = signer.verify(
+  method: 'POST',
+  path: '/webhook',
+  timestamp: request.env['HTTP_X_HMAC_TIMESTAMP'],
+  nonce: request.env['HTTP_X_HMAC_NONCE'],
+  body: request.body.read,
+  signature: request.env['HTTP_X_HMAC_SIGNATURE']
+)
+```
+
+## Tratamento de Erros
+
+Todos os erros herdam de `NXGate::Error` e incluem informacoes detalhadas.
+
+```ruby
+begin
+  nx.pix_generate(valor: 100.0, nome_pagador: 'Joao', documento_pagador: '123')
+rescue NXGate::AuthenticationError => e
+  # Erro de autenticacao (401)
+  puts "Autenticacao falhou: #{e.message}"
+  puts "HTTP Status: #{e.http_status}"
+rescue NXGate::ServiceUnavailableError => e
+  # Servico indisponivel (503) - apos retentativas
+  puts "Servico indisponivel: #{e.message}"
+rescue NXGate::TimeoutError => e
+  # Timeout na conexao
+  puts "Timeout: #{e.message}"
+rescue NXGate::Error => e
+  # Outros erros da API
+  puts "Erro: #{e.code} - #{e.title}"
+  puts "Detalhe: #{e.description}"
+  puts "HTTP: #{e.http_status}"
+end
+```
+
+### Hierarquia de Erros
+
+```
+NXGate::Error (StandardError)
+  |-- NXGate::AuthenticationError    # 401 - Falha na autenticacao
+  |-- NXGate::TimeoutError           # Timeout na conexao
+  |-- NXGate::ServiceUnavailableError # 503 - Servico indisponivel
+```
+
+## Retentativas Automaticas
+
+Requisicoes que retornam HTTP 503 sao automaticamente retentadas ate 2 vezes com backoff exponencial:
+
+- 1a retentativa: aguarda 1 segundo
+- 2a retentativa: aguarda 2 segundos
+- Apos 2 retentativas falhas, lanca `NXGate::ServiceUnavailableError`
+
+## Gerenciamento de Token
+
+O token OAuth2 e gerenciado automaticamente:
+
+- Obtido na primeira requisicao
+- Cacheado em memoria
+- Renovado automaticamente 60 segundos antes da expiracao
+- Invalidado e renovado em caso de erro 401
+- Thread-safe (utiliza Mutex)
+
+## Testes
+
+```bash
+# Executar todos os testes
+bundle exec rake test
+
+# Ou diretamente
+ruby -Ilib -Itest test/test_client.rb
+```
+
+## Licenca
+
+Distribuido sob a licenca MIT. Consulte o arquivo [LICENSE](LICENSE) para mais informacoes.

data/lib/nxgate/client.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module NXGate
+  # Cliente principal da SDK NXGATE PIX.
+  #
+  # Gerencia autenticacao, assinatura HMAC, retentativas e todas
+  # as operacoes da API PIX.
+  #
+  # @example Uso basico
+  #   client = NXGate::Client.new(
+  #     client_id: "nxgate_xxx",
+  #     client_secret: "secret"
+  #   )
+  #   charge = client.pix_generate(valor: 100.0, nome_pagador: "Joao", documento_pagador: "12345678901")
+  #
+  class Client
+    DEFAULT_BASE_URL = "https://api.nxgate.com.br"
+    DEFAULT_TIMEOUT = 30
+    MAX_RETRIES = 2
+    RETRY_BASE_DELAY = 1.0 # segundos
+
+    attr_reader :base_url
+
+    # @param client_id [String] ID do cliente NXGATE
+    # @param client_secret [String] Segredo do cliente NXGATE
+    # @param hmac_secret [String, nil] Segredo HMAC (opcional). Quando fornecido, todas as requisicoes serao assinadas.
+    # @param base_url [String] URL base da API (padrao: https://api.nxgate.com.br)
+    # @param timeout [Integer] Timeout em segundos para requisicoes HTTP (padrao: 30)
+    def initialize(client_id:, client_secret:, hmac_secret: nil, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT)
+      @client_id = client_id
+      @client_secret = client_secret
+      @base_url = base_url.chomp("/")
+      @timeout = timeout
+
+      @hmac_signer = if hmac_secret
+        HmacSigner.new(client_id: client_id, hmac_secret: hmac_secret)
+      end
+
+      @token_manager = TokenManager.new(
+        base_url: @base_url,
+        client_id: client_id,
+        client_secret: client_secret,
+        hmac_signer: @hmac_signer
+      )
+    end
+
+    # Gera uma cobranca PIX (cash-in) e retorna o QR Code.
+    #
+    # @param valor [Float] Valor da cobranca (obrigatorio)
+    # @param nome_pagador [String] Nome do pagador (obrigatorio)
+    # @param documento_pagador [String] CPF ou CNPJ do pagador (obrigatorio)
+    # @param forcar_pagador [Boolean, nil] Forcar dados do pagador
+    # @param email_pagador [String, nil] Email do pagador
+    # @param celular [String, nil] Celular do pagador
+    # @param descricao [String, nil] Descricao da cobranca
+    # @param webhook [String, nil] URL de webhook para notificacoes
+    # @param magic_id [String, nil] ID magico para rastreamento
+    # @param api_key [String, nil] Chave de API adicional
+    # @param split_users [Array<Hash>, nil] Lista de split de pagamento [{username:, percentage:}]
+    # @return [NXGate::PixChargeResponse] Resposta com QR Code e dados da cobranca
+    # @raise [NXGate::Error] Se a requisicao falhar
+    def pix_generate(valor:, nome_pagador:, documento_pagador:, forcar_pagador: nil,
+                     email_pagador: nil, celular: nil, descricao: nil, webhook: nil,
+                     magic_id: nil, api_key: nil, split_users: nil)
+      body = {
+        valor: valor,
+        nome_pagador: nome_pagador,
+        documento_pagador: documento_pagador
+      }
+
+      body[:forcar_pagador] = forcar_pagador unless forcar_pagador.nil?
+      body[:email_pagador] = email_pagador if email_pagador
+      body[:celular] = celular if celular
+      body[:descricao] = descricao if descricao
+      body[:webhook] = webhook if webhook
+      body[:magic_id] = magic_id if magic_id
+      body[:api_key] = api_key if api_key
+
+      if split_users
+        body[:split_users] = split_users.map do |user|
+          if user.is_a?(SplitUser)
+            user.to_h
+          else
+            { "username" => user[:username] || user["username"],
+              "percentage" => user[:percentage] || user["percentage"] }
+          end
+        end
+      end
+
+      data = post("/pix/gerar", body)
+      PixChargeResponse.from_hash(data)
+    end
+
+    # Realiza um saque PIX (cash-out).
+    #
+    # @param valor [Float] Valor do saque (obrigatorio)
+    # @param chave_pix [String] Chave PIX de destino (obrigatorio)
+    # @param tipo_chave [String] Tipo da chave: CPF, CNPJ, PHONE, EMAIL ou RANDOM (obrigatorio)
+    # @param documento [String, nil] Documento do destinatario
+    # @param webhook [String, nil] URL de webhook para notificacoes
+    # @param magic_id [String, nil] ID magico para rastreamento
+    # @param api_key [String, nil] Chave de API adicional
+    # @return [NXGate::PixWithdrawResponse] Resposta do saque
+    # @raise [NXGate::Error] Se a requisicao falhar
+    def pix_withdraw(valor:, chave_pix:, tipo_chave:, documento: nil, webhook: nil,
+                     magic_id: nil, api_key: nil)
+      valid_key_types = %w[CPF CNPJ PHONE EMAIL RANDOM]
+      unless valid_key_types.include?(tipo_chave.to_s.upcase)
+        raise Error.new(
+          code: "INVALID_KEY_TYPE",
+          title: "Tipo de chave invalido",
+          description: "tipo_chave deve ser um de: #{valid_key_types.join(', ')}. Recebido: #{tipo_chave}"
+        )
+      end
+
+      body = {
+        valor: valor,
+        chave_pix: chave_pix,
+        tipo_chave: tipo_chave.to_s.upcase
+      }
+
+      body[:documento] = documento if documento
+      body[:webhook] = webhook if webhook
+      body[:magic_id] = magic_id if magic_id
+      body[:api_key] = api_key if api_key
+
+      data = post("/pix/sacar", body)
+      PixWithdrawResponse.from_hash(data)
+    end
+
+    # Consulta o saldo da conta.
+    #
+    # @return [NXGate::BalanceResponse] Saldo disponivel, bloqueado e total
+    # @raise [NXGate::Error] Se a requisicao falhar
+    def get_balance
+      data = get("/v1/balance")
+      BalanceResponse.from_hash(data)
+    end
+
+    # Consulta uma transacao especifica.
+    #
+    # @param type [String] Tipo da transacao: "cash-in" ou "cash-out"
+    # @param txid [String] ID da transacao
+    # @return [NXGate::TransactionResponse] Dados da transacao
+    # @raise [NXGate::Error] Se a requisicao falhar
+    def get_transaction(type:, txid:)
+      path = "/v1/transactions?type=#{uri_encode(type)}&txid=#{uri_encode(txid)}"
+      data = get(path)
+      TransactionResponse.from_hash(data)
+    end
+
+    private
+
+    def get(path)
+      request_with_retry(:get, path)
+    end
+
+    def post(path, body)
+      request_with_retry(:post, path, body)
+    end
+
+    def request_with_retry(method, path, body = nil)
+      attempts = 0
+
+      loop do
+        attempts += 1
+
+        begin
+          return execute_request(method, path, body)
+        rescue ServiceUnavailableError => e
+          raise e if attempts > MAX_RETRIES
+
+          delay = RETRY_BASE_DELAY * (2**(attempts - 1))
+          sleep(delay)
+        end
+      end
+    end
+
+    def execute_request(method, path, body = nil)
+      uri = URI("#{@base_url}#{path}")
+      http = build_http(uri)
+
+      request = build_request(method, uri, body)
+      response = http.request(request)
+
+      handle_response(response)
+    end
+
+    def build_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+      http
+    end
+
+    def build_request(method, uri, body = nil)
+      path = uri.request_uri
+      json_body = body ? JSON.generate(body) : ""
+
+      request = case method
+      when :get
+        Net::HTTP::Get.new(path)
+      when :post
+        req = Net::HTTP::Post.new(path)
+        req.body = json_body
+        req
+      else
+        raise ArgumentError, "Metodo HTTP nao suportado: #{method}"
+      end
+
+      request["Content-Type"] = "application/json"
+      request["Accept"] = "application/json"
+      request["Authorization"] = "Bearer #{@token_manager.access_token}"
+      request["User-Agent"] = "nxgate-ruby/#{NXGate::VERSION}"
+
+      if @hmac_signer
+        hmac_headers = @hmac_signer.sign(
+          method: method.to_s.upcase,
+          path: uri.path,
+          body: json_body
+        )
+        hmac_headers.each { |key, value| request[key] = value }
+      end
+
+      request
+    end
+
+    def handle_response(response)
+      status = response.code.to_i
+
+      case status
+      when 200..299
+        parse_success(response)
+      when 401
+        @token_manager.invalidate!
+        error_data = parse_error_body(response.body)
+        raise AuthenticationError.new(
+          code: error_data[:code],
+          title: error_data[:title],
+          description: error_data[:description],
+          http_status: status
+        )
+      when 503
+        error_data = parse_error_body(response.body)
+        raise ServiceUnavailableError.new(
+          code: error_data[:code] || "SERVICE_UNAVAILABLE",
+          title: error_data[:title] || "Servico indisponivel",
+          description: error_data[:description] || "A API esta temporariamente indisponivel",
+          http_status: status
+        )
+      else
+        error_data = parse_error_body(response.body)
+        raise Error.new(
+          code: error_data[:code],
+          title: error_data[:title],
+          description: error_data[:description],
+          http_status: status
+        )
+      end
+    end
+
+    def parse_success(response)
+      return {} if response.body.nil? || response.body.empty?
+
+      JSON.parse(response.body)
+    rescue JSON::ParserError
+      { "raw" => response.body }
+    end
+
+    def parse_error_body(body)
+      return { code: nil, title: nil, description: nil } if body.nil? || body.empty?
+
+      data = JSON.parse(body)
+      {
+        code: data["code"] || data["error"],
+        title: data["title"] || data["error_description"],
+        description: data["description"] || data["message"] || body
+      }
+    rescue JSON::ParserError
+      { code: nil, title: nil, description: body }
+    end
+
+    def uri_encode(str)
+      URI.encode_www_form_component(str.to_s)
+    end
+  end
+end

data/lib/nxgate/error.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module NXGate
+  # Erro personalizado para respostas da API NXGATE.
+  #
+  # Atributos:
+  #   code        - Codigo interno retornado pela API (ex.: "INVALID_TOKEN")
+  #   title       - Titulo curto do erro
+  #   description - Descricao detalhada
+  #   http_status - Codigo HTTP da resposta (ex.: 401, 422, 503)
+  class Error < StandardError
+    attr_reader :code, :title, :description, :http_status
+
+    def initialize(message = nil, code: nil, title: nil, description: nil, http_status: nil)
+      @code        = code
+      @title       = title
+      @description = description
+      @http_status = http_status
+
+      full_message = build_message(message)
+      super(full_message)
+    end
+
+    def to_h
+      {
+        code: @code,
+        title: @title,
+        description: @description,
+        http_status: @http_status
+      }
+    end
+
+    private
+
+    def build_message(message)
+      return message if message
+
+      parts = []
+      parts << "[#{@code}]" if @code
+      parts << @title if @title
+      parts << "- #{@description}" if @description
+      parts << "(HTTP #{@http_status})" if @http_status
+      parts.empty? ? "NXGate API Error" : parts.join(" ")
+    end
+  end
+
+  # Erro de autenticacao (401)
+  class AuthenticationError < Error; end
+
+  # Erro de timeout na conexao
+  class TimeoutError < Error; end
+
+  # Erro quando o servico esta indisponivel (503) apos retentativas
+  class ServiceUnavailableError < Error; end
+end

data/lib/nxgate/hmac_signer.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+require "securerandom"
+require "time"
+
+module NXGate
+  # Responsavel por gerar assinaturas HMAC-SHA256 para requisicoes autenticadas.
+  #
+  # O payload assinado segue o formato:
+  #   "METHOD\nPATH\nTIMESTAMP\nNONCE\nBODY"
+  #
+  # Headers gerados:
+  #   X-Client-ID       - Identificador do cliente
+  #   X-HMAC-Signature  - Assinatura HMAC-SHA256 em Base64
+  #   X-HMAC-Timestamp  - Timestamp ISO 8601
+  #   X-HMAC-Nonce      - String unica por requisicao
+  class HmacSigner
+    # @param client_id [String] ID do cliente NXGATE
+    # @param hmac_secret [String] Chave secreta para HMAC
+    def initialize(client_id:, hmac_secret:)
+      @client_id = client_id
+      @hmac_secret = hmac_secret
+    end
+
+    # Gera os headers de assinatura HMAC para uma requisicao.
+    #
+    # @param method [String] Metodo HTTP (GET, POST, etc.)
+    # @param path [String] Caminho da requisicao (ex.: "/pix/gerar")
+    # @param body [String] Corpo da requisicao (string vazia para GET)
+    # @return [Hash] Headers de assinatura
+    def sign(method:, path:, body: "")
+      timestamp = Time.now.utc.iso8601
+      nonce = SecureRandom.uuid
+
+      payload = "#{method.upcase}\n#{path}\n#{timestamp}\n#{nonce}\n#{body}"
+
+      digest = OpenSSL::Digest.new("SHA256")
+      hmac = OpenSSL::HMAC.digest(digest, @hmac_secret, payload)
+      signature = Base64.strict_encode64(hmac)
+
+      {
+        "X-Client-ID" => @client_id,
+        "X-HMAC-Signature" => signature,
+        "X-HMAC-Timestamp" => timestamp,
+        "X-HMAC-Nonce" => nonce
+      }
+    end
+
+    # Verifica se uma assinatura HMAC recebida e valida.
+    # Util para validar webhooks assinados.
+    #
+    # @param method [String] Metodo HTTP
+    # @param path [String] Caminho da requisicao
+    # @param timestamp [String] Timestamp ISO 8601 recebido
+    # @param nonce [String] Nonce recebido
+    # @param body [String] Corpo da requisicao
+    # @param signature [String] Assinatura Base64 recebida
+    # @return [Boolean] true se a assinatura e valida
+    def verify(method:, path:, timestamp:, nonce:, body:, signature:)
+      payload = "#{method.upcase}\n#{path}\n#{timestamp}\n#{nonce}\n#{body}"
+
+      digest = OpenSSL::Digest.new("SHA256")
+      hmac = OpenSSL::HMAC.digest(digest, @hmac_secret, payload)
+      expected = Base64.strict_encode64(hmac)
+
+      secure_compare(expected, signature)
+    end
+
+    private
+
+    # Comparacao em tempo constante para evitar timing attacks.
+    def secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      result = 0
+      a.bytes.zip(b.bytes) { |x, y| result |= x ^ y }
+      result.zero?
+    end
+  end
+end

data/lib/nxgate/token_manager.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module NXGate
+  # Gerencia tokens OAuth2 com cache automatico e renovacao.
+  #
+  # O token e cacheado e renovado automaticamente 60 segundos antes
+  # da expiracao para evitar falhas por token expirado.
+  class TokenManager
+    # Margem de seguranca em segundos antes da expiracao para renovar o token.
+    EXPIRY_MARGIN = 60
+
+    # @param base_url [String] URL base da API
+    # @param client_id [String] ID do cliente
+    # @param client_secret [String] Segredo do cliente
+    # @param hmac_signer [HmacSigner, nil] Assinador HMAC opcional
+    def initialize(base_url:, client_id:, client_secret:, hmac_signer: nil)
+      @base_url = base_url
+      @client_id = client_id
+      @client_secret = client_secret
+      @hmac_signer = hmac_signer
+      @token = nil
+      @expires_at = nil
+      @mutex = Mutex.new
+    end
+
+    # Retorna um token valido, renovando se necessario.
+    # Thread-safe via Mutex.
+    #
+    # @return [String] Token de acesso Bearer
+    # @raise [NXGate::AuthenticationError] Se a autenticacao falhar
+    def access_token
+      @mutex.synchronize do
+        fetch_token if token_expired?
+        @token
+      end
+    end
+
+    # Forca a renovacao do token na proxima chamada.
+    def invalidate!
+      @mutex.synchronize do
+        @token = nil
+        @expires_at = nil
+      end
+    end
+
+    private
+
+    def token_expired?
+      @token.nil? || @expires_at.nil? || Time.now >= @expires_at
+    end
+
+    def fetch_token
+      uri = URI("#{@base_url}/oauth2/token")
+      body = JSON.generate({
+        grant_type: "client_credentials",
+        client_id: @client_id,
+        client_secret: @client_secret
+      })
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = 10
+      http.read_timeout = 15
+
+      request = Net::HTTP::Post.new(uri.path)
+      request["Content-Type"] = "application/json"
+      request["Accept"] = "application/json"
+
+      if @hmac_signer
+        hmac_headers = @hmac_signer.sign(method: "POST", path: uri.path, body: body)
+        hmac_headers.each { |key, value| request[key] = value }
+      end
+
+      request.body = body
+
+      response = http.request(request)
+
+      unless response.is_a?(Net::HTTPSuccess)
+        parsed = parse_error_body(response.body)
+        raise AuthenticationError.new(
+          code: parsed[:code] || "AUTH_FAILED",
+          title: parsed[:title] || "Falha na autenticacao",
+          description: parsed[:description] || response.body,
+          http_status: response.code.to_i
+        )
+      end
+
+      data = JSON.parse(response.body)
+      @token = data["access_token"]
+      expires_in = (data["expires_in"] || 3600).to_i
+      @expires_at = Time.now + expires_in - EXPIRY_MARGIN
+    end
+
+    def parse_error_body(body)
+      data = JSON.parse(body)
+      {
+        code: data["code"] || data["error"],
+        title: data["title"] || data["error_description"],
+        description: data["description"] || data["message"]
+      }
+    rescue JSON::ParserError
+      { code: nil, title: nil, description: body }
+    end
+  end
+end

data/lib/nxgate/types.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module NXGate
+  # Resposta de autenticacao OAuth2.
+  TokenResponse = Struct.new(
+    :access_token,
+    :token_type,
+    :expires_in,
+    keyword_init: true
+  )
+
+  # Resposta de geracao de cobranca PIX (cash-in).
+  PixChargeResponse = Struct.new(
+    :status,
+    :message,
+    :payment_code,
+    :id_transaction,
+    :payment_code_base64,
+    keyword_init: true
+  ) do
+    def self.from_hash(hash)
+      new(
+        status: hash["status"],
+        message: hash["message"],
+        payment_code: hash["paymentCode"],
+        id_transaction: hash["idTransaction"],
+        payment_code_base64: hash["paymentCodeBase64"]
+      )
+    end
+  end
+
+  # Resposta de saque PIX (cash-out).
+  PixWithdrawResponse = Struct.new(
+    :status,
+    :message,
+    :internal_reference,
+    keyword_init: true
+  ) do
+    def self.from_hash(hash)
+      new(
+        status: hash["status"],
+        message: hash["message"],
+        internal_reference: hash["internalreference"]
+      )
+    end
+  end
+
+  # Resposta de consulta de saldo.
+  BalanceResponse = Struct.new(
+    :balance,
+    :blocked,
+    :available,
+    keyword_init: true
+  ) do
+    def self.from_hash(hash)
+      new(
+        balance: hash["balance"],
+        blocked: hash["blocked"],
+        available: hash["available"]
+      )
+    end
+  end
+
+  # Resposta de consulta de transacao.
+  TransactionResponse = Struct.new(
+    :id_transaction,
+    :status,
+    :amount,
+    :paid_at,
+    :end_to_end,
+    :raw,
+    keyword_init: true
+  ) do
+    def self.from_hash(hash)
+      new(
+        id_transaction: hash["idTransaction"],
+        status: hash["status"],
+        amount: hash["amount"],
+        paid_at: hash["paidAt"],
+        end_to_end: hash["endToEnd"],
+        raw: hash
+      )
+    end
+  end
+
+  # Evento de webhook recebido.
+  WebhookEvent = Struct.new(
+    :type,
+    :data,
+    :raw,
+    keyword_init: true
+  ) do
+    # Retorna true se o evento e de cash-in (QR Code).
+    def cash_in?
+      type&.start_with?("QR_CODE_")
+    end
+
+    # Retorna true se o evento e de cash-out (saque).
+    def cash_out?
+      type&.start_with?("PIX_CASHOUT_")
+    end
+
+    # Retorna true se o pagamento foi confirmado com sucesso.
+    def success?
+      type == "QR_CODE_COPY_AND_PASTE_PAID" || type == "PIX_CASHOUT_SUCCESS"
+    end
+
+    # Retorna true se houve reembolso.
+    def refunded?
+      type == "QR_CODE_COPY_AND_PASTE_REFUNDED" || type == "PIX_CASHOUT_REFUNDED"
+    end
+
+    # Retorna true se houve erro (apenas cash-out).
+    def error?
+      type == "PIX_CASHOUT_ERROR"
+    end
+  end
+
+  # Dados de split de pagamento.
+  SplitUser = Struct.new(
+    :username,
+    :percentage,
+    keyword_init: true
+  ) do
+    def to_h
+      { "username" => username, "percentage" => percentage }
+    end
+  end
+end

data/lib/nxgate/webhook.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "json"
+
+module NXGate
+  # Parser de eventos de webhook da NXGATE.
+  #
+  # Suporta eventos de cash-in (QR Code) e cash-out (saque PIX).
+  #
+  # Tipos de evento cash-in:
+  #   - QR_CODE_COPY_AND_PASTE_PAID     - Pagamento confirmado
+  #   - QR_CODE_COPY_AND_PASTE_REFUNDED - Pagamento reembolsado
+  #
+  # Tipos de evento cash-out:
+  #   - PIX_CASHOUT_SUCCESS  - Saque realizado com sucesso
+  #   - PIX_CASHOUT_ERROR    - Erro no saque
+  #   - PIX_CASHOUT_REFUNDED - Saque reembolsado
+  module Webhook
+    CASH_IN_TYPES = %w[
+      QR_CODE_COPY_AND_PASTE_PAID
+      QR_CODE_COPY_AND_PASTE_REFUNDED
+    ].freeze
+
+    CASH_OUT_TYPES = %w[
+      PIX_CASHOUT_SUCCESS
+      PIX_CASHOUT_ERROR
+      PIX_CASHOUT_REFUNDED
+    ].freeze
+
+    ALL_TYPES = (CASH_IN_TYPES + CASH_OUT_TYPES).freeze
+
+    class << self
+      # Faz o parse de um payload de webhook.
+      #
+      # @param payload [String, Hash] Payload JSON (string) ou Hash ja parseado
+      # @return [NXGate::WebhookEvent] Evento parseado
+      # @raise [NXGate::Error] Se o payload for invalido
+      def parse(payload)
+        data = normalize_payload(payload)
+        event_type = data["type"]
+
+        unless event_type && ALL_TYPES.include?(event_type)
+          raise Error.new(
+            code: "INVALID_WEBHOOK",
+            title: "Webhook invalido",
+            description: "Tipo de evento desconhecido: #{event_type.inspect}"
+          )
+        end
+
+        if CASH_IN_TYPES.include?(event_type)
+          parse_cash_in(event_type, data)
+        else
+          parse_cash_out(event_type, data)
+        end
+      end
+
+      # Verifica se um tipo de evento e valido.
+      #
+      # @param type [String] Tipo do evento
+      # @return [Boolean]
+      def valid_type?(type)
+        ALL_TYPES.include?(type)
+      end
+
+      private
+
+      def normalize_payload(payload)
+        case payload
+        when String
+          JSON.parse(payload)
+        when Hash
+          payload.transform_keys(&:to_s)
+        else
+          raise Error.new(
+            code: "INVALID_PAYLOAD",
+            title: "Payload invalido",
+            description: "Esperado String ou Hash, recebido #{payload.class}"
+          )
+        end
+      rescue JSON::ParserError => e
+        raise Error.new(
+          code: "INVALID_JSON",
+          title: "JSON invalido",
+          description: "Erro ao parsear JSON do webhook: #{e.message}"
+        )
+      end
+
+      def parse_cash_in(event_type, raw)
+        event_data = raw["data"] || {}
+        event_data = event_data.transform_keys(&:to_s) if event_data.is_a?(Hash)
+
+        WebhookEvent.new(
+          type: event_type,
+          data: {
+            amount: event_data["amount"],
+            status: event_data["status"],
+            worked: event_data["worked"],
+            tag: event_data["tag"],
+            tx_id: event_data["tx_id"],
+            end_to_end: event_data["end_to_end"]
+          },
+          raw: raw
+        )
+      end
+
+      def parse_cash_out(event_type, raw)
+        WebhookEvent.new(
+          type: event_type,
+          data: {
+            amount: raw["amount"],
+            status: raw["status"],
+            worked: raw["worked"],
+            id_transaction: raw["idTransaction"],
+            key: raw["key"]
+          },
+          raw: raw
+        )
+      end
+    end
+  end
+end

data/lib/nxgate.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "nxgate/error"
+require_relative "nxgate/types"
+require_relative "nxgate/hmac_signer"
+require_relative "nxgate/token_manager"
+require_relative "nxgate/webhook"
+require_relative "nxgate/client"
+
+# SDK oficial NXGATE para operacoes PIX.
+#
+# Oferece integracoes completas para:
+# - Gerar cobranças PIX (cash-in) com QR Code
+# - Realizar saques PIX (cash-out)
+# - Consultar saldo
+# - Consultar transacoes
+# - Receber e processar webhooks
+#
+# @example
+#   require 'nxgate'
+#
+#   client = NXGate::Client.new(
+#     client_id: 'nxgate_xxx',
+#     client_secret: 'secret'
+#   )
+#
+#   charge = client.pix_generate(
+#     valor: 100.00,
+#     nome_pagador: 'Joao da Silva',
+#     documento_pagador: '12345678901'
+#   )
+#
+module NXGate
+  VERSION = "1.0.0"
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: nxgate
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- NXGATE
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-11 00:00:00.000000000 Z
+dependencies: []
+description: SDK Ruby para integracao com a API NXGATE PIX. Suporta geracao de cobranças
+  (cash-in), saques (cash-out), consulta de saldo, transacoes e webhooks. Inclui autenticacao
+  OAuth2, assinatura HMAC e retentativas automaticas.
+email:
+- dev@nxgate.com.br
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/nxgate.rb
+- lib/nxgate/client.rb
+- lib/nxgate/error.rb
+- lib/nxgate/hmac_signer.rb
+- lib/nxgate/token_manager.rb
+- lib/nxgate/types.rb
+- lib/nxgate/webhook.rb
+homepage: https://github.com/nxgate/nxgate-sdk-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/nxgate/nxgate-sdk-ruby
+  source_code_uri: https://github.com/nxgate/nxgate-sdk-ruby
+  changelog_uri: https://github.com/nxgate/nxgate-sdk-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/nxgate/nxgate-sdk-ruby/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: SDK oficial NXGATE para operacoes PIX
+test_files: []