's Ruby API


Build Status Ruby library


Getting Started


gem install pagarme

or add the following line to Gemfile:

gem 'pagarme'

and run bundle install from your shell.

Configure your API key

You can set your API key in Ruby:

PagarMe.api_key        = 'YOUR_API_KEY_HERE'
PagarMe.encryption_key = 'YOUR_ENCRYPTION_KEY_HERE' # If needed

or set the environment variable PAGARME_API_KEY (recommended) and PAGARME_ENCRYPTION_KEY (recommended if needed)

Using Checkout

See our demo checkout.

More about how to use it here.


Creating a Credit Card Transaction

To create a credit card transaction, you need a card_hash.
    amount:    1000,      # in cents
    card_hash: card_hash  # how to get a card hash:

More about Creating a Credit Card Transaction.

Creating a Boleto Transaction

  transaction =
    amount:         1000,    # in cents
    payment_method: 'boleto'

  transaction.boleto_url     # => boleto's URL
  transaction.boleto_barcode # => boleto's barcode

More about Creating a Boleto Transaction.

Split Rules

With split rules, received amount could be splitted between more than one recipient. For example, splitting equally a transaction:
    amount:    1000,      # in cents
    card_hash: card_hash, # how to get a card hash:
    split\_rules: [
      { recipient_id: recipient_id_1, percentage: 50 },
      { recipient_id: recipient_id_2, percentage: 50 }

More about Split Rules.

Plans & Subscriptions

You can use recurring charges, learn more here.

It's important to understand the charges flow, learn more here

Creating a Plan
    amount: 4990,
    days:   30,
    name:   'Gold Plan'

More about Creating a Plan.

Creating a Subscription
    plan:      PagarMe::Plan.find_by_id('1234'),
    card_hash: card_hash,
    customer:  { email: '' }

More about Creating a Subscription.


Creating a Recipient

To create a recipient, so it can receive payments through split rules or transfers:

    bank_account: {
      bank_code:       '237',
      agencia:         '1935',
      agencia_dv:      '9',
      conta:           '23398',
      conta_dv:        '9',
      legal_name:      'Fulano da Silva',
      document_number: '00000000000000' # CPF or CNPJ
    transfer_enabled: false

More about Creating a Recipient.

Transfer Available Amout to Bank Account Manually

This is only needed if transfer_enabled is set to false. If set to true, transfer_interval and transfer_day will handle it automatically.

  PagarMe::Recipient.find(recipient_id).receive amount

Balance And Balance Operations

Checking Balance

  balance = PagarMe::Balance.balance
  balance.waiting_funds.amount # money to be received in your account
  balance.available.amount     # in your pagarme account
  balance.transferred.amount   # transferred to your bank account

Just that!

More about Balance

Checking Balance Operations

To access the history of balance operations:



  PagarMe::BalanceOperation.balance_operations 2, 50 # second page, 50 per page

More about Balance Operations

Checking Recipient Balance

  balance = PagarMe::Recipient.find(recipient_id).balance
  balance.waiting_funds.amount # money to be received in his account
  balance.available.amount     # in his pagarme account
  balance.transferred.amount   # transferred to his bank account

Just that!

More about Recipient Balance

Checking Recipient Balance Operations

To access the history of balance operations:



  PagarMe::Recipient.find(recipient_id).balance_operations 2, 50 # second page, 50 per page

More about Recipient Balance Operations

Request Bulk Anticipation

Checking limits


More about Checking Bulk Anticipation Limits

Requesting Bulk Anticipation

    timeframe:        :start,
    payment_date:, 12, 25),
    requested_amount: 10000 # in cents

More about Requesting Bulk Anticipation

Getting Bulk Anticipation

  PagarMe::BulkAnticipation.all page, count

More about Getting Bulk Anticipation


Getting Payable

  PagarMe::Payable.find 'payable_id'

More about Getting Payable

Querying Payables

  PagarMe::Payable.all page, count
  PagarMe::Payable.find_by status: 'paid'

More about Querying Payables

Querying Payables by Transaction

  transaction = PagarMe::Transaction.find 'transaction_id'

More about Payable Transactions

Validating Postback

You need to ensure that all received postback are sent by and not from anyone else, to do this, is very important to validate it.

You must do it using the raw payload received on post request, and check it signature provided in HTTP header X-Hub-Signature.

You can check it like this:

  PagarMe::Postback.valid_request_signature?(payload, signature)

Rails Example

If you are using Rails, you should do it your controller like this:

    class PostbackController < ApplicationController
      skip_before_action :verify_authenticity_token

      def postback
        if valid_postback?
          # Handle your code here
          # postback payload is in params

      def valid_postback?
        raw_post  = request.raw_post
        signature = request.headers['HTTP_X_HUB_SIGNATURE']
        PagarMe::Postback.valid_request_signature?(raw_post, signature)

      def render_invalid_postback_response
        render json: {error: 'invalid postback'}, status: 400


Undocumented Features

This gem is stable, but in constant development.

This README is just a quick abstract of it's main features.

You can easily browse it's source code to see all supported resources.

We will document everything while adding support to all resources listed in Full API Guide.

Feel free to help us to add support to features sending pull requests.



Add support to ElasticSearch Query DSL, so you can search your data optimally.

And document all the source code.


If you have any problem or suggestion please open an issue here.


Check here.