Stripe Gateway Guide

close

Services and Compatibility

Payment Gateway Company Name:
Stripe
Services that work with Spreedly:
  • Stripe
Supported operations:
Purchase, Authorize, Capture, Refund, Void, Verify, Store
Supported payment types:
Credit Card, Apple Pay, Bank Account, Google Pay
Spreedly 3DS2 Global Supported
No
Gateway Specific 3DS2 Supported
No
Populate MIT GSF Support
No
Regions:
Asia Pacific, Europe, North America
API endpoint URL:
https://api.stripe.com/v1/

Authentication and Security

Specific names for credentials:
Api Key

Onboarding Merchants in:

Additional Notes

This gateway supports Level 2 and Level 3 transaction processing via Spreedly. If you are interested in Level 2 or Level 3 transaction support, please contact the gateway to confirm that your account is enabled for these processing types. Please let us know if there are any specific parameters you would like to have enabled.

This is the legacy Stripe API. To access the newest features, such as support for 3D Secure 2, see the Stripe Payment Intents gateway.

Adding a Stripe gateway

To add a Stripe gateway you just need to supply a login, which is your API secret key at Stripe.

You may choose to specify the Stripe API version to transact against via version_override when creating a gateway. Spreedly currently defaults to Stripe API version 2020-08-27 if no version_override is specified. Please refer to Stripe’s API Upgrades guide and changelog to verify differences between our default and versions you may choose, as our support is designed for this version, and may not be compatible with every Stripe version available.


curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>stripe</gateway_type>
        <login>your api secret key</login>
        <version_override>2015-04-07</version_override>
      </gateway>'

<gateway>
  <token>Nz4bLMriDXlllDtWhBespFpsfVA</token>
  <gateway_type>stripe</gateway_type>
  <name>Stripe</name>
  <description nil="true"/>
  <merchant_profile_key nil="true"/>
  <sub_merchant_key nil="true"/>
  <characteristics>
    <supports_purchase type="boolean">true</supports_purchase>
    <supports_authorize type="boolean">true</supports_authorize>
    <supports_capture type="boolean">true</supports_capture>
    <supports_credit type="boolean">true</supports_credit>
    <supports_general_credit type="boolean">false</supports_general_credit>
    <supports_void type="boolean">true</supports_void>
    <supports_adjust type="boolean">false</supports_adjust>
    <supports_verify type="boolean">true</supports_verify>
    <supports_reference_purchase type="boolean">false</supports_reference_purchase>
    <supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
    <supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
    <supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
    <supports_3dsecure_purchase type="boolean">true</supports_3dsecure_purchase>
    <supports_3dsecure_authorize type="boolean">true</supports_3dsecure_authorize>
    <supports_3dsecure_2_mpi_purchase type="boolean">false</supports_3dsecure_2_mpi_purchase>
    <supports_3dsecure_2_mpi_authorize type="boolean">false</supports_3dsecure_2_mpi_authorize>
    <supports_store type="boolean">true</supports_store>
    <supports_remove type="boolean">true</supports_remove>
    <supports_fraud_review type="boolean">false</supports_fraud_review>
    <supports_network_tokenization type="boolean">false</supports_network_tokenization>
    <supports_populate_mit_fields type="boolean">false</supports_populate_mit_fields>
  </characteristics>
  <credentials>
  </credentials>
  <gateway_settings>
    <webhook_id nil="true"/>
    <version_override>2015-04-07</version_override>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>receipt_email</gateway_specific_field>
    <gateway_specific_field>radar_session_id</gateway_specific_field>
    <gateway_specific_field>skip_radar_rules</gateway_specific_field>
    <gateway_specific_field>application_fee</gateway_specific_field>
    <gateway_specific_field>stripe_account</gateway_specific_field>
    <gateway_specific_field>metadata</gateway_specific_field>
    <gateway_specific_field>idempotency_key</gateway_specific_field>
    <gateway_specific_field>reason</gateway_specific_field>
    <gateway_specific_field>refund_application_fee</gateway_specific_field>
    <gateway_specific_field>refund_fee_amount</gateway_specific_field>
    <gateway_specific_field>reverse_transfer</gateway_specific_field>
    <gateway_specific_field>account_id</gateway_specific_field>
    <gateway_specific_field>customer_id</gateway_specific_field>
    <gateway_specific_field>validate</gateway_specific_field>
    <gateway_specific_field>make_default</gateway_specific_field>
    <gateway_specific_field>statement_description</gateway_specific_field>
    <gateway_specific_field>statement_descriptor_suffix</gateway_specific_field>
    <gateway_specific_field>destination</gateway_specific_field>
    <gateway_specific_field>destination_amount</gateway_specific_field>
    <gateway_specific_field>merchant_reference</gateway_specific_field>
    <gateway_specific_field>customer_reference</gateway_specific_field>
    <gateway_specific_field>shipping_address_zip</gateway_specific_field>
    <gateway_specific_field>shipping_from_zip</gateway_specific_field>
    <gateway_specific_field>shipping_amount</gateway_specific_field>
    <gateway_specific_field>line_items</gateway_specific_field>
    <gateway_specific_field>transfer_destination</gateway_specific_field>
    <gateway_specific_field>transfer_amount</gateway_specific_field>
    <gateway_specific_field>transfer_group</gateway_specific_field>
    <gateway_specific_field>on_behalf_of</gateway_specific_field>
    <gateway_specific_field>application_fee_amount</gateway_specific_field>
    <gateway_specific_field>recurring</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
    <payment_method>third_party_token</payment_method>
    <payment_method>apple_pay</payment_method>
    <payment_method>bank_account</payment_method>
    <payment_method>google_pay</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <sandbox type="boolean">false</sandbox>
  <created_at type="dateTime">2022-02-25T18:13:47Z</created_at>
  <updated_at type="dateTime">2022-02-25T18:13:47Z</updated_at>
</gateway>

Stripe Connect

Stripe Connect allows you to obtain permission from your customer to access their Stripe account. If you have a Stripe Connect standalone account you will go through the OAuth process, at the end of which you’ll have an access_token. Once you have that access_token, you can create a gateway in the Spreedly API by passing it as the login parameter like so:


curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>stripe</gateway_type>
        <login>access_token you received</login>
      </gateway>'

<gateway>
  <token>EZ2ODwbifDz6bL9PKTm4KMcsIjN</token>
  <gateway_type>stripe</gateway_type>
  <name>Stripe</name>
  <description nil="true"/>
  <merchant_profile_key nil="true"/>
  <characteristics>
    <supports_purchase type="boolean">true</supports_purchase>
    <supports_authorize type="boolean">true</supports_authorize>
    <supports_capture type="boolean">true</supports_capture>
    <supports_credit type="boolean">true</supports_credit>
    <supports_general_credit type="boolean">false</supports_general_credit>
    <supports_void type="boolean">true</supports_void>
    <supports_adjust type="boolean">false</supports_adjust>
    <supports_verify type="boolean">true</supports_verify>
    <supports_reference_purchase type="boolean">false</supports_reference_purchase>
    <supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
    <supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
    <supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
    <supports_3dsecure_purchase type="boolean">true</supports_3dsecure_purchase>
    <supports_3dsecure_authorize type="boolean">true</supports_3dsecure_authorize>
    <supports_3dsecure_2_mpi_purchase type="boolean">false</supports_3dsecure_2_mpi_purchase>
    <supports_3dsecure_2_mpi_authorize type="boolean">false</supports_3dsecure_2_mpi_authorize>
    <supports_store type="boolean">true</supports_store>
    <supports_remove type="boolean">true</supports_remove>
    <supports_fraud_review type="boolean">false</supports_fraud_review>
    <supports_network_tokenization type="boolean">false</supports_network_tokenization>
    <supports_populate_mit_fields type="boolean">false</supports_populate_mit_fields>
  </characteristics>
  <credentials>
  </credentials>
  <gateway_settings>
    <webhook_id nil="true"/>
    <version_override nil="true"/>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>receipt_email</gateway_specific_field>
    <gateway_specific_field>radar_session_id</gateway_specific_field>
    <gateway_specific_field>skip_radar_rules</gateway_specific_field>
    <gateway_specific_field>application_fee</gateway_specific_field>
    <gateway_specific_field>stripe_account</gateway_specific_field>
    <gateway_specific_field>metadata</gateway_specific_field>
    <gateway_specific_field>idempotency_key</gateway_specific_field>
    <gateway_specific_field>refund_application_fee</gateway_specific_field>
    <gateway_specific_field>refund_fee_amount</gateway_specific_field>
    <gateway_specific_field>reverse_transfer</gateway_specific_field>
    <gateway_specific_field>account_id</gateway_specific_field>
    <gateway_specific_field>customer_id</gateway_specific_field>
    <gateway_specific_field>validate</gateway_specific_field>
    <gateway_specific_field>make_default</gateway_specific_field>
    <gateway_specific_field>statement_description</gateway_specific_field>
    <gateway_specific_field>statement_descriptor_suffix</gateway_specific_field>
    <gateway_specific_field>destination</gateway_specific_field>
    <gateway_specific_field>destination_amount</gateway_specific_field>
    <gateway_specific_field>merchant_reference</gateway_specific_field>
    <gateway_specific_field>customer_reference</gateway_specific_field>
    <gateway_specific_field>shipping_address_zip</gateway_specific_field>
    <gateway_specific_field>shipping_from_zip</gateway_specific_field>
    <gateway_specific_field>shipping_amount</gateway_specific_field>
    <gateway_specific_field>line_items</gateway_specific_field>
    <gateway_specific_field>transfer_destination</gateway_specific_field>
    <gateway_specific_field>transfer_amount</gateway_specific_field>
    <gateway_specific_field>transfer_group</gateway_specific_field>
    <gateway_specific_field>on_behalf_of</gateway_specific_field>
    <gateway_specific_field>application_fee_amount</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
    <payment_method>third_party_token</payment_method>
    <payment_method>apple_pay</payment_method>
    <payment_method>bank_account</payment_method>
    <payment_method>google_pay</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <sandbox type="boolean">false</sandbox>
  <created_at type="dateTime">2022-01-04T20:11:45Z</created_at>
  <updated_at type="dateTime">2022-01-04T20:11:45Z</updated_at>
</gateway>

If you’re using a Stripe Connect managed account, you can create a Stripe gateway normally without having to go through the OAuth process.

To use Stripe Connect (whether it be standalone or managed), your Stripe account will likely need a special one-time approval from Stripe. Stripe prefers you to log in and contact them directly via their support form so they can confirm you own the account. They also ask that you include your email address and any unique IDs on the account (like charge IDs ch_, payout IDs po_, etc. that they can use to locate the account.​

Here’s an example message for Stripe Support:

We would love to use Stripe Connect. We are using Spreedly and in the past, you’ve been able to remove a restriction such that others wouldn’t receive this error message: “OAuth based requests must use card tokens from Stripe.js, but card details were directly provided”.

We have a live publishable key of: “live publishable key” The email address associated with our Stripe account is: “your email address”

Can you remove the restriction for us as well?

NOTE: If instead, you need to create direct charges on the connected account, use the stripe_account gateway specific field.

Stripe Radar

Stripe Radar is a fraud detection tool that was created by Stripe. Radar is included with Stripe payment processing and uses a variety of signals to detect fraud. Per Stripe’s documentation:

As part of their role in payment processing, Stripe.js provides advanced fraud detection by looking at signals about both device characteristics and user activity indicators that help distinguish between legitimate and fraudulent transactions.

To use these advanced fraud detection signals through the Spreedly platform, the customer activity must be linked to a Radar Session ID that can be passed into the transaction. Spreedly provides a helper function in our iFrame library that helps customers obtain a Stripe Radar Session ID. To use this feature through Spreedly, you will need to write to Stripe support (support@stripe.com) and request for the Stripe Radar Sessions feature to be enabled.

Follow these instructions to obtain a Radar Session ID using Spreedly’s iFrame:

1) Include the Stripe javascript library on your checkout page. To increase the effectiveness of Radar, add the Stripe javascript library to other pages of your website as well.

  <script src="https://js.stripe.com/v3/"></script>

2) Call the stripeRadar function from our iFrame helper to establish a Radar session and obtain the radar_session_id. This function takes three arguments:

  • Your Stripe publishable key available in the Stripe dashboard.
  • A callback function that will receive the radar_session_id. The stripeRadar function requires an API call to Stripe, so the callback function will be called asynchronously when the request completes.
  • A object with stripeAccount passed in (eg., { stripeAccount: ‘acct_24BFMpJ1svR5A89k’ }). This is only intended for users of Stripe Connect. If you’re not a user of Stripe Connect and/or don’t intend to use this object then skip on sending this parameter.
function callback(radar_session_id) {
  // pass radar_session_id to your backend to use it
  // as a gateway specific field when making an authorization
  // or purchase request
}

Spreedly.stripeRadar("publishableKey", callback, options)

The stripeRadar function can be called at any point on the checkout page.

3) Pass the radar_session_id obtained in your callback during your authorization/purchase request as a gateway specific field radar_session_id.

curl https://core.spreedly.com/v1/gateways/T11bJAANtTWnxl36GYjKWvbNK0g/purchase.xml \
  -u ''C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</payment_method_token>
        <amount>100</amount>
        <currency_code>USD</currency_code>
        <gateway_specific_fields>
          <stripe>
            <radar_session_id>re_dfa3648ceeaf456a</radar_session_id>
          </stripe>
        </gateway_specific_fields>
      </transaction>'


4) If you have enabled Stripe Radar through Stripe support and you want the ability to selectively disable Radar on a transaction-by-transaction basis, you may pass the skip_radar_rules GSF with a value of true (see example below). This will cause all Radar rules to be skipped for that transaction. Note that you may need to ask Stripe support (support@stripe.com) to enable the 'skip rules’ feature for your account.

curl https://core.spreedly.com/v1/gateways/T11bJAANtTWnxl36GYjKWvbNK0g/purchase.xml \
  -u ''C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</payment_method_token>
        <amount>100</amount>
        <currency_code>USD</currency_code>
        <gateway_specific_fields>
          <stripe>
            <skip_radar_rules>true</skip_radar_rules>
          </stripe>
        </gateway_specific_fields>
      </transaction>'

ACH transactions

Stripe supports ACH transactions but requires bank accounts be stored and verified before use. Stripe does not support making a purchase or refund with a bank account directly.

First, create the bank account payment method in Spreedly.

curl https://core.spreedly.com/v1/payment_methods.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<payment_method>
        <bank_account>
            <first_name>Jon</first_name>
            <last_name>Doe</last_name>
            <bank_name>Test Bank</bank_name>
            <bank_routing_number>021000021</bank_routing_number>
            <bank_account_number>9876543210</bank_account_number>
            <bank_account_type>checking</bank_account_type>
            <bank_account_holder_type>personal</bank_account_holder_type>
        </bank_account>
        <email>jon.doe@example.com</email>
        <data>
            <my_payment_method_identifier>448</my_payment_method_identifier>
            <extra_stuff>
                <some_other_things>Can be anything really</some_other_things>
            </extra_stuff>
        </data>
        <metadata>
          <key>String Value</key>
          <another_key>123</another_key>
          <final_key>true</final_key>
        </metadata>
      </payment_method>'

and get the output:

<transaction>
  <token>NZ8uQMvwLw2ICqiGtJfIVOVYa2j</token>
  <created_at type="dateTime">2023-05-22T19:46:39Z</created_at>
  <updated_at type="dateTime">2023-05-22T19:46:39Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <transaction_type>AddPaymentMethod</transaction_type>
  <retained type="boolean">false</retained>
  <state>succeeded</state>
  <message key="messages.transaction_succeeded">Succeeded!</message>
  <payment_method>
    <token>4FZOtVeKxuyI7WMOepXi3P3JRwA</token>
    <created_at type="dateTime">2023-05-22T19:46:39Z</created_at>
    <updated_at type="dateTime">2023-05-22T19:46:39Z</updated_at>
    <email>jon.doe@example.com</email>
    <data>
      <my_payment_method_identifier>448</my_payment_method_identifier>
      <extra_stuff>
        <some_other_things>Can be anything really</some_other_things>
      </extra_stuff>
    </data>
    <storage_state>cached</storage_state>
    <test type="boolean">true</test>
    <metadata>
      <key>String Value</key>
      <another_key>123</another_key>
      <final_key>true</final_key>
    </metadata>
    <callback_url nil="true"/>
    <full_name>Jon Doe</full_name>
    <bank_name>Test Bank</bank_name>
    <account_type>checking</account_type>
    <account_holder_type>personal</account_holder_type>
    <routing_number_display_digits>021</routing_number_display_digits>
    <account_number_display_digits>3210</account_number_display_digits>
    <first_name>Jon</first_name>
    <last_name>Doe</last_name>
    <address1 nil="true"/>
    <address2 nil="true"/>
    <city nil="true"/>
    <state nil="true"/>
    <zip nil="true"/>
    <country nil="true"/>
    <phone_number nil="true"/>
    <company nil="true"/>
    <payment_method_type>bank_account</payment_method_type>
    <errors>
    </errors>
    <routing_number>021*</routing_number>
    <account_number>*3210</account_number>
  </payment_method>
</transaction>

Second, use third party vaulting to store that payment method in Stripe.

curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/store.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>PsZvGrh0mIrmxzHQUNAscxyA7B1</payment_method_token>
      </transaction>'

and get the output:

<transaction>
  <created_at type="dateTime">2015-12-02T20:47:25Z</created_at>
  <updated_at type="dateTime">2015-12-02T20:47:25Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <token>LjrY8RmuVklBWtnGFskt9PMZdv6</token>
  <state>succeeded</state>
  <gateway_specific_fields nil="true"></gateway_specific_fields>
  <gateway_specific_response_fields>
    <stripe>
      <customer_id>cus_7s6levMt8IqhTR</customer_id>
      <bank_account_id>ba_17cMXgAWOtgoysog7UDWXbn4</bank_account_id>
    </stripe>
  </gateway_specific_response_fields>
  <transaction_type>Store</transaction_type>
  <third_party_token nil="true"></third_party_token>
  <gateway_transaction_id>cus_7s6levMt8IqhTR|ba_17cMXgAWOtgoysog7UDWXbn4</gateway_transaction_id>
  <message key="messages.transaction_succeeded">Succeeded!</message>
  <payment_method>
    <token>LgpTNGjsWQs9DwdxcbreUVz0R8p</token>
    <created_at type="dateTime">2015-12-02T20:47:25Z</created_at>
    <updated_at type="dateTime">2015-12-02T20:47:25Z</updated_at>
    <gateway_type>stripe</gateway_type>
    <storage_state>retained</storage_state>
    <third_party_token>cus_7s6levMt8IqhTR|ba_17cMXgAWOtgoysog7UDWXbn4</third_party_token>
    <payment_method_type>third_party_token</payment_method_type>
    <errors></errors>
  </payment_method>
  <basis_payment_method>
    <token>PsZvGrh0mIrmxzHQUNAscxyA7B1</token>
    <created_at type="dateTime">2015-12-02T20:47:13Z</created_at>
    <updated_at type="dateTime">2015-12-02T20:47:13Z</updated_at>
    <email>joey@example.com</email>
    <data>
      <my_payment_method_identifier>448</my_payment_method_identifier>
      <extra_stuff>
        <some_other_things>Can be anything really</some_other_things>
      </extra_stuff>
    </data>
    <storage_state>cached</storage_state>
    <test type="boolean">true</test>
    <full_name>Joey Jones</full_name>
    <bank_name nil="true"/>
    <account_type>checking</account_type>
    <account_holder_type>personal</account_holder_type>
    <routing_number_display_digits>021</routing_number_display_digits>
    <account_number_display_digits>3210</account_number_display_digits>
    <first_name>Joey</first_name>
    <last_name>Jones</last_name>
    <payment_method_type>bank_account</payment_method_type>
    <errors></errors>
    <routing_number>021*</routing_number>
    <account_number>*3210</account_number>
  </basis_payment_method>
  <response>
    <success type="boolean">true</success>
    <message>Transaction approved</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_detail nil="true"/>
    <cancelled type="boolean">false</cancelled>
    <fraud_review nil="true"/>
    <created_at type="dateTime">2015-12-02T20:47:25Z</created_at>
    <updated_at type="dateTime">2015-12-02T20:47:25Z</updated_at>
  </response>
</transaction>

Third, after the bank account has been stored it will need to be verified by Stripe before it can be used for transactions.

Stripe will make two small deposits into the stored bank account. You will need to verify the vaules with Stripe by using their API directly. For this verification you will need the Stripe customer_id and bank_account_id fields from Stripe included in the gateway_specific_response_fields from the third party vaulting response.

Finally, once the bank account has been verified the payment_method_token can be used for transactions.

3DS transactions

NOTE: Stripe recommends use of their Payment Intents API when initiating 3DS transactions. To utilize the new API with Spreedly, see the Stripe Payment Intents gateway.

Spreedly supports 3DS on Stripe through the sources API. Stripe uses an asynchronous flow for processing 3DS transactions, relying upon callback notifications to communicate when a source becomes chargeable. Due to the asynchronous nature of 3DS transactions on Stripe, there is no guarantee that a transaction is complete when a customer’s browser is redirected back to your site. You will need to continue to check the status of the transaction at Spreedly until it has completed. To be notified by Spreedly when the transaction has succeeded, see the callbacks section in our guide to 3D Secure.

To use Stripe 3DS on Spreedly, you must create a webhook endpoint at Stripe so that they can notify us about changes to a source’s status. Create the webhook through your Stripe dashboard, or programmatically, with the following properties:

  • Endpoint URL: https://core.spreedly.com/stripe/webhooks
  • Events: source.chargeable, source.cancelled, and source.failed

NOTE: If you are using connected accounts you must create a webhook endpoint that receives events from Connect applications.

After saving the webhook, you will need to obtain two properties for use in your Stripe gateway at Spreedly that are available by accessing the webhook detail page in Stripe’s dashboard.

The webhook_id can be found in your browser’s address bar and is the last segment of the URL. The Stripe webhook id begins with we_, for example: we_1EYfxCAWOtgoysog3lIoCESp. The webhook_signing_secret is located in the 'Signing Secret’ section of the webhook detail page. Spreedly uses these values to ensure we can receive notifications for changes to a source’s status and to verify that events are sent by Stripe.

Once you have the webhook_id and webhook_signing_secret, you can create a gateway in the Spreedly API by passing them as parameters like so:


curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>stripe</gateway_type>
        <login>your api secret key</login>
        <webhook_id>your webhook id</webhook_id>
        <webhook_signing_secret>your webhook signing secret</webhook_signing_secret>
      </gateway>'

<gateway>
  <token>L1EYLFSsPaBMhSWQ8XNRh5YuzOP</token>
  <gateway_type>stripe</gateway_type>
  <name>Stripe</name>
  <description nil="true"/>
  <merchant_profile_key nil="true"/>
  <characteristics>
    <supports_purchase type="boolean">true</supports_purchase>
    <supports_authorize type="boolean">true</supports_authorize>
    <supports_capture type="boolean">true</supports_capture>
    <supports_credit type="boolean">true</supports_credit>
    <supports_general_credit type="boolean">false</supports_general_credit>
    <supports_void type="boolean">true</supports_void>
    <supports_adjust type="boolean">false</supports_adjust>
    <supports_verify type="boolean">true</supports_verify>
    <supports_reference_purchase type="boolean">false</supports_reference_purchase>
    <supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
    <supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
    <supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
    <supports_3dsecure_purchase type="boolean">true</supports_3dsecure_purchase>
    <supports_3dsecure_authorize type="boolean">true</supports_3dsecure_authorize>
    <supports_3dsecure_2_mpi_purchase type="boolean">false</supports_3dsecure_2_mpi_purchase>
    <supports_3dsecure_2_mpi_authorize type="boolean">false</supports_3dsecure_2_mpi_authorize>
    <supports_store type="boolean">true</supports_store>
    <supports_remove type="boolean">true</supports_remove>
    <supports_fraud_review type="boolean">false</supports_fraud_review>
    <supports_network_tokenization type="boolean">false</supports_network_tokenization>
    <supports_populate_mit_fields type="boolean">false</supports_populate_mit_fields>
  </characteristics>
  <credentials>
  </credentials>
  <gateway_settings>
    <webhook_id>your webhook id</webhook_id>
    <version_override nil="true"/>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>receipt_email</gateway_specific_field>
    <gateway_specific_field>radar_session_id</gateway_specific_field>
    <gateway_specific_field>skip_radar_rules</gateway_specific_field>
    <gateway_specific_field>application_fee</gateway_specific_field>
    <gateway_specific_field>stripe_account</gateway_specific_field>
    <gateway_specific_field>metadata</gateway_specific_field>
    <gateway_specific_field>idempotency_key</gateway_specific_field>
    <gateway_specific_field>refund_application_fee</gateway_specific_field>
    <gateway_specific_field>refund_fee_amount</gateway_specific_field>
    <gateway_specific_field>reverse_transfer</gateway_specific_field>
    <gateway_specific_field>account_id</gateway_specific_field>
    <gateway_specific_field>customer_id</gateway_specific_field>
    <gateway_specific_field>validate</gateway_specific_field>
    <gateway_specific_field>make_default</gateway_specific_field>
    <gateway_specific_field>statement_description</gateway_specific_field>
    <gateway_specific_field>statement_descriptor_suffix</gateway_specific_field>
    <gateway_specific_field>destination</gateway_specific_field>
    <gateway_specific_field>destination_amount</gateway_specific_field>
    <gateway_specific_field>merchant_reference</gateway_specific_field>
    <gateway_specific_field>customer_reference</gateway_specific_field>
    <gateway_specific_field>shipping_address_zip</gateway_specific_field>
    <gateway_specific_field>shipping_from_zip</gateway_specific_field>
    <gateway_specific_field>shipping_amount</gateway_specific_field>
    <gateway_specific_field>line_items</gateway_specific_field>
    <gateway_specific_field>transfer_destination</gateway_specific_field>
    <gateway_specific_field>transfer_amount</gateway_specific_field>
    <gateway_specific_field>transfer_group</gateway_specific_field>
    <gateway_specific_field>on_behalf_of</gateway_specific_field>
    <gateway_specific_field>application_fee_amount</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
    <payment_method>third_party_token</payment_method>
    <payment_method>apple_pay</payment_method>
    <payment_method>bank_account</payment_method>
    <payment_method>google_pay</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <sandbox type="boolean">false</sandbox>
  <created_at type="dateTime">2022-01-04T20:11:45Z</created_at>
  <updated_at type="dateTime">2022-01-04T20:11:45Z</updated_at>
</gateway>

Gateway specific fields

Spreedly supports the following gateway specific fields when transacting with a Stripe gateway:

  • application_fee
  • refund_application_fee
  • refund_fee_amount
  • reverse_transfer
  • reason
  • statement_description
  • statement_descriptor_suffix
  • destination
  • destination_amount
  • idempotency_key
  • metadata
  • stripe_account
  • receipt_email
  • merchant_reference
  • customer_reference
  • shipping_address_zip
  • shipping_from_zip
  • shipping_amount
  • line_items
  • customer_id
  • account_id
  • validate
  • make_default
  • transfer_destination
  • transfer_amount
  • transfer_group
  • on_behalf_of
  • application_fee_amount
  • radar_session_id
  • skip_radar_rules
  • recurring

When using Stripe Connect, Stripe allows you to specify an application_fee on authorize, purchase, or captures, which is a number of cents to be charged on top of Stripe’s normal fees.

The statement_description and statement_descriptor_suffix fields are ways to set the string that is displayed on your customer’s credit card statement. See the Stripe documentation on statement descriptors for more information.

Setting a destination parameter identifies the Stripe account that should receive the funds from the payment. An optional parameter, destination_amount, can be used to specify the amount of the charge to be transfered to the destination account.

The transfer_destination, transfer_group, transfer_amount, on_behalf_of, and application_fee_amount fields may be set if you want to create charges on behalf of connected accounts. For more information about charging connected accounts using Stripe, see here. NOTE: transfer_amount and application_fee_amount are mutually exclusive; when using this feature, only set one of them in your request.

The idempotency_key is for safely retrying requests without accidentally performing the same operation twice. Pass the metadata array to attach custom key-value data to Stripe transactions. The stripe_account field is for processing a charge directly on a connected account, and the receipt_email field is for specifying an email address to receive the payment receipt.

The recurring field accepts a boolean value which can be used to mark a transaction as recurring or non-recurring. NOTE: Stripe already has logic in place to identify whether or not a transaction is recurring, but Stripe has provided this field as a way to supplement or override that logic. If you plan to use this field it is recommended that you contact Stripe’s support team to understand the settings on your Stripe account pertaining to recurring transactions.

Requests to Stripe may include several additional pieces of data to qualify for Level 2 or Level 3 rates. These include merchant_reference, customer_reference, shipping_address_zip, shipping_from_zip, shipping_amount, and line_items. line_items is itself an array of JSON objects detailing the line items of the purchase. See the above section Stripe Radar for usage of the radar_session_id and skip_radar_rules fields.

  • merchant_reference - An alphanumeric string of up to 25 characters in length. This unique value is assigned by the merchant to identify the order. Also known as an “Order ID”.
  • customer_reference - An alphanumeric string of up to 17 characters in length. Customers sometimes are required to supply this; see further discussion below.
  • shipping_address_zip - The customer’s U.S. shipping ZIP code.
  • shipping_from_zip - The merchant’s U.S. shipping ZIP code.
  • shipping_amount - The shipping cost, in cents, as a non-negative integer.
  • line_items - (Array of objects. One object per type of item. Maximum of 200 line items allowed.)
    • product_code: Up to 12 characters that uniquely identify the product.
    • product_description: Up to 26 alphanumeric characters long describing the product.
    • unit_cost: Cost of the product, in cents, as a positive integer greater than 0.
    • quantity: The number of items of this type sold, as a positive integer greater than 0.
    • tax_amount: The amount of tax this item had added to it, in cents, as a non-negative integer.
    • discount_amount: The amount an item was discounted—if there was a sale, for example, as a non-negative integer.

curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
        <amount>100</amount>
        <currency_code>USD</currency_code>
        <gateway_specific_fields>
          <stripe>
            <application_fee>103</application_fee>
            <statement_description>5K Race Ticket</statement_description>
            <statement_descriptor_suffix>ORDER 10108</statement_descriptor_suffix>
            <destination>123456789</destination>
            <destination_amount>10</destination_amount>
            <idempotency_key>idempotency_key</idempotency_key>
            <metadata>
              <hat_type>Fedora</hat_type>
              <cat_name>Waffles</cat_name>
            </metadata>
            <stripe_account>123456789</stripe_account>
            <receipt_email>email@example.com</receipt_email>
            <merchant_reference>cb76a9ffcb</merchant_reference>
            <customer_reference>ab839defab</customer_reference>
            <shipping_address_zip>90210</shipping_address_zip>
            <shipping_from_zip>90210</shipping_from_zip>
            <shipping_amount>10</shipping_amount>
            <line_items><![CDATA[
              [{"product_description": "Used toothpaste", "product_code": 1234}]
            ]]>
            </line_items>
            <transfer_destination>acct_123456789</transfer_destination>
            <transfer_amount>100</transfer_amount>
            <transfer_group>ORDER10</transfer_group>
            <on_behalf_of>acct_123456789</on_behalf_of>
            <application_fee_amount>100</application_fee_amount>
            <radar_session_id>re_dfa3648ceeaf456a</radar_session_id>
            <skip_radar_rules>true</skip_radar_rules>
            <recurring>true</recurring>
          </stripe>
        </gateway_specific_fields>
      </transaction>'

<transaction>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2022-02-25T18:13:47Z</created_at>
  <updated_at type="dateTime">2022-02-25T18:13:47Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>HJsqpGLrTSIoWGMlYyd54HW3mIg</token>
  <transaction_type>Purchase</transaction_type>
  <order_id nil="true"/>
  <ip nil="true"/>
  <description nil="true"/>
  <email nil="true"/>
  <merchant_name_descriptor nil="true"/>
  <merchant_location_descriptor nil="true"/>
  <merchant_profile_key nil="true"/>
  <gateway_specific_fields>
    <stripe>
      <application_fee>103</application_fee>
      <statement_description>5K Race Ticket</statement_description>
      <statement_descriptor_suffix>ORDER 10108</statement_descriptor_suffix>
      <destination>123456789</destination>
      <destination_amount>10</destination_amount>
      <idempotency_key>idempotency_key</idempotency_key>
      <metadata>
        <hat_type>Fedora</hat_type>
        <cat_name>Waffles</cat_name>
      </metadata>
      <stripe_account>123456789</stripe_account>
      <receipt_email>email@example.com</receipt_email>
      <merchant_reference>cb76a9ffcb</merchant_reference>
      <customer_reference>ab839defab</customer_reference>
      <shipping_address_zip>90210</shipping_address_zip>
      <shipping_from_zip>90210</shipping_from_zip>
      <shipping_amount>10</shipping_amount>
      <line_items>
              [{"product_description": "Used toothpaste", "product_code": 1234}]
            
            </line_items>
      <transfer_destination>acct_123456789</transfer_destination>
      <transfer_amount>100</transfer_amount>
      <transfer_group>ORDER10</transfer_group>
      <on_behalf_of>acct_123456789</on_behalf_of>
      <application_fee_amount>100</application_fee_amount>
      <radar_session_id>re_dfa3648ceeaf456a</radar_session_id>
      <skip_radar_rules>true</skip_radar_rules>
      <recurring>true</recurring>
    </stripe>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
  </gateway_specific_response_fields>
  <gateway_transaction_id>59</gateway_transaction_id>
  <sub_merchant_key nil="true"/>
  <gateway_latency_ms type="integer">0</gateway_latency_ms>
  <stored_credential_initiator nil="true"/>
  <stored_credential_reason_type nil="true"/>
  <populate_mit_fields type="boolean">false</populate_mit_fields>
  <warning nil="true"/>
  <application_id nil="true"/>
  <amount type="integer">100</amount>
  <currency_code>USD</currency_code>
  <retain_on_success type="boolean">false</retain_on_success>
  <payment_method_added type="boolean">false</payment_method_added>
  <smart_routed type="boolean">false</smart_routed>
  <message key="messages.transaction_succeeded">Succeeded!</message>
  <gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
  <gateway_type>test</gateway_type>
  <shipping_address>
    <name>Newfirst Newlast</name>
    <address1 nil="true"/>
    <address2 nil="true"/>
    <city nil="true"/>
    <state nil="true"/>
    <zip nil="true"/>
    <country nil="true"/>
    <phone_number nil="true"/>
  </shipping_address>
  <response>
    <success type="boolean">true</success>
    <message>Successful purchase</message>
    <avs_code nil="true"/>
    <avs_message nil="true"/>
    <cvv_code nil="true"/>
    <cvv_message nil="true"/>
    <pending type="boolean">false</pending>
    <result_unknown type="boolean">false</result_unknown>
    <error_code nil="true"/>
    <error_detail nil="true"/>
    <cancelled type="boolean">false</cancelled>
    <fraud_review nil="true"/>
    <created_at type="dateTime">2022-02-25T18:13:47Z</created_at>
    <updated_at type="dateTime">2022-02-25T18:13:47Z</updated_at>
  </response>
  <api_urls>
  </api_urls>
  <payment_method>
    <token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
    <created_at type="dateTime">2017-06-26T17:04:38Z</created_at>
    <updated_at type="dateTime">2022-02-24T15:21:08Z</updated_at>
    <email>joey@example.com</email>
    <data>
      <my_payment_method_identifier>448</my_payment_method_identifier>
      <extra_stuff>
        <some_other_things>Can be anything really</some_other_things>
      </extra_stuff>
    </data>
    <storage_state>retained</storage_state>
    <test type="boolean">true</test>
    <metadata>
      <key>string value</key>
    </metadata>
    <callback_url nil="true"/>
    <last_four_digits>1111</last_four_digits>
    <first_six_digits>411111</first_six_digits>
    <card_type>visa</card_type>
    <first_name>Newfirst</first_name>
    <last_name>Newlast</last_name>
    <month type="integer">3</month>
    <year type="integer">2032</year>
    <address1 nil="true"/>
    <address2 nil="true"/>
    <city nil="true"/>
    <state nil="true"/>
    <zip nil="true"/>
    <country nil="true"/>
    <phone_number nil="true"/>
    <company nil="true"/>
    <full_name>Newfirst Newlast</full_name>
    <eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
    <shipping_address1 nil="true"/>
    <shipping_address2 nil="true"/>
    <shipping_city nil="true"/>
    <shipping_state nil="true"/>
    <shipping_zip nil="true"/>
    <shipping_country nil="true"/>
    <shipping_phone_number nil="true"/>
    <payment_method_type>credit_card</payment_method_type>
    <errors>
    </errors>
    <verification_value></verification_value>
    <number>XXXX-XXXX-XXXX-1111</number>
    <fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
  </payment_method>
  <attempt_3dsecure type="boolean">false</attempt_3dsecure>
</transaction>

Please refer to using a payment method for more information on how to send GSFs

Refund fields

Pass refund_application_fee on refunds if the application_fee should be refunded when refunding the charge. Use refund_fee_amount to specify a specific amount of the Stripe Connect application fee that should be refunded. If an amount is specified here, do not use the refund_application_fee field. Use reason to send feedback to Stripe on why the refund is being issued see here. You can also optionally pass reverse_transfer on refunds.


curl https://core.spreedly.com/v1/transactions/KS3oZgWXCfFeirK16anYbijLxR/credit.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
        <amount>100</amount>
        <currency_code>USD</currency_code>
        <gateway_specific_fields>
          <stripe>
            <refund_application_fee>true</refund_application_fee>
            <refund_fee_amount>95</refund_fee_amount>
            <reverse_transfer>true</reverse_transfer>
            <reason>fraudulent</reason>
          </stripe>
        </gateway_specific_fields>
      </transaction>'

<transaction>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2022-01-11T15:30:45Z</created_at>
  <updated_at type="dateTime">2022-01-11T15:30:45Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>8pQpq8PPhmwMCjSJzGCqdlwDvgM</token>
  <transaction_type>Credit</transaction_type>
  <order_id nil="true"/>
  <ip nil="true"/>
  <description nil="true"/>
  <email nil="true"/>
  <merchant_name_descriptor nil="true"/>
  <merchant_location_descriptor nil="true"/>
  <merchant_profile_key nil="true"/>
  <gateway_specific_fields>
    <stripe>
      <refund_application_fee>true</refund_application_fee>
      <refund_fee_amount>95</refund_fee_amount>
      <reverse_transfer>true</reverse_transfer>
      <reason>fraudulent</reason>
    </stripe>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
  </gateway_specific_response_fields>
  <gateway_transaction_id>60</gateway_transaction_id>
  <gateway_latency_ms type="integer">0</gateway_latency_ms>
  <stored_credential_initiator nil="true"/>
  <stored_credential_reason_type nil="true"/>
  <populate_mit_fields type="boolean">false</populate_mit_fields>
  <warning nil="true"/>
  <application_id nil="true"/>
  <amount type="integer">100</amount>
  <currency_code>USD</currency_code>
  <message key="messages.transaction_succeeded">Succeeded!</message>
  <gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
  <gateway_type>test</gateway_type>
  <shipping_address>
    <name nil="true"/>
    <address1 nil="true"/>
    <address2 nil="true"/>
    <city nil="true"/>
    <state nil="true"/>
    <zip nil="true"/>
    <country nil="true"/>
    <phone_number nil="true"/>
  </shipping_address>
  <response>
    <success type="boolean">true</success>
    <message>Successful credit</message>
    <avs_code nil="true"/>
    <avs_message nil="true"/>
    <cvv_code nil="true"/>
    <cvv_message nil="true"/>
    <pending type="boolean">false</pending>
    <result_unknown type="boolean">false</result_unknown>
    <error_code nil="true"/>
    <error_detail nil="true"/>
    <cancelled type="boolean">false</cancelled>
    <fraud_review nil="true"/>
    <created_at type="dateTime">2022-01-11T15:30:45Z</created_at>
    <updated_at type="dateTime">2022-01-11T15:30:45Z</updated_at>
  </response>
  <api_urls>
  </api_urls>
  <reference_token>Myj0xB1lSSymF3we6ZgclVuySgL</reference_token>
</transaction>

Store fields

When storing a credit card in the Stripe vault using third party vaulting, you can specify a customer_id if you’d like to add the card onto an existing customer in your Stripe account. Specify an account_id if you’d like to add the card onto an existing managed account within your Stripe account. Use the validate option and set it to false if you would like Stripe to skip their card validations. If you’d like the card you’re storing to be the default card for that customer, pass in the make_default option.


curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/store.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
        <gateway_specific_fields>
          <stripe>
            <customer_id>cus_3sgheFxeBgTQ8m</customer_id>
            <account_id>acct_3sgheFxeBgTQ8m</account_id>
            <validate>false</validate>
            <make_default>true</make_default>
          </stripe>
        </gateway_specific_fields>
      </transaction>'

<transaction>
  <created_at type="dateTime">2019-10-21T18:27:05Z</created_at>
  <currency_code nil="true"/>
  <updated_at type="dateTime">2019-10-21T18:27:05Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <token>6nrZ5cj0hGg62s4TJDd7gMrOA0G</token>
  <state>succeeded</state>
  <gateway_specific_fields>
    <stripe>
      <customer_id>cus_3sgheFxeBgTQ8m</customer_id>
      <account_id>acct_3sgheFxeBgTQ8m</account_id>
      <validate>false</validate>
      <make_default>true</make_default>
    </stripe>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
  </gateway_specific_response_fields>
  <transaction_type>Store</transaction_type>
  <third_party_token nil="true"/>
  <gateway_transaction_id>45</gateway_transaction_id>
  <gateway_latency_ms type="integer">9</gateway_latency_ms>
  <message key="messages.transaction_succeeded">Succeeded!</message>
  <gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
  <gateway_type>test</gateway_type>
  <payment_method>
    <token>3Hj9YVhFYkCesfnXdYTPf1z2kd3</token>
    <created_at type="dateTime">2019-10-21T18:27:05Z</created_at>
    <updated_at type="dateTime">2019-10-21T18:27:05Z</updated_at>
    <gateway_type>test</gateway_type>
    <storage_state>retained</storage_state>
    <third_party_token>test_vault:4111111111111111</third_party_token>
    <payment_method_type>third_party_token</payment_method_type>
    <errors>
    </errors>
  </payment_method>
  <basis_payment_method>
    <token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
    <created_at type="dateTime">2017-06-26T17:04:38Z</created_at>
    <updated_at type="dateTime">2019-10-21T18:27:05Z</updated_at>
    <email>joey@example.com</email>
    <data>
      <my_payment_method_identifier>448</my_payment_method_identifier>
      <extra_stuff>
        <some_other_things>Can be anything really</some_other_things>
      </extra_stuff>
    </data>
    <storage_state>retained</storage_state>
    <test type="boolean">true</test>
    <metadata>
      <key>string value</key>
    </metadata>
    <callback_url nil="true"/>
    <last_four_digits>1111</last_four_digits>
    <first_six_digits>411111</first_six_digits>
    <card_type>visa</card_type>
    <first_name>Newfirst</first_name>
    <last_name>Newlast</last_name>
    <month type="integer">3</month>
    <year type="integer">2032</year>
    <address1 nil="true"/>
    <address2 nil="true"/>
    <city nil="true"/>
    <state nil="true"/>
    <zip nil="true"/>
    <country nil="true"/>
    <phone_number nil="true"/>
    <company nil="true"/>
    <full_name>Newfirst Newlast</full_name>
    <eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
    <shipping_address1 nil="true"/>
    <shipping_address2 nil="true"/>
    <shipping_city nil="true"/>
    <shipping_state nil="true"/>
    <shipping_zip nil="true"/>
    <shipping_country nil="true"/>
    <shipping_phone_number nil="true"/>
    <payment_method_type>credit_card</payment_method_type>
    <errors>
    </errors>
    <verification_value></verification_value>
    <number>XXXX-XXXX-XXXX-1111</number>
    <fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
  </basis_payment_method>
  <response>
    <success type="boolean">true</success>
    <message>Successful store</message>
    <avs_code nil="true"/>
    <avs_message nil="true"/>
    <cvv_code nil="true"/>
    <cvv_message nil="true"/>
    <pending type="boolean">false</pending>
    <result_unknown type="boolean">false</result_unknown>
    <error_code nil="true"/>
    <error_detail nil="true"/>
    <cancelled type="boolean">false</cancelled>
    <fraud_review nil="true"/>
    <created_at type="dateTime">2019-10-21T18:27:05Z</created_at>
    <updated_at type="dateTime">2019-10-21T18:27:05Z</updated_at>
  </response>
</transaction>

Gateway specific response fields

The following gateway specific response fields could be returned in a response from Stripe.

  • card_funding
  • decline_code
  • outcome_network_status
  • outcome_reason
  • outcome_risk_level
  • outcome_seller_message
  • outcome_type
  • outcome_network_advice_code
  • outcome_network_decline_code
  • stripe_source
  • stripe_source_country
  • stripe_source_fingerprint
  • stripe_source_funding
  • customer_id
  • bank_account_id
  • network_token
  • receipt_url

card_funding indicates what type of funding source was used to complete the transaction, such as credit or debit. decline_code provides a reason as to why a payment was declined. A selection of fields from the outcome and source objects are returned in their corresponding response fields. network_token indicates if Stripe used a network token for the transaction vs PAN.

A response from storing a bank account payment method in Stripe will include customer_id and bank_account_id in the gateway_specific_response_fields. You will need these IDs in order to manually verify the bank account with Stripe.

<transaction>
  <token>LgpTNGjsWQs9DwdxcbreUVz0R8p</token>
  <transaction_type>Purchase</transaction_type>
  <gateway_specific_response_fields>
     <stripe>
       <card_funding>debit</card_funding>
       <decline_code>pickup_card</decline_code>
       <outcome_network_status>network_status</outcome_network_status>
       <outcome_reason>reason</outcome_reason>
       <outcome_risk_level>risk_level</outcome_risk_level>
       <outcome_seller_message>seller_message</outcome_seller_message>
       <outcome_type>type</outcome_type>
       <outcome_network_advice_code>01</outcome_network_advice_code>
       <outcome_network_decline_code>54</outcome_network_decline_code>
       <stripe_source_brand>brand</stripe_source_brand>
       <stripe_source_country>country</stripe_source_country>
       <stripe_source_fingerprint>fingerprint</stripe_source_fingerprint>
       <stripe_source_funding>funding</stripe_source_funding>
       <customer_id>cus_7s6levMt8IqhTR</customer_id>
       <bank_account_id>ba_17cMXgAWOtgoysog7UDWXbn4</bank_account_id>
       <receipt_url>https://pay.stripe.com/receipts/payment/123456</receipt_url>
     </stripe>
  </gateway_specific_response_fields>
</transaction>

If you’d like to request any gateway_specific_fields or gateway_specific_response_fields, please contact Support with your request and the gateway documentation for the fields of interest.