pagarme-ruby
Pagar.me Ruby library
Documentation
Getting Started
Install
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 Pagar.me Checkout
See our demo checkout.
More about how to use it here.
Transactions
Creating a Credit Card Transaction
To create a credit card transaction, you need a card_hash.
PagarMe::Transaction.new(
amount: 1000, # in cents
card_hash: card_hash # how to get a card hash: docs.pagar.me/capturing-card-data
).charge
More about Creating a Credit Card Transaction.
Creating a Boleto Transaction
transaction = PagarMe::Transaction.new(
amount: 1000, # in cents
payment_method: 'boleto'
)
transaction.charge
transaction.boleto_url # => boleto's URL
transaction. # => 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:
PagarMe::Transaction.new(
amount: 1000, # in cents
card_hash: card_hash, # how to get a card hash: docs.pagar.me/capturing-card-data
split\_rules: [
{ recipient_id: recipient_id_1, percentage: 50 },
{ recipient_id: recipient_id_2, percentage: 50 }
]
).charge
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
PagarMe::Plan.new(
amount: 4990,
days: 30,
name: 'Gold Plan'
).create
More about Creating a Plan.
Creating a Subscription
PagarMe::Subscription.new(
plan: PagarMe::Plan.find_by_id('1234'),
card_hash: card_hash,
customer: { email: '[email protected]' }
).create
More about Creating a Subscription.
Recipients
Creating a Recipient
To create a recipient, so it can receive payments through split rules or transfers:
PagarMe::Recipient.create(
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
Paginating:
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
Paginating:
PagarMe::Recipient.find(recipient_id).balance_operations 2, 50 # second page, 50 per page
More about Recipient Balance Operations
Request Bulk Anticipation
Checking limits
PagarMe::Recipient.default.bulk_anticipations_limits
More about Checking Bulk Anticipation Limits
Requesting Bulk Anticipation
PagarMe::Recipient.default.bulk_anticipate(
timeframe: :start,
payment_date: Date.new(2016, 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
Payables
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'
transaction.payables
More about Payable Transactions
Validating Postback
You need to ensure that all received postback are sent by Pagar.me 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
else
render_invalid_postback_response
end
end
protected
def valid_postback?
raw_post = request.raw_post
signature = request.headers['HTTP_X_HUB_SIGNATURE']
PagarMe::Postback.valid_request_signature?(raw_post, signature)
end
def render_invalid_postback_response
render json: {error: 'invalid postback'}, status: 400
end
end
request.raw_post
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.
Thanks!
TODO
Add support to ElasticSearch Query DSL, so you can search your data optimally.
And document all the source code.
Support
If you have any problem or suggestion please open an issue here.
License
Check here.