Skip to main content
The Decisionly API uses versioning to ensure backward compatibility while allowing us to improve the API over time.

​
How Versioning Works

The Decisionly API uses URL-based versioning. You specify the API version directly in the URL path of your requests. We will bump the API version for breaking changes. Non-breaking changes, such as adding new fields or endpoints, will not trigger a version bump. All API endpoints are versioned by including the version in the URL path. For example:
  • https://api.decisionly.com/v2/issuer/cases
  • https://api.decisionly.com/v1/issuer/cases

​
Version History

  • v2 (Current)
  • v1 (Legacy)

​
v2 Changes

​
Terminal Statuses

Terminal case states are now represented as distinct status values instead of using a generic closed status with a closed_reason field: v1 behavior:
  • Terminal cases had status: "closed" with a closed_reason field indicating the specific outcome
  • A single case.closed webhook was triggered for all terminal states
v2 behavior:
  • Terminal states are now first-class status values: accepted, rejected, expired, withdrawn, merchant_credited
  • The closed_reason field has been removed
  • Each terminal status has its own dedicated webhook event: case.accepted, case.rejected, case.expired, case.withdrawn, case.merchant_credited
  • The case.closed webhook is deprecated
See the Case Lifecycle documentation for more details.

​
File endpoint

Cases are now filed using a dedicated file endpoint.

​
Evidence Structure Changes

The issuer_evidence object has been reorganized in v2 for better clarity and consistency: Field groupings:
  • Amount corrections: correct_amount and correct_currency → amount_correction.amount and amount_correction.currency
  • Return shipping: return.shipping_carrier and return.shipping_tracking → return.shipping.carrier and return.shipping.tracking_number
  • Service end date: service_end_date → service.end_date
  • Resolution: Previously flat resolution fields are now organized into specific resolution type objects:
    • Product resolution fields → product object (order_id, description, condition, type)
    • Cancellation fields → cancellation object (id, date, description, policy_provided)
    • Refund fields → refund object (was_promised, promise_date, description)
    • Return fields → return object (date, was_successful, description, policy_provided, shipping)
    • Delivery fields → delivery object (date, expected_date)
    • Service fields → service object (end_date)
    • Card fraud fields → card object (lost_date, is_active, cardholder_has_possession, possession_at_transaction)
Boolean field renames:
  • merchant_contact.success → merchant_contact.was_successful
  • return.success → return.was_successful
  • refund.promised → refund.was_promised
  • card.active → card.is_active
Other field renames:
  • cardholder_message → cardholder_explanation
  • explanation → issuer_explanation
  • merchant_contact.prohibited_description → merchant_contact.prohibited_reason