The sumup gem(Opens in a new tab) provides Ruby clients for SumUp APIs, response models, and RBS signatures. Request bodies accept keyword arguments, hashes, or models from SumUp::Types.
Before you begin
You need Ruby 3.3 or later, a sandbox merchant account, and a secret API key. Set SUMUP_API_KEY and SUMUP_MERCHANT_CODE in your server environment. You can also pass an OAuth access token through the client’s api_key option to act on behalf of another merchant.
Install the SDK
Add the SDK to your application’s Gemfile:
gem "sumup"Install the gem with Bundler:
bundle installKeep your credentials and the SDK calls on your server.
Create an online checkout
Create a Hosted Checkout and retrieve its payment URL:
require "sumup"
require "securerandom"
client = SumUp::Client.new(api_key: ENV.fetch("SUMUP_API_KEY"))
checkout = client.checkouts.create(
checkout_reference: SecureRandom.uuid,
amount: 19.99,
currency: "EUR",
merchant_code: ENV.fetch("SUMUP_MERCHANT_CODE"),
description: "Order 1234",
hosted_checkout: {enabled: true}
)
puts checkout.hosted_checkout_urlSend the customer to hosted_checkout_url to pay. Retrieve the checkout on your server to verify its status before fulfilling the order.
Start a reader checkout
Follow the Cloud API setup and pairing instructions first, including its affiliate key requirements. Set SUMUP_READER_ID to the paired reader’s ID.
Start a checkout for EUR 19.99 on that reader:
require "sumup"
client = SumUp::Client.new(api_key: ENV.fetch("SUMUP_API_KEY"))
checkout = client.readers.create_checkout(
merchant_code: ENV.fetch("SUMUP_MERCHANT_CODE"),
reader_id: ENV.fetch("SUMUP_READER_ID"),
total_amount: {currency: "EUR", minor_unit: 2, value: 1999},
description: "Order 1234"
)
puts checkout.data.client_transaction_idOnline checkout amounts use major units (19.99 EUR); reader amounts use minor units (1999 cents). The response identifies the reader checkout. Follow reader checkout status notifications to determine the result and verify the transaction before fulfilling the order.
Test your integration
Use your sandbox merchant account to test online payments or follow the in-person payment testing guide. Verify successful, failed, and canceled payments before going live.
Next steps
- Use the API reference for Ruby samples and request fields.
- Review error handling and request options(Opens in a new tab).
- See the Ruby SDK examples(Opens in a new tab) for OAuth and signed event handling.