Stored Credentials

Major card networks require that merchants include additional data values in their purchase and authorization requests to identify the storage and use of payment credentials. According to the card networks, merchants utilizing the stored credentials framework should see an improvement in approval rates especially for recurring and subscription based charges.

In continuing to provide a consistent interface to payment gateways, Spreedly provides first class support for sending stored credential data to a select number of gateways. Adding a bit of additional data to your transaction will enable Spreedly to generate the appropriate payment gateway request taking into account both the state of the payment method you are using and the additional data you are sending. Furthermore Spreedly handles storing and sending card network specific information allowing payment methods to be seamlessly used between different gateways while still providing the appropriate mapping of stored credential fields.

The enforcement of strong customer authentication(SCA) in the EEA has made Stored Credentials even more pertinent when it comes to improving success rates. Merchant Initiated Transactions(MIT) are out of scope of SCA and therefore 3DS does not need to be requested on MITs that have were previously authenticated during the CIT. Since transactions cannot be challenged when out of scope, utilizing the stored credentials framework will let the issuing bank know that the transaction is merchant initiated, and will link back to the original CIT that was authenticated.

You can read more about stored credentials in this document provided by Visa.

Supported Gateways

MIT Frameworks Supported Gateways

Sending Stored Credential Data

Sending stored credential data is simple. For any Authorize or Purchase request you need to include two fields which tell Spreedly a little bit more about the nature of the transaction.

  • stored_credential_initiator
  • stored_credential_reason_type

Both fields are required for Spreedly to populate requests to your payment gateway with the necessary stored credential fields. If only one of the fields is sent Spreedly will continue with the transaction but skip adding any stored credential data. Additionally, the two fields have a subset of values that are accepted.

  • stored_credential_initiator - merchant or cardholder
  • stored_credential_reason_type - recurring or unscheduled or installment

You should use the combination of those two field values to properly identify the type of transaction you are sending. For example, if your transaction is for a regular monthly subscription and is charged the same time at a set interval (such as monthly) you would send a combination of "merchant" and "recurring". Or, if your customer is purchasing something on your website as a one time purchase but you are storing their payment details for future use, you would send "cardholder" and "unscheduled".

Example Usage

$ curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.json \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/json' \
  -d '{
        "transaction": {
          "payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
          "amount": 100,
          "currency_code": "USD",
          "stored_credential_initiator": "cardholder",
          "stored_credential_reason_type": "unscheduled"
        }
      }'

$ 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>
        <stored_credential_initiator>cardholder</stored_credential_initiator>
        <stored_credential_reason_type>unscheduled</stored_credential_reason_type>
      </transaction>'


To see how Spreedly used the stored credential fields you submitted along with the payment method used to generate the request to the gateway, you can use the transcript request to view the communication between Spreedly and your payment gateway. You may need to match it against the gateway docs to see that gateway’s specific stored credential fields.

Populate Merchant Initiated Transactions Fields

If you want to request Merchant Initiated Transactions (MIT), you are still able to do so using the above stored credential fields, however, Spreedly has a feature that can be used concurrently with the above fields in order to take away the burden of mapping additional MIT gateway specific fields. Often times gateways require the stored credential fields to be sent along with additional GSFs, using the populate MIT GSFs functionality takes away the extra mapping required on the gateway side to mark a transaction as merchant initiated.

When you provide populate_mit_fields=true, Spreedly includes the gateway specific fields (GSFs) required to identify the transaction as a Merchant Initiated Transaction (MIT) on your behalf. The first transaction is required to be Customer Initiated Transaction (CIT) in order to enable subsequent MIT transactions.

In many cases, gateways require GSFs to be sent in during a purchase or authorize in order to note that the transaction is a MIT and therefore out of scope of SCA. Managing the different gateway specific rules/fields in addition to stored credentials can be cumbersome, especially for merchants that perform MIT on multiple gateways.

Note: We recommend not sending these GSFs when populate_mit_fields=true, as they are always overwritten for MIT.

Setup using CIT

$ curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.json \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/json' \
  -d '{
        "transaction": {
          "payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
          "amount": 100,
          "currency_code": "USD",
          "stored_credential_initiator": "cardholder",
          "stored_credential_reason_type": "recurring",
          "populate_mit_fields": "true"
        }
      }'

$ 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>
        <stored_credential_initiator>cardholder</stored_credential_initiator>
        <stored_credential_reason_type>recurring</stored_credential_reason_type>
        <populate_mit_fields>true</populate_mit_fields>
      </transaction>'


Subsequent MIT Transactions

$ curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.json \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/json' \
  -d '{
        "transaction": {
          "payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
          "amount": 100,
          "currency_code": "USD",
          "stored_credential_initiator": "merchant",
          "stored_credential_reason_type": "recurring",
          "populate_mit_fields": "true"
        }
      }'

$ 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>
        <stored_credential_initiator>merchant</stored_credential_initiator>
        <stored_credential_reason_type>recurring</stored_credential_reason_type>
        <populate_mit_fields>true</populate_mit_fields>
      </transaction>'


When you set populate_mit_fields to false or omit it, stored credentials work as usual and you must send in any GSFs that the gateway requires to properly identify the transaction as MIT.

Card Network Transaction Id

If you’ve read up on stored credentials regulations, you might be wondering where the card network transaction id is or if you need to worry about accessing that from a gateway response in order to submit that with future transactions. The short answer is no, you don’t need to worry about accessing that response from the gateway. Spreedly is handling storing that information for you with your payment methods and automatically injecting it into future transactions. Moreover, we’ll save multiple card network transaction ids by gateway and only use a network transaction id that was returned from a gateway in future transaction requests.

For example, if you initially use a payment method against Worldpay we’ll save a network transaction id returned from Worldpay with your payment method. Then down the road you use that same payment method against Orbital. We won’t send the Worldpay card network transaction id to Orbital, but we will get a new one from Orbital and your payment method will now have a Worldpay and Orbital network transaction id saved with it. If you later switch back to Worldpay you’ll see us send that old Worldpay network transaction id instead of a more recent one returned by Orbital.