API Versioning

Quick Reference

• Latest API Version: 2019-05-29
• Available Versions: 2019-05-29, 2017-11-02, 2015-11-17, 2014-07-27
• Version Header: Omise-Version
• Version Management: Independent for Test and Live modes
• Breaking Changes: Require new API version
• Backwards Compatible: Applied automatically

Overview

Omise regularly releases new features to the service. These updates are categorized into two types to ensure stability and predictability for merchant integrations:

• Non-breaking changes that Omise automatically applies to your account
• Breaking changes that require a new API version

The API versioning system allows you to control when and how you adopt new features, ensuring your integration remains stable while giving you access to the latest capabilities when you're ready.

Important: You can manage Test mode and Live mode API versions independently, allowing you to test new versions safely before deploying to production.

Available API Versions

Currently, four API versions are available:

• 2019-05-29 (latest)
• 2017-11-02
• 2015-11-17
• 2014-07-27

Each version represents a snapshot of the API at a specific point in time. Newer versions include additional features and improvements while maintaining backward compatibility within the version. We may occasionally release backward-compatible updates to legacy API versions to address critical issues or add select features.

Types of Changes

Backward Compatible Changes

The following changes can be implemented without requiring a version update and are automatically applied to your account:

API Endpoint Changes

• Adding new API endpoints: New functionality becomes available without affecting existing integrations
• Adding optional headers or request parameters: Existing integrations continue to work while new parameters provide additional functionality
• Adding response headers and parameters: Additional data becomes available in responses without breaking existing parsing logic

Response Structure Changes

• Modifying the order of properties: Response properties may be reordered without affecting functionality
• Changing response property from null to intended type: Properties that previously returned null may start returning their proper data type (e.g., null to object)
• Adding new properties to responses: Additional data fields become available in API responses

Webhook Changes

• Adding new event types: New webhook events for new features are introduced (ensure your webhook endpoint can handle unfamiliar event types gracefully)

Breaking Changes

The following modifications require a new API version and cannot be applied automatically:

Parameter and Header Changes

• Adding new required parameters: New mandatory fields in headers or request parameters
• Removing or renaming request parameters: Existing parameter names or structures are modified
• Removing or renaming headers: Required or optional headers are changed

Response Changes

• Removing or renaming response properties: Existing response fields are modified or removed
• Modifying parameter or property types: Data types of request parameters or response properties are changed

Endpoint and Authentication Changes

• Removing API endpoints: Existing endpoints are deprecated and removed
• Changing authentication requirements: Authentication methods or requirements are modified

Webhook Changes

• Removing webhook event types: Existing webhook events are discontinued

Note: We must notify merchants in advance if we need to implement breaking changes to an existing API version for security concerns.

Version Management

Setting Account API Version

You can update your Test mode and Live mode API versions independently from the dashboard. Independent version control allows you to:

• Test new API versions in development without affecting production
• Gradually migrate to newer versions at your own pace
• Maintain stable production environments while exploring new features

Steps to View the Account API Version

1. Log in to your dashboard.

   

2. Click the account icon.

   

3. Click API Versions

   

4. View the API version as shown in the example.

   

To view the API version from the command line, run:

curl https://api.omise.co/account \
  -u $OMISE_SECRET_KEY:

Setting Per-Request API Version

For testing and gradual migration purposes, you can specify an API version for individual requests using the Omise-Version header. This header takes precedence over your account's default version.

Example Usage

curl https://api.omise.co/account \
  -H "Omise-Version: 2019-05-29" \
  -u $OMISE_SECRET_KEY:

Benefits of Per-Request Versioning

• Safe testing: Test new API versions without changing your account settings
• Gradual migration: Migrate individual API calls one at a time
• Version comparison: Compare responses between different API versions
• Rollback capability: Quickly revert to previous versions if issues arise

Best Practices for Merchants

Build Resilient Integrations

Handle Unknown Fields

• Design for flexibility: Build your integration to handle unknown fields in API responses
• Ignore unexpected data: Don't break when new fields are added to responses
• Future-proof parsing: Use flexible JSON parsing that accommodates new properties

Error Handling

• Graceful degradation: Handle API errors and version mismatches gracefully
• Fallback mechanisms: Implement fallbacks for when new features aren't available
• Informative logging: Log version-related issues for debugging

Testing and Validation

Use Test Mode

• Validate thoroughly: Use test mode to validate requests and responses before going live
• Test version changes: Always test API version changes in test mode first
• Simulate scenarios: Test various success and failure scenarios with new versions

Version Testing Process

1. Review release notes: Understand changes in the new API version
2. Update integration code: Modify your code to accommodate new features or requirements
3. Test with Omise-Version header: Use per-request versioning to test without changing account settings
4. Validate all endpoints: Test all API endpoints your integration uses
5. Deploy to staging: Test in a staging environment that mirrors production
6. Update account version: Update your account's API version after thorough testing

Migration Strategy

Planning Your Migration

1. Review release notes: Understand what changes affect your implementation
2. Assess impact: Identify which parts of your integration need updates
3. Plan timeline: Create a migration timeline that allows for thorough testing
4. Prepare rollback: Have a plan to revert changes if issues arise

Implementation Steps

1. Update your code: Modify your application to support the new API version
2. Test thoroughly: Use the Omise-Version header to test the new version extensively
3. Deploy updated application: Deploy your changes to staging and then production
4. Update account version: Change your account's API version through the dashboard
5. Monitor closely: Watch for any issues after the version update

Staying Current

Regular Maintenance

• Monitor release notes: Stay updated on new API versions and features
• Update regularly: Don't let your API version fall too far behind
• Plan upgrades: Schedule regular API version reviews and upgrades

Feature Adoption

• Evaluate new features: Assess how new API features can benefit your integration
• Prioritize upgrades: Focus on API versions that provide the most value
• Document changes: Keep internal documentation updated with API version changes

Common Version Management Scenarios

Testing New Features

When you want to test new API features without affecting your production environment:

1. Use the Omise-Version header in your test requests
2. Compare responses between your current version and the new version
3. Update your test environment to use the new version
4. Thoroughly test all functionality before updating production

Gradual Migration

For large applications with multiple API integrations:

1. Identify all API endpoints your application uses
2. Test each endpoint individually with the new API version
3. Update and deploy changes for each endpoint incrementally
4. Update your account's API version once all endpoints are compatible

Emergency Rollback

If issues arise after updating your API version:

1. Identify the problematic changes
2. Use the Omise-Version header to revert specific requests temporarily
3. Update your account's API version back to the previous stable version
4. Fix the integration issues in your test environment
5. Re-test and deploy the corrected integration

Troubleshooting API Versions

Common Issues

Version Mismatch Errors

• Check your account version: Verify which version your account uses
• Verify request headers: Ensure you set the Omise-Version header correctly
• Review error messages: API errors often indicate version-related issues

Unexpected Response Format

• Compare API documentation: Check if response formats changed between versions
• Update parsing logic: Modify your code to handle new response structures
• Test with different versions: Use the version header to compare responses

Missing Features

• Check feature availability: Verify that features are available in your API version
• Update API version: Upgrade to a version that includes the required features
• Review deprecation notices: Ensure you're not using deprecated functionality

Getting Help

If you encounter issues with API versioning:

1. Review documentation: Check the API documentation for your specific version
2. Check release notes: Look for known issues or changes in release notes
3. Test in isolation: Isolate the issue by testing individual API calls
4. Contact support: Reach out to Omise support with specific version information and error details

Security Considerations

Version Security Updates

• Monitor security notices: Stay informed about security-related API updates
• Prioritize security versions: Treat security-related version updates with high priority
• Test security updates: Test all security updates before deploying to production

Best Practices

• Keep versions current: Don't use outdated API versions that may have security vulnerabilities
• Regular security reviews: Include API version updates in your security review process
• Monitor for deprecation: Watch for announcements about version deprecations

API Versioning FAQ

Version Management Questions

What is the latest API version?

The latest API version is 2019-05-29. This version includes the most recent features and improvements to the Omise API.

How many API versions are currently available?

Four API versions are currently available: 2019-05-29 (latest), 2017-11-02, 2015-11-17, and 2014-07-27.

Can I use different API versions for Test and Live modes?

You can update your Test mode and Live mode API versions independently from the dashboard. Independent version control allows you to test new versions safely before production deployment.

How do I check my current API version?

You can check your API version by logging into your dashboard, clicking the account icon, and selecting API Versions. Alternatively, you can make an API call to the account endpoint.

Can I change my API version back to a previous version?

You can update your account's API version to any available version through the dashboard. Version flexibility allows you to roll back if you encounter issues with a newer version.

Implementation and Technical Questions

How do I test a new API version without changing my account settings?

You can use the Omise-Version header in individual API requests to test new versions without changing your account's default version. This header takes precedence over your account settings.

What happens if I don't specify an API version?

If you don't specify an API version, your requests will use your account's default API version, which is set on the dashboard.

Do I need to update my integration when a new API version is released?

Not necessarily. New API versions are opt-in, so your existing integration will continue to work with your current API version. However, you can upgrade to access new features and improvements.

How do I handle unknown fields in API responses?

Design your integration to gracefully handle unknown fields using flexible JSON parsing that ignores unexpected properties. Flexible parsing ensures your integration won't break when new fields are added to responses.

What should I do if my integration breaks after updating the API version?

If issues arise, you can immediately roll back by updating your account's API version to the previous stable version through the dashboard. Then, fix the integration issues in your test environment before attempting the upgrade again.

Changes and Compatibility Questions

What are backwards-compatible changes?

Backward-compatible changes are modifications that don't break existing integrations. Examples include adding new optional parameters, response fields, API endpoints, and webhook event types.

What are breaking changes?

We will notify merchants in advance if we need to implement breaking changes to an existing API version (e.g., for security concerns).

Will I be notified before breaking changes are implemented?

Yes, if breaking changes need to be implemented to an existing API version (e.g., for security concerns), we will notify merchants in advance.

Do backwards-compatible changes require me to update my API version?

No, backwards-compatible changes are automatically applied to your account and don't require you to update your API version.

How often are new API versions released?

New API versions are released as needed when we introduce breaking changes. The frequency varies depending on new features and improvements we develop.

Best Practices and Migration Questions

What is the recommended approach for migrating to a new API version?

The recommended approach is: 1) Review release notes, 2) Update your code to accommodate changes, 3) Test thoroughly using the Omise-Version header, 4) Deploy your updated application, and 5) Update your account's API version through the dashboard.

Should I always use the latest API version?

While using the latest version gives you access to the newest features, you should only upgrade when you're ready and have thoroughly tested your integration. Stability is more important than having the latest version.

How long are older API versions supported?

Omise supports multiple API versions to ensure merchants have time to migrate. When older versions are scheduled for retirement, we communicate specific deprecation timelines well in advance.

Can I use different API versions for various parts of my application?

You can use the Omise-Version header to specify different API versions for various API calls within the same application. Header-based version control is useful during gradual migration processes.

What should I include in my API version migration plan?

Your migration plan should include an impact assessment, a timeline for testing and deployment, rollback procedures, team coordination, and monitoring plans for post-migration.

Troubleshooting Questions

Why am I getting version-related errors?

Version-related errors typically occur when using features unavailable in your current API version or when request/response formats have changed between versions. Check your account's API version and review the documentation for your specific version.

How do I handle version mismatches between Test and Live modes?

Ensure both your Test and Live mode environments are using compatible API versions. If you need different versions for testing purposes, use the Omise-Version header instead of having different account-level settings.

What should I do if a feature I need isn't available in my current API version?

You must upgrade to an API version that includes your desired feature. Test the upgrade thoroughly in your test environment before updating your production API version.

How can I debug issues related to API versioning?

Use the Omise-Version header to test different versions and compare responses. Check error messages for version-specific information, and review the API documentation for your specific version.

Can API version issues cause webhook delivery problems?

While API versions primarily affect direct API calls, ensure your webhook handling code can process events from your current API version. New webhook event types are backward compatible, but response formats may vary between versions.