Syncing Gateway Transactions

The Spreedly API allows merchants to update the status of a purchase that originally returned an ambiguous state. This lets merchants know whether or not a purchase was eventually completed at the gateway. This is useful for purchases with a final status that isn’t immediately determined, such as if the purchase is under review at the gateway.

The updated transaction status is considered synced with the transaction’s status at the gateway, and is available to view by the merchant via their dashboard or our transaction API.

Supported Gateways:

Requesting Gateway Transaction Updates

Example Usage

Create a purchase

The first step is to create a purchase on a gateway that supports transaction updates.

curl https://core.spreedly.com/v1/gateways/T11bJAANtTWnxl36GYjKWvbNK0g/purchase.json \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/json' \
  -d '{
        "transaction": {
          "payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
          "amount": 100,
          "currency_code": "USD",
          "order_id": 44837
        }
      }'

If the response returns a transaction with an ambiguous status, as demonstrated below, this transaction is a good candidate for being updated with our API.

{
  "transaction": {
    "on_test_gateway": false,
    "created_at": "2022-11-03T13:48:26Z",
    "updated_at": "2022-11-03T13:48:26Z",
    "succeeded": false,
    "state": "pending",
    "token": "Rs0JRsByYUEPqh3wL0hPzG6oBcW",
    "transaction_type": "Purchase",
    "order_id": "44837",
    //...
}

Update the transaction

Use the transaction’s token as a query parameter in your request when updating the transaction.

This request will inquire about the status of the transaction at the gateway, and then update the transaction at Spreedly based on that inquiry. Depending on the gateway we can use gateway_transaction_id or order_id to inquire about the status. Make sure to see each gateway’s “Syncing Transactions” section for more information.

curl -X PATCH https://core.spreedly.com/v1/transactions/Rs0JRsByYUEPqh3wL0hPzG6oBcW.json \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/json'

Responses from Spreedly will provide information about the transaction being updated, whether the transaction was successfully updated, as well as whether the current request to inquire about the gateway transaction status was successful or not.

Specifically, the response field original_transaction_updated will return true if the transaction was ever successfully updated.

{
    "transaction": {
        "on_test_gateway": false,
        "created_at": "2022-11-04T17:15:05Z",
        "updated_at": "2022-11-04T17:15:05Z",
        "succeeded": true,
        "state": "succeeded",
        "token": "2AhGXGZpm5IqetB3PHHId7hH12s",
        "transaction_type": "UpdateTransaction",
        "original_transaction_updated": true,
        "message_key": "messages.transaction_succeeded",
        "message": "Succeeded!",
        "gateway_token": "T11bJAANtTWnxl36GYjKWvbNK0g",
        "gateway_type": "example_gateway_brand",
        "original_transaction": {
            "on_test_gateway": false,
            "created_at": "2022-10-27T14:55:46Z",
            "updated_at": "2022-10-27T14:55:50Z",
            "succeeded": true,
            "state": "succeeded",
            "token": "Rs0JRsByYUEPqh3wL0hPzG6oBcW",
            "transaction_type": "Purchase",
            "order_id": "44837",
            "gateway_transaction_id": "1309352841",
            "message_key": "messages.transaction_succeeded",
            "message": "Succeeded!",
            "gateway_token": "T11bJAANtTWnxl36GYjKWvbNK0g",
            "gateway_type": "example_gateway_brand",
            "response": {
                "success": true,
                "message": "purchase complete",
                "avs_code": null,
                "avs_message": null,
                "cvv_code": null,
                "cvv_message": null,
                "pending": false,
                "result_unknown": false,
                "error_code": null,
                "error_detail": null,
                "cancelled": false,
                "fraud_review": null,
                "created_at": "2022-10-27T14:55:47Z",
                "updated_at": "2022-10-27T14:55:50Z"
            }
        }
    }
}

It’s important not to confuse the status of the inquire request and that of the gateway transaction that is being queried. It’s possibly that a purchase transaction that has failed at the gateway was successfully updated to this failed status.

The information in the top level transaction object is related to the sync transaction's status, whereas the information under original_transaction will reflect the gateway transaction's information.

The Sync transactions do not have transcripts. In order to view the transcript, look up the original transaction. A new object UPDATE_TRANSACTION_GATEWAY_API_CALL RESPONSE will be included at the bottom. The transcript can be viewed in the Spreedly Dashboard or via the API.

Ineligible gateway transactions

Not all transactions are eligible for an update. The transaction must have taken place on a gateway that Spreedly supports transaction updates from, and that initial transaction must not have been in the following states at Spreedly before the transaction update request was made:

succeeded
failed
gateway_setup_failed

These are terminal transaction states, meaning that those transactions cannot transition into another state at the gateway, so Spreedly does not support updating their status through our API. Those transactions would need to be retried by the merchant; our transaction update API does not retry any transactions.

Example failure

{
    "errors": [
        {
            "key": "errors.transaction_state_not_eligible_for_update",
            "message": "Unable to update the transaction state because the transaction is in a state of succeeded"
        }
    ]
}

Some gateways may have custom terminal transaction state rules. Check the “Syncing Transactions” section of the gateway guide for your gateway for more information.