Versioning

Plexy uses API versioning to ensure stability while allowing improvements.

Version format

API versions use date-based naming:

2024-01-15

Setting your version

Specify the API version by passing the Plexy-Version header:

curl -X POST https://api.plexypay.com/v2/payments \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Plexy-Version: 2024-01-15" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1000, "currency": "USD"}'

Default version

If no version is specified, your account's default version is used. Set your default in the Dashboard under Developers > API Version.

Upgrade policy

Breaking changes

Breaking changes are released as new API versions:

• Removing fields or endpoints
• Changing field types
• Modifying error formats
• Changing default behaviors

Non-breaking changes

Non-breaking changes are added to all versions:

• New optional fields
• New endpoints
• New enum values
• Bug fixes

Changelog

2024-01-15 (Current)

• Added metadata field to all resources
• New payment.requires_action status
• Improved error messages

2023-09-01

• Added off_session parameter for saved cards
• New dispute management endpoints
• Updated webhook payload structure

2023-06-01

• Initial API release
• Core payments, refunds, customers
• Webhook support

Testing versions

Test new versions before upgrading by pinning the version header in your test requests:

curl -X POST https://api.plexypay.com/v2/payments \
  -H "x-api-key: YOUR_TEST_API_KEY" \
  -H "Plexy-Version: 2024-01-15" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1000, "currency": "USD"}'

If tests pass, update your account's default version in the Dashboard.

Webhook versions

Webhooks use your account's default version. To change:

1. Go to Developers > Webhooks
2. Select endpoint
3. Change API Version

Migration guide

When upgrading versions:

1. Read the changelog for breaking changes
2. Update your code for new field names/types
3. Test thoroughly in test environment
4. Update your account default version
5. Monitor for errors after deployment

Deprecation policy

• Deprecated versions supported for 12 months
• Email notifications sent before deprecation
• Upgrade assistance available

See also

• Live Endpoints
• API Reference