Library Updates Required

📖 Overview

Omise's official libraries used to rely on certificate pinning, a security technique that hardcodes the expected server certificate inside the library itself. Certificate pinning is no longer considered best practice, so it has been removed from Omise's libraries — but any copy of a library still running the old, pinned version will stop trusting Omise's servers once the pinned certificate rotates. In practice, that means API requests — including charge creation — can fail without warning if you're running an outdated library.

There's a second, related issue: Omise's TLS certificate chain roots to a DigiCert G2 certificate. Most systems already trust it, but older or infrequently patched servers may not, and will need it installed manually.

Check and fix your version in three steps

1. Find your library's current version in your project's dependency file (see the FAQ further down this page if you're not sure where to look).
2. Compare it against the minimum required version for your library.
3. If you're below it, follow the update instructions for your language, then verify the fix.

Diagnose before you fix

If you want to confirm the actual problem before changing anything, inspect the certificate chain your server currently sees from a terminal:

openssl s_client -connect api.omise.co:443 -showcerts

Look at the certificate chain in the output. A chain that terminates in a root your system doesn't recognize, or a handshake that fails outright, confirms a certificate trust issue rather than something else (a network/firewall block, a DNS problem, or an application-level bug). This command works the same regardless of which language or library you use, since it tests the underlying TLS connection directly.

🛠️ Minimum required library versions

The following table lists the minimum required version of each library, its release date, and a link to its full changelog. If you're not already on at least the listed version, upgrade before it affects your integration.

A library not listed here is not known to be affected. Check this page periodically, since that can change with future releases.

🛠️ How to update each library

Each section shows a basic update example. Your build setup may differ, and any method that gets you to at least the minimum required version works.

Jump to: Android · iOS · Go · Java · PHP · Python · Ruby

SDK: Android

Update the version in your app's build.gradle:

dependencies {
    implementation 'co.omise:omise-android:3.0.0'
}

• TLS 1.1 dropped (2.6.5 → 2.6.6): use TLS 1.2 or higher going forward. See Omise's internal TLS deprecation notice for background, or contact support@omise.co if you need the details and don't have access to it.

SDK: iOS

See the upgrade steps for Swift Package Manager. The 4.x branch no longer supports iOS 10 or Swift 4.

Library: Go

Update to the latest version:

go get github.com/omise/omise-go

Update to a specific version:

go get github.com/omise/omise-go@v1.0.5

Library: Java

Update the version in your app's build.gradle:

dependencies {
    implementation 'co.omise:omise-java:3.1.1'
}

• No breaking changes (4.x → latest): the upgrade should be smooth.
• Breaking changes (3.1.1 → 4.0): see the migration guide. If you can't move to the latest version yet, upgrade to at least 3.1.1.

Library: PHP

Update the version in composer.json to at least the minimum required version, then run:

composer update omise-php

Upgrading from any 2.x version is straightforward with no breaking changes. Use a non-EOL PHP version if you can.

Library: Python

Update the version in requirements.txt to at least the minimum required version, then run:

pip install --upgrade omise

Upgrading from any version is straightforward with no breaking changes. Use a non-EOL Python version if you can.

Library: Ruby

Update the version in your Gemfile to at least the minimum required version, then run:

bundle update omise

Upgrading from any version is straightforward with no breaking changes. Use a non-EOL Ruby version if you can.

🛠️ If you're not using an Omise library

The certificate-pinning issue only affects the libraries listed here. But the DigiCert root certificate issue is library-agnostic — it affects the TLS connection itself, so it can affect you even if you call the Omise API directly with curl, a raw HTTP client, or a language/framework not covered on this page.

If that's your setup: the minimum-version table and per-library steps don't apply, but the diagnostic command and the server root certificate update further down this page still do. Run the diagnostic first to confirm whether this is actually your issue.

🛠️ Updating PHP-Based plugins

EC-CUBE

See the official EC-CUBE plugin documentation for installation and configuration details.

Magento

See the official Magento plugin documentation for installation and configuration details.

OpenCart

See the official OpenCart plugin documentation for installation and configuration details.

PrestaShop

See the official PrestaShop plugin documentation for installation and configuration details.

WooCommerce

See the official WooCommerce plugin documentation for installation and configuration details.

🛠️ Updating your server's root certificate

If API requests still fail after your library is up to date, your server's trusted root certificates are likely out of date. Omise's certificate chain roots to DigiCert Global Root G2 — see DigiCert's root certificate update advisory for background.

On Linux

Linux keeps CA certificates in /etc/ssl/certs/, and a normal OS update refreshes them automatically. To update manually:

RHEL and clones

1. Create /etc/pki/ca-trust/source/anchors if it doesn't already exist.
2. Download the DigiCert Global Root G2 certificate.
3. Copy the downloaded PEM file into /etc/pki/ca-trust/source/anchors.
4. Add it to the system's trust store:

sudo update-ca-trust extract

Debian and derivatives

1. Create /usr/local/share/ca-certificates if it doesn't already exist.
2. Download the DigiCert Global Root G2 certificate.
3. Copy the downloaded PEM file into /usr/local/share/ca-certificates, renaming it with a .crt extension.
4. Add it to the system's trust store:

sudo update-ca-certificates

On macOS

A normal macOS update refreshes root certificates automatically. To add the certificate manually, download the DigiCert Global Root G2 certificate, then add it to the System keychain and trust it for SSL, adjusting the filename in the command that follows to match what you downloaded:

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain path/to/downloaded-certificate.crt

On Windows

A normal OS update automatically refreshes root certificates. To update manually:

Step 1: Open a Command Prompt as Administrator.

Step 2: Navigate to a working folder, for example C:\Temp.

Step 3: Run the following command, which downloads the current root certificate updates into a file named Rootstore.sst in that folder:

CertUtil --generateSSTFromWU Rootstore.sst

Step 4: If the target server has no internet access, copy Rootstore.sst from that folder to the offline machine and import it there instead of running the command directly.

🛠️ Confirm it's fixed

After updating your library, your server's root certificates, or both, confirm the fix before moving on:

1. Send a test request — a charge creation in test mode is the most direct check, since that's the request most likely to have been failing.
2. If it succeeds without a certificate or connection error, you're done.
3. If it still fails the same way, work through whichever of the two fixes you haven't done yet — most integrations only need the library update, but some servers also need the root certificate update.
4. If it still fails after both, check status.omise.co to rule out a wider incident, then contact Omise support with the exact error message.

❓ FAQ

Q: How do I check which library version I'm currently running? A: Check your dependency manifest (composer.json, requirements.txt, Gemfile, build.gradle, or your go.mod/Podfile/package manager of choice) for the pinned Omise library version, or inspect the installed package directly with your language's package manager.

Q: My library isn't listed in the minimum versions table. Am I affected? A: Not that Omise is aware of, but check this page periodically, since the list can change as new releases ship.

Q: I updated my library and requests are still failing. What else should I check? A: Update your server's trusted root certificates next — see Updating Your Server's Root Certificate. Outdated server-side trust stores are the next most common cause.

Q: Do I need to do anything if I only use a hosted checkout or redirect flow, with no library installed? A: No — this only applies to integrations using an Omise-provided library or plugin.

Q: I call the Omise API directly (curl, a raw HTTP client, or a language not listed here) — does this affect me? A: The library-version issue doesn't, since it's specific to Omise's own libraries. The server root certificate issue can still affect you, since it's about the TLS connection itself. See If You're Not Using an Omise Library.

Q: My app is on the latest Omise SDK version, but users on older phones still get certificate errors. Why? A: Android and iOS validate certificates against the device's own OS-level trust store, separate from your app's SDK version. A device on a very old OS release may not trust a current root certificate no matter what SDK version you ship. There's no in-app fix for this beyond encouraging affected users to update their device OS.

Q: What actually breaks if I don't update? A: API requests — including charge creation — can start failing without warning once the certificate your library pinned to is no longer valid.

👉 Related content

• Credit Card Payments
• Collecting Cards
• Plugins, Libraries & SDKs
• Omise API status

Have more questions? Contact Omise support directly.