Channels

Connecting providers and payment methods.

Consider going over Dynamic Routing.

Dynamic Routing provides real-time switching capabilities that allow you to select the best provider for a given transaction.

The combination of a payment method and a provider, considering the integration of choice, represents a channel in the Switch Platform. It is an actual medium that can be used to perform a financial transaction (e.g. Credit Card through Elavon, or Alipay through Worldpay).

A channel is configured through our Dashboard UI using the API keys for the merchant account that you have opened with the provider. By setting up multiple payment channels for the same payment method, and leveraging our Dynamic Routing component, you can define specific rules for real-time transaction routing between multiple providers.

POST `/v1/channels`

Method	Path	Description
POST	Sandbox `https://merchant-api-test.switchpayments.com/v1/channels` Production `https://merchant-api.switchpayments.com/v1/channels`	Create a new channel.

Request Parameter

charge_typeStringRequired

Identifier of the charge type associated with the channel being created.

labelStringRequired

Designation attributed to the channel being created.

enabledBooleanRequired

Whether the channel is currently enabled or not.

metadataJSON ObjectRequired

Metadata necessary for the provider to process payments. You can find the correct metadata schema using the GET /v1/channels/schemasendpoint.

processorStringRequired

The provider associated with the channel you are creating.

REQUEST
  $ curl -vX POST https://merchant-api.switchpayments.com/v1/channels?merchant_id={accountId} -u accountId:merchantApiKey -d '{
    "charge_type": "card_onetime",
    "enabled": true,
    "label": "card_onetime_acapture",
    "metadata": {},
    "processor": "acapture"
  }'

Result Parameter

idString

Unique identifier for the channel.

charge_typeString

Identifier of the charge type associated with the channel in question.

labelString

Designation attributed to the channel.

enabledBoolean

Whether the channel is currently enabled or not.

processorString

The channel's payment provider.

RESULT: HTTP 201
  {
    "id": "1d52aab23982d512f651dcb98ffe010b7b8570ff5dd5312a",
    "charge_type": "card_onetime",
    "label": "card_onetime_acapture",
    "enabled": true,
    "processor": "acapture"
  }

Find metadata requirements.

GET `/v1/channels/schemas`

Method	Path	Description
GET	Sandbox `https://merchant-api-test.switchpayments.com/v1/channels/schemas` Production `https://merchant-api.switchpayments.com/v1/channels/schemas`	Tap into the metadata required to manage each channel.

Result Parameter

schemaString

The channel's metadata schema in JSON schema format.

ui_schemaString

The channel's metadata UI schema in JSON Schema format. This field is non-compulsory.

REQUEST
  $ curl GET https://merchant-api.switchpayments.com/v1/channels/schemas?merchant_id={accountId}&charge_type={chargeType}&processor={processor} -u accountId:merchantApiKey

RESULT: HTTP 200
  {
    "schema": {
      "title": "Acapture",
      "type": "object",
      "properties": {
        "user_id": {
          "type": "string",
          "title": "User ID",
          "minLength": 1
        },
        "password": {
          "type": "string",
          "title": "Password",
          "minLength": 1
        },
        "webhook_secret_for_encryption": {
          "type": ["string", "null"],
          "title": "Webhook Decryption Secret",
          "minLength": 1
        }
      },
      "required": ["user_id", "password"]
    },
    "ui_schema": {
      "user_id": {
        "ui:help": "Your unique identifier in Acapture."
      }
    }
  }

GET `/v1/channels`

Method	Path	Description
GET	Sandbox `https://merchant-api-test.switchpayments.com/v1/channels` Production `https://merchant-api.switchpayments.com/v1/channels`	List the available channels.

Result Parameter

idString

Identifier for the channel being listed.

charge_typeString

Identifier of the charge type (e.g.card_onetime, card_recurring, paypal.)

labelString

The routing conditions associated with each channel.

created_atString

Designation attributed to the channel.

enabledBoolean

Whether the channel is currently enabled or not.

processorString

Provider associated with th channel in question.

merchant_idString

Merchant associated with this channel.

metadataJSON Object

Additional information related to this channel. Might include details on the integration.

REQUEST
  $ curl GET https://merchant-api.switchpayments.com/v1/channels?merchant_id={accountId} -u accountId:merchantApiKey

RESULT: HTTP 200
    {
        "multibanco": {
            "id": "multibanco",
            "label": "Multibanco",
            "channels": [
                {
                    "id": "f030ea091b661bcba0dcdf0309ee8663505",
                    "charge_type": "multibanco",
                    "label": "multibanco_eupago",
                    "enabled": true,
                    "processor": "eupago",
                    "merchant_id": "IdxIqq9YYvmQ4izAw6DZpm3nfhUGxHD1MnHTPZWC",
                    "metadata": {
                        "environment": "middle earth",
                        "api_key": "12345",
                        "integration": "s_v1"
                    }
                }
            ]
        },
        "card_onetime": {
            "id": "card_onetime",
            "label": "Card One-Time",
            "channels": [
                {
                    "id": "b348b08a74f9ac0f5f6b490de5eaaa3d9",
                    "charge_type": "card_onetime",
                    "label": "onetime_acapture",
                    "enabled": true,
                    "processor": "acapture",
                    "merchant_id": "IdxIqq9YYvmQ4izAw6DZpm3nfhUGxHD1MnHTPZWC",
                    "metadata": {
                        "user_id": "0",
                        "password": "0",
                        "channel_ids": {
                            "card_onetime": "000"
                        },
                        "allow_test_mode": true,
                        "webhook_secret_for_encryption": "0665",
                        "autodetect_card_brand": true
                    }
                },
                {
                    "id": "7adec7d5ec676f101909e661985501ec",
                    "charge_type": "card_onetime",
                    "label": "onetime_stripe",
                    "enabled": true,
                    "processor": "stripe",
                    "merchant_id": "IdxIqq9YYvmQ4izAw6DZpm3nfhUGxHD1MnHTPZWC",
                    "metadata": {
                        "secret_key": "034",
                        "publishable_key": "0",
                        "integration": "charges"
                    }
                }
            ]
        }
    }

GET `/v1/channels/{id}`

Method	Path	Description
GET	Sandbox `https://merchant-api-test.switchpayments.com/v1/channels/{id}` Production `https://merchant-api.switchpayments.com/v1/channels/{id}`	Get the details of a specific channel using its ID.

Result Parameter

idString

Unique identifier for the channel.

charge_typeString

Identifier of the charge_type.

labelString

Channel label.

enabledBoolean

Whether the channel is currently enabled or not.

processorString

The channel's payment provider.

REQUEST
  $ curl -vX GET https://merchant-api.switchpayments.com/v1/channels/{id}?merchant_id={accountId} -u accountId:merchantApiKey

RESULT: HTTP 200
  {
    "id": "1d52aab23982d512f651dcb98ffe010b7b8570ff5dd5312a",
    "charge_type": "card_onetime",
    "label": "card_onetime_acapture",
    "enabled": true,
    "processor": "acapture"
  }

PATCH `/v1/channels/{id}`

Method	Path	Description
PATCH	Sandbox `https://merchant-api-test.switchpayments.com/v1/channels/{id}` Production `https://merchant-api.switchpayments.com/v1/channels/{id}`	Make changes to existing channel through its ID.

Request Parameter

enabledBoolean

Whether the channel is currently enabled or not. This is the parameter we are making changes to in this example. Turning a previously enabled channel into an active channel.

metadataJSON Object

Metadata necessary for the provider to process payments. You can find the correct metadata schema using the GET /v1/channels/schemas endpoint. For changes it can include parameters like user_id and password.

REQUEST
  $ curl -vX PATCH https://merchant-api.switchpayments.com/v1/channels/{id}?merchant_id={accountId} -u accountId:merchantApiKey -d '{
    "enabled": true,
    "metadata": {}
  }'

Result Parameter

idString

Unique identifier for the channel

charge_typeString

Identifier of the charge type

labelString

Channel label

enabledBoolean

Whether the channel is currently enabled

processorString

The channel's payment processor

RESULT: HTTP 200
  {
    "id": "1d52aab23982d512f651dcb98ffe010b7b8570ff5dd5312a",
    "charge_type": "card_onetime",
    "label": "card_onetime_acapture",
    "enabled": true,
    "processor": "acapture"
  }

Channel Shares

Merchants have access to all the channels made available to their account. They can choose which of these channels should be shared with their sub-merchants. In the following examples we will expand on how you can create new shares and consult the ones in use.

POST `/v1/channels/{id}/shares`

Method	Path	Description
POST	Sandbox `https://merchant-api-test.switchpayments.com/v1/channels/{id}/shares` Production `https://merchant-api.switchpayments.com/v1/channels/{id}/shares`	Create a new channel share.

Request Parameter

labelString

The share label.

merchantString

The merchant or sub-merchant with whom this channel should be shared with.

REQUEST
  $ curl -vX POST https://merchant-api.switchpayments.com/v1/channels/{id}/shares?merchant_id={accountId} -u accountId:merchantApiKey -d '{
    "label": "My Share",
    "merchant": "121cd198aa405f7e9643a5ba083a3265f5f9a3745dd5228c"
  }'

Result Parameter

idString

The share ID

labelString

The channel share label.

channel_idString

The channel ID this share is associated with.

merchantString

The merchant or sub-merchant associated with this share.

enabledBoolean

Whether the share is currently enabled or not.

RESULT: HTTP 201
  {
    "id": "1d52aab23982d512f651dcb98ffe010b7b8570ff5dd5312a",
    "label": "My Share",
    "channel_id": "536dd315e6eaa162c9032930c71a0915a351a2c15dd53108",
    "merchant": "121cd198aa405f7e9643a5ba083a3265f5f9a3745dd5228c",
    "enabled": true
  }

GET `/v1/channels/{id}/shares`

Method	Path	Description
GET	Sandbox `https://merchant-api-test.switchpayments.com/v1/channels/{id}/shares` Production `https://merchant-api.switchpayments.com/v1/channels/{id}/shares`	List the shares associated with a specific channel through its ID.

Result Parameter

idString

The channel share identification.

labelString

The designation attributed to the channel share.

channel_idString

The channel ID this share is associated with.

merchantString

The merchant associated with this share.

enabledBoolean

Whether the share is currently enabled or not.

REQUEST
  $ curl GET https://merchant-api.switchpayments.com/v1/channels/{id}/shares?merchant_id={accountId} -u accountId:merchantApiKey

RESULT: HTTP 200
  {
    "id": "1d52aab23982d512f651dcb98ffe010b7b8570ff5dd5312a",
    "label": "My Share",
    "channel_id": "536dd315e6eaa162c9032930c71a0915a351a2c15dd53108",
    "merchant": "121cd198aa405f7e9643a5ba083a3265f5f9a3745dd5228c",
    "enabled": true
  }

It is not possible to create a channel share without registering all the required fields. Tending to this error case, a list with all the invalid fields and the respective errors is returned.

REQUEST
  $ curl -vX POST https://merchant-api.switchpayments.com/v1/channels?merchant_id={accountId} -u accountId:merchantApiKey -d '{
    "label": "My Share"
  }'

Result Parameter

idString

The channel share ID.

labelString

The share label.

channel_idString

The channel ID this share is associated with.

merchantString

The merchant or sub-merchant associated with this share.

enabledBoolean

Whether the share is currently enabled or not.

RESULT: HTTP 400
  {
    "message": "Invalid parameters",
    "parameters": {
      "merchant": [
        "This field is required."
      ]
    }
  }

Next Steps

Understand how you can use settlements and sources to watch over your transactions and how to access agreements and disputes. Learn more about Reconciliation.
Complement your channels using routing rules, take a look into Dynamic Routing.

Channels

Connecting providers and payment methods.

Consider going over Dynamic Routing.

POST `/v1/channels`

Request Parameter

Result Parameter

Channel Schemas

GET `/v1/channels/schemas`

Result Parameter

GET `/v1/channels`

Result Parameter

GET `/v1/channels/{id}`

Result Parameter

PATCH `/v1/channels/{id}`

Request Parameter

Result Parameter

Channel Shares

POST `/v1/channels/{id}/shares`

Request Parameter

Result Parameter

GET `/v1/channels/{id}/shares`

Result Parameter

Check out the following use case

Result Parameter

Next Steps

Channels

Connecting providers and payment methods.

Consider going over Dynamic Routing.

POST /v1/channels

Request Parameter

Result Parameter

Channel Schemas

GET /v1/channels/schemas

Result Parameter

GET /v1/channels

Result Parameter

GET /v1/channels/{id}

Result Parameter

PATCH /v1/channels/{id}

Request Parameter

Result Parameter

Channel Shares

POST /v1/channels/{id}/shares

Request Parameter

Result Parameter

GET /v1/channels/{id}/shares

Result Parameter

Check out the following use case

Result Parameter

Next Steps

POST `/v1/channels`

GET `/v1/channels/schemas`

GET `/v1/channels`

GET `/v1/channels/{id}`

PATCH `/v1/channels/{id}`

POST `/v1/channels/{id}/shares`

GET `/v1/channels/{id}/shares`