Stored Credentials

Major card network are now mandating 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.

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

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_transaction_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_transaction_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.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>'