Channels

Connecting providers and payment methods.

The combination of a payment method and a provider 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 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.

The available operations for the Channels resource are:

GET /v1/channels

Result Parameter

charge_typeString

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


conditionsJSON Object

The routing conditions


created_atString

The date when the rule was created


updated_atString

The date when the rule was last updated


enabledBoolean

Whether the rule is enabled or not


priorityInteger

The rule's priority (the lower, the more priority it has)


paramsArray

Necessary configurations to calculate the rule's output


typeString

Type of algorithm that will be used to select the processor


idString

The rule's ID

REQUEST
$ curl GET https://merchant-api.switchpayments.com/v1/channels?merchant_id={accountId} -u accountId:merchantApiKey
RESULT: HTTP 200
{
"collection": [
{
"id": "1d52aab23982d512f651dcb98ffe010b7b8570ff5dd5312a",
"charge_type": "card_onetime",
"label": "card_onetime_acapture",
"enabled": true,
"processor": "acapture"
},
{
"id": "536dd315e6eaa162c9032930c71a0915a351a2c15dd53108",
"charge_type": "card_recurring",
"label": "card_recurring_acapture",
"enabled": true,
"processor": "acapture"
},
{
"id": "121cd198aa405f7e9643a5ba083a3265f5f9a3745dd5228c",
"charge_type": "card_recurring",
"label": "card_recurring_stripe",
"enabled": true,
"processor": "stripe"
}
],
"filters": {},
"pagination": {
"page": 1,
"per_page": 20,
"total_pages": 1,
"total_items": 3
}
}

POST /v1/channels

Request Parameter

charge_typeString

Identifier of the charge type


labelString

Channel label


enabledBoolean

Whether the channel is currently enabled


metadataJSON Object

Necessary metadata for the processor to use to process payments (you can find the correct metadata schema in the /channels/schemas endpoint)


processorString

The channel's payment processor

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


labelString

Channel label


enabledBoolean

Whether the channel is currently enabled


processorString

The channel's payment processor

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

Create charge without required fields

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

messageString

String with the error details, in this case: "Invalid parameters"


parametersJSON Object

A list with all the invalid fields and the respective errors

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

Channel ID

The available operations for the Channel ID resource are:

GET /v1/channels/{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


processorString

The channel's payment processor

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}

Request Parameter

enabledBoolean

Whether the channel is currently enabled


metadataJSON Object

Necessary metadata for the processor to use to process payments (you can find the correct metadata schema in the /channels/schemas endpoint)

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 Schemas

The available operations for the Channel Schemas resource are:

GET /v1/channels/schemas

Result Parameter

schemaString

The channel's metadata schema in JSON Schema format


ui_schemaString

(Optional) The channel's metadata ui-schema in JSON Schema format

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."
}
}
}

Channel Shares

The available operations for the Channel Shares resource are:

GET /v1/channels/{id}/shares

Result Parameter

idString

The share ID


labelString

The share label


channel_idString

The channel ID this share is associated with


merchantString

The merchant associated with this share


enabledBoolean

Whether the share is 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
}

POST /v1/channels/{id}/shares

Request Parameter

labelString

The share label


merchantString

The merchant associated with this share

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 share label


channel_idString

The channel ID this share is associated with


merchantString

The merchant associated with this share


enabledBoolean

Whether the share is enabled or not

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

Create api key without required fields

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 share ID


labelString

The share label


channel_idString

The channel ID this share is associated with


merchantString

The merchant associated with this share


enabledBoolean

Whether the share is enabled or not

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

Routing Rules

The available operations for the Routing Rules resource are:

GET /v1/router/rules

Result Parameter

<charge_type>String

Identifier of the charge type (card_onetime, card_recurring, paypal...). If the request does not include charge_type, all charge types will be returned


charge_typeString

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


conditionsJSON Object

The routing conditions


created_atString

The date when the rule was created


updated_atString

The date when the rule was last updated


enabledBoolean

Whether the rule is enabled or not


priorityInteger

The rule's priority (the lower, the more priority it has)


paramsArray

Necessary configurations to calculate the rule's output


typeString

Type of algorithm that will be used to select the processor


idString

The rule's ID

REQUEST
$ curl GET https://merchant-api.switchpayments.com/v1/router/rules?charge_type={chargeType}&merchant_id={accountId} -u accountId:merchantApiKey
RESULT: HTTP 200
{
"card_onetime": [
{
"charge_type": "card_onetime",
"conditions": {
"amount__gt": 50,
"processing_currency__in": [
"DOP"
]
},
"created_at": "2019-09-10T12:09:47.583718+00:00",
"enabled": true,
"priority": 2,
"params": [
{
"channel": {
"label": "card_onetime_cardnet",
"processor": "cardnet",
"id": "7581c500240442c1ec8b2f755583cdd4d488708f5ccb1ba5"
},
"value": 1
}
],
"type": "percentage",
"id": "7d50afab5076d99ffcf84ce3abe7b056ab8844c45cd0190b"
},
{
"charge_type": "card_onetime",
"conditions": null,
"created_at": null,
"enabled": true,
"updated_at": null,
"priority": null,
"params": [
{
"channel": {
"label": "card_onetime_acapture",
"processor": "acapture",
"id": "9c62fb17a095f6dc32f3f36ea289f8a9473afcb95b1ead14"
},
"value": 1
}
],
"type": "percentage",
"id": null
}
]
}

POST /v1/router/rules

Request Parameter

charge_typeString

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


conditionsJSON Object

The routing conditions


created_atString

The date when the rule was created


updated_atString

The date when the rule was last updated


enabledBoolean

Whether the rule is enabled or not


priorityInteger

The rule's priority (the lower, the more priority it has)


paramsArray

Necessary configurations to calculate the rule's output


typeString

Type of algorithm that will be used to select the processor


idString

The rule's ID

REQUEST
$ curl -vX POST https://merchant-api.switchpayments.com/v1/router/rules?merchant_id={accountId} -u accountId:merchantApiKey -d '{
"charge_type": "card_onetime",
"conditions": {
"amount__gt": 50,
"processing_currency__in": [
"DOP"
]
},
"created_at": "2019-09-10T12:09:47.583718+00:00",
"enabled": true,
"priority": 2,
"params": [
{
"channel": {
"label": "card_onetime_cardnet",
"processor": "cardnet",
"id": "7581c500240442c1ec8b2f755583cdd4d488708f5ccb1ba5"
},
"value": 1
}
],
"type": "percentage",
"id": "7d50afab5076d99ffcf84ce3abe7b056ab8844c45cd0190b"
}
Result Parameter

charge_typeString

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


conditionsJSON Object

The routing conditions


created_atString

The date when the rule was created


updated_atString

The date when the rule was last updated


enabledBoolean

Whether the rule is enabled or not


priorityInteger

The rule's priority (the lower, the more priority it has)


paramsArray

Necessary configurations to calculate the rule's output


typeString

Type of algorithm that will be used to select the processor


idString

The rule's ID

RESULT: HTTP 201
{
"charge_type": "card_onetime",
"conditions": {
"amount__gt": 50,
"processing_currency__in": [
"DOP"
]
},s
"created_at": "2019-09-10T12:09:47.583718+00:00",
"enabled": true,
"priority": 2,
"params": [
{
"channel": {
"label": "card_onetime_cardnet",
"processor": "cardnet",
"id": "7581c500240442c1ec8b2f755583cdd4d488708f5ccb1ba5"
},
"value": 1
}
],
"type": "percentage",
"id": "7d50afab5076d99ffcf84ce3abe7b056ab8844c45cd0190b"
}

Create routing without required fields

REQUEST
$ curl -vX POST https://merchant-api.switchpayments.com/v1/router/rules?merchant_id={accountId} -u accountId:merchantApiKey -d '{
"charge_type": "card_onetime",
"type": "percentage"
}'
Result Parameter

messageString

String with the error details, in this case: "Invalid parameters"


parametersJSON Object

A list with all the invalid fields and the respective errors

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

Routing Rule ID

The available operations for the Routing Rule ID resource are:

GET /v1/router/rules/{id}

Result Parameter

charge_typeString

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


conditionsJSON Object

The routing conditions


created_atString

The date when the rule was created


updated_atString

The date when the rule was last updated


enabledBoolean

Whether the rule is enabled or not


priorityInteger

The rule's priority (the lower, the more priority it has)


paramsArray

Necessary configurations to calculate the rule's output


typeString

Type of algorithm that will be used to select the processor


idString

The rule's ID

REQUEST
$ curl -vX GET https://merchant-api.switchpayments.com/v1/router/rules/{id}?merchant_id={accountId} -u accountId:merchantApiKey
RESULT: HTTP 200
{
"charge_type": "card_onetime",
"conditions": {
"amount__gt": 50,
"processing_currency__in": [
"DOP"
]
},
"created_at": "2019-09-10T12:09:47.583718+00:00",
"enabled": true,
"priority": 2,
"params": [
{
"channel": {
"label": "card_onetime_cardnet",
"processor": "cardnet",
"id": "7581c500240442c1ec8b2f755583cdd4d488708f5ccb1ba5"
},
"value": 1
}
],
"type": "percentage",
"id": "7d50afab5076d99ffcf84ce3abe7b056ab8844c45cd0190b"
}

PUT /v1/router/rules/{id}

Request Parameter

charge_typeString

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


conditionsJSON Object

The routing conditions


created_atString

The date when the rule was created


updated_atString

The date when the rule was last updated


enabledBoolean

Whether the rule is enabled or not


priorityInteger

The rule's priority (the lower, the more priority it has)


paramsArray

Necessary configurations to calculate the rule's output


typeString

Type of algorithm that will be used to select the processor


idString

The rule's ID

REQUEST
$ curl -vX PUT https://merchant-api.switchpayments.com/v1/router/rules/{id}?merchant_id={accountId} -u accountId:merchantApiKey -d '{
"charge_type": "card_onetime",
"conditions": {
"amount__gt": 50,
"processing_currency__in": [
"DOP"
]
},
"created_at": "2019-09-10T12:09:47.583718+00:00",
"enabled": true,
"priority": 2,
"params": [
{
"channel": {
"label": "card_onetime_cardnet",
"processor": "cardnet",
"id": "7581c500240442c1ec8b2f755583cdd4d488708f5ccb1ba5"
},
"value": 1
}
],
"type": "percentage",
"id": "7d50afab5076d99ffcf84ce3abe7b056ab8844c45cd0190b"
}
Result Parameter

charge_typeString

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


conditionsJSON Object

The routing conditions


created_atString

The date when the rule was created


updated_atString

The date when the rule was last updated


enabledBoolean

Whether the rule is enabled or not


priorityInteger

The rule's priority (the lower, the more priority it has)


paramsArray

Necessary configurations to calculate the rule's output


typeString

Type of algorithm that will be used to select the processor


idString

The rule's ID

RESULT: HTTP 200
{
"charge_type": "card_onetime",
"conditions": {
"amount__gt": 50,
"processing_currency__in": [
"DOP"
]
},
"created_at": "2019-09-10T12:09:47.583718+00:00",
"enabled": true,
"priority": 2,
"params": [
{
"channel": {
"label": "card_onetime_cardnet",
"processor": "cardnet",
"id": "7581c500240442c1ec8b2f755583cdd4d488708f5ccb1ba5"
},
"value": 1
}
],
"type": "percentage",
"id": "7d50afab5076d99ffcf84ce3abe7b056ab8844c45cd0190b"
}

DELETE /v1/router/rules/{id}

REQUEST
$ curl -vX DELETE https://merchant-api.switchpayments.com/v1/router/rules/{id}?merchant_id={accountId} -u accountId:apiKey

Result: HTTP204


Routing Rules Priority

The available operations for the Routing Rules Priority resource are:

POST /v1/router/rules/priority

Request Parameter

charge_typeString

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


priorityInteger

The rule's priority (the lower, the more priority it has)

REQUEST
$ curl -vX POST https://merchant-api.switchpayments.com/v1/router/rules/priority?merchant_id={accountId} -u accountId:merchantApiKey -d '{
"charge_type": "card_onetime",
"priority": 2
}
Result Parameter

<charge_type>String

Identifier of the charge type (card_onetime, card_recurring, paypal...). If the request does not include charge_type, all charge types will be returned


charge_typeString

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


conditionsJSON Object

The routing conditions


created_atString

The date when the rule was created


updated_atString

The date when the rule was last updated


enabledBoolean

Whether the rule is enabled or not


priorityInteger

The rule's priority (the lower, the more priority it has)


paramsArray

Necessary configurations to calculate the rule's output


typeString

Type of algorithm that will be used to select the processor


idString

The rule's ID

RESULT: HTTP 200
{
"card_onetime": [
{
"charge_type": "card_onetime",
"conditions": {
"amount__gt": 50,
"processing_currency__in": [
"DOP"
]
},
"created_at": "2019-09-10T12:09:47.583718+00:00",
"enabled": true,
"priority": 2,
"params": [
{
"channel": {
"label": "card_onetime_cardnet",
"processor": "cardnet",
"id": "7581c500240442c1ec8b2f755583cdd4d488708f5ccb1ba5"
},
"value": 1
}
],
"type": "percentage",
"id": "7d50afab5076d99ffcf84ce3abe7b056ab8844c45cd0190b"
},
{
"charge_type": "card_onetime",
"conditions": null,
"created_at": null,
"enabled": true,
"updated_at": null,
"priority": null,
"params": [
{
"channel": {
"label": "card_onetime_acapture",
"processor": "acapture",
"id": "9c62fb17a095f6dc32f3f36ea289f8a9473afcb95b1ead14"
},
"value": 1
}
],
"type": "percentage",
"id": null
}
]
}