A Ruby gem for integrating with Przelewy24 (P24), a popular Polish payment gateway. This library provides a simple and intuitive interface for handling online payments through the Przelewy24 API v1.
- Transaction registration and verification
- Payment method discovery
- Transaction notification handling with signature verification
- Support for both sandbox and production environments
- Built-in authentication and request signing
- Comprehensive error handling
Add this line to your application's Gemfile:
gem 'p24'And then execute:
bundle installOr install it yourself as:
gem install p24Initialize the client with your Przelewy24 credentials:
client = P24::Client.new(
user: 'your_merchant_id',
secret_id: 'your_api_secret',
crc: 'your_crc_key',
base_url: 'https://sandbox.przelewy24.pl/api/v1', # Use production URL for live transactions
timeout: 30,
encoding: 'UTF-8',
debug: false
)
# Alternatively, you can use the Przelewy24 alias
client = Przelewy24.new(
user: 'your_merchant_id',
secret_id: 'your_api_secret',
crc: 'your_crc_key'
)user(required): Your Przelewy24 merchant IDsecret_id(required): Your API secret/passwordcrc(required): Your CRC key for request signingbase_url(optional): API endpoint URL (defaults to sandbox)timeout(optional): Request timeout in seconds (default: 30)encoding(optional): Character encoding (default: 'UTF-8')debug(optional): Enable debug output (default: false)
Verify your credentials and API connectivity:
response = client.test_access
puts response.error_code # Should be 0 for successful connectionCreate a new payment transaction:
response = client.transaction_register(
merchant_id: 12345,
pos_id: 12345,
session_id: 'unique_session_id',
amount: 1000, # Amount in grosze (1000 = 10.00 PLN)
currency: 'PLN',
description: 'Order #123',
email: 'customer@example.com',
country: 'PL',
language: 'pl',
url_return: 'https://yoursite.com/payment/return',
url_status: 'https://yoursite.com/payment/status'
)
# Get the payment token
token = response.token
# Redirect user to payment page
redirect_url = client.redirect_url(token)
# => "https://sandbox.przelewy24.pl/trnRequest/{token}"Verify transaction status after payment:
response = client.transaction_verify(
merchant_id: 12345,
pos_id: 12345,
session_id: 'unique_session_id',
amount: 1000,
currency: 'PLN',
order_id: 98765 # Received from P24 notification
)
puts response.error_code # 0 means successful verificationVerify incoming payment notifications from Przelewy24:
# In your webhook/callback endpoint
is_valid = client.transaction_notification(
merchant_id: params[:merchantId],
pos_id: params[:posId],
session_id: params[:sessionId],
amount: params[:amount],
origin_amount: params[:originAmount],
currency: params[:currency],
order_id: params[:orderId],
method_id: params[:methodId],
statement: params[:statement],
sign: params[:sign]
)
if is_valid
# Process successful payment
else
# Invalid signature - potential fraud attempt
endRetrieve available payment methods for your customers:
methods = client.payment_methods(
'pl', # Language
amount: 1000, # Optional: filter by amount
currency: 'PLN' # Optional: filter by currency
)
methods.each do |method|
puts "#{method.name} - #{method.status}"
endRegisters a new transaction and returns a token for payment redirection.
Verifies a completed transaction.
Validates the signature of a payment notification from P24.
Retrieves available payment methods.
Tests API credentials and connectivity.
Generates the payment page URL for a given token.
After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install.
Bug reports and pull requests are welcome on GitHub at https://github.com/DeVeLo/p24.
The gem is available as open source under the terms of the MIT License.