Ruby

AbacatePay Ruby SDK

Repositório oficial — issues, changelog e contribuições.

Pré-requisitos

Ruby 3.2+
Gem abacatepay-ruby 1.2.2 ou superior
Uma chave de API (criar no dashboard)

Instalação

# Adicione ao seu Gemfile:
gem 'abacatepay-ruby'
# Depois execute:
bundle install

bundle add abacatepay-ruby

gem install abacatepay-ruby

Configuração

Armazene sua chave de API em uma variável de ambiente e nunca no código:

# config/initializers/abacatepay.rb
AbacatePay.configure do |config|
  config.api_token = ENV['ABACATEPAY_API_KEY']
  config.timeout   = 30 # opcional, em segundos
end

Dev mode x Produção

O ambiente é definido pela chave utilizada, não por configuração do SDK — chaves criadas em Dev mode geram transações simuladas. Saiba mais aqui.

Primeira cobrança

checkout = AbacatePay.checkouts.create(
  AbacatePay::Resources::Checkouts.new(
    methods: ['PIX'],
    products: [
      AbacatePay::Resources::Billings::Product.new(
        external_id: 'prod_abc123xyz',
        name:        'Pro plan',
        quantity:    1,
        price:       1000 # em centavos
      )
    ],
    metadata: AbacatePay::Resources::Billings::Metadata.new(
      return_url:     'https://meusite.com/app',
      completion_url: 'https://meusite.com/pagamento/sucesso'
    )
  )
)

puts checkout.url # URL de pagamento para o cliente

Resposta:

{
  "success": true,
  "error": null,
  "data": {
    "id": "bill_12345667",
    "url": "https://app.abacatepay.com/pay/bill_12345667",
    "amount": 1000,
    "status": "PENDING",
    "devMode": true,
    "createdAt": "2026-08-04T18:38:28.573Z"
  }
}

Recursos disponíveis

Todos os recursos são acessíveis pela fachada AbacatePay.<recurso>:

Recurso	Métodos
`customers`	`list` `get` `create` `delete`
`products`	`list` `get` `create` `delete`
`coupons`	`list` `get` `create` `delete` `toggle`
`checkouts`	`list` `get` `create` `refund`
`payment_links`	`list` `get` `create` `refund`
`subscriptions`	`list` `create` `cancel` `change_plan` `record_usage`
`transparents`	`list` `create` `check` `simulate_payment` `refund`
`pix`	`list` `get` `send_pix`
`payouts`	`list` `get` `create`
`store`	`get` `merchant_info` `mrr` `revenue`
`webhook_endpoints`	`list` `get` `create` `delete`

AbacatePay.customers.list(limit: 25)
AbacatePay.products.get('prod_abc123xyz')
AbacatePay.checkouts.refund('bill_abc123xyz')
AbacatePay.subscriptions.cancel('subs_abc123xyz')

Tratamento de erros

O SDK de Ruby levanta exceções — ele não retorna { data, error, success }. Toda falha herda de AbacatePay::Error:

begin
  checkout = AbacatePay.checkouts.create(data)
rescue AbacatePay::ConfigurationError => e
  # token ausente ou vazio
rescue AbacatePay::ApiError => e
  # erro da API, falha de rede ou timeout
end

Exceção	Quando acontece
`AbacatePay::ConfigurationError`	Token ausente ou vazio
`AbacatePay::ApiError`	Erro da API, falha de rede ou timeout
`AbacatePay::Webhooks::SignatureError`	Assinatura de webhook ausente, vazia ou inválida
`AbacatePay::Webhooks::PayloadError`	Corpo do webhook malformado ou que não é um objeto JSON

Webhooks

A AbacatePay usa dois mecanismos e a documentação de segurança orienta usar os dois:

Mecanismo	O que garante
`webhookSecret` na query	autentica a origem
Assinatura HMAC no header	integridade do corpo

A chave HMAC é pública e global, publicada na documentação, então a assinatura sozinha não prova origem.

payload   = request.body.read
signature = request.headers['X-Webhook-Signature']

begin
  # 1. Autentica a origem com o secret definido ao criar o webhook.
  AbacatePay::Webhooks.verify_secret!(
    received: params[:webhookSecret],
    expected: ENV['ABACATEPAY_WEBHOOK_SECRET']
  )

  # 2. Verifica a integridade do corpo antes de fazer o parse.
  event = AbacatePay::Webhooks.construct_event(
    payload: payload, signature: signature
  )
rescue AbacatePay::Webhooks::SignatureError
  return head :unauthorized
rescue AbacatePay::Webhooks::PayloadError
  return head :bad_request
end

case event.type
when 'checkout.completed'          then handle_payment(event.data)
when 'subscription.payment_failed' then handle_dunning(event.data)
end

A AbacatePay reentrega qualquer webhook que não responda 2xx. Guarde o id do evento com índice único no banco e responda 200 também para duplicatas, senão a reentrega não para.

Em Rails, leia request.query_parameters em vez de params antes de validar. Tocar em params faz o framework parsear o corpo, e um corpo malformado estoura antes do seu código rodar.

Boleto

Boleto tem vencimento, juros e multa próprios. Valores em centavos.

AbacatePay.checkouts.create(
  AbacatePay::Resources::Checkouts.new(
    methods: ['BOLETO'],
    due_date: '2026-09-15',
    interest: { value: 100 },
    fine: { value: 200, type: 'PERCENTAGE' },
    products: [
      AbacatePay::Resources::Billings::Product.new(external_id: 'prod_abc123xyz', quantity: 1)
    ]
  )
)

No checkout transparente, o boleto exige nome e CPF/CNPJ do pagador. O SDK valida isso localmente, antes de gastar uma chamada:

boleto = AbacatePay.transparents.create(charge, method: 'BOLETO')
boleto.bar_code   # linha digitável
boleto.url        # PDF para impressão
boleto.br_code    # PIX alternativo da mesma cobrança

Paginação

Listas retornam no máximo 100 itens. Para percorrer tudo sem lidar com cursor:

AbacatePay.customers.auto_paging_each { |customer| puts customer.name }

Resiliência

O SDK já traz retry com backoff exponencial e jitter em 429 e 5xx. Escritas nunca são repetidas, porque refazer uma criação de cobrança após timeout poderia cobrar o cliente duas vezes.

AbacatePay.configure do |config|
  config.api_token   = ENV['ABACATEPAY_API_KEY']
  config.timeout     = 30  # segundos
  config.max_retries = 2   # 0 desliga
  config.logger      = Rails.logger  # opcional, o token é redigido
end

Próximos passos

Configurar webhooks

Receba notificações em tempo real sobre pagamentos confirmados.

Checkout Transparente

Aceite PIX e cartão diretamente na sua interface.

Criar clientes

Gerencie clientes vinculados às cobranças.

Referência completa

Todos os endpoints, status codes e formato de resposta.

SDKs

Backend

Mobile

AbacatePay Ruby SDK

Pré-requisitos

Instalação

Configuração

Dev mode x Produção

Primeira cobrança

Recursos disponíveis

Tratamento de erros

Webhooks

Boleto

Paginação

Resiliência

Próximos passos

Configurar webhooks

Checkout Transparente

Criar clientes

Referência completa

AbacatePay Ruby SDK

​Pré-requisitos

​Instalação

​Configuração

Dev mode x Produção

​Primeira cobrança

​Recursos disponíveis

​Tratamento de erros

​Webhooks

​Boleto

​Paginação

​Resiliência

​Próximos passos

Configurar webhooks

Checkout Transparente

Criar clientes

Referência completa

Pré-requisitos

Instalação

Configuração

Primeira cobrança

Recursos disponíveis

Tratamento de erros

Webhooks

Boleto

Paginação

Resiliência

Próximos passos