Change to UpdateTransaction response 12/12/2025

To make our suite of API endpoints more consistent we will be changing the response syntax for the Update Transaction API call on December 12th, 2025. Currently, this API response returns a transaction that wraps the original transaction to be updated. Starting December 12th it will just return the updated original transaction. If you are not using this API, there is no action required. If you are using this API endpoint then please carefully review this page to ensure no impact to your integration.

Changes

The transaction.original_transaction nested hash will no longer be present in the response for this API request. This means that to determine if the original transaction was updated you should use original_transaction_updated boolean variable, which is available today and will continue to share the same information.
Additionally, since the transaction.original_transaction nested hash will no longer be present in the response for this API, in order to know the state or message of the original transaction intended to be updated you will now need to parse transaction.state and transaction.message instead of transaction.original_transaction.state or transaction.original_transaction.message.
The HTTP status code returned will now reflect the original transaction meaning:
- 200 = original transaction succeeded
- 202 = original transaction is pending or processing
- 408 = original transaction state is still unknown
- 422 = original transaction state is failed or gateway_processing_failed.

Current response

{
  "transaction": {
    "original_transaction": {
      "gateway_token": "HaQOnzrDfDHdqWmO0WAjw9zDjGE",
      "gateway_transaction_id": "a_gateway_transaction_id",
      "order_id": "order_id",
      "on_test_gateway": false,
      "transaction_type": "Purchase",
      "created_at": "2025-11-14T14:17:10Z",
      "gateway_type": "worldpay",
      "updated_at": "2025-11-14T14:17:13Z",
      "token": "C7cRfNJGODKh4Iu5Ox3PToKjniY",
      "succeeded": false,
      "response": {
        "fraud_review": false,
        "error_detail": null,
        "result_unknown": true,
        "cvv_message": null,
        "cvv_code": null,
        "avs_message": null,
        "avs_code": null,
        "created_at": "2025-11-14T14:17:13Z",
        "updated_at": "2025-11-14T14:17:13Z",
        "error_code": null,
        "success": true,
        "cancelled": false,
        "status": null,
        "pending": false,
        "message": "1000 approved"
      },
      "state": "succeeded",
      "message": "Succeeded!"
    },
    "original_transaction_updated": true,
    "gateway_token": "HaQOnzrDfDHdqWmO0WAjw9zDjGE",
    "on_test_gateway": false,
    "message_key": "messages.transaction_succeeded",
    "transaction_type": "UpdateTransaction",
    "created_at": "2025-11-14T14:17:12Z",
    "gateway_type": "worldpay",
    "updated_at": "2025-11-14T14:17:13Z",
    "token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
    "succeeded": true,
    "state": "succeeded",
    "message": "Succeeded!"
  }
}

New response

{
  "transaction": {
      "gateway_token": "HaQOnzrDfDHdqWmO0WAjw9zDjGE",
      "gateway_transaction_id": "a_gateway_transaction_id",
      "order_id": "order_id",
      "on_test_gateway": false,
      "transaction_type": "Purchase",
      "created_at": "2025-11-14T14:17:10Z",
      "gateway_type": "worldpay",
      "updated_at": "2025-11-14T14:17:13Z",
      "token": "C7cRfNJGODKh4Iu5Ox3PToKjniY",
      "succeeded": false,
      "response": {
        "fraud_review": false,
        "error_detail": null,
        "result_unknown": true,
        "cvv_message": null,
        "cvv_code": null,
        "avs_message": null,
        "avs_code": null,
        "created_at": "2025-11-14T14:17:13Z",
        "updated_at": "2025-11-14T14:17:13Z",
        "error_code": null,
        "success": true,
        "cancelled": false,
        "status": null,
        "pending": false,
        "message": "1000 approved"
      },
      "state": "succeeded",
      "message": "Succeeded!",
      "original_transaction_updated": true
    }
}

Action Required

If you are digging in transaction.original_transaction.state for the state of the original transaction you will need to change your response parsing to be transaction.state. Likewise for any other attributes you are searching for in transaction.original_transaction.
If you are tracking HTTP status codes, please be mindful of the change taking place which may result in a higher number of 422s since the status will reflect the original transaction instead of the attempt to determine a new status.
To make this cutover seamless Spreedly recommends using the following logic for parsing the state of the original transaction

response = make_update_call_to_spreedly
if response.dig('transaction', 'original_transaction')
  # Current response structure, parse state here for the state of the original transaction
  return response.dig('transaction', 'original_transaction', 'state')
else
  # New response structure, parse state at top level transaction object.
  return response.dig('transaction', 'state')
end

response = make_update_call_to_spreedly()

transaction = response.get('transaction', {})
original_tx = transaction.get('original_transaction')

if original_tx:
    # Current response structure
    state = original_tx.get('state')
else:
    # New response structure
    state = transaction.get('state')

return state

const response = makeUpdateCallToSpreedly();

const transaction = response?.transaction || {};
const originalTransaction = transaction.original_transaction;

let state;

if (originalTransaction) {
  // Current response structure
  state = originalTransaction.state;
} else {
  // New response structure
  state = transaction.state;
}

return state;

Map<String, Object> response = makeUpdateCallToSpreedly();

Map<String, Object> transaction = (Map<String, Object>) response.getOrDefault("transaction", Map.of());
Map<String, Object> originalTransaction = (Map<String, Object>) transaction.get("original_transaction");

String state;

if (originalTransaction != null) {
    // Current response structure
    state = (String) originalTransaction.get("state");
} else {
    // New response structure
    state = (String) transaction.get("state");
}

return state;