API referenceiFrame APIExpress APISupportBlog
Guides

Exporting payment methods

Suggest Edits

Performing an export from Spreedly to a supported endpoint/gateway, whether for the purpose of migrating one of your merchants to a new provider or for leaving the Spreedly platform completely, is a self-service process that lets you control the export timing and specifics of the process. If your export destination is not listed as a supported endpoint, see Unsupported Endpoints for further instructions.

Self Service on Supported endpoints

For any gateways that support the store transaction type, you can perform an automated export. Please reference the Third Party Vaulting page for a list of all gateways that support store.

Performing the export

To perform an export, iterate through your list of payment method tokens and use the store API to copy a payment method currently in your Spreedly vault to the gateway.

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

You’ll notice in the response that comes back that the ThirdPartyToken payment method has a field called third_party_token. This is the unique ID of the payment method at the gateway which you can then use to transact directly against the target gateway.

<transaction>
  <created_at type="dateTime">2017-07-27T17:53:22Z</created_at>
  <updated_at type="dateTime">2017-07-27T17:53:22Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <token>M6i0pval4KIZBBBGz16ZOqCVhWh</token>
  <state>succeeded</state>
  <gateway_specific_fields nil="true"/>
  <gateway_specific_response_fields>
  </gateway_specific_response_fields>
  <transaction_type>Store</transaction_type>
  <third_party_token nil="true"/>
  <gateway_transaction_id>58</gateway_transaction_id>
  <gateway_latency_ms type="integer">0</gateway_latency_ms>
  <message key="messages.transaction_succeeded">Succeeded!</message>
  <gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
  <payment_method>
    <token>2MPedsuenG2o8yFfrsdOBWmOuEf</token>
    <created_at type="dateTime">2017-07-27T17:53:22Z</created_at>
    <updated_at type="dateTime">2017-07-27T17:53:22Z</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>EToYqm9L2xXQY0wKt9zh1NO0jlX</token>
    <created_at type="dateTime">2017-07-27T17:53:22Z</created_at>
    <updated_at type="dateTime">2017-07-27T17:53:22Z</updated_at>
    <email nil="true"/>
    <data nil="true"/>
    <storage_state>cached</storage_state>
    <test type="boolean">true</test>
    <last_four_digits>1111</last_four_digits>
    <first_six_digits>411111</first_six_digits>
    <card_type>visa</card_type>
    <first_name>Bob</first_name>
    <last_name>Smith</last_name>
    <month type="integer">2</month>
    <year type="integer">2020</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>Bob Smith</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>XXX</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></error_code>
    <error_detail nil="true"/>
    <cancelled type="boolean">false</cancelled>
    <fraud_review nil="true"/>
    <created_at type="dateTime">2017-07-27T17:53:22Z</created_at>
    <updated_at type="dateTime">2017-07-27T17:53:22Z</updated_at>
  </response>
</transaction>

At this point you have a payment method stored at Spreedly and one stored at the gateway (stored in your Spreedly environment as a new third party token payment method). If you are no longer using Spreedly to transact against the payment method and don’t wish to be charged for its storage, you must redact both the original payment method and the third party token payment method created during the store operation.

When performing an export we ask that you limit your requests to no more than five concurrent requests as, for some gateways, the store call can take some time to execute.

Unsupported endpoints

If the location you’re exporting to is not on our supported gateway list, we’ll need to do a manual export of the data. A manual export involves the secure exchange of encrypted files between Spreedly and the PCI compliant third party location. Spreedly generally processes exports within 2 weeks once Spreedly has all required details, assuming the third party location you’re exporting to is responsive.

You must provide Spreedly with:

  • Your environment key(s) where the tokens are located
  • A .csv file of the tokens you would like to export.
    • If you'd like to export an entire environment, the .csv file is not necessary, but please let us know in your request that you'd like a complete migration.
  • The PGP Public Key for the third party destination/gateway.
    • We will provision an SFTP on our end and provide the third party you're exporting the data to with login credentials (encrypted with their PGP key). The third party can retrieve the export file from our SFTP endpoint. If the third party prefers to create the SFTP, please see our File Transfer guide for more information.

After the export is complete, the Spreedly tokens will still remain in your vault. It is your responsibility to redact any payment data you no longer wish to retain in the Spreedly vault.

📘

All communications regarding the manual export request should be kept in one email thread with all the necessary parties involved. Any additional details or side conversations that we are not aware of could cause delays or miscommunications. Our primary objective is to complete your request within the provided timelines to ensure a satisfactory service experience.

Data Format

As part of our standard migration practice, Spreedly will export payment method data to the gateway/third party in JSON or CSV format as shown below.

JSON

For JSON exports, Spreedly will send an encrypted file with the following format:

{
  "credit_cards": [
    {
      "token": "7J4pmjU400wW3qosgNBHbBDKoGM",
      "email": null,
      "number": "5555555555554444",
      "card_type": "visa",
      "first_name": "First",
      "last_name": "Last",
      "full_name": "First Last",
      "year": 2019,
      "month": 3,
      "address1": null,
      "address2": null,
      "city": null,
      "state": null,
      "zip": null,
      "country": null,
      "phone_number": null,
      "shipping_address1": null,
      "shipping_address2": null,
      "shipping_city": null,
      "shipping_state": null,
      "shipping_zip": null,
      "shipping_country": null,
      "shipping_phone_number": null,
      "data": null
    }
  ],
  "bank_accounts": [
    {
      "token": "Kpz9RJRw8Yp4Z3jp8ZjjtixDDW0",
      "email": "[email protected]",
      "account_number": "9876543210",
      "routing_number": "021000021",
      "account_type": "checking",
      "account_holder_type": "personal",
      "first_name": "First",
      "last_name": "Last",
      "full_name": "First Last",
      "address1": null,
      "address2": null,
      "city": null,
      "state": null,
      "zip": null,
      "country": null,
      "phone_number": null,
      "data": null
    }
  ]
}

CSV

For CSV exports, credit cards and bank accounts will be sent in separate encrypted files, with the following headers:

Credit Cards

token,email,number,card_type,first_name,last_name,full_name,year,month,address1,address2,city,state,zip,country,phone_number,shipping_address1,shipping_address2,shipping_city,shipping_state,shipping_zip,shipping_country,shipping_phone_number,data,metadata

Bank Accounts

token,email,account_number,routing_number,account_type,account_holder_type,first_name,last_name,full_name,address1,address2,city,state,zip,country,phone_number,data,metadata

Pricing

Note that Spreedly does one free export per merchant for each third party storage service receiving data. Should you or your customer request multiple exports to the same third party storage service, Spreedly will charge for each additional export.

Any request for modification or addition to the data format above will be considered a custom export and may incur a fee.

Please contact us to request an export or discuss pricing details.

Updated 5 months ago