Ruby SDK

Create online checkouts and accept reader payments with the SumUp Ruby SDK.

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 install

Keep 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_url

Send 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_id

Online 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

Type to search…