Stripe Payment Intents Gateway Guide

close

Services and Compatibility

Payment Gateway Company Name:
Stripe Payment Intents
Services that work with Spreedly:
  • Stripe Payment Intents
Supported operations:
Purchase, Authorize, Capture, Refund, Void, Verify, Store
Supported payment types:
Credit Card, Apple Pay, Bank Account, Android Pay
3D Secure 1 Supported
Yes
3D Secure 2 Supported
Yes
Regions:
Africa, Asia Pacific, Europe, Latin America, Middle East, North America
API endpoint URL:
https://api.stripe.com/v1/

Authentication and Security

Specific names for credentials:
Login

Onboarding Merchants in:

Adding a Stripe Payment Intents gateway

NOTE: Stripe Payment Intents is an alpha gateway implementation utilizing the Stripe Payment Intents API. If you want to use the legacy Stripe API, see the Stripe Gateway.

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


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

<gateway>
  <token>PDAcBQW1vtPaPaqWhgfOBxgZw8n</token>
  <gateway_type>stripe_payment_intents</gateway_type>
  <name>Stripe Payment Intents</name>
  <description 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_3dsecure_2_purchase type="boolean">true</supports_3dsecure_2_purchase>
    <supports_3dsecure_2_authorize type="boolean">true</supports_3dsecure_2_authorize>
  </characteristics>
  <credentials>
  </credentials>
  <gateway_specific_fields>
    <gateway_specific_field>statement_description</gateway_specific_field>
    <gateway_specific_field>destination</gateway_specific_field>
    <gateway_specific_field>destination_amount</gateway_specific_field>
    <gateway_specific_field>idempotency_key</gateway_specific_field>
    <gateway_specific_field>receipt_email</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>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>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>stripe_account</gateway_specific_field>
    <gateway_specific_field>capture_method</gateway_specific_field>
    <gateway_specific_field>confirmation_method</gateway_specific_field>
    <gateway_specific_field>customer</gateway_specific_field>
    <gateway_specific_field>description</gateway_specific_field>
    <gateway_specific_field>off_session</gateway_specific_field>
    <gateway_specific_field>return_url</gateway_specific_field>
    <gateway_specific_field>save_payment_method</gateway_specific_field>
    <gateway_specific_field>setup_future_usage</gateway_specific_field>
    <gateway_specific_field>statement_descriptor</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>android_pay</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <created_at type="dateTime">2019-08-19T18:29:06Z</created_at>
  <updated_at type="dateTime">2019-08-19T18:29:06Z</updated_at>
</gateway>

3DS Transactions

Spreedly supports 3DS on Stripe through the Payment Intents API. Both 3DS2 and 3DS1 transactions utilize a redirect flow for customers to authorize their payment method before completing an authorization or purchase.

NOTE: As you initiate a new 3DS transaction, Spreedly will automatically attempt to confirm the associated PaymentIntent on creation. Additionally, we set the capture_method to be manual, making a separate call to capture the funds once 3DS is successful (or bypassed), as long as your transaction is a purchase.

Stripe uses an asynchronous flow for processing 3DS transactions, relying upon callback notifications to communicate the payment intent’s stages. 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 payment intent’s status. Create the webhook through your Stripe dashboard, or programmatically, with the following properties:

  • Endpoint URL: https://core.spreedly.com/stripe/webhooks
  • Events: payment_intent.succeeded, payment_intent.payment_failed, and payment_intent.amount_capturable_updated

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 payment intent’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_payment_intents</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>372l4ofBwGQvmCGOeEyhGFZMAMh</token>
  <gateway_type>stripe_payment_intents</gateway_type>
  <name>Stripe Payment Intents</name>
  <description 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_3dsecure_2_purchase type="boolean">true</supports_3dsecure_2_purchase>
    <supports_3dsecure_2_authorize type="boolean">true</supports_3dsecure_2_authorize>
  </characteristics>
  <credentials>
  </credentials>
  <gateway_specific_fields>
    <gateway_specific_field>statement_description</gateway_specific_field>
    <gateway_specific_field>destination</gateway_specific_field>
    <gateway_specific_field>destination_amount</gateway_specific_field>
    <gateway_specific_field>idempotency_key</gateway_specific_field>
    <gateway_specific_field>receipt_email</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>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>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>stripe_account</gateway_specific_field>
    <gateway_specific_field>capture_method</gateway_specific_field>
    <gateway_specific_field>confirmation_method</gateway_specific_field>
    <gateway_specific_field>customer</gateway_specific_field>
    <gateway_specific_field>description</gateway_specific_field>
    <gateway_specific_field>off_session</gateway_specific_field>
    <gateway_specific_field>return_url</gateway_specific_field>
    <gateway_specific_field>save_payment_method</gateway_specific_field>
    <gateway_specific_field>setup_future_usage</gateway_specific_field>
    <gateway_specific_field>statement_descriptor</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>android_pay</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <created_at type="dateTime">2019-08-20T14:27:23Z</created_at>
  <updated_at type="dateTime">2019-08-20T14:27:23Z</updated_at>
</gateway>

Gateway Specific Fields

Optional gateway specific fields of particular note, particularly when attempting 3D Secure transactions, are highlighted below:

  • return_url
  • setup_future_usage
  • off_session
  • customer
  • transfer_destination
  • transfer_group
  • transfer_amount
  • application_fee
  • description
  • confirm

If the customer is directly in the checkout flow and may need to authenticate their payment method, be sure to include a return_url. This is the url the customer will be redirected to following authentication.

In order to use the payment method attached to a Payment Intent in future transactions, set the value of setup_future_usage to off_session. If you want to ensure that the payment method is only used when the customer is present in the checkout flow, set it to on_session. In subsequent transactions using a payment method that’s been setup for future usage, set the gateway specific field off_session to true. Note: If you plan to use these features, ensure that you have obtained permission from the customer.

If a customer already exists for a payment method, you can pass the customer id in the customer field. When this is used, any payment methods used with the intent can only be attached to the customer provided, and payment methods that have been attached to another customer can’t be used with the current payment intent.

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

Payment Intents must be confirmed before they can be used. When initiating Spreedly’s solution for Stripe Payment Intents, we will automatically confirm the intent in order to kick off and proceed through the intended action. However, if you desire to confirm the payment intent on your end, set the confirm field to false.

NOTE: Only set confirm to false if you are prepared to manually confirm the intent yourself; when false, Spreedly will create a new payment intent, but halt any other processing of the payment intent. You may retrieve the Payment Intent’s id from the transaction’s gateway_transaction_id to proceed directly with Stripe.


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_payment_intents>
            <return_url>http://www.example.com/redirect</return_url>
            <description>Description of transaction</description>
            <capture_method>manual</capture_method>
            <customer>cus_3sgheFxeBgTQ8m</customer>
            <setup_future_usage>off_session</setup_future_usage>
            <off_session>false</off_session>
          </stripe_payment_intents>
        </gateway_specific_fields>
      </transaction>'


<transaction>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2019-08-20T15:34:10Z</created_at>
  <updated_at type="dateTime">2019-08-20T15:34:10Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>31cTmDy4I1jUX0QFZtQFe7wSEKb</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"/>
  <gateway_specific_fields>
    <stripe_payment_intents>
      <return_url>http://www.example.com/redirect</return_url>
      <description>Description of transaction</description>
      <capture_method>manual</capture_method>
      <customer>cus_3sgheFxeBgTQ8m</customer>
      <setup_future_usage>off_session</setup_future_usage>
      <off_session>false</off_session>
    </stripe_payment_intents>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
  </gateway_specific_response_fields>
  <gateway_transaction_id>45</gateway_transaction_id>
  <gateway_latency_ms type="integer">22</gateway_latency_ms>
  <stored_credential_initiator nil="true"/>
  <stored_credential_reason_type 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>
  <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">2019-08-20T15:34:10Z</created_at>
    <updated_at type="dateTime">2019-08-20T15:34:10Z</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">2019-08-20T15:34:09Z</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>
</transaction>


env = Spreedly::Environment.new('C7cRfNJGODKh4Iu5Ox3PToKjniY', '4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ', base_url: 'https://core.spreedly.com')
env.purchase_on_gateway("LlkjmEk0xNkcWrNixXa1fvNoTP4", "56wyNnSmuA6CWYP7w0MiYCVIbW6", 4432,
  gateway_specific_fields: {
    stripe_payment_intents: {
      return_url: 'http://www.example.com/redirect',
      description: 'Description of transaction',
      capture_method: 'manual',
      customer: 'cus_3sgheFxeBgTQ8m',
      setup_future_usage: 'off_session',
      off_session: false
    }
  }
)


#<Spreedly::Purchase:0x00007ff59d53e5e0
@token="AZnD7CqRbdZRU4qLmZasLetFHEG",
@created_at="2019-08-20T15:34:10Z",
@updated_at="2019-08-20T15:34:10Z",
@state="succeeded",
@message="Succeeded!",
@succeeded="true",
@order_id="",
@ip="",
@description="",
@gateway_token="T11bJAANtTWnxl36GYjKWvbNK0g",
@gateway_transaction_id="46",
@email="",
@transaction_type="Purchase",
@merchant_name_descriptor="",
@merchant_location_descriptor="",
@on_test_gateway="true",
@currency_code="USD",
@callback_url="",
@stored_credential_initiator="",
@stored_credential_reason_type="",
@amount="4432",
@response,=
#<Spreedly::Response:0x00007ff59d5246e0
@success="true",
@pending="false",
@cancelled="false",
@fraud_review="",
@created_at="2019-08-20T15:34:10Z",
@updated_at="2019-08-20T15:34:10Z",
@message="Successful purchase",
@avs_code="",
@avs_message="",
@cvv_code="",
@cvv_message="",
@error_code="",
@error_detail="">,
@shipping_address,=
#<Spreedly::ShippingAddress:0x00007ff59d5153c0
@name="Newfirst Newlast",
@address1="",
@address2="",
@city="",
@state="",
@zip="",
@country="",
@phone_number="">,
@gateway_specific_fields={:stripe_payment_intents=>{:return_url=>"http://www.example.com/redirect", :description=>"Description of transaction", :capture_method=>"manual", :customer=>"cus_3sgheFxeBgTQ8m", :setup_future_usage=>"off_session", :off_session=>"false"}},
@gateway_specific_response_fields={},
@payment_method,=
#<Spreedly::CreditCard:0x00007ff59d50cb08
@token="1rpKvP8zOUhj4Y9EDrIoIYQzzD5",
@created_at="2017-06-26T17:04:38Z",
@updated_at="2019-08-20T15:34:10Z",
@email="joey@example.com",
@storage_state="retained",
@data="<my_payment_method_identifier>448</my_payment_method_identifier>\n      <extra_stuff>\n        <some_other_things>Can be anything really</some_other_things>\n      </extra_stuff>",
@payment_method_type="credit_card",
@first_name="Newfirst",
@last_name="Newlast",
@full_name="Newfirst Newlast",
@month="3",
@year="2032",
@number="XXXX-XXXX-XXXX-1111",
@last_four_digits="1111",
@first_six_digits="411111",
@card_type="visa",
@verification_value="",
@address1="",
@address2="",
@city="",
@state="",
@zip="",
@country="",
@phone_number="",
@company="",
@fingerprint="e3cef43464fc832f6e04f187df25af497994",
@eligible_for_card_updater="true",
@errors=[]>>

3DS Exemptions

A number of exemptions, including transaction risk analysis and low value requests, are covered automatically by Stripe Radar. As long as your account has access to this service, you do not need to take any further action to take advantage of these exemptions. Contact Stripe if you have any questions about this feature, or need to add it to your account.

Other exemptions that require additional fields are listed below:

MOTO

In order to mark any payments as MOTO, set the gateway specific field moto to true. You must contact Stripe to enable this feature on your account.

MIT

To set up recurring transactions that have the best success of bypassing 3DS authentication, set the value of setup_future_usage to off_session on the initial transaction. This will allow the customer to authenticate once, and then indicates that you plan to use the card in subsequent, off-session transactions where the customer isn’t present. In subsequent transactions using a payment method that’s been setup for future usage, set the gateway specific field off_session to true. Additionally, if you saved the payment method before September 14, 2019, Stripe will attempt to grandfather the payment method in.