Syncing Your Gateway Transaction

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

1. 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",
    //...
}
2. 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.

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.

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 page of any gateway that supports this feature for further information.