> This is Payabli documentation. For a complete page index, fetch https://docs.payabli.com/llms.txt — append .md to any page URL for lightweight markdown. For section-level indexes, query parameters, and other AI-optimized access methods, see https://docs.payabli.com/ai-agents.md

# Use the Ruby SDK

> Learn how to install and use the Ruby SDK to develop apps

Payabli offers an official Software Development Kit (SDK) for the Ruby programming language.
The official Ruby SDK can be installed in your projects to support app development and provide type safety when calling Payabli's APIs.
Most development environments can use the SDK to generate code suggestions and inline documentation.
See the [`payabli`](https://rubygems.org/gems/payabli/) package for more information.

## Dependencies

Before you begin, make sure you have the following installed on your machine:

* [bundler](https://bundler.io/)
* [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)

## Use the SDK

This section shows you how to install and use the Payabli SDK in a new Ruby project.
The example code shows how to use the SDK to make a transaction with the `money_in.getpaidv_2` method.
The `money_in.getpaidv_2` method calls the [POST /v2/MoneyIn/getpaid](/developers/api-reference/moneyinV2/make-a-transaction) endpoint.
See the [SDK reference](https://github.com/payabli/sdk-ruby/blob/main/reference.md) for a full list of methods.

Method names in the SDK correspond to endpoint names in the API reference.
For example: the `notification.add_notification` method calls the [POST Notification](/developers/api-reference/notification/add-notification) endpoint.

#### Create a new Ruby project

Open your terminal and run the following commands to create a new Ruby project:

```bash
mkdir my-payabli-app
cd my-payabli-app
```

#### Initialize Bundler

Create a `Gemfile` to manage your dependencies:

```bash
bundle init
```

#### Install the SDK

Add the Payabli SDK to your `Gemfile`:

```bash
bundle add payabli
```

#### Create a new file

Create a new file called `main.rb` in the root of your `my-payabli-app` directory:

```bash
touch main.rb
```

Open the `main.rb` file in your code editor.

#### Make a transaction

### Use the Ruby SDK with OAuth

/// Import the SDK

Import the Payabli SDK to make it available in your code.
/// Initialize the client

Create an authenticated client instance with your OAuth2 client ID and client secret.
This client has methods that call Payabli's API endpoints.
The `base_url` parameter specifies which environment to use.
Use `Payabli::Environment::SANDBOX` for testing and `Payabli::Environment::PRODUCTION` for production.
/// Define the entrypoint

Define your entrypoint. Get this value from your Payabli account.
/// Build the payment request

Construct a request object that contains all the necessary fields to process a transaction. Include payment details, a payment method, and customer data.
/// Execute the transaction

Call `money_in.getpaidv_2()` to process the transaction. The client calls Payabli's `POST /v2/MoneyIn/getpaid` endpoint.
/// Show the result

Print key fields from the response to confirm the transaction succeeded.

```ruby
# main.rb
require 'payabli'

client = Payabli::Client.new(
    client_id: "REPLACE_WITH_YOUR_CLIENT_ID",
    client_secret: "REPLACE_WITH_YOUR_CLIENT_SECRET",
    base_url: Payabli::Environment::SANDBOX
)

entry_point = "REPLACE_WITH_YOUR_ENTRYPOINT"

request_params = {
  customer_data: {
    customer_id: 4440
  },
  entry_point: entry_point,
  ipaddress: "255.255.255.255",
  payment_details: {
    service_fee: 0.0,
    total_amount: 100.0
  },
  payment_method: {
    cardcvv: "999",
    cardexp: "02/27",
    card_holder: "Kassiane Cassian",
    cardnumber: "4111111111111111",
    cardzip: "12345",
    initiator: "payor",
    method: "card"
  }
}

result = client.money_in.getpaidv_2(**request_params)

puts "Reason: #{result.reason}"
puts "Transaction ID: #{result.data.payment_trans_id}"
puts "Auth code: #{result.data.response_data.authcode}"
```

### Use the Ruby SDK with an API key

/// Import the SDK

Import the Payabli SDK to make it available in your code.
/// Initialize the client

Create an authenticated client instance with your API key.
This client has methods that call Payabli's API endpoints.
The `base_url` parameter specifies which environment to use.
Use `Payabli::Environment::SANDBOX` for testing and `Payabli::Environment::PRODUCTION` for production.
/// Define the entrypoint

Define your entrypoint. Get this value from your Payabli account.
/// Build the payment request

Construct a request object that contains all the necessary fields to process a transaction. Include payment details, a payment method, and customer data.
/// Execute the transaction

Call `money_in.getpaidv_2()` to process the transaction. The client calls Payabli's `POST /v2/MoneyIn/getpaid` endpoint.
/// Show the result

Print key fields from the response to confirm the transaction succeeded.

```ruby
# main.rb
require 'payabli'

client = Payabli::Client.new(
    api_key: "REPLACE_WITH_YOUR_API_KEY",
    base_url: Payabli::Environment::SANDBOX
)

entry_point = "REPLACE_WITH_YOUR_ENTRYPOINT"

request_params = {
  customer_data: {
    customer_id: 4440
  },
  entry_point: entry_point,
  ipaddress: "255.255.255.255",
  payment_details: {
    service_fee: 0.0,
    total_amount: 100.0
  },
  payment_method: {
    cardcvv: "999",
    cardexp: "02/27",
    card_holder: "Kassiane Cassian",
    cardnumber: "4111111111111111",
    cardzip: "12345",
    initiator: "payor",
    method: "card"
  }
}

result = client.money_in.getpaidv_2(**request_params)

puts "Reason: #{result.reason}"
puts "Transaction ID: #{result.data.payment_trans_id}"
puts "Auth code: #{result.data.response_data.authcode}"
```

#### Run the app

Run the app with the following command:

```bash
ruby main.rb
```

#### Check the result

Check the console output for the result of the transaction.
A successful transaction returns output like this:

```txt
    Reason: Approved
    Transaction ID: 255-9242c1dd69ac44f292c44be7a995e8b1
    Auth code: TAS815
```

In production, we recommend that you pass a stored method ID to the `payment_method` object instead of card details.
See more information in [Tokenization Overview](/guides/platform-tokenization-overview).

## SDK example app

The SDK example app is a basic web app built with the Payabli Ruby SDK.
It shows how to manage customers and use the temporary token flow with the SDK.
The code is publicly available in the [example repository](https://github.com/payabli/examples/tree/main/sdk/ruby-sdk).

![customer creation page of SDK example app](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/payabli.docs.buildwithfern.com/d440856d350fd1d5a41c108ca9145534f79f17f2e3a0bca8038ba370ee594b83/images/sdk-example-app.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260905%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260905T174742Z&X-Amz-Expires=604800&X-Amz-Signature=802ecc0cc9a1525db5dbbbfb484a2911b5e6e69e5b72c5d251dc6d2790a0db10&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

### Set up the app

Follow these steps to set up the SDK example app on your local machine:

#### Clone the repository

Open your terminal and run the following command to clone the SDK example app repository:

```bash
git clone https://github.com/payabli/examples
```

#### Navigate to the app directory

In your terminal, navigate to the directory containing the SDK example app:

```bash
cd examples/sdk/ruby-sdk
```

#### Install Bundler dependencies

Install the project dependencies with Bundler:

```bash
bundle install
```

#### Copy the environment template

Copy the `.env.template` file to a new file called `.env`:

```bash
cp .env.template .env
```

#### Fill in your environment variables

Open the `.env` file in your code editor. Set `PAYABLI_KEY` to a private API token, `PAYABLI_ENTRY` to your Payabli entrypoint, and `PAYABLI_PUBLIC_TOKEN` to a public API token:

```bash
  # your Payabli Private API token
  PAYABLI_KEY="o.Oim...Mekgjw="
  # your Payabli entrypoint
  PAYABLI_ENTRY="41xxxxxa7e"
  # your Payabli Public API token
  PAYABLI_PUBLIC_TOKEN="o.Oim...Mekgjw="
```

#### Start the development server

Run this command to start the development server, and open the app in your browser:

```bash
bundle exec ruby app.rb
```

### Use the app

The SDK example app has three pages:

1. **Create Customer** - Create a new customer in the Payabli entrypoint.
2. **List Customers** - View a list of all customers in the Payabli entrypoint.
3. **Make Transaction** - Make a transaction using the temporary token flow.

#### Create customer

The **Create Customer** page has a form that allows you to create a new customer.
Fill in the form with the customer's information and click the "Create" button.
If the customer is created successfully, a green success message appears below the button.

#### List customers

The **List Customers** page has a table of all customers in the entrypoint.
You can view the customer's information, including their name, email address, and ZIP Code.
Click the "X" button on the right side of a customer's row to delete the customer.
If the customer is deleted successfully, the row is removed from the table.

#### Make transaction

The **Make Transaction** page contains an EmbeddedMethod UI component using the temporary token flow.
Fill in the form with payment information and click the "Process" button when the payment information is valid.
The app performs these steps:

1. The embedded component saves the payment method as a temporary token and sends it to the server.
2. The server converts the temporary token to a permanent token with the **POST TokenStorage/add** endpoint.
3. The server uses the permanent token to make a transaction with the **POST /v2/MoneyIn/getpaid** endpoint.

If everything is successful, a green success message appears below the embedded component.
See [Extend embedded components with the temporary token flow](/guides/platform-developer-tokenization-temp-flow) for more information.