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:

gem 'nxgate'

E execute:

bundle install

Ou instale diretamente:

gem install nxgate

Configuracao

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.

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

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.

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

balance = nx.get_balance

puts balance.balance    # Saldo total
puts balance.blocked    # Saldo bloqueado
puts balance.available  # Saldo disponivel

Consultar Transacao

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

# 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

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)

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.

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

# 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 para mais informacoes.