Merchant Registration and Value-Add-Services

Spreedly’s registration services allows merchant aggregators and direct merchants to formally identify atomic units (e.g. individual merchants within a platform) or logical segments (e.g. geography) of their business and provides:

  1. The prerequisite foundation to turn on, track, and monetize value-add-services (VAS) on those individual segments.
  2. Track payment method transactional volume and reporting metrics on a per-merchant or segment basis.

Aggregators can organize their business and merchants using a top-level organization that can be associated to 1:N environments. Spreedly has introduced capabilities to allow customers to create environments, create environment secrets, and associate merchant meta-data via the appropriate APIs to enable aggregators to configure and manage their merchants programmatically.

Summary of the New Registration APIs:

  1. Create environments via the API - allows aggregators to segment their merchants into individual, logical vaults at scale: Environments API
  2. Create single-environment level access secrets via the API - create and associate credentials to environments through automation: Access_secrets API
  3. Create and associate sub_merchant objects - this is a new API object that allows the aggregator to associate representative identification data for each individual merchant, including name, URL, email, industry payment identifiers, and ad-hoc meta-data or internal identifiers that the aggregator is leveraging to associate to their merchants (e.g. UIDs). Along for their own identification, the aggregator can help themselves by helping Spreedly quickly isolate and identify impacted merchants when there are issues or support cases. The API is referenced here: Sub_merchant API

Although aggregators that are the non-merchant of record (non-MoR) which have many merchant of record customers are the ideal candidates for the new registration APIs, any direct merchant of record (MoR) that wants to segment and enable services on a more granular level for their business can leverage and take advantage of these capabilities (e.g. a merchant wants to track and enable services on a per country basis).

In general, we would recommend that the aggregator have a 1:1 relationship between the environment and their merchant (i.e. create a unique environment and sub_merchant object for each of their individual merchants). Payment services are planned to be controlled (enabled and disabled) at the environment-level; along with the logical separation, segmenting by environment will then allow the merchant aggregator to enable, monitor, and report on services at a per-merchant granularity. The account structure with merchant aggregator registration and controls for VAS enablement is shared below:

Not all customers may find it conducive or necessary to move a 1:1 environment to merchant setup. The table below summarizes guidance that merchant aggregators can leverage to determine how best to register their merchants:

Merchant Aggregator Registration Guidance Summary

Aggregator’s Business Model Customer Status with Spreedly Characteristics Recommendation
Aggregator = non-MoR*

Aggregator’s merchant = MoR**		 New Spreedly Aggregator Customer Aggregator’s merchant has its own unique payment methods (e.g. eCommerce platforms). The same can hold true for a direct MoR merchant that wants to also manage services on a segmentation of their business (e.g. by geography) Create an environment per merchant (1:1)

Benefit: Merchant aggregator can manage and control VAS enablement on a per-merchant basis
Aggregator = non-MoR

Aggregator’s merchant = MoR		 Existing Spreedly Aggregator Customer Aggregator’s merchant has its own unique payment methods (e.g. eCommerce platforms) Merchant aggregator has a few options:

1. Update to a 1:1 setup - Spreedly is developing tooling to help facilitate this process for the merchant aggregator.

2. For net new merchants, the aggregator can start creating a new environment per merchant.

3. Only migrate select merchants (e.g. those with subscription payments and those that want to enable VAS).

Benefits for options #1-3 are similar to the above.

4. Stay in their current setup. Services would be enabled for all merchants in that environment.

Disadvantages with this option are that the aggregator would lose the ability to enable/disable a payment service AND the visibility to track service specific reporting (usage, etc.) on a per merchant basis but still could get transactional reporting on a per merchant basis (if the merchant aggregator tags the sub_merchant’s key to the respective gateway).
Aggregator = MoR

Aggregator’s merchant = non-MoR		 New or Existing Spreedly Aggregator Customer Payment methods are shared across merchants (e.g. a marketplace) If services would like to be managed for the entire merchant base (e.g. Account Updater is desired to be enabled for all payment methods that would be used in the marketplace), merchants can remain grouped in a single environment.

*non-MoR = non-merchant of record
**MoR = merchant of record

Transactional Reporting

Aggregators that are segmenting their merchants via individual environments will be able to track and view payment method transactions details (number of transactions, GMV, etc.) on a per merchant (environment) basis in Dashboard.

Aggregators that have many merchants or a single merchant in an environment will need to tag their merchant gateway(s) with the sub_merchant key to get visibility into merchant transactional reporting.

In the case where multiple merchants are transacting through the same gateway (token), there is an ability to tag a transaction with the sub_merchant key directly. Transactions tagged with the sub_merchant key always have a higher precedence than the sub_merchant key tagged on the gateway.

Implementation Guide for the Merchant Registration APIs

This section provides contextual implementation details to configure the registration flow.

Before environment creation via API can begin, you will need to manually create one environment and an organization-level access secret. Assuming this step has been completed, you can use the following steps to create environments and transact within these environments.

Steps to associate a merchant to an environment

1. Create environment via API call.

The credentials for this call should be the environment_key and organization access_secret created with steps above in the UI. Note that the field name is required. Spreedly suggests naming your environments to mirror the store/merchant it will represent. The returned environment_key will be needed for all future transactions in this environment. If you are only allowing payment method creation via the Spreedly iframe, update the environment created in Step 1 with allow_direct_api_payment_method_creation: false.
Sample usage:

$ curl https://core.spreedly.com/v1/environments.json \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/json' \
  -d '{
        "environment": {
          "name": "Test Environment"
        }
      }'


$ curl https://core.spreedly.com/v1/environments.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<environment>
        <name>Test Environment</name>
      </environment>'

2. Create single-environment access secret.

The credentials for this call should be the environment_key and organization access_secret. The field name is required here. This field will be used to differentiate your access secrets from one another in reporting. The returned access_secret can be used for all future transactions in this environment.
Sample usage:

$ curl https://core.spreedly.com/v1/environments/<environment_key>/access_secrets.json \
  -u '<environment_key>:credentials' \
  -H 'Content-Type: application/json' \
  -d '{
        "access_secret": {
          "name": "New Access Secret"
        }
      }'


$ curl https://core.spreedly.com/v1/environments/<environment_key>/access_secrets.xml \
  -u '<environment_key>:credentials' \
  -H 'Content-Type: application/xml' \
  -d '<access_secret>
        <name>New Access Secret</name>
      </access_secret>'

3. Create sub-merchant object to represent a merchant and/or a merchant segment.

The credentials for this call should be the environment_key and access_secret created in steps 1 and 2. Required fields within the request body include name for the merchant and environment_key to associate the sub_merchant to. If merchant_data is passed through then the acquirer_merchant_id field is required for each datum. merchant_data can hold multiple acquirer_mechant_id:mcc combinations for each card_network. merchant_defined_uid is where you can include a mapping to an internal identifier that they have for the stores/merchants. You will want to retain the returned token for reporting on this merchant’s activities.
Sample usage:

$ curl https://core.spreedly.com/v1/sub_merchants.json \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/json' \
  -d '{
        "sub_merchant": {
          "name": "My Submerchant name",
          "environment_key": "C7cRfNJGODKh4Iu5Ox3PToKjniY",
          "merchant_url": "www.submerchanturl.com",
          "merchant_email": "example@email.com",
          "ein": "12-3456789",
          "merchant_defined_uid": "abcd1234",
          "merchant_data": [
            {
              "card_network": "visa",
              "acquirer_merchant_id": "sub-merchants mid",
              "mcc": "5978",
              "acquirer_bin": "4444444444",
              "business_id": "7654321"
            }
          ],
          "address": {
            "address1": "100 Main Street",
            "city": "Funk",
            "state": "NE",
            "zip": "68940",
            "country": "US"
          },
          "metadata": {
            "custom_key": "custom_value"
          }
        }
      }'



$ curl https://core.spreedly.com/v1/sub_merchants.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<sub_merchant>
        <name>My Submerchants name</name>
        <environment_key>C7cRfNJGODKh4Iu5Ox3PToKjniY</environment_key>
        <merchant_url>www.submerchanturl.com</merchant_url>
        <merchant_email>example@email.com</merchant_email>
        <ein>12-3456789</ein>
        <merchant_defined_uid>abcd1234</merchant_defined_uid>
        <merchant_data type ="array">
          <value>
            <card_network>visa</card_network>
            <acquirer_merchant_id>sub-merchant mid</acquirer_merchant_id>
            <mcc>5978</mcc>
            <acquirer_bin>4444444444</acquirer_bin>
            <business_id>7654321</business_id>
          </value>
        </merchant_data>
        <address>
          <address1>100 Main Street</address1>
          <city>Funk</city>
          <state>NE</state>
          <zip>68940</zip>
          <country>US</country>
        </address>
        <metadata>
          <custom_key>custom_value</custom_key>
        </metadata>
      </sub_merchant>'

4. Create gateways.

The credentials for this call should be the environment_key and access_secret created in steps 1 and 2. These calls will include the merchant’s credentials for that gateway and the gateway type. For more information on specific gateways, see Spreedly’s Gateway Guides.
Sample usage:

curl https://core.spreedly.com/v1/gateways.json \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/json' \
  -d '{
        "gateway": {
          "gateway_type": "test",
          "sub_merchant_key": <your_sub_merchant_token>
        }
      }'

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>test</gateway_type>
        <sub_merchant_key>{your_sub_merchant_token}<sub_merchant_key>
      </gateway>'

Note: You can also pass in the sub_merchant_key in the body of the request when you transact with a gateway. The sub_merchant_key from the request body will then override the sub_merchant_key from the gateway. This method can also be used if the gateway doesn’t have a sub_merchant_key specified. Retain each created gateway token. These will be used for transactional API calls

5. Create payment methods in the new environment.

This should be utilized if running a self-managed migration. POST to payment-methods endpoint for each new payment method. The credentials for this call should be the environment_key and access_secret created in steps 1 and 2

curl https://core.spreedly.com/v1/payment_methods.json \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/json' \
  -d '{
        "payment_method": {
          "credit_card": {
              "first_name": "Joe",
              "last_name": "Jones",
              "number":"5555555555554444",
              "verification_value": "423",
              "month":"3",
              "year":"2029",
              "company": "Acme Inc.",
              "address1": "33 Lane Road",
              "address2": "Apartment 4",
              "city": "Wanaque",
              "state": "NJ",
              "zip": "31331",
              "country": "US",
              "phone_number": "919.331.3313",
              "shipping_address1": "33 Lane Road",
              "shipping_address2": "Apartment 4",
              "shipping_city": "Wanaque",
              "shipping_state": "NJ",
              "shipping_zip": "31331",
              "shipping_country": "US",
              "shipping_phone_number": "919.331.3313"
          },
          "email": "joey@example.com",
          "metadata": {
              "key": "string value",
              "another_key": 123,
              "final_key": true
          }
        }
      }'

curl https://core.spreedly.com/v1/payment_methods.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<payment_method>
        <credit_card>
            <first_name>Joey</first_name>
            <last_name>Jones</last_name>
            <number>5555555555554444</number>
            <verification_value>423</verification_value>
            <month>3</month>
            <year>2029</year>
            <company>Acme Inc.</company>
            <address1>33 Lane Road</address1>
            <address2>Apartment 4</address2>
            <city>Wanaque</city>
            <state>NJ</state>
            <zip>31331</zip>
            <country>US</country>
            <phone_number>919.331.3313</phone_number>
            <shipping_address1>33 Lane Road</shipping_address1>
            <shipping_address2>Apartment 4</shipping_address2>
            <shipping_city>Wanaque</shipping_city>
            <shipping_state>NJ</shipping_state>
            <shipping_zip>31331</shipping_zip>
            <shipping_country>US</shipping_country>
            <shipping_phone_number>919.331.3313</shipping_phone_number>
        </credit_card>
        <email>joey@example.com</email>
        <metadata>
          <key>String Value</key>
          <another_key>123</another_key>
          <final_key>true</final_key>
        </metadata>
      </payment_method>'

6. Optionally update the environment’s security

If you are only allowing payment method creation via the Spreedly iframe, update the environment created in Step 1 with allow_direct_api_payment_method_creation: false

7. Naming recommendations

We recommend that the environment, sub_merchant, and access_secret follow the naming pattern.

  • sub_merchant: sub_merchant_{sub_merchant_name}
  • environment: environment_{sub_merchant_name}
  • secret: secret_{environment_name}

Other endpoints of note:

Account Updater Support for Merchant Aggregators

Historically, opting-in to the Account Updater has been controlled at the Organization level, which affects ALL environments within the organization. Alternatively, the service can be controlled down to an individual payment method (card) as well. However, these options can either be too broad or too narrow to effectively and efficiently enable Account Updater for customers of merchant aggregators. Account Updater can now be managed at an environment level as well, providing the aggregator the ability to enable the service for specific segments of their business and for individual merchants if they have a 1:1 relationship with environments. For additional implementation details, please see the Environment-Level Controls for Account Updater

Apple Pay Support for Merchant Aggregators

Apple Pay Implementation for Merchant Aggregators will still follow the guidance provided in Spreedly’s Apple Pay Documentation with the following items in mind:

  • Apple Pay For Mobile:

    • Apple Pay will require a single Payment Processing Certificate for each mobile application. If your mobile application is shared by multiple sub-merchants, you can have the associated Payment Processing certificate at Spreedly configured as an organization level certificate so that it can be used across the sub-merchants.
    • If your mobile application(s) are unique for each sub-merchant, then you can follow the general Apple Pay Guidance

  • Apple Pay For Web:

    • Create the Payment Processing Certificate as an organization level certificate following guidance on the certificates API i.e. include the parameter level='organization'
    • The organization level certificate will allow Spreedly to use the same certificate to decrypt Apple Pay data sent from your web application across all sub-merchants.
    • Follow Mass Enablement Guidance from Apple Pay when onboarding or de-boarding sub-merchants.