• Documentation
• Guides

Payment Method Distribution

In addition to built-in gateway integration, Spreedly supports the ability to distribute vaulted credit card data to third parties, referred to as “receivers”. Distribution differs from third-party vaulting in that the recipient of the card data is not a known and supported endpoint that Spreedly has fully integrated with; it can be another third party with whom you do business.

How distribution works

Payment method distribution (PMD) allows you to transact against another service’s API while still controlling your customer’s card data by vaulting with Spreedly.

Consider a travel service that books accommodations on behalf of its users. The travel service would be able to store its customers’ card data in Spreedly up front and use that data to purchase airline and hotel reservations on behalf of its customers later. The service would ask its customers to enter their credit card information only once but would be able to use that information at any later time to make purchases at multiple independent services (e.g., airlines and hotels).

Spreedly’s payment method distribution enables businesses to transact with multiple endpoints on behalf of their customers via a single integration.

Single vs. batch distribution

Payment method distribution (PMD) can operate in two modes: single card PMD or batch export PMD. If you’re working with an external HTTPS API endpoint that accepts a single card per call, then use single card PMD. If you’re working with an SFTP endpoint that accepts a file containing multiple cards, then use batch export PMD.

In both modes, the basic workflow remains the same: you specify a template that tells Spreedly how to format the request and which card(s) to deliver, and Spreedly executes the call on your behalf. Spreedly provides an open repository of code templates for simplifying implementation of new receivers. The single card and batch export PMD modes operate very similarly; one small difference between the two is that batch export operates asynchronously, making it a bit more complex.

The following guides explain how to provision a receiver and how to distribute payment methods for the two PMD modes:

• Single card PMD
• Batch export PMD

Supporting your receiver

You can begin developing and testing your PMD workflow using a test receiver. However, before you can distribute real payment method data, your receiver must be confirmed and implemented by Spreedly. Please email the following information to Spreedly to get your receiver in the approval queue:

• the receiver name and/or company name,
• a link to their public site, and
• the production URL you will be invoking with Spreedly payment data. While HTTPS endpoints must utilize SSL, Spreedly does not require the SSL certificate to set up and allow the domain, which ensures that you are not affected when the receiver updates their certificates. If there will be a domain change, please contact Spreedly Support and let us know in advance.

Alternatively, if you have an existing relationship or contact at the receiver company, you can send them to Becoming a Receiver so that they can work with Spreedly directly.

We ask that you allow several weeks for Spreedly to approve and configure a receiver for production use. During this time, you can begin testing against a test receiver, which simulates the delivery of test payment methods to a user-specified endpoint URL. We will return the parsed and formatted request in the delivery response, with sensitive data scrubbed, but we will not deliver the request to a third-party endpoint. The test receiver allows you to validate the deliver API request while ensuring the request is properly formatted using our provided receiver variables and functions.

Once you’ve set up your receiver, you can see which requests are powered by Spreedly by looking for the X-Transaction-Powered-By: Spreedly header. Filtering requests to ones with this header can be helpful for debugging and for tracking Spreedly-originating transactions.

Using SSL certification with your receiver

Some endpoints require a certificate to authenticate your call. In these cases, you can attach a certificate to your receiver using the Spreedly API.

1. Generate a certificate signing request using the certificates API, which will return a certificate token.
2. Send the CSR to the endpoint so it can be signed
3. Update the certificate with the signed PEM received from the endpoint
4. Provision your receiver using the field ssl_certificate_token adding the certificate token as the value

Use PMD with 3DS

Payment Method Distribution can be used with 3DS2 by passing 3DS2 authentication results into the body of your request. The 3DS2 authentication can be performed by Spreedly via the Spreedly Global 3DS2 service.

If using the Spreedly Global 3DS2 service for authentication, follow these steps to send authentication data through PMD:

1. Create an SCA Authentication for the payment method and amount that will be used in the delivery
   • See our Spreedly Global 3DS2 Global Guide for more information on performing 3DS2 authentications with Spreedly
2. Pass the authentication values from the response of the SCA Authentication into your deliver request’s body
   • Please see our API reference for details on the SCA Authentication response object

Note: Values required by receiver from the SCA Authentication can vary depending on your receiver. Refer back to the receiver’s documentation to get specifics like sample requests etc.

List of supported receivers

We currently support the following receiver types and their associated URLs: