Make a Purchase

Once you have a gateway provisioned for your environment, and have collected payment information from your users, you can begin making purchases and other transactions.

Create purchase transaction

Submitting the payment form to Spreedly doesn’t do anything except store that payment method - regardless of whether it’s valid or not - for later usage. Now that you have a token representing the payment method in hand, you can actually run a purchase against a specific gateway from your authenticated server environment (where you can safely store and access your Spreedly environment’s access key).

Using the token of the gateway you want to transact against, as well as the token of the payment method you want to charge, you can create a purchase by POSTing to the Spreedly API endpoint at:<gateway_token>/purchase.<format>

$ curl \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/json' \
  -d '{
        "transaction": {
          "payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
          "amount": 100,
          "currency_code": "USD",
          "retain_on_success": true

$ curl \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>

The amount is always given as an integer number of cents. So if you’d like to run a purchase of $83.45, you’d pass an amount of 8345.

If you are working with a zero decimal currency, you’ll still use a multiplier - for example, a purchase of ¥455 would be sent to Spreedly as an amount of 45500.

Running that will give you the following response:

  "transaction": {
    "on_test_gateway": true,
    "created_at": "2018-11-07T15:05:09Z",
    "updated_at": "2018-11-07T15:05:09Z",
    "succeeded": true,
    "state": "succeeded",
    "token": "LjZEII3nej4v0Oq8wt5VAnWcMRq",
    "transaction_type": "Purchase",
    "order_id": null,
    "ip": null,
    "description": null,
    "email": null,
    "merchant_name_descriptor": null,
    "merchant_location_descriptor": null,
    "gateway_specific_fields": null,
    "gateway_specific_response_fields": {
    "gateway_transaction_id": "53",
    "gateway_latency_ms": 19,
    "amount": 100,
    "currency_code": "USD",
    "retain_on_success": true,
    "payment_method_added": false,
    "message_key": "messages.transaction_succeeded",
    "message": "Succeeded!",
    "gateway_token": "T11bJAANtTWnxl36GYjKWvbNK0g",
    "gateway_type": "test",
    "response": {
      "success": true,
      "message": "Successful purchase",
      "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": "2018-11-07T15:05:09Z",
      "updated_at": "2018-11-07T15:05:09Z"
    "shipping_address": {
      "name": "Newfirst Newlast",
      "address1": null,
      "address2": null,
      "city": null,
      "state": null,
      "zip": null,
      "country": null,
      "phone_number": null
    "api_urls": [
        "referencing_transaction": [

    "payment_method": {
      "token": "1rpKvP8zOUhj4Y9EDrIoIYQzzD5",
      "created_at": "2017-06-26T17:04:38Z",
      "updated_at": "2018-11-07T15:05:08Z",
      "email": "",
      "data": {
        "my_payment_method_identifier": "448",
        "extra_stuff": {
          "some_other_things": "Can be anything really"
      "storage_state": "retained",
      "test": true,
      "metadata": {
        "key": "string value",
        "another_key": 123,
        "final_key": true
      "last_four_digits": "1111",
      "first_six_digits": "411111",
      "card_type": "visa",
      "first_name": "Newfirst",
      "last_name": "Newlast",
      "month": 3,
      "year": 2032,
      "address1": null,
      "address2": null,
      "city": null,
      "state": null,
      "zip": null,
      "country": null,
      "phone_number": null,
      "company": null,
      "full_name": "Newfirst Newlast",
      "eligible_for_card_updater": null,
      "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": "e3cef43464fc832f6e04f187df25af497994",
      "verification_value": "",
      "number": "XXXX-XXXX-XXXX-1111"
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2018-11-07T15:05:08Z</created_at>
  <updated_at type="dateTime">2018-11-07T15:05:08Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <order_id nil="true"></order_id>
  <ip nil="true"></ip>
  <description nil="true"></description>
  <email nil="true"></email>
  <merchant_name_descriptor nil="true"></merchant_name_descriptor>
  <merchant_location_descriptor nil="true"></merchant_location_descriptor>
  <gateway_specific_fields nil="true"></gateway_specific_fields>
  <gateway_latency_ms type="integer">31</gateway_latency_ms>
  <amount type="integer">100</amount>
  <retain_on_success type="boolean">true</retain_on_success>
  <payment_method_added type="boolean">false</payment_method_added>
  <message key="messages.transaction_succeeded">Succeeded!</message>
    <name>Newfirst Newlast</name>
    <address1 nil="true"></address1>
    <address2 nil="true"></address2>
    <city nil="true"></city>
    <state nil="true"></state>
    <zip nil="true"></zip>
    <country nil="true"></country>
    <phone_number nil="true"></phone_number>
    <success type="boolean">true</success>
    <message>Successful purchase</message>
    <avs_code nil="true"></avs_code>
    <avs_message nil="true"></avs_message>
    <cvv_code nil="true"></cvv_code>
    <cvv_message nil="true"></cvv_message>
    <pending type="boolean">false</pending>
    <result_unknown type="boolean">false</result_unknown>
    <error_code nil="true"></error_code>
    <error_detail nil="true"></error_detail>
    <cancelled type="boolean">false</cancelled>
    <fraud_review nil="true"></fraud_review>
    <created_at type="dateTime">2018-11-07T15:05:08Z</created_at>
    <updated_at type="dateTime">2018-11-07T15:05:08Z</updated_at>
    <created_at type="dateTime">2017-06-26T17:04:38Z</created_at>
    <updated_at type="dateTime">2018-11-07T15:05:08Z</updated_at>
        <some_other_things>Can be anything really</some_other_things>
    <test type="boolean">true</test>
      <key>string value</key>
      <another_key type="integer">123</another_key>
      <final_key type="boolean">true</final_key>
    <month type="integer">3</month>
    <year type="integer">2032</year>
    <address1 nil="true"></address1>
    <address2 nil="true"></address2>
    <city nil="true"></city>
    <state nil="true"></state>
    <zip nil="true"></zip>
    <country nil="true"></country>
    <phone_number nil="true"></phone_number>
    <company nil="true"></company>
    <full_name>Newfirst Newlast</full_name>
    <eligible_for_card_updater nil="true"></eligible_for_card_updater>
    <shipping_address1 nil="true"></shipping_address1>
    <shipping_address2 nil="true"></shipping_address2>
    <shipping_city nil="true"></shipping_city>
    <shipping_state nil="true"></shipping_state>
    <shipping_zip nil="true"></shipping_zip>
    <shipping_country nil="true"></shipping_country>
    <shipping_phone_number nil="true"></shipping_phone_number>

The succeeded element will indicate if the transaction was successful, with the message element providing further details if it was not. Once you have a successful transation, you can show a success page to your customer - you’ve successfully collected payment!

You can also execute other transactions against the gateway with your collected payment information, such as an authorize, capture, void or refund. See the reference docs for additional details.


By default, when a payment method is added to Spreedly it is placed in a “cached” storage state. This state indicates that, unless told otherwise, the card will be purged from Spreedly after a short period of time (several minutes, not hours). If you are performing a one-time transaction where the workflow is 1) collect payment information 2) immediately charge the card then you don’t need to do anything else. However, if you want to charge the card again in the future, or have a longer period of time between collecting the payment information and executing a purchase, then you will need to “retain” the card.

Since it’s such a common workflow to want to keep valid cards around for future purchases, Spreedly provides a retain_on_success parameter that can be used to automatically retain the card when it was used in a successful transaction. In the example purchase call above, you did just that, setting the retain element to be true.

If you don’t want to automatically retain a card when it’s used in a transaction, you can omit the retain_on_success parameter


When you no longer need to store a card and want to remove it from Spreedly, you can redact it. This will wipe all sensitive information from the payment method and make the card inoperable (and it will no longer count towards your plan’s storage limits).


You should now be successfully integrated with Spreedly, having created a gateway, collected payment information and executed a purchase. If you would like to explore more advanced topics, we recommend the following: