---
title: Ruby
slug: sdks/server-sdks/ruby
excerpt: Pine Labs Server SDK for Ruby.
hidden: false
sidebar_order: 6
metadata:
  title: "Ruby SDK — Official Ruby Gem | Pine Labs Gateway"
  description: "Official Pine Labs Ruby SDK. Install via gem, authenticate, and integrate payment APIs in your Ruby/Rails backend with idiomatic Ruby patterns."
  keywords: "Ruby SDK, Pine Labs Ruby, Ruby gem, Rails payment SDK, Ruby backend integration, Ruby payment library"
  robots: index
---
`pinelabs` is the official Ruby SDK for the **Pine Labs Online Payment Gateway** (Plural). It is generated from the same OpenAPI spec that powers this documentation, so every operation, request, and response model is fully typed.

- **Gem:** [`pinelabs`](https://rubygems.org/gems/pinelabs) on RubyGems
- **Runtime:** Ruby ≥ 3.3

## Install

<CodeTabs>
  <Tab label="Bundler">
    ```ruby
    # Gemfile
    gem "pinelabs"
    ```
    ```bash
    bundle install
    ```
  </Tab>
  <Tab label="gem">
    ```bash
    gem install pinelabs
    ```
  </Tab>
</CodeTabs>

## Quickstart

The Pine Labs API uses **OAuth2 with the `client_credentials` grant**. Exchange your credentials for an access token, then pass it to `Pinelabs::Client`.

```ruby
require "pinelabs"

base_url = "https://pluraluat.v2.pinepg.in" # UAT
# base_url = "https://api.pluralpay.in"     # Production

# 1. Get a token (the auth call itself does not need a bearer token)
auth = Pinelabs::Client.new(token: "", base_url: base_url)

token_response = auth.authentication.generate_token(
  grant_type: "client_credentials",
  client_id: ENV["PINELABS_CLIENT_ID"],
  client_secret: ENV["PINELABS_CLIENT_SECRET"]
)

# 2. Build an authenticated client
client = Pinelabs::Client.new(
  token: token_response.access_token,
  base_url: base_url
)

# 3. Call any operation
order = client.orders.create_order(
  merchant_order_reference: "order-001",
  order_amount: { value: 50_000, currency: "INR" } # ₹500.00
)

puts order
```

## Environments

| Environment | Base URL                            |
| ----------- | ----------------------------------- |
| UAT         | `https://pluraluat.v2.pinepg.in`    |
| Production  | `https://api.pluralpay.in`          |

Pass the URL via `base_url:`. The default (when omitted) points to Production.

## Sub-clients

`Pinelabs::Client` exposes one sub-client per API tag via accessor methods:

| Sub-client                                  | Purpose                                            |
| ------------------------------------------- | -------------------------------------------------- |
| `client.authentication`                     | OAuth token generation                             |
| `client.orders`                             | Create, capture, cancel, and fetch orders          |
| `client.refunds`                            | Create and look up refunds                         |
| `client.settlements`                        | Settlement reports + UTR lookup                    |
| `client.checkout`                           | Hosted-checkout related operations                 |
| `client.payment_links`                      | Single + bulk payment links                        |
| `client.card_payments`                      | Direct card payment + OTP flow                     |
| `client.bnpl`                               | Buy-Now-Pay-Later eligibility and flows            |
| `client.convenience_fee`                    | Convenience-fee config and computation             |
| `client.e_challans`                         | Government e-challan integration                   |
| `client.apple_pay`                          | Apple Pay session + decryption                     |
| `client.international_payments`             | Cross-border (DCC / MCC) payments                  |
| `client.customers`                          | Customer profile management                        |
| `client.tokenization`                       | Card / network tokenization                        |
| `client.payouts`                            | Payouts: balance, create, cancel, list             |
| `client.subscriptions_plans`                | Recurring-billing plans                            |
| `client.subscriptions_subscriptions`        | Subscription lifecycle                             |
| `client.subscriptions_presentations`        | Subscription debit presentations                   |
| `client.pay_by_points`                      | Loyalty / points-based payments                    |
| `client.affordability_suite`                | EMI / offer eligibility                            |
| `client.split_settlements`                  | Split settlements between sub-merchants            |

For the full operation list and request/response schemas, see the [API reference](/docs/api-reference).

## Error handling

The SDK raises typed errors. Catch `Pinelabs::Errors::ResponseError` to inspect HTTP-level details:

```ruby
begin
  client.orders.get_order_by_id(order_id: "missing")
rescue Pinelabs::Errors::ResponseError => e
  puts "HTTP #{e.status_code}: #{e.body}"
rescue Pinelabs::Errors::ApiError => e
  puts "Error: #{e.message}"
end
```

## Source & support

- RubyGems: [pinelabs](https://rubygems.org/gems/pinelabs)
- GitHub: [github.com/plural-pinelabs/pinelabs-ruby](https://github.com/plural-pinelabs/pinelabs-ruby)
- API reference: [/docs/api-reference](/docs/api-reference)