Transaction Metadata

Transaction Metadata is a flexible object consisting of custom key-value pairs that merchants include in an initial Authorize or Purchase API request. This data acts as persistent information that follows the transaction throughout its entire lifecycle.

By storing business-specific context directly within the transaction, merchants can use this data for routing transactions via Composer, in addition to ingesting webhooks and responses into their reporting tools without needing to query a secondary database to identify the transaction’s purpose.

Key Technical Notes

Persistence: Once defined in the initial authorize or purchase transaction, the transaction_metadata is fixed and will appear in all downstream transaction objects and webhooks.
Scope: transaction_metadata is used for routing within the Spreedly platform and merchant reporting only; it is not transmitted to the payment gateway.

Response Behavior & Object Names

The transaction_metadata is returned in every transaction response, but the object name changes depending on whether the response is for the initial request or a subsequent action:

Transaction Type	Object Name in Response
Authorize Purchase	`transaction_metadata`
Capture Credit General credit Void Store Verify Asynchronous callbacks	`reference_transaction_metadata`

Implementation Examples

Initial Request (Auth or Purchase) Merchants pass the transaction_metadata object during the initial API call, defining key:value pairs custom to business needs.

📘
Note that this data is stored by Spreedly and is not passed to the payment gateway.

{
  "transaction": {
    "payment_method_token": "",
    "amount": 100,
    "currency_code": "USD",
	"transaction_metadata": {
          "storedPaymentDetails": "false",
          "shipping_method": "HomeDelivery",
          "risk_amount": "50.01",
          "pss_payment_method": "CREDIT_CARD",
          "promotionalInstallment": "false",
          "payment_order_id": "23932",
          "orderSource": "ABC",
          "market": "XY",
          "is_logged_in": "false",
          "installments_promotion": "false",
          "flow": "EARLY_CAPTURE",
          "channel": "web",
          "source": "Checkout Service"
  },

Initial Response The response to the Auth or Purchase request will echo the transaction_metadata back to you immediately.

{
  "transaction_metadata": {
    "storedPaymentDetails": "false",
    "shipping_method": "HomeDelivery",
    "risk_amount": "50.01",
    "pss_payment_method": "CREDIT_CARD",
    "promotionalInstallment": "false",
    "payment_order_id": "23932",
    "orderSource": "ABC",
    "market": "XY",
    "is_logged_in": "false",
    "installments_promotion": "false",
    "flow": "EARLY_CAPTURE",
    "channel": "web",
    "source": "Checkout Service"
  },
  "state": "succeeded",
  }

Secondary Transaction Response (e.g., Capture or Credit) When performing a secondary action - or when receiving an asynchronous callback - the transaction_metadata is nested within the "reference" object. This allows your systems to maintain context even when the secondary action happens days after the original purchase.

{
  "state": "succeeded",
  "gateway_specific_response_fields": {
    "d_local": {
      "notification_url": "https://core.spreedly.com/transaction/...",
      "calculated_amount": 40.01,
      "order_id": "KQX8938493",
      "status": "SUCCESS"
    }
  },
  "transaction_type": "Credit",
  "gateway_latency_ms": 1999,
  "ip": null,
  "api_urls": [],
  "warning": null,
  "callback_url": null,
  "reference_transaction_metadata": {
    "storedPaymentDetails": "false",
    "shipping_method": "HomeDelivery",
    "risk_amount": "50.01",
    "pss_payment_method": "CREDIT_CARD",
    "promotionalInstallment": "false",
    "payment_order_id": "23932",
    "orderSource": "ABC",
    "market": "XY",
    "is_logged_in": "false",
    "installments_promotion": "false",
    "flow": "EARLY_CAPTURE",
    "channel": "web",
    "source": "Checkout Service"
  },