Account Updater

Spreedly’s Account Updater allows you to always keep your customers’ card details up-to-date. When your customers’ credit card numbers expire or are updated, Account Updater protects you from the lost revenue, involuntary churn, and decreased customer satisfaction associated with outdated payment information. No additional development is required on your side since cards are updated behind the scenes.

How Account Updater Works

When you opt-in, Spreedly defaults to submitting all retained, non-test, Visa, MasterCard, and Discover cards in your Spreedly vault for automatic updating twice monthly, on the 1st and 15th of every month. The table below lists current regional participation by card brand:

Supported Schemes Market Coverage
Visa
  • North America: near full participation.
  • Europe: high participation in the UK, Ireland, Italy, Greece. Sweden and Finland are mandated as of January 2019. Denmark and Norway optionally able to participate.
Mastercard
  • North America: near full participation.
  • Europe: high participation in the UK, Ireland, and Italy. Remaining markets are mandated as of December 2018.
  • Latin America: mandated as of October 2018.
  • Asia Pacific: mandated as of November 2018 (excluding India).
  • Middle East and Africa: mandated as of October 2018.
Discover
  • North America: near full participation.

Card-Level Controls

You can optionally exclude individual cards from the Account Updater service via our API. For example, you may want to exclude a card if your customer has paused their subscription. Payment methods include an eligible_for_card_updater field that when set to false will result in Spreedly excluding the associated card from subsequent submissions to the Account Updater service. You can set this field to true to resume submitting the given card at any time.

Opting-in to Account Updater happens at the organization level - all environments will be affected. By turning on the Account Updater feature, you confirm that all eligible cards will be sent to the card brands for updates twice monthly, but you will only be charged for those cards that are actually updated.

Analyze Results

Dashboard

Results of Account Updater submissions can be tracked in your Spreedly dashboard. You can view summary statistics for each twice-monthly submission (or “batch”). You can also drill into detailed per-card results and download a CSV report for any given batch right from the dashboard. The status for each card is shown:

  1. ReplacePaymentMethod - The number and/or expiration date has been updated.
  2. InvalidReplacePaymentMethod - We received either a new card number or expiration date that was invalid. The payment method was not updated, and there is no charge.
  3. ContactCardHolder - The card network identified this account needs to be updated but the issuer did not provide the updated values. Contact the cardholder for a new number and/or expiration date.
  4. ClosePaymentMethod - The account is no longer open and should no longer be used. The payment method will remain available, but Spreedly’s Account Updater will no longer attempt to update it.

Callbacks

Callbacks are available for pre-paid Account Updater accounts only. Please contact success@spreedly.com for more information.

As an alternative to viewing results in the Spreedly dashboard, callbacks are provided that will push Account Updater results to a destination of your choosing. These notifications are delivered via an HTTPS or HTTP POST to a public-facing URL on your server. This should be a URL to your system that is able to receive a POST request with a list of transactions whose state has been updated.

Since Account Updater operates in a batch manner and card updates may result in a large number of transactions, Spreedly only delivers callbacks every few minutes. A single callback may contain up to 150 transactions with a maximum delivery of approximately 500 callbacks within a 24 hour period period per environment when using an environment based callback URL or per URL when using an override.

Note that all transactions contained in a callback are signed; this allows you to process the results of the callback without having to round trip back to Spreedly (though you certainly can round trip if you’d like - see below). Since an attacker could call your callback url with a valid looking transaction, the signature allows you to verify that the information is really coming from Spreedly. Full details on validating the signature is in our signing reference.

We recognize that some customers are not interested in going through the trouble of writing code to validate the signature of the callback response. In this case, you can use the tokens of the transactions you receive in the callback and then make an authenticated API call to retrieve the details of each transaction. Because that call is authenticated and you’re making the request, there’s no need to verify where the information is coming from.

The incoming callback POST requests will be structured as follows:

{
  "transactions": [
    {
      "token": "S6cl5f11LqdVLe9m1TtQGMSMUuz",
      "created_at": "2019-02-13T13:40:43Z",
      "updated_at": "2019-02-13T13:42:48Z",
      "succeeded": true,
      "transaction_type": "ReplacePaymentMethod",
      "state": "succeeded",
      "account_key": "2H2HmVvjh171NvjCzr37D7jWG6c",
      "environment_key": "DDB58wpfgxHA1qD7p0LkqCLBnZw",
      "message_key": "messages.transaction_succeeded",
      "message": "Succeeded!",
      "payment_method": {
        "token": "EjpBzUVNHWnF1Y0MNaefuNpXwyR",
        "created_at": "2019-02-13T13:27:53Z",
        "updated_at": "2019-02-13T13:40:43Z",
        "email": "mm@example.com",
        "data": null,
        "storage_state": "retained",
        "test": false,
        "metadata": null,
        "callback_url": "https://7fba2acd.ngrok.io",
        "last_four_digits": "0003",
        "first_six_digits": "511201",
        "card_type": "master",
        "first_name": "Mighty",
        "last_name": "Mouse",
        "month": 1,
        "year": 2050,
        "address1": null,
        "address2": null,
        "city": null,
        "state": null,
        "zip": null,
        "country": null,
        "phone_number": null,
        "company": null,
        "full_name": "Mighty Mouse",
        "eligible_for_card_updater": true,
        "shipping_address1": null,
        "shipping_address2": null,
        "shipping_city": null,
        "shipping_state": null,
        "shipping_zip": null,
        "shipping_country": null,
        "shipping_phone_number": null,
        "payment_method_type": "credit_card",
        "errors": [],
        "fingerprint": "84fd610e28258201fffea68dc0f9e7c66859",
        "verification_value": "",
        "number": "XXXX-XXXX-XXXX-0003"
      },
      "signed": {
        "signature": "d5595f3a4e00177b73ba4de40b638ddf787c735c",
        "fields": "token created_at updated_at succeeded transaction_type state",
        "algorithm": "sha1"
      }
    },
    {
      "token": "I5kuefCHe8Tvm9HypLRLIKYHCmm",
      "created_at": "2019-02-13T13:40:40Z",
      "updated_at": "2019-02-13T13:42:48Z",
      "succeeded": true,
      "transaction_type": "ClosePaymentMethod",
      "state": "succeeded",
      "account_key": "2H2HmVvjh171NvjCzr37D7jWG6c",
      "environment_key": "DDB58wpfgxHA1qD7p0LkqCLBnZw",
      "message_key": "messages.transaction_succeeded",
      "message": "Succeeded!",
      "payment_method": {
        "token": "7xHGM9h7a8OoUboXPNHvY5pihgv",
        "created_at": "2019-02-13T13:27:56Z",
        "updated_at": "2019-02-13T13:40:40Z",
        "email": "mm@example.com",
        "data": null,
        "storage_state": "retained",
        "test": false,
        "metadata": null,
        "callback_url": "https://7fba2acd.ngrok.io",
        "last_four_digits": "0002",
        "first_six_digits": "601101",
        "card_type": "discover",
        "first_name": "Mighty",
        "last_name": "Mouse",
        "month": 8,
        "year": 1950,
        "address1": null,
        "address2": null,
        "city": null,
        "state": null,
        "zip": null,
        "country": null,
        "phone_number": null,
        "company": null,
        "full_name": "Mighty Mouse",
        "eligible_for_card_updater": false,
        "shipping_address1": null,
        "shipping_address2": null,
        "shipping_city": null,
        "shipping_state": null,
        "shipping_zip": null,
        "shipping_country": null,
        "shipping_phone_number": null,
        "payment_method_type": "credit_card",
        "errors": [],
        "fingerprint": "2b4184e42067002e39fb3f5a7e9275f34b17",
        "verification_value": "",
        "number": "XXXX-XXXX-XXXX-0002"
      },
      "signed": {
        "signature": "1274de9851aa0b5862289cc7edcad80b5e2ce947",
        "fields": "token created_at updated_at succeeded transaction_type state",
        "algorithm": "sha1"
      }
    }
  ]
}

Callback Response

You should respond back with a 200 OK response within 5 seconds. If Spreedly does not receive back a 200 response within this time, it will retry the callback again at least 4 times at ever-increasing intervals. If you need to do potentially time-consuming operations when a callback is received, we recommend doing them asynchronously to avoid being timed out. Additionally, callbacks should be treated as idempotent since they may be sent more than once.

Getting started with callbacks

Callbacks are available for pre-paid Account Updater accounts only. Please contact success@spreedly.com for more information.

To get started with callbacks on Account Updater, a callback URL must be added to your Spreedly environment. Log in, select the environment you wish configure, and add a callback URL. If you store payment methods in multiple environments, a callback URL must be configured for each environment.

Additionally, Spreedly provides the ability to override the per-environment level callback URL with a payment method specific callback URL. This override is useful in situations where card update notifications are to be delivered to a location different from the environment level callback URL. To override the environment level callback URL, both the create payment method and update payment method API calls include a callback_url property that can be set. Once set, any update notifications related to this payment method will be delivered to the callback_url set on the payment method instead of the environment. By default, the callback_url property on a payment method is null and will only take precedence over the environment level setting when set. Spreedly does not update all of your payment methods when the environment level setting is present.

Email Notifications

We will send two e-mail notifications when your cards are updated. Notifications will be sent to all active users associated with the organization. The first email is notice that the card update process has started. Example:

The second email is notice that card updates have completed and contains aggregate information about the updates that were performed. Example:

Please visit the Help Center for a detailed walkthrough on pricing, opting-in, and opting-out.