How To Add Gateways and Receivers

Gateways and receivers

The API only needs to be called when a new merchant or gateway is being added to a Spreedly environment, using the environmental credentials as described in the section above. They are not part of the transaction flow. Gateways can also be added from the Spreedly web application user interface.

Create a gateway using our API or use our no-code dropdown interface to create your gateways. - This will create a gateway token for use in subsequent transaction APIs and is a requirement prior to making any other orchestration calls. Depending on the gateway, you will need to include different gateway specific fields outlined here.
- [Optional] To associate a gateway to a sub-merchant, pass the returned token in the sub_merchant_token when creating 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.
Create a receiver token [Optional] - This will be required before sending any Deliver requests to Spreedly. This will act in a similar fashion to the create gateway token process if orchestration is used. Please refer to the Payment Method Distribution Guide for more information.

Adding a gateway

Using your API credentials, you can add a gateway by POSTing to the Spreedly API endpoint https://core.spreedly.com/v1/gateways. For example, to add the Spreedly test gateway to your environment, you can run the following curl command (replace the example environment key and access secret with your own):

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

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

The response you receive will be a new gateway record identified by its token element. Store this token in your system so you can reference it in future transactions.

{
  "gateway": {
    "token": "HaQOnzrDfDHdqWmO0WAjw9zDjGE",
    "gateway_type": "test",
    "description": null,
    "merchant_profile_key": null,
    "sub_merchant_key": null,
    "payment_methods": [
      "credit_card",
      "sprel",
      "third_party_token",
      "bank_account",
      "apple_pay",
      "google_pay"
    ],
    "state": "retained",
    "created_at": "2023-06-06T17:15:23Z",
    "updated_at": "2023-06-06T17:15:23Z",
    "name": "Spreedly Test",
    "characteristics": [
      "purchase",
      "authorize",
      "capture",
      "credit",
      "general_credit",
      "void",
      "adjust",
      "verify",
      "reference_purchase",
      "purchase_via_preauthorization",
      "offsite_purchase",
      "offsite_authorize",
      "offsite_synchronous_purchase",
      "offsite_synchronous_authorize",
      "3dsecure_purchase",
      "3dsecure_authorize",
      "3dsecure_2_mpi_purchase",
      "3dsecure_2_mpi_authorize",
      "store",
      "remove",
      "network_tokenization",
      "populate_mit_fields",
      "transaction_retry",
      "reference_authorization",
      "3dsecure_2_purchase",
      "3dsecure_2_authorize",
      "stored_credentials"
    ],
    "credentials": [

    ],
    "gateway_settings": {
    },
    "gateway_specific_fields": [
      "simulate_error",
      "simulate_decline",
      "idempotency_key",
      "mit_override_demo"
    ],
    "redacted": false,
    "sandbox": false,
    "mode": "default"
  }
}

<gateway>
  <token>7dPJgE2MQZajMypeVkpfWnNMRlk</token>
  <gateway_type>test</gateway_type>
  <name>Spreedly Test</name>
  <description nil="true"></description>
  <merchant_profile_key nil="true"></merchant_profile_key>
  <sub_merchant_key nil="true"></sub_merchant_key>
  <characteristics>
    <supports_purchase type="boolean">true</supports_purchase>
    <supports_authorize type="boolean">true</supports_authorize>
    <supports_capture type="boolean">true</supports_capture>
    <supports_credit type="boolean">true</supports_credit>
    <supports_general_credit type="boolean">true</supports_general_credit>
    <supports_void type="boolean">true</supports_void>
    <supports_adjust type="boolean">true</supports_adjust>
    <supports_verify type="boolean">true</supports_verify>
    <supports_reference_purchase type="boolean">true</supports_reference_purchase>
    <supports_purchase_via_preauthorization type="boolean">true</supports_purchase_via_preauthorization>
    <supports_offsite_purchase type="boolean">true</supports_offsite_purchase>
    <supports_offsite_authorize type="boolean">true</supports_offsite_authorize>
    <supports_offsite_synchronous_purchase type="boolean">true</supports_offsite_synchronous_purchase>
    <supports_offsite_synchronous_authorize type="boolean">true</supports_offsite_synchronous_authorize>
    <supports_3dsecure_purchase type="boolean">true</supports_3dsecure_purchase>
    <supports_3dsecure_authorize type="boolean">true</supports_3dsecure_authorize>
    <supports_3dsecure_2_mpi_purchase type="boolean">true</supports_3dsecure_2_mpi_purchase>
    <supports_3dsecure_2_mpi_authorize type="boolean">true</supports_3dsecure_2_mpi_authorize>
    <supports_store type="boolean">true</supports_store>
    <supports_remove type="boolean">true</supports_remove>
    <supports_fraud_review type="boolean">false</supports_fraud_review>
    <supports_network_tokenization type="boolean">true</supports_network_tokenization>
    <supports_populate_mit_fields type="boolean">true</supports_populate_mit_fields>
    <supports_inquire_by_gateway_transaction_id type="boolean">false</supports_inquire_by_gateway_transaction_id>
    <supports_inquire_by_order_id type="boolean">false</supports_inquire_by_order_id>
    <supports_transaction_retry type="boolean">true</supports_transaction_retry>
    <supports_stored_stored_credentials type="boolean">false</supports_stored_stored_credentials>
    <supports_reference_authorization type="boolean">true</supports_reference_authorization>
    <supports_3dsecure_2_purchase type="boolean">true</supports_3dsecure_2_purchase>
    <supports_3dsecure_2_authorize type="boolean">true</supports_3dsecure_2_authorize>
    <supports_stored_credentials type="boolean">true</supports_stored_credentials>
  </characteristics>
  <credentials>
  </credentials>
  <gateway_settings>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>simulate_error</gateway_specific_field>
    <gateway_specific_field>simulate_decline</gateway_specific_field>
    <gateway_specific_field>idempotency_key</gateway_specific_field>
    <gateway_specific_field>mit_override_demo</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
    <payment_method>sprel</payment_method>
    <payment_method>third_party_token</payment_method>
    <payment_method>bank_account</payment_method>
    <payment_method>apple_pay</payment_method>
    <payment_method>google_pay</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <sandbox type="boolean">false</sandbox>
  <mode>default</mode>
  <created_at type="dateTime">2023-06-06T17:16:02Z</created_at>
  <updated_at type="dateTime">2023-06-06T17:16:02Z</updated_at>
</gateway>

Spreedly supports many production gateways. While this example shows a test gateway, you can provision any of the supported production gateways in the same way by specifying the correct gateway_type parameter along with any credentials required for the desired gateway. For complex integrations, such as 3DS2, Spreedly allows a gateway to be created in sandbox mode (this requires a production Spreedly account). See our testing guide for more details.

To learn more about creating and managing gateways in our Marketplace, review the Gateway user guide. For gateways not included in the Marketplace, review the steps below.

Create a gateway

Visit your Connections area to review all gateways and add new ones. When creating your gateways, select the gateway name and authentication mode (if prompted) before completing required fields. Select ☑️Sandbox to create a gateway in Sandbox mode, for processing test card data and transactions in your Spreedly environment.

Store gateway tokens

When you add a gateway, the response contains a token element that represents the specific gateway (it's like the gateway's ID). You don't need to create a new gateway token every time you want to run a transaction.

All future references to that gateway will use the same token, so you will need to store the gateway token for future use. Reference your saved gateway token to transact against the gateway ad infinitum. If you forget to save a gateway's token, you can always use the API to list all your provisioned gateways.

If you wish to transact against a third-party API endpoint, please read about payment method distribution