TapPay Ruby Gem
A Ruby library for integrating with TapPay payment services. This gem provides a simple and elegant way to process payments, refunds, and handle instalments through TapPay's payment gateway.
Features
- Multiple payment methods:
- Credit card payments (one-time and tokenized)
- Instalment payments (3, 6, 12, 18, 24, 30 months)
- Line Pay
- JKO Pay
- Apple Pay
- Flexible merchant identification:
- Support for both
merchant_idandmerchant_group_id - Automatic fallback handling
- Priority-based merchant ID resolution
- Support for both
- Universal refund processing for all payment methods
- Transaction status queries
- Comprehensive error handling
- Configurable sandbox/production environments
- Environment-based endpoints management
- Card holder information management
Installation
Add this line to your application's Gemfile:
gem 'tappay_ruby'And then execute:
$ bundle installOr install it yourself as:
$ gem install tappay_rubyConfiguration
There are several ways to configure the gem:
Option 1: Using merchant_id
# Using merchant_id with optional payment-specific merchant IDs
Tappay.configure do |config|
config.partner_key = 'YOUR_PARTNER_KEY'
config.merchant_id = 'YOUR_MERCHANT_ID'
config.jko_pay_merchant_id = 'YOUR_JKO_PAY_MERCHANT_ID' # Optional, falls back to merchant_id if not set
config.line_pay_merchant_id = 'YOUR_LINE_PAY_MERCHANT_ID' # Optional, falls back to merchant_id if not set
endOption 2: Using merchant_group_id
# Using merchant_group_id (takes precedence over all other merchant IDs)
Tappay.configure do |config|
config.partner_key = 'YOUR_PARTNER_KEY'
config.merchant_group_id = 'YOUR_MERCHANT_GROUP_ID'
# When merchant_group_id is set, all other merchant IDs will be ignored
endMerchant ID Resolution
The gem uses the following priority order when resolving merchant IDs:
-
If
merchant_group_idis set (either in configuration or options):- Uses
merchant_group_idfor all payment types - Ignores all other merchant IDs (including specific ones for Line Pay, JKO Pay, etc.)
- Uses
-
If
merchant_group_idis not set:- For Line Pay: Uses
line_pay_merchant_idif set, otherwise falls back tomerchant_id - For JKO Pay: Uses
jko_pay_merchant_idif set, otherwise falls back tomerchant_id - For Instalments: Uses
instalment_merchant_idif set, otherwise falls back tomerchant_id - For other payment types: Uses
merchant_id
- For Line Pay: Uses
Usage
Credit Card Payment
# One-time payment
result = Tappay::CreditCard::Pay.by_prime(
prime: 'prime_from_tappay_sdk',
amount: 1000,
details: 'Order Details',
cardholder: {
phone_number: '0912345678',
name: 'Test User',
email: 'test@example.com'
}
)
# Instalment payment (3-30 months)
result = Tappay::CreditCard::Instalment.by_prime(
prime: 'prime_from_tappay_sdk',
amount: 1000,
instalment: 12, # 12 months instalment
details: 'Order Details',
cardholder: {
phone_number: '0912345678',
name: 'Test User',
email: 'test@example.com'
}
)Line Pay
# Create Line Pay payment
result = Tappay::LinePay::Pay.new(
prime: 'line_pay_prime',
amount: 1000,
details: 'Order Details',
frontend_redirect_url: 'https://example.com/line_pay/result',
backend_notify_url: 'https://example.com/line_pay/notify',
cardholder: {
phone_number: '0912345678',
name: 'Test User',
email: 'test@example.com'
}
).executeRefund Processing
Process refunds for any payment method:
# Process a full refund
result = Tappay::Refund.new(
rec_trade_id: 'TRANSACTION_ID'
).execute
# Process a partial refund
result = Tappay::Refund.new(
rec_trade_id: 'TRANSACTION_ID',
amount: 1000 # Optional: specify amount for partial refund
).executeJKO Pay
Configuration
Tappay.configure do |config|
config.partner_key = 'YOUR_PARTNER_KEY'
config.merchant_id = 'YOUR_MERCHANT_ID'
config.merchant_group_id = 'YOUR_MERCHANT_GROUP_ID' # Optional, mutually exclusive with merchant_id
config.jko_pay_merchant_id = 'YOUR_JKO_PAY_MERCHANT_ID' # Optional, falls back to merchant_id if not set
config.sandbox = true # Set to false for production
endProcessing a JKO Pay Payment
payment_options = {
prime: 'jko_pay_prime',
amount: 1000,
details: 'Some item',
frontend_redirect_url: 'https://your-site.com/jko_pay/result',
backend_notify_url: 'https://your-site.com/jko_pay/notify',
cardholder: {
phone_number: '0912345678',
name: 'Test User',
email: 'test@example.com'
}
}
payment = Tappay::JkoPay::Pay.new(payment_options)
result = payment.executeTransaction Query
Query transaction records with required time range:
# Query transactions within a specific time range
result = Tappay::Transaction::Query.new(
time: {
start_time: 1706198400, # Unix timestamp for start time
end_time: 1706284800 # Unix timestamp for end time
},
order_number: 'ORDER123', # Optional: filter by order number
records_per_page: 50, # Optional: default is 50
page: 0, # Optional: default is 0
order_by: { # Optional: sort results
attribute: 'time',
is_descending: true
}
).execute
# Access the results
result[:trade_records].each do |record|
puts "Transaction ID: #{record[:rec_trade_id]}"
puts "Amount: #{record[:amount]}"
puts "Status: #{record[:record_status]}"
endNote: The time parameter with both start_time and end_time is required for querying transactions.
Error Handling
The gem provides comprehensive error handling:
begin
result = Tappay::CreditCard::Pay.by_prime(
prime: 'prime_from_tappay_sdk',
amount: 100,
order_number: 'ORDER-123'
)
rescue Tappay::ValidationError => e
# Handle validation errors (e.g., missing required fields)
puts "Validation error: #{e.message}"
rescue Tappay::APIError => e
# Handle API errors (e.g., invalid prime, insufficient balance)
puts "API error: #{e.message}"
rescue Tappay::Error => e
# Handle other TapPay errors
puts "TapPay error: #{e.message}"
endDevelopment
After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/7a6163/tappay.
License
The gem is available as open source under the terms of the MIT License.