Skip to main content

Server Libraries

Omise provides official server-side libraries for multiple programming languages, making it easy to integrate payment processing into your application. Our libraries handle API communication, authentication, request signing, and error handling, allowing you to focus on building your application.

Available Librariesโ€‹

Rubyโ€‹

The omise-ruby gem provides a Ruby interface to the Omise API with Rails integration and comprehensive error handling.

Pythonโ€‹

The omise-python library offers a Pythonic interface with type hints and async support.

PHPโ€‹

The omise-php library provides PSR-compliant code with Composer support.

Node.jsโ€‹

The omise-node library supports both promises and async/await patterns with TypeScript definitions.

.NETโ€‹

The Omise.Net library provides a modern C# implementation with LINQ support and async/await patterns.

Javaโ€‹

The omise-java library offers Java 8+ support with Optional and Stream APIs.

Goโ€‹

The omise-go library provides idiomatic Go code with goroutine support.

Elixirโ€‹

The omise-elixir library leverages Elixir's pattern matching and OTP features.

Key Featuresโ€‹

All Omise server libraries provide:

  • Secure Authentication: API key management and request signing
  • Comprehensive API Coverage: Access to all Omise API endpoints
  • Type Safety: Strong typing and validation where supported by the language
  • Error Handling: Structured error handling with detailed error messages
  • Idempotency: Support for idempotent requests to prevent duplicate charges
  • Testing Support: Test mode configuration for development
  • Webhook Verification: Tools for verifying webhook signatures
  • Documentation: Inline documentation and code examples

Common Operationsโ€‹

Creating a Chargeโ€‹

All libraries support creating charges with a token or source:

# Ruby
charge = Omise::Charge.create(amount: 100_000, currency: 'THB', card: 'tokn_test_123')
# Python
charge = omise.Charge.create(amount=100000, currency='THB', card='tokn_test_123')
// PHP
$charge = OmiseCharge::create(['amount' => 100000, 'currency' => 'THB', 'card' => 'tokn_test_123']);
// Node.js
const charge = await omise.charges.create({ amount: 100000, currency: 'THB', card: 'tokn_test_123' });

Managing Customersโ€‹

Create and manage customers for recurring payments:

// C#
var customer = await client.Customers.CreateAsync(new CreateCustomerRequest {
    Email = "customer@example.com",
    Description = "John Doe"
});
// Java
Customer customer = client.customers().create(new CustomerRequest()
    .email("customer@example.com")
    .description("John Doe"));
// Go
customer, err := client.Customers.Create(&omise.CreateCustomerRequest{
    Email:       "customer@example.com",
    Description: "John Doe",
})
# Elixir
{:ok, customer} = Omise.Customer.create(%{
  email: "customer@example.com",
  description: "John Doe"
})

Choosing a Libraryโ€‹

When selecting a server library, consider:

  1. Language Ecosystem: Choose the library that matches your backend language
  2. Framework Integration: Some libraries provide specific framework integrations (Rails, Django, Laravel, etc.)
  3. Async Support: If your application requires high concurrency, choose libraries with async support
  4. Type Safety: For large applications, consider languages with strong type systems (Java, C#, Go, TypeScript)
  5. Community: All libraries are actively maintained by Omise with community contributions

Getting Startedโ€‹

To get started with a specific library:

  1. Choose the library that matches your programming language
  2. Follow the installation instructions for your package manager
  3. Configure your API keys (secret key for server-side operations)
  4. Review the quick start guide for basic operations
  5. Explore advanced features and best practices

Authenticationโ€‹

All server libraries require your Omise API keys:

  • Secret Key: Used for server-side operations (never expose to clients)
  • Public Key: Used for client-side operations (tokenization only)
# Test keys (for development)
export OMISE_SECRET_KEY="skey_test_123456789"
export OMISE_PUBLIC_KEY="pkey_test_123456789"

# Live keys (for production)
export OMISE_SECRET_KEY="skey_live_123456789"
export OMISE_PUBLIC_KEY="pkey_live_123456789"
Security Best Practice

Never commit API keys to version control. Use environment variables or secure key management systems.

Error Handlingโ€‹

All libraries provide structured error handling:

  • Network Errors: Connection timeouts, DNS failures
  • API Errors: Invalid parameters, authentication failures
  • Business Logic Errors: Insufficient funds, card declined

Each library implements error handling using language-specific patterns (exceptions, error objects, Result types, etc.).

Testingโ€‹

All libraries support test mode for development:

  1. Use test API keys (prefix: skey_test_ and pkey_test_)
  2. Use test card numbers for successful and failed transactions
  3. Test webhooks using the test endpoint
  4. No real money is charged in test mode

Support and Resourcesโ€‹

Compliance and Securityโ€‹

All Omise libraries are designed with security in mind:

  • PCI DSS: Libraries help maintain PCI compliance by never handling raw card data
  • TLS 1.2+: All API communication uses modern encryption
  • Key Management: Secure handling of API credentials
  • Input Validation: Parameter validation to prevent injection attacks

Version Supportโ€‹

Omise maintains compatibility with:

  • Ruby: 2.6+ (including Ruby 3.x)
  • Python: 3.6+ (including Python 3.11+)
  • PHP: 7.2+ (including PHP 8.x)
  • Node.js: 12+ (Node.js 16+ recommended as 12.x reached EOL)
  • .NET: .NET Core 3.1+, .NET 5+, .NET 6+
  • Java: Java 8+ (including Java 17+)
  • Go: Go 1.16+ (including Go 1.20+)
  • Elixir: Elixir 1.10+ (including Elixir 1.14+)

Next Stepsโ€‹

Choose your programming language to get started:

Contributingโ€‹

All Omise libraries are open source and welcome contributions:

  1. Fork the repository on GitHub
  2. Create a feature branch
  3. Write tests for your changes
  4. Submit a pull request

See individual library repositories for contribution guidelines.